From 561f26608e87a9ba3c4f2aea3c03214b23dfee4d Mon Sep 17 00:00:00 2001 From: Antonio Sergio Rodrigues Figueiredo Date: Wed, 9 Sep 2026 15:01:48 -0300 Subject: [PATCH] =?UTF-8?q?Docs=20v2.0.0:=20cap=C3=ADtulos=2011=20e=2012?= =?UTF-8?q?=20(evolu=C3=A7=C3=A3o=20de=20schema=20+=20view/procedure)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/11-v2-evolucao-schema.html: documenta o Passo 1 (sql/03_v2_ddl_schema_evolution.sql) — o quê, por quê, script resumido, como rodar, validação, rollback. Callout deixa explícito que ainda está em validação, não é procedimento definitivo. - docs/12-v2-view-procedure.html: documenta o Passo 2 (sql/04_v2_view_procedure_update.sql), mesmo formato, com dependência explícita do capítulo 11. - Nav lateral (sidebar) atualizada nas 12 páginas do doc set para incluir os capítulos novos; pillnav do capítulo 10 ganhou link 'next' para o 11. Co-Authored-By: Claude Sonnet 5 --- docs/02-arquitetura.html | 2 + docs/03-pre-requisitos-credenciais.html | 2 + docs/04-passo-a-passo-banco.html | 2 + docs/05-passo-a-passo-apex.html | 2 + docs/06-validacao-testes.html | 2 + docs/07-seguranca-boas-praticas.html | 2 + docs/08-glossario-roadmap.html | 2 + docs/09-operacao-observabilidade.html | 2 + docs/10-carga-cmdb-vulnerabilidades.html | 4 +- docs/11-v2-evolucao-schema.html | 143 +++++++++++++++++++++++ docs/12-v2-view-procedure.html | 117 +++++++++++++++++++ docs/index.html | 2 + 12 files changed, 281 insertions(+), 1 deletion(-) create mode 100644 docs/11-v2-evolucao-schema.html create mode 100644 docs/12-v2-view-procedure.html diff --git a/docs/02-arquitetura.html b/docs/02-arquitetura.html index 5eecd83..fe32c8f 100644 --- a/docs/02-arquitetura.html +++ b/docs/02-arquitetura.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/03-pre-requisitos-credenciais.html b/docs/03-pre-requisitos-credenciais.html index 0e0824e..8ffe765 100644 --- a/docs/03-pre-requisitos-credenciais.html +++ b/docs/03-pre-requisitos-credenciais.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/04-passo-a-passo-banco.html b/docs/04-passo-a-passo-banco.html index 11f47e5..9096072 100644 --- a/docs/04-passo-a-passo-banco.html +++ b/docs/04-passo-a-passo-banco.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/05-passo-a-passo-apex.html b/docs/05-passo-a-passo-apex.html index e524d94..aec01f3 100644 --- a/docs/05-passo-a-passo-apex.html +++ b/docs/05-passo-a-passo-apex.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/06-validacao-testes.html b/docs/06-validacao-testes.html index 89ab66d..c2cfd6c 100644 --- a/docs/06-validacao-testes.html +++ b/docs/06-validacao-testes.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/07-seguranca-boas-praticas.html b/docs/07-seguranca-boas-praticas.html index e2cfa3b..cc95fb2 100644 --- a/docs/07-seguranca-boas-praticas.html +++ b/docs/07-seguranca-boas-praticas.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/08-glossario-roadmap.html b/docs/08-glossario-roadmap.html index 4178226..a434056 100644 --- a/docs/08-glossario-roadmap.html +++ b/docs/08-glossario-roadmap.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/09-operacao-observabilidade.html b/docs/09-operacao-observabilidade.html index 1fc5915..2f7e6df 100644 --- a/docs/09-operacao-observabilidade.html +++ b/docs/09-operacao-observabilidade.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    diff --git a/docs/10-carga-cmdb-vulnerabilidades.html b/docs/10-carga-cmdb-vulnerabilidades.html index 88f7907..551b854 100644 --- a/docs/10-carga-cmdb-vulnerabilidades.html +++ b/docs/10-carga-cmdb-vulnerabilidades.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights
    @@ -154,7 +156,7 @@ COMMIT;
    -
    +
    diff --git a/docs/11-v2-evolucao-schema.html b/docs/11-v2-evolucao-schema.html new file mode 100644 index 0000000..ec55bef --- /dev/null +++ b/docs/11-v2-evolucao-schema.html @@ -0,0 +1,143 @@ + + + + + +ampmInsights · v2.0.0 — Evolução de schema + + + + +
    + +
    +

    v2.0.0 · Passo 1

    +

    Evolução de schema: CVE, CVSS, solução e mais

    +

    Promove os campos "Tier 1" do Tenable e do ServiceNow — hoje fora do banco — a colunas novas em TB_26AI_TECH_V2 e TB_26AI_TECH_CMDB, para que o AI Insight consiga citar CVE, pacote afetado e remediação por ativo.

    + +
    +
    Status: em validação, ainda não roda em produção
    +

    Este capítulo documenta um passo já implementado no script (sql/03_v2_ddl_schema_evolution.sql), mas ainda não confirmado em nenhum ambiente. Não use este passo como procedimento definitivo até a seção 5 (Validação) ter sido de fato executada e conferida.

    +
    + +

    1. Por que isto era necessário

    +

    PRC_26AI_TECH (geração do AI Insight) monta o JSON enviado ao LLM inteiramente a +partir da view V_26AI_TECH, que só expõe as colunas que existem em +TB_26AI_TECH_V2/TB_26AI_TECH_CMDB. 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.

    + +

    2. O que foi adicionado

    +

    Estratégia híbrida: colunas tipadas para os campos que realmente importam para o "plano de +ação" do AI Insight, mais uma coluna RAW_JSON por linha guardando o +export completo — assim nada da planilha se perde, mesmo o que não virou coluna tipada.

    + +
    + + + + +
    TabelaColunas novasDestaque
    TB_26AI_TECH_V2
    (vulnerabilidades Tenable)    		23 colunasDEFINITION_CVE, DEFINITION_SOLUTION, DEFINITION_DESCRIPTION, SOFTWARE_VULNS, DEFINITION_CVSS3_BASE_SCORE, DEFINITION_EPSS_SCORE, CISA_KEV_FLAG, RAW_JSON
    TB_26AI_TECH_CMDB
    (CMDB ServiceNow)    		12 colunasU_FIM_DO_SUPORTE (EOL), ATTESTATION_SCORE/_STATUS, INSTALL_STATUS, RAW_JSON
    +
    + +
    +
    100% aditivo — nenhum DROP
    +

    Todas as colunas são novas e NULLable. 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.

    +
    + +

    3. Script

    +

    Arquivo completo: sql/03_v2_ddl_schema_evolution.sql no repositório. Resumo do que ele faz:

    +
    +
    + sql/03_v2_ddl_schema_evolution.sql (resumo) + +
    + 
    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
