ampmInsights/docs/13-v2-perfis-carga.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 — Perfis de carga</title>
<meta name="description" content="Passo 3 da v2.0.0: novos perfis de carga (DL_TECH_VULNERABILIDADE_V3, DL_TECH_CMDB_V2) para alimentar os campos Tier-1 novos.">
<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="" 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>
<li><a class="active" href="13-v2-perfis-carga.html"><span class="step-no">13</span>v2.0.0 — Perfis de carga</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 3</p>
    <h1>Perfis de carga: DL_TECH_VULNERABILIDADE_V3 e DL_TECH_CMDB_V2</h1>
    <p class="lede">Novos perfis de carga do APEX para alimentar as colunas Tier-1 criadas no <a href="11-v2-evolucao-schema.html">capítulo 11</a> — sem sobrescrever <code>DL_TECH_VULNERABILIDADE_V2</code>/<code>DL_TECH_CMDB_V1</code>, que continuam servindo a v1.3.0 em produção.</p>

<div class="callout warning">
  <div class="callout-title">Status: mapeamento confirmado contra export real, perfis ainda não criados</div>
  <p>O mapeamento abaixo foi conferido campo a campo contra um export real de Tenable/ServiceNow
  (arquivos em <code>ampmInsights_V1_Cliente/Artefatos/</code>, só linhas <code>AM...</code>) — não
  é suposição. O que falta é a parte que <strong>não é scriptável</strong>: criar os dois perfis de
  carga de fato no App Builder (Shared Components → Data Load Definitions), seguindo o roteiro da
  seção 4.</p>
</div>

<h2>1. Por que perfis novos, não sobrescrever os antigos</h2>
<p>Mesma regra já usada na v1.3.0 (ver <a href="10-carga-cmdb-vulnerabilidades.html">capítulo 10</a>):
não alterar <code>DL_TECH_VULNERABILIDADE_V2</code>/<code>DL_TECH_CMDB_V1</code> até o fluxo novo
estar validado, para não quebrar a carga que já roda em produção no cliente. Os perfis novos são
<strong>adicionais</strong> às colunas de sempre — não removem nenhum mapeamento existente.</p>

<h2>2. RAW_JSON continua pendente (de propósito)</h2>
<p>Este passo não popula <code>RAW_JSON</code>. O motivo: o Data Load do APEX só leva pra tabela
as colunas que ele mapeia — os campos Tier 2/3 do export (que nunca ganharam coluna tipada) não
chegam nem perto da tabela por este caminho. Popular <code>RAW_JSON</code> de verdade (a linha
completa do export, todas as ~99/41 colunas) depende da tabela de staging (próximo item da Fase 1
no <code>TASKS.md</code>) — lá sim a linha inteira do CSV existe antes de qualquer filtro de
coluna, e um `JSON_OBJECT(*)` sobre o staging resolve isso corretamente.</p>

<h2>3. Mapeamento — DL_TECH_CMDB_V2 (12 colunas novas)</h2>
<p>Coluna de origem exatamente como aparece no export ServiceNow real:</p>
<div class="table-wrap">
<table>
<tr><th>Coluna no export ServiceNow</th><th>Coluna destino (v2.0.0)</th><th>Observação</th></tr>
<tr><td><code>install_status</code></td><td><code>INSTALL_STATUS</code></td><td>texto direto</td></tr>
<tr><td><code>life_cycle_stage_status</code></td><td><code>LIFE_CYCLE_STAGE_STATUS</code></td><td>texto direto</td></tr>
<tr><td><code>assigned_to</code> (ou <code>assigned</code>, se <code>assigned_to</code> vier vazio)</td><td><code>ASSIGNED_TO</code></td><td>nos ativos AMPM amostrados, os dois vinham vazios com frequência — não é bug, é lacuna do cadastro de origem</td></tr>
<tr><td><code>attestation_score</code></td><td><code>ATTESTATION_SCORE</code></td><td>numérico direto</td></tr>
<tr><td><code>attestation_status</code></td><td><code>ATTESTATION_STATUS</code></td><td>texto direto (ex.: "Ainda não revisada")</td></tr>
<tr><td><code>attested</code></td><td><code>ATTESTED_FLAG</code></td><td>vem como <code>Verdadeiro(a)</code>/<code>Falso(a)</code> — mesma convenção já usada em <code>SOX</code>/<code>COFRE</code>/<code>TENABLE</code>/<code>SIEM</code> no capítulo 10; converter para 1/0</td></tr>
<tr><td><code>attested_by</code></td><td><code>ATTESTED_BY</code></td><td>texto direto</td></tr>
<tr><td><code>u_fim_do_suporte</code></td><td><code>U_FIM_DO_SUPORTE</code></td><td>formato confirmado: <code>DD-MM-YYYY</code> (ex.: <code>01-07-2029</code>) — configurar a máscara de data do Data Load Wizard como <code>DD-MM-YYYY</code></td></tr>
<tr><td><code>location</code></td><td><code>LOCATION</code></td><td>texto direto</td></tr>
<tr><td><code>asset_tag</code></td><td><code>ASSET_TAG</code></td><td>texto direto</td></tr>
<tr><td><code>u_server_role</code></td><td><code>U_SERVER_ROLE</code></td><td>texto direto</td></tr>
</table>
</div>

