ampmInsights/docs/11-v2-evolucao-schema.html

<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; v2.0.0 — Evolução de schema</title>
<meta name="description" content="Passo 1 da v2.0.0: colunas novas em TB_26AI_TECH_V2/CMDB para CVE, pacotes e remediação chegarem ao AI Insight.">
<link rel="stylesheet" href="assets/main.css">
</head>
<body>
<div class="layout">
  <aside class="sidebar">
    <div class="brand">
      <span class="oracle">ORACLE</span>
      <span class="name">ampmInsights</span>
    </div>
    <button class="menu-toggle" type="button">Menu &#9776;</button>
    <div class="kicker">Documentação V2 &middot; AM/PM</div>
    <ul class="nav-list">
      <li><a class="" href="index.html"><span class="step-no">1</span>Visão geral</a></li>
<li><a class="" href="02-arquitetura.html"><span class="step-no">2</span>Arquitetura</a></li>
<li><a class="" href="03-pre-requisitos-credenciais.html"><span class="step-no">3</span>Pré-requisitos & credenciais</a></li>
<li><a class="" href="04-passo-a-passo-banco.html"><span class="step-no">4</span>Passo a passo: banco de dados</a></li>
<li><a class="" href="05-passo-a-passo-apex.html"><span class="step-no">5</span>Passo a passo: aplicação APEX</a></li>
<li><a class="" href="06-validacao-testes.html"><span class="step-no">6</span>Validação & testes</a></li>
<li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
<li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
<li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
<li><a class="active" href="11-v2-evolucao-schema.html"><span class="step-no">11</span>v2.0.0 — Evolução de schema</a></li>
<li><a class="" href="12-v2-view-procedure.html"><span class="step-no">12</span>v2.0.0 — View & Procedure</a></li>
    </ul>
    <div class="sidebar-footer">
      Vulnerability &amp; Audit AI Insights<br>
      Oracle AI Database 26ai &middot; AI Vector Search<br>
      Versão V2 &middot; em desenvolvimento, ainda não validada
    </div>
  </aside>
  <main class="content">
    <p class="page-kicker">v2.0.0 &middot; Passo 1</p>
    <h1>Evolução de schema: CVE, CVSS, solução e mais</h1>
    <p class="lede">Promove os campos "Tier 1" do Tenable e do ServiceNow — hoje fora do banco — a colunas novas em <code>TB_26AI_TECH_V2</code> e <code>TB_26AI_TECH_CMDB</code>, para que o AI Insight consiga citar CVE, pacote afetado e remediação por ativo.</p>

<div class="callout warning">
  <div class="callout-title">Status: em validação, ainda não roda em produção</div>
  <p>Este capítulo documenta um passo já implementado no script (<code>sql/03_v2_ddl_schema_evolution.sql</code>), mas ainda <strong>não confirmado em nenhum ambiente</strong>. Não use este passo como procedimento definitivo até a seção 5 (Validação) ter sido de fato executada e conferida.</p>
</div>

<h2>1. Por que isto era necessário</h2>
<p><code>PRC_26AI_TECH</code> (geração do AI Insight) monta o JSON enviado ao LLM inteiramente a
partir da <code>view V_26AI_TECH</code>, que só expõe as colunas que existem em
<code>TB_26AI_TECH_V2</code>/<code>TB_26AI_TECH_CMDB</code>. Antes da v2.0.0, apenas 18 das 99
colunas do export Tenable chegavam ao banco — nenhum campo de CVE, CVSS, EPSS, CISA KEV, pacote
afetado ou solução sugerida existia na tabela. Não era um problema de prompt: o modelo nunca via
esses dados porque eles simplesmente não estavam disponíveis.</p>

<h2>2. O que foi adicionado</h2>
<p>Estratégia híbrida: colunas tipadas para os campos que realmente importam para o "plano de
ação" do AI Insight, <strong>mais</strong> uma coluna <code>RAW_JSON</code> por linha guardando o
export completo — assim nada da planilha se perde, mesmo o que não virou coluna tipada.</p>

<div class="table-wrap">
<table>
<tr><th>Tabela</th><th>Colunas novas</th><th>Destaque</th></tr>
<tr><td><code>TB_26AI_TECH_V2</code><br>(vulnerabilidades Tenable)</td><td>23 colunas</td><td><code>DEFINITION_CVE</code>, <code>DEFINITION_SOLUTION</code>, <code>DEFINITION_DESCRIPTION</code>, <code>SOFTWARE_VULNS</code>, <code>DEFINITION_CVSS3_BASE_SCORE</code>, <code>DEFINITION_EPSS_SCORE</code>, <code>CISA_KEV_FLAG</code>, <code>RAW_JSON</code></td></tr>
<tr><td><code>TB_26AI_TECH_CMDB</code><br>(CMDB ServiceNow)</td><td>12 colunas</td><td><code>U_FIM_DO_SUPORTE</code> (EOL), <code>ATTESTATION_SCORE</code>/<code>_STATUS</code>, <code>INSTALL_STATUS</code>, <code>RAW_JSON</code></td></tr>
</table>
</div>