+);
    +
    +

    O arquivo real tem, além disso, o ANNOTATIONS("LLM_DESCRIPTION_PT_BR" ...) 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.

    + +

    4. Como rodar

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

    5. Validação

    +

    O próprio script termina com este checkpoint — rode e confira STATUS = 'OK' nas duas linhas:

    +
    +
    + Checkpoint de validação + +
    + 
    SELECT table_name, /* ... */ status, colunas_novas_encontradas
+FROM ( /* ver script completo */ );
+-- Esperado: TB_26AI_TECH_V2 -> OK (23) | TB_26AI_TECH_CMDB -> OK (12)
    +
    + +
    +
    Rollback, se precisar desfazer
    +

    Todas as colunas são novas e nullable — para desfazer, um ALTER TABLE ... DROP COLUMN por coluna adicionada (lista completa no final do script). Nenhum dado existente é afetado ao reverter.

    +
    + +
    +
    +
    + + + diff --git a/docs/12-v2-view-procedure.html b/docs/12-v2-view-procedure.html new file mode 100644 index 0000000..baa909c --- /dev/null +++ b/docs/12-v2-view-procedure.html @@ -0,0 +1,117 @@ + + + + + +ampmInsights · v2.0.0 — View & Procedure + + + + +
    + +
    +

    v2.0.0 · Passo 2

    +

    Expondo os dados novos ao AI Insight

    +

    Ter as colunas novas na tabela não basta — V_26AI_TECH e o json_object de prc_26ai_tech precisam repassar esses campos até o LLM. Este é o passo que faz isso.

    + +
    +
    Status: em validação, ainda não roda em produção
    +

    Documenta um passo já implementado (sql/04_v2_view_procedure_update.sql), mas ainda não confirmado em nenhum ambiente. Depende do capítulo 11 já ter sido aplicado e validado no mesmo ambiente.

    +
    + +

    1. Por que este passo é separado do anterior

    +

    A coluna existir na tabela e o LLM receber o dado são duas coisas diferentes. O AI Insight +("Gerar Insight") lê o registro através de V_26AI_TECH, e o texto que vai pro modelo +é montado campo a campo dentro de um json_object(...) em prc_26ai_tech. +Sem tocar nesses dois objetos, os campos do capítulo 11 +ficariam na tabela mas invisíveis para a IA.

    + +

    2. O que muda

    +
    + + + + +
    ObjetoMudança
    V_26AI_TECH+35 colunas (23 de TB_26AI_TECH_V2 + 12 de TB_26AI_TECH_CMDB). As colunas antigas ficam exatamente como estavam — só houve acréscimo no final da lista. RAW_JSON de cada tabela vira RAW_JSON_TENABLE/RAW_JSON_CMDB na view, para não colidir nome.
    prc_26ai_techSó o json_object do ramo p_source_type = 'VUL' ganhou os campos novos. O ramo 'SYS' (syslog), o texto do prompt, a vetorização, o log e o tratamento de erro ficam idênticos ao script original.
    +
    + +
    +
    O prompt não mudou
    +

    O texto enviado ao LLM (v_pre_prompt) já pedia "recomendações" e "plano de ação" + desde a v1.x — ele só não recebia matéria-prima suficiente para cumprir isso. Este passo resolve + isso enriquecendo os dados, sem precisar reescrever o prompt.

    +
    + +

    3. Como rodar

    +
      +
    1. Mesmo ambiente/schema (AMPMINSIGHTS) onde o capítulo 11 já foi validado — a view não compila sem as colunas de lá existirem.
      2. +
    2. Cole e rode sql/04_v2_view_procedure_update.sql inteiro, de uma vez.
      3. +
    + +

    4. Validação

    +

    Dois checkpoints, sem gastar nenhuma chamada de LLM:

    +
    +
    + 1) Compilação dos objetos + +
    + 
    SELECT object_name, object_type, status