<h2>4. Mapeamento — DL_TECH_VULNERABILIDADE_V3 (23 colunas novas)</h2>
<div class="table-wrap">
<table>
<tr><th>Coluna no export Tenable</th><th>Coluna destino (v2.0.0)</th><th>Observação</th></tr>
<tr><td><code>definition.cve</code></td><td><code>DEFINITION_CVE</code></td><td>lista separada por vírgula, texto direto</td></tr>
<tr><td><code>definition.description</code></td><td><code>DEFINITION_DESCRIPTION</code></td><td>texto direto (CLOB)</td></tr>
<tr><td><code>definition.solution</code></td><td><code>DEFINITION_SOLUTION</code></td><td>texto direto (CLOB)</td></tr>
<tr><td><code>definition.synopsis</code></td><td><code>DEFINITION_SYNOPSIS</code></td><td>texto direto</td></tr>
<tr><td><code>software_vulns</code></td><td><code>SOFTWARE_VULNS</code></td><td>texto bruto (CLOB) — <strong>não</strong> fazer parsing agora, formato não é JSON válido (ver <a href="../../ANALISE_DADOS_v1.4.0_gap_schema.md">gap analysis</a> seção 2.4)</td></tr>
<tr><td><code>definition.cvss3.base_score</code></td><td><code>DEFINITION_CVSS3_BASE_SCORE</code></td><td>numérico direto</td></tr>
<tr><td><code>definition.cvss3.base_vector</code></td><td><code>DEFINITION_CVSS3_BASE_VECTOR</code></td><td>texto direto</td></tr>
<tr><td><code>definition.cpe</code></td><td><code>DEFINITION_CPE</code></td><td>texto direto</td></tr>
<tr><td><code>definition.epss.score</code></td><td><code>DEFINITION_EPSS_SCORE</code></td><td>numérico direto</td></tr>
<tr><td><code>definition.vpr.drivers_on_cisa_kev</code></td><td><code>CISA_KEV_FLAG</code></td><td>confirmado: vem como texto <code>true</code>/<code>false</code> (não aninhado) — converter para 1/0</td></tr>
<tr><td><code>definition.exploited_by_malware</code></td><td><code>EXPLOITED_BY_MALWARE_FLAG</code></td><td>confirmado: texto <code>true</code>/<code>false</code> — converter para 1/0</td></tr>
<tr><td><code>definition.exploited_by_nessus</code></td><td><code>EXPLOITED_BY_NESSUS_FLAG</code></td><td>confirmado: texto <code>true</code>/<code>false</code> — converter para 1/0</td></tr>
<tr><td><code>port</code></td><td><code>PORT</code></td><td>numérico direto</td></tr>
<tr><td><code>asset.operating_system</code></td><td><code>ASSET_OPERATING_SYSTEM</code></td><td>texto direto; <code>asset.operating_systems</code> (plural) tem o mesmo conteúdo nos exemplos vistos — usar o singular como principal</td></tr>
<tr><td><code>last_fixed</code></td><td><code>LAST_FIXED</code></td><td>data/timestamp direto</td></tr>
<tr><td><code>time_to_fix</code></td><td><code>TIME_TO_FIX</code></td><td>numérico direto</td></tr>
<tr><td><code>vuln_sla_date</code></td><td><code>VULN_SLA_DATE</code></td><td>data/timestamp direto</td></tr>
<tr><td><code>definition.patch_published</code></td><td><code>PATCH_PUBLISHED</code></td><td><strong>correção</strong>: o nome real no export tem o prefixo <code>definition.</code>, diferente do que constava antes</td></tr>
<tr><td><code>definition.vulnerability_published</code></td><td><code>VULNERABILITY_PUBLISHED</code></td><td><strong>correção</strong>: idem, prefixo <code>definition.</code></td></tr>
<tr><td><code>source</code></td><td><code>SOURCE_SCAN</code></td><td>texto direto</td></tr>
<tr><td><code>scan.id</code></td><td><code>SCAN_ID</code></td><td>texto direto</td></tr>
<tr><td><code>scan.target</code></td><td><code>SCAN_TARGET</code></td><td>texto direto</td></tr>
</table>
</div>