<div class="callout info">
  <div class="callout-title">100% aditivo — nenhum DROP</div>
  <p>Todas as colunas são novas e <code>NULL</code>able. Nenhuma tabela é recriada, nenhuma coluna
  existente é alterada, nenhum dado é apagado. A carga e a aplicação atuais continuam funcionando
  exatamente como antes — os campos novos só ficam vazios até um perfil de carga novo alimentá-los
  (ver capítulo 13, ainda não publicado). Decisão deliberada: um release aditivo, não um
  drop/recriação, para a v2.0.0 chegar ao ambiente do cliente sem impacto no que já roda.</p>
</div>

<h2>3. Script</h2>
<p>Arquivo completo: <code>sql/03_v2_ddl_schema_evolution.sql</code> no repositório. Resumo do que ele faz:</p>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">sql/03_v2_ddl_schema_evolution.sql (resumo)</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">ALTER TABLE TB_26AI_TECH_V2 ADD (
    DEFINITION_CVE VARCHAR2(4000), DEFINITION_DESCRIPTION CLOB,
    DEFINITION_SOLUTION CLOB, DEFINITION_SYNOPSIS VARCHAR2(4000),
    SOFTWARE_VULNS CLOB, DEFINITION_CVSS3_BASE_SCORE NUMBER,
    DEFINITION_CVSS3_BASE_VECTOR VARCHAR2(255), DEFINITION_CPE VARCHAR2(4000),
    DEFINITION_EPSS_SCORE NUMBER, CISA_KEV_FLAG NUMBER(1),
    EXPLOITED_BY_MALWARE_FLAG NUMBER(1), EXPLOITED_BY_NESSUS_FLAG NUMBER(1),
    PORT NUMBER, ASSET_OPERATING_SYSTEM VARCHAR2(255),
    LAST_FIXED TIMESTAMP(9) WITH TIME ZONE, TIME_TO_FIX NUMBER,
    VULN_SLA_DATE TIMESTAMP(9) WITH TIME ZONE,
    PATCH_PUBLISHED TIMESTAMP(9) WITH TIME ZONE,
    VULNERABILITY_PUBLISHED TIMESTAMP(9) WITH TIME ZONE,
    SOURCE_SCAN VARCHAR2(100), SCAN_ID VARCHAR2(255), SCAN_TARGET VARCHAR2(255),
    RAW_JSON CLOB
);

ALTER TABLE TB_26AI_TECH_CMDB ADD (
    INSTALL_STATUS VARCHAR2(100), LIFE_CYCLE_STAGE_STATUS VARCHAR2(100),
    ASSIGNED_TO VARCHAR2(255), ATTESTATION_SCORE NUMBER,
    ATTESTATION_STATUS VARCHAR2(100), ATTESTED_FLAG VARCHAR2(10),
    ATTESTED_BY VARCHAR2(255), U_FIM_DO_SUPORTE DATE, LOCATION VARCHAR2(255),
    ASSET_TAG VARCHAR2(100), U_SERVER_ROLE VARCHAR2(255), RAW_JSON CLOB
);</code></pre>
</div>
<p>O arquivo real tem, além disso, o <code>ANNOTATIONS("LLM_DESCRIPTION_PT_BR" ...)</code> em cada
coluna (padrão já usado em todo o schema, ajuda o Select AI a entender o dado) e um checkpoint de
validação embutido — use o arquivo do repositório para rodar, não este resumo.</p>

<h2>4. Como rodar</h2>
<ol>
  <li>Abra Database Actions (ou SQL Developer/SQLcl) conectado como o schema <code>AMPMINSIGHTS</code> — nunca como <code>ADMIN</code>.</li>
  <li>Confirme que está no ambiente correto antes de rodar (o script tem um aviso explícito sobre isso no topo).</li>
  <li>Cole e rode <code>sql/03_v2_ddl_schema_evolution.sql</code> inteiro, de uma vez — é idempotente, pode rodar de novo sem erro se uma coluna já existir.</li>
</ol>

<h2>5. Validação</h2>
<p>O próprio script termina com este checkpoint — rode e confira <code>STATUS = 'OK'</code> nas duas linhas:</p>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">Checkpoint de validação</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">SELECT table_name, /* ... */ status, colunas_novas_encontradas
FROM ( /* ver script completo */ );
-- Esperado: TB_26AI_TECH_V2 -> OK (23) | TB_26AI_TECH_CMDB -> OK (12)</code></pre>
</div>

<div class="callout danger">
  <div class="callout-title">Rollback, se precisar desfazer</div>
  <p>Todas as colunas são novas e nullable — para desfazer, um <code>ALTER TABLE ... DROP COLUMN</code> por coluna adicionada (lista completa no final do script). Nenhum dado existente é afetado ao reverter.</p>
</div>

    <div class="pillnav"><a class="prev" href="10-carga-cmdb-vulnerabilidades.html">&larr; Carga: CMDB & Vulnerabilidades</a><a class="next" href="12-v2-view-procedure.html">v2.0.0 — View & Procedure &rarr;</a></div>
  </main>
</div>
<script src="assets/main.js"></script>
</body>
</html>