+FROM user_objects
+WHERE object_name IN ('V_26AI_TECH', 'PRC_26AI_TECH')
+ORDER BY object_name;
+-- Esperado: as duas linhas com STATUS = 'VALID'.
    +
    +
    +
    + 2) Os campos novos chegam pela view + +
    + 
    SELECT cid, asset_name, definition_cve, definition_solution,
+       sistema_operacional, u_fim_do_suporte
+FROM V_26AI_TECH
+FETCH FIRST 3 ROWS ONLY;
+-- Pode vir tudo NULL se ainda não recarregou dado com o Tenable/ServiceNow
+-- novos (normal) - o que importa aqui é a coluna existir e ser lida.
    +
    +

    Um teste completo de ponta a ponta (o AI Insight citando CVE/pacote/remediação de fato) só faz +sentido depois do capítulo 13 (perfis de carga novos, ainda não publicado) — ver +TASKS.md no repositório para o board de tarefas atualizado.

    + +
    +
    Rollback, se precisar desfazer
    +

    Rode de novo o CREATE OR REPLACE VIEW/PROCEDURE originais (sql/01_ampminsights_db_setup.sql, trechos V_26AI_TECH e prc_26ai_tech) — como são CREATE OR REPLACE, isso restaura o comportamento anterior sem afetar dado nenhum (view e procedure não guardam estado).

    +
    + +
    +
    +
    + + + diff --git a/docs/index.html b/docs/index.html index 6a7ecf0..d5adf6c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -27,6 +27,8 @@
  • 8Glossário & roadmap
  • 9Operação & observabilidade
  • 10Carga: CMDB & Vulnerabilidades
    • +
  • 11v2.0.0 — Evolução de schema
    • +
  • 12v2.0.0 — View & Procedure
    • Vulnerability & Audit AI Insights