<h2>5. Como criar os perfis — e por que não é um script SQL</h2>
<div class="callout danger">
  <div class="callout-title">Por que isto não vira um .sql como os Passos 1 e 2</div>
  <p>As definições de carga (<code>DL_TECH_CMDB_V1</code> e as duas de vulnerabilidades) já existem
  hoje dentro de <code>sql/02_ampminsights_apex_app.sql</code>, criadas via
  <code>wwv_flow_imp_shared.create_data_profile</code>/<code>.create_data_profile_col</code>/
  <code>.create_load_table</code> — a API interna que o próprio export/import do APEX usa. Escrever
  essas chamadas à mão, fora do contexto de um import completo (com os IDs que só o APEX gera
  corretamente), arrisca corromper os Shared Components da Application 100. Por isso este passo é
  feito uma vez no App Builder e depois <strong>capturado automaticamente</strong> num novo export
  completo (seção 7) — o cliente nunca toca em Data Load Definitions manualmente, só importa esse
  arquivo, exatamente como já faz hoje em cada release.</p>
</div>

<div class="callout warning">
  <div class="callout-title">Passo a passo confirmado tela a tela — sem adivinhação</div>
  <p>A versão anterior deste capítulo sugeria "subir um arquivo de amostra para detectar colunas
  automaticamente" — essa tela <strong>não existe</strong> neste wizard, era um chute meu, não
  confirmado contra o ambiente real. O roteiro abaixo segue exatamente as telas reais, uma a uma.
  Onde uma tela ainda não foi vista/confirmada, isso está marcado explicitamente — não vou
  documentar o que não vi.</p>
</div>

<ol>
  <li>App Builder → Application 100 → <strong>Shared Components</strong> → <strong>Data Load Definitions</strong>.</li>
  <li>Clique no botão verde <strong>Create</strong> (canto superior direito).</li>
  <li><strong>Tela "Create Data Load - Method"</strong>: marque <strong>"As copy of an existing Data Load Definition"</strong> (não "From scratch") → <strong>Next</strong>.</li>
  <li><strong>Tela "Create Data Load - Application"</strong>: no campo <strong>Copy From Application</strong>, selecione <strong>"100 ampminsights"</strong> (a própria aplicação) → <strong>Next</strong>.</li>
  <li><strong>Tela "Create Data Load - As Copy"</strong>: aparece uma tabela com as 3 definições que já existem (<code>DL_TECH_CMDB_V1</code>, <code>DL_TECH_VULNERABILIDADES</code>, <code>DL_TECH_VULNERABILIDADE_V2</code>), cada uma com um campo <strong>To Name</strong> e um dropdown <strong>Action</strong> (No/Yes/Copy and Subscribe). Faça, nesta mesma tela, as duas cópias de uma vez:
    <ul>
      <li>Linha <code>DL_TECH_CMDB_V1</code>: mude <strong>Action</strong> para <strong>Yes</strong>; no campo <strong>To Name</strong>, apague "Copy of DL_TECH_CMDB_V1" e escreva <code>DL_TECH_CMDB_V2</code>.</li>
      <li>Linha <code>DL_TECH_VULNERABILIDADE_V2</code>: mude <strong>Action</strong> para <strong>Yes</strong>; no campo <strong>To Name</strong>, escreva <code>DL_TECH_VULNERABILIDADE_V3</code>.</li>
      <li>Linha <code>DL_TECH_VULNERABILIDADES</code>: deixe <strong>Action = No</strong> (essa não faz parte do v2.0.0).</li>
    </ul>
  </li>
  <li>Clique em <strong>Copy Data Load Definition</strong> (canto inferior direito).</li>
</ol>

<div class="callout danger">
  <div class="callout-title">Pegadinha confirmada: o campo "To Name" da tela de cópia é ignorado</div>
  <p>Apesar de preencher "To Name" com os nomes certos na tela "As Copy", as cópias nasceram com o
  nome padrão (<code>Copy of DL_TECH_CMDB_V1</code>, <code>Copy of DL_TECH_VULNERABILIDADES</code>,
  <code>Copy of DL_TECH_VULNERABILIDADE_V2</code>) — <strong>as três</strong>, mesmo a que estava
  marcada <code>No</code>. Não tem problema: renomeia e apaga depois, direto na lista (próximos
  passos). Não perca tempo tentando fazer o "To Name" funcionar na hora da cópia.</p>
</div>

<ol start="7">
  <li>De volta à lista <strong>Data Load Definitions</strong>, mude pra visão em tabela (ícone ao lado da grade) pra ver os nomes completos e a coluna <strong>Target Name</strong> de cada cópia — assim dá pra confirmar qual é qual antes de mexer (compare com a tabela abaixo).</li>
</ol>
<div class="table-wrap">
<table>
<tr><th>Nome logo após copiar</th><th>Target Name (tabela destino)</th><th>O que fazer</th></tr>
<tr><td><code>Copy of DL_TECH_CMDB_V1</code></td><td><code>TB_26AI_TECH_CMDB</code></td><td>✅ renomear para <code>DL_TECH_CMDB_V2</code></td></tr>
<tr><td><code>Copy of DL_TECH_VULNERABILIDADES</code></td><td><code>TB_26AI_TECH</code></td><td>❌ apagar — é a tabela legada (<code>DL_TECH_VULNERABILIDADES</code> alimenta <code>TB_26AI_TECH</code>, não <code>TB_26AI_TECH_V2</code>)</td></tr>
<tr><td><code>Copy of DL_TECH_VULNERABILIDADE_V2</code></td><td><code>TB_26AI_TECH_V2</code></td><td>✅ renomear para <code>DL_TECH_VULNERABILIDADE_V3</code></td></tr>
</table>
</div>
<ol start="8">
  <li>Abra a cópia indesejada (<code>Copy of DL_TECH_VULNERABILIDADES</code>) → botão <strong>Delete</strong> (topo da tela).</li>
  <li>Abra <code>Copy of DL_TECH_CMDB_V1</code> → campo <strong>Name</strong> (e <strong>Static ID</strong>, que atualiza junto): troque para <code>DL_TECH_CMDB_V2</code> → <strong>Apply Changes</strong>. Todos os outros campos (Target Type, Table Owner, Table Name, Loading Method, Commit Interval, Error Handling, Data Profile com as 16 colunas originais) ficam exatamente como vieram da cópia — não mexer.</li>
  <li>Abra <code>Copy of DL_TECH_VULNERABILIDADE_V2</code> → mesmo processo: <strong>Name</strong>/<strong>Static ID</strong> → <code>DL_TECH_VULNERABILIDADE_V3</code> → <strong>Apply Changes</strong>.</li>
</ol>
<p><strong>Confirmado:</strong> a lista final tem 5 definições — as 3 originais intactas
(<code>DL_TECH_CMDB_V1</code>, <code>DL_TECH_VULNERABILIDADES</code>,
<code>DL_TECH_VULNERABILIDADE_V2</code>) + as 2 novas já renomeadas
(<code>DL_TECH_CMDB_V2</code> → <code>TB_26AI_TECH_CMDB</code>,
<code>DL_TECH_VULNERABILIDADE_V3</code> → <code>TB_26AI_TECH_V2</code>).</p>

<div class="callout info">
  <div class="callout-title">A partir daqui, ainda não confirmado — preciso da próxima tela</div>
  <p>O próximo passo é abrir <code>DL_TECH_CMDB_V2</code> (ou a de vulnerabilidades) e clicar em
  <strong>Edit Data Profile</strong> pra adicionar as colunas novas da seção 3/4 — ainda não vi
  essa tela. Assim que tiver o print, completo o roteiro.</p>
</div>

<p>Depois de ter as colunas novas adicionadas na cópia (roteiro a completar), os ajustes que já sei
que vão ser necessários, pela tabela da seção 3/4:</p>
<ul>
  <li><code>DEFINITION_CVSS3_BASE_SCORE</code>, <code>DEFINITION_EPSS_SCORE</code>, <code>PORT</code>, <code>TIME_TO_FIX</code>, <code>ATTESTATION_SCORE</code> → tipo <code>NUMBER</code>.</li>
  <li><code>LAST_FIXED</code>, <code>VULN_SLA_DATE</code>, <code>PATCH_PUBLISHED</code>, <code>VULNERABILITY_PUBLISHED</code> → data/timestamp.</li>
  <li><code>U_FIM_DO_SUPORTE</code> → data, máscara <code>DD-MM-YYYY</code>.</li>
  <li><code>ATTESTED_FLAG</code>, <code>CISA_KEV_FLAG</code>, <code>EXPLOITED_BY_MALWARE_FLAG</code>, <code>EXPLOITED_BY_NESSUS_FLAG</code> → transformação de valor <code>Verdadeiro(a)/true → 1</code>, <code>Falso(a)/false → 0</code> (mesma convenção já usada em <code>SOX</code>/<code>COFRE</code>/<code>TENABLE</code>/<code>SIEM</code>).</li>
</ul>
<p>Os arquivos <code>templates/sample_DL_TECH_CMDB_V2.xlsx</code> e
<code>templates/sample_DL_TECH_VULNERABILIDADE_V3.xlsx</code> continuam úteis, só que num momento
diferente do que eu disse antes: não servem pra criar o perfil, servem como planilha de teste (só
o cabeçalho — adicione 5-10 linhas de ativos <code>AM...</code> com dado real antes de subir) pra
validar a carga depois que o perfil estiver pronto, na seção 6.</p>

<h2>6. Como validar</h2>
<p>Depois de rodar uma carga de teste pequena:</p>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">Confirma que os campos novos vieram preenchidos</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">SELECT asset_name, definition_cve, definition_cvss3_base_score,
       cisa_kev_flag, exploited_by_malware_flag
FROM V_26AI_TECH
WHERE definition_cve IS NOT NULL
FETCH FIRST 5 ROWS ONLY;</code></pre>
</div>
<p>Se vier linha com <code>DEFINITION_CVE</code> preenchido e <code>CISA_KEV_FLAG</code>/
<code>EXPLOITED_BY_MALWARE_FLAG</code> como <code>1</code> ou <code>0</code> (nunca texto), os
perfis estão funcionando.</p>

<h2>7. Como isso chega ao cliente (sem ele tocar em App Builder)</h2>
<p>Depois dos perfis criados e testados (seções 5 e 6), a captura definitiva é um novo
<strong>export completo</strong> da Application 100 (App Builder → Application 100 → ícone de
exportar/download → SQL Script) — isso gera um <code>02_ampminsights_apex_app.sql</code> novo, com
os dois perfis novos já embutidos com os IDs corretos gerados pelo próprio APEX. Esse arquivo
substitui o atual no próximo release (mesmo fluxo já usado em toda entrega anterior — zip →
bucket → PAR, ver o processo de release do projeto). O cliente só importa esse arquivo via
App Builder → Import — um wizard guiado, não precisa entender Data Load Definitions.</p>
<div class="callout info">
  <div class="callout-title">Você faz isso uma vez; o cliente nunca faz</div>
  <p>As seções 5-6 (criar e testar os perfis) são trabalho seu, num ambiente com acesso ao App
  Builder. O cliente recebe só o resultado — o export completo atualizado — e importa como já
  importa qualquer outra versão da aplicação.</p>
</div>

    <div class="pillnav"><a class="prev" href="12-v2-view-procedure.html">&larr; v2.0.0 — View & Procedure</a></div>
  </main>
</div>
<script src="assets/main.js"></script>
</body>
</html>