@pathbit/agentdevkit 0.0.10 → 0.0.12

package/.pbai4devs/scripts/verificar-recursos/SCRIPT.mjs

@@ -2,9 +2,12 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
 import { buildCatalog } from '../lib/catalog.mjs';
 import { isGeneratedOutput } from '../lib/gitignore.mjs';
+import { canonicalEntrypoint, extractManagedBlock, managedBlockDigest } from '../lib/managed-content.mjs';
+import { extractTomlManagedBlock, tomlManagedBlockDigest } from '../lib/managed-toml.mjs';
 
 const fail = message => { throw new Error(message); };
 const normalize = value => value.split(sep).join('/');
@@ -29,28 +32,38 @@ function checkedPath(root, path) {
 
 function ownership(root) {
   const file = checkedPath(root, '.pbai4devs/estado/agentdevkit.json');
-  if (!checkedStat(root, file)) return null;
+  const derivedFile = checkedPath(root, '.pbai4devs/estado/derived.json');
+  if (!checkedStat(root, file) && !checkedStat(root, derivedFile)) return null;
   const readState = location => {
     try { return JSON.parse(readFileSync(location, 'utf8')); }
     catch { fail(`Estado invalido: ${normalize(relative(root, location))}`); }
   };
-  const state = readState(file);
+  const state = checkedStat(root, file) ? readState(file) : { schemaVersion: 1, files: {}, blocks: {} };
   const validMap = value => value && typeof value === 'object' && !Array.isArray(value)
     && Object.values(value).every(hash => typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash));
   if (state?.schemaVersion !== 1 || !validMap(state.files) || !validMap(state.blocks)) fail('Estado de propriedade invalido.');
   const files = { ...state.files };
-  const derivedFile = checkedPath(root, '.pbai4devs/estado/derived.json');
+  const blocks = { ...state.blocks };
   if (checkedStat(root, derivedFile)) {
     const derived = readState(derivedFile);
-    if (derived?.schemaVersion !== 1 || !validMap(derived.entries) || Object.keys(derived.entries).some(path => !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(path))
+    if (derived?.schemaVersion !== 1 || !validMap(derived.entries) || Object.keys(derived.entries).some(path => !canonicalEntrypoint(path))
+      || !validMap(derived.files ?? {}) || !validMap(derived.blocks ?? {})
+      || !Array.isArray(derived.removedBlocks ?? []) || (derived.removedBlocks ?? []).some(path => typeof path !== 'string')
       || !validMap(derived.outputs ?? {}) || Object.keys(derived.outputs ?? {}).some(path => !/^\.[a-z0-9][a-z0-9-]*\/(?:skills|rules|agents)\.json$/.test(path))) fail('Estado de entradas derivadas invalido.');
-    Object.assign(files, derived.entries, derived.outputs);
+    Object.assign(files, derived.entries, derived.outputs, derived.files);
+    for (const [path, hash] of Object.entries({ ...derived.entries, ...derived.files })) {
+      const location = checkedPath(root, path);
+      if (checkedStat(root, location)?.isFile() && createHash('sha256').update(readFileSync(location)).digest('hex') === hash) delete blocks[path];
+    }
+    for (const path of derived.removedBlocks ?? []) { checkedPath(root, path); delete blocks[path]; }
+    Object.assign(blocks, derived.blocks);
   }
-  for (const path of [...Object.keys(files), ...Object.keys(state.blocks)]) {
+  for (const path of Object.keys(blocks)) delete files[path];
+  for (const path of [...Object.keys(files), ...Object.keys(blocks)]) {
     const location = checkedPath(root, path);
     if (!checkedStat(root, location)?.isFile()) fail(`Arquivo gerenciado ausente: ${path}`);
   }
-  return { files, blocks: state.blocks };
+  return { files, blocks };
 }
 
 export function registryRoots(root) {
@@ -151,6 +164,28 @@ export function localLinkTargets(text) {
   }).filter(Boolean);
 }
 
+export function checkManagedBlocks(root, blocks) {
+  for (const [path, expected] of Object.entries(blocks)) {
+    const toml = extname(path).toLowerCase() === '.toml';
+    if (!toml && !['.md', '.mdc'].includes(extname(path).toLowerCase())) continue;
+    const file = checkedPath(root, path), bytes = readFileSync(file);
+    if ((toml ? tomlManagedBlockDigest(bytes) : managedBlockDigest(bytes)) !== expected) fail(`Bloco AgentDevKit alterado ou ausente: ${path}`);
+    const block = toml ? extractTomlManagedBlock(bytes) : extractManagedBlock(bytes);
+    const imports = [...block.matchAll(/^@(?:\{([^}\r\n]+)\}|([^\r\n]+))$/gm)]
+      .filter(match => !match[2]?.startsWith('['))
+      .map(match => ({ target: match[1] || match[2], base: match[1] ? root : dirname(file) }));
+    for (const { target, base } of [...localLinkTargets(block).map(target => ({ target, base: dirname(file) })), ...imports]) {
+      const destination = resolve(base, target), local = normalize(relative(root, destination));
+      if (!local || isAbsolute(local) || local === '..' || local.startsWith('../')) fail(`Referencia fora do projeto: ${path}`);
+      if (canonicalEntrypoint(local)) {
+        // The user's root entry may be an existing link; do not follow it.
+        const item = lstatSync(destination);
+        if (!item.isFile() && !item.isSymbolicLink()) fail(`Referencia indisponivel: ${path}`);
+      } else if (!checkedStat(root, checkedPath(root, local))?.isFile()) fail(`Referencia indisponivel: ${path}`);
+    }
+  }
+}
+
 export function checkMarkdown(root, files, { virtualPaths = new Set() } = {}) {
   for (const file of files) {
     const label = normalize(relative(root, file));
@@ -237,6 +272,7 @@ export function verifyResources({ root = projectRoot, sourceOnly = false, synchr
   const files = collectMarkdown(root, registry, { installed });
   const virtualPaths = new Set(sourceOnly ? [...built.outputs.keys(), '.pbai4devs/espelhos.conf'] : []);
   checkMarkdown(root, files, { virtualPaths });
+  if (installed) checkManagedBlocks(root, installed.blocks);
   checkResourceReferences(root, files);
   checkAgentExtras(root, registry.agents, { installed });
   return { files, messages: [...lint(root, files), 'recursos=passed'] };

package/.pbai4devs/scripts/verificar-recursos/tests/TEST.mjs

@@ -162,10 +162,11 @@ test('instalação confere entradas derivadas sem aplicar lint a blocos humanos'
   const contents = document('# Entrada gerada\n');
   file('GEMINI.md', contents);
   file('.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: { 'GEMINI.md': createHash('sha256').update(contents).digest('hex') } }));
-  file('AGENTS.md', '# Instruções humanas sem frontmatter\n\n<!-- BEGIN AGENTDEVKIT -->\nLeia as fontes.\n<!-- END AGENTDEVKIT -->\n');
+  const block = '<!-- BEGIN AGENTDEVKIT -->\nLeia as fontes.\n<!-- END AGENTDEVKIT -->';
+  file('AGENTS.md', `# Instruções humanas sem frontmatter\n\n${block}\n`);
   const statePath = join(root, '.pbai4devs/estado/agentdevkit.json');
   const state = JSON.parse(readFileSync(statePath, 'utf8'));
-  state.blocks['AGENTS.md'] = createHash('sha256').update('bloco registrado').digest('hex');
+  state.blocks['AGENTS.md'] = createHash('sha256').update(block).digest('hex');
   state.files['.pbai4devs/skills/exemplo/SKILL.md'] = createHash('sha256').update('fonte anterior').digest('hex');
   writeFileSync(statePath, JSON.stringify(state));
   const result = verify(root);

package/.pbai4devs/skills/README.md

@@ -4,13 +4,19 @@ description: Finalidade e criação de skills compartilhadas.
 
 # Skills
 
-São procedimentos reutilizáveis, organizados em `git`, `projeto`, `produto` e
-`specs`. Cada skill usa `<grupo>/<nome>/SKILL.md` com nome e descrição no YAML.
+São procedimentos reutilizáveis, organizados por assunto. Cada skill usa
+`<grupo>/<nome>/SKILL.md` com nome e descrição no YAML. A skill orienta decisões;
+o agente responsável pode acionar comandos, scripts e outros perfis conforme
+as capacidades do cliente.
 
 - `git`: operações de versionamento.
 - `projeto`: configuração, criação e manutenção dos recursos.
 - `produto`: PRD, experiência e design técnico.
 - `specs`: especificações, roadmap e implementação.
+- `seguranca`: [revisão](seguranca/revisar-seguranca/SKILL.md),
+  [autorização](seguranca/revisar-autorizacao/SKILL.md),
+  [ameaças](seguranca/modelar-ameacas/SKILL.md) e
+  [correção](seguranca/corrigir-vulnerabilidade/SKILL.md).
 
 Use `criar-skill` quando uma tarefa recorrente precisar de decisões próprias;
 use `criar-recurso` para encontrar um fluxo existente antes de criar outro.
@@ -21,4 +27,6 @@ Use [proximos-passos](projeto/proximos-passos/SKILL.md) para orientar a
 continuidade conforme a fase e as pendências reais.
 
 O [guia compartilhado](../INSTRUCTIONS.md) orienta o uso das skills.
+As skills de segurança integram a instalação do kit; os scanners exigem
+[preparo explícito](../commands/preparar-seguranca/COMMAND.md).
 Ao alterar o inventário, sincronize os índices e apontamentos locais.

package/.pbai4devs/skills/projeto/preparar-ferramentas/SKILL.md

@@ -24,7 +24,8 @@ instalador compartilhado.
 No preparo inicial, execute `preparar-ferramentas setup` pelo seletor:
 instala e verifica todas as ferramentas compatíveis, sem atualizar as saudáveis.
 Aceita seleção por nome/grupo; relate falhas e itens não aplicáveis.
-Para buscar versões novas, `update` consulta `latest` oficial.
+Para npm, `update` consulta `latest` oficial; ferramentas nativas de segurança
+seguem o pin revisado em `TOOL.json`, sem atualização silenciosa para outro binário.
 `install` reutiliza uma instalação saudável; `check` verifica sem rede;
 `info` mostra a configuração; `run <nome> [argumentos]` executa sem instalar.
 Sem ação, mostre ajuda. Não interprete ausência de argumentos como instalação.
@@ -41,6 +42,9 @@ Em `skills`, use `find` ou `add <origem> --list`; incorporações passam por
 O shell virtual não substitui testes reais. Só ative proxy, certificados,
 serviços ou gravação quando necessários à tarefa e com dependências preparadas.
 
+Para segurança, use [preparar-seguranca](../../../commands/preparar-seguranca/COMMAND.md).
+Preparar o CLI e atualizar bases são operações separadas da análise offline.
+
 Antes de usar agent-desktop, leia `skills get desktop` e `skills get platform`
 da versão instalada e confira `status`. Para agent-browser, leia
 `skills get core` e `--help` da versão instalada e

package/.pbai4devs/skills/seguranca/REFERENCE.md

@@ -0,0 +1,104 @@
+---
+description: Segurança com scanners locais, triagem e provas de controles.
+---
+
+# Segurança local
+
+A instalação do kit inclui skills, regras, comandos e perfis de segurança.
+Os scanners são preparados por uma ação explícita; os arquivos de instrução
+não iniciam auditorias, serviços ou downloads em segundo plano.
+
+## Como os componentes trabalham juntos
+
+O comando [auditar-seguranca][audit] organiza o trabalho. A
+[skill de revisão][review] define como analisar e o [auditor][auditor] faz a
+triagem contextual. O script executa ferramentas e produz evidências; as
+[regras][rules] orientam todas as etapas. Veja o [catálogo de comandos](../../commands/README.md).
+
+| Ferramenta | Pergunta que ajuda a responder |
+| --- | --- |
+| [Gitleaks][gitleaks] | Há indícios de segredos nos arquivos analisados? |
+| [OSV-Scanner][osv] | A base local conhece falhas nas versões das dependências? |
+| [Opengrep][opengrep] | O código corresponde aos padrões das regras locais? |
+
+As ferramentas executam localmente e não exigem conta ou assinatura.
+Versões revisadas e suas origens ficam nos `TOOL.json`. Downloads públicos de
+binários e bases são separados da análise. A política do cliente/modelo de IA
+continua sendo própria; não coloque valores secretos no contexto da conversa.
+
+## Preparar e executar
+
+Use Node.js 24+ e o projeto autorizado. O fluxo de
+[preparar-seguranca][prepare] instala os scanners e confere seu funcionamento:
+
+```console
+node .pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs setup security
+```
+
+Para dependências, baixe a base dos ecossistemas realmente utilizados. Exemplo
+para npm; substitua por `Go` ou pela seleção suportada que corresponda ao projeto:
+
+```console
+node .pbai4devs/scripts/auditar-seguranca/SCRIPT.mjs update-data --ecosystems npm
+node .pbai4devs/scripts/auditar-seguranca/SCRIPT.mjs check
+node .pbai4devs/scripts/auditar-seguranca/SCRIPT.mjs run
+```
+
+`run` usa os três checks: `secrets`, `dependencies` e `sast`. Para limitar,
+use [verificar-segredos][secrets] ou [verificar-dependencias][dependencies].
+A análise usa dados locais; base ausente não autoriza enviar o projeto a uma API.
+Confira no relatório a versão da ferramenta, a base e o escopo efetivamente lido.
+
+## O que ainda precisa ser provado
+
+O [artigo sobre falhas recorrentes][article] motiva os temas abaixo. As
+verificações dependem da arquitetura e não equivalem a uma certificação.
+
+| Tema | Prova necessária no projeto |
+| --- | --- |
+| Autorização no servidor | API direta recusa visitante e papel insuficiente. |
+| Acesso por identificador | Usuário A não lê ou altera o recurso de B. |
+| Isolamento dos dados | Policies/RLS ou Security Rules restringem o acesso. |
+| Segredos | Credenciais privadas não chegam a fontes, bundles ou logs. |
+| Entradas e abuso | Testes de validação, saída, upload e limites do fluxo. |
+
+RLS é um controle de PostgreSQL usado pelo Supabase; Firebase tem Security Rules.
+SDKs privilegiados podem atravessar esses controles e precisam de autorização
+no servidor. Esconder um botão de administrador não protege a API.
+
+Use [revisar-autorizacao][authorization] com identidades sintéticas distintas,
+testes negativos e dados locais. Para entradas, prefira consultas parametrizadas,
+codificação de saída por contexto e limites de upload; sanitização genérica não
+resolve todos os casos. Teste a interface no navegador quando ela existir.
+Sem aplicação executável, registre essas provas como **não verificadas**.
+
+## Interpretar e corrigir
+
+O runner retorna `0` sem achados, `1` com achados e `2` em falha ou verificação
+incompleta. Leia o estado de cada check: não aplicável e não executado não
+significam aprovado. Regras locais e formatos suportados limitam a cobertura.
+
+O relatório fica em `.agent-tests/security/<execucao>/report.json`, sem valores
+secretos. O auditor distingue suspeitas, falhas confirmadas e falsos positivos.
+Use [modelar-ameacas][threats] para novos fluxos e
+[corrigir-vulnerabilidade][fix] para reparar a causa com teste de regressão.
+Uma credencial real exposta precisa de revogação pelo responsável; não a teste
+contra serviços externos. Feche a entrega com [revisão independente][gate].
+
+[Skills](../README.md) · [Ferramentas](../../tools/README.md)
+
+[audit]: ../../commands/auditar-seguranca/COMMAND.md
+[review]: ../../skills/seguranca/revisar-seguranca/SKILL.md
+[auditor]: ../../agents/auditor-seguranca/AGENT.md
+[rules]: ../../rules/seguranca/RULE.md
+[gitleaks]: ../../tools/gitleaks/README.md
+[osv]: ../../tools/osv-scanner/README.md
+[opengrep]: ../../tools/opengrep/README.md
+[prepare]: ../../commands/preparar-seguranca/COMMAND.md
+[secrets]: ../../commands/verificar-segredos/COMMAND.md
+[dependencies]: ../../commands/verificar-dependencias/COMMAND.md
+[authorization]: ../../skills/seguranca/revisar-autorizacao/SKILL.md
+[threats]: ../../skills/seguranca/modelar-ameacas/SKILL.md
+[fix]: ../../skills/seguranca/corrigir-vulnerabilidade/SKILL.md
+[gate]: ../../commands/revisar-entrega/COMMAND.md
+[article]: https://manodeyvin.com.br/p/5-vacilacoes-de-seguranca-que-a-ia

package/.pbai4devs/skills/seguranca/corrigir-vulnerabilidade/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: corrigir-vulnerabilidade
+description: Corrige um achado validado e prova que a causa foi removida.
+---
+
+# Corrigir vulnerabilidade
+
+Receba o achado e sua evidência de [revisar-seguranca](../revisar-seguranca/SKILL.md).
+Confirme o caminho de abuso e o escopo autorizado. Esclareça dúvidas e apresente
+o plano antes de editar, respeitando aprovações já dadas.
+
+Corrija a causa, preserve o contrato legítimo e acrescente um teste de regressão
+que falhe antes e passe depois. Não silencie regra ou exclua arquivo apenas
+para deixar o scanner verde; documente falsos positivos com justificativa.
+
+Use [implementar-spec](../../specs/implementar-spec/SKILL.md) quando houver spec
+e [verificar-trabalho](../../projeto/verificar-trabalho/SKILL.md) para as provas.
+Repita o scanner relevante e o cenário original. Mudanças web exigem navegador;
+autorização exige a matriz de [permissões](../revisar-autorizacao/SKILL.md).
+
+Se houver segredo real, não o reproduza. Informe o responsável para revogação
+e rotação pelo canal apropriado; remover do código não invalida a credencial.
+Não altere contas, histórico Git ou serviços externos sem escopo explícito.
+
+Saída: correção, teste, risco residual e documentação atualizada. Feche com
+[revisar-entrega](../../../commands/revisar-entrega/COMMAND.md), incluindo
+revisão independente e evidências ignoradas em `.agent-tests/security/`.

package/.pbai4devs/skills/seguranca/modelar-ameacas/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: modelar-ameacas
+description: Identifica ativos, fronteiras de confiança e ameaças do escopo aprovado.
+---
+
+# Modelar ameaças
+
+Leia produto, design e código relacionados. Reúna primeiro as dúvidas sobre
+dados, atores, operações privilegiadas e limites do ambiente. Registre o que
+é fato, hipótese ou informação ausente; não invente arquitetura.
+
+Mapeie os ativos, entradas, fluxos e fronteiras de confiança. Para cada ameaça,
+descreva pré-condição, caminho de abuso, impacto, controle e teste observável.
+Priorize o que o desenho realmente permite: acesso entre usuários, elevação
+de privilégio, vazamento, injeção e abuso de recursos.
+
+Use o [modelo de revisão](../../../templates/revisao-seguranca/TEMPLATE.md)
+como apoio e o [auditor](../../../agents/auditor-seguranca/AGENT.md) para revisão.
+Se o projeto precisar de um documento permanente, combine seu destino com o
+usuário e siga [atualizar-documentacao](../../projeto/atualizar-documentacao/SKILL.md).
+Rascunhos e evidências ficam em `.agent-tests/security/`.
+
+Saída: ameaças priorizadas, controles existentes, lacunas e critérios de teste.
+O modelo orienta [revisar-seguranca](../revisar-seguranca/SKILL.md); não comprova
+que os controles foram implementados ou testados.

package/.pbai4devs/skills/seguranca/revisar-autorizacao/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: revisar-autorizacao
+description: Verifica identidade, permissões por recurso e isolamento entre usuários.
+---
+
+# Revisar autorização
+
+Identifique sujeitos, papéis, recursos e operações permitidas. Leia rotas,
+middleware, políticas de dados e testes; não deduza autorização pela interface.
+Se o contrato não existir, reúna as dúvidas antes de propor mudanças.
+
+Confira autenticação e autorização no servidor em cada operação sensível,
+incluindo IDs manipuláveis, operações em lote e ações administrativas.
+Em PostgreSQL/Supabase, revise RLS, policies, papéis e acessos privilegiados.
+Em Firebase, revise Security Rules e SDKs privilegiados; são controles distintos.
+
+Com contas sintéticas no ambiente local autorizado, prove no mínimo:
+
+- Visitante não autenticado recebe a recusa prevista.
+- Usuário A acessa seu recurso e não acessa o de B trocando o identificador.
+- Usuário comum não obtém a ação administrativa pela API direta.
+- Listagens, alterações e exclusões obedecem ao mesmo isolamento.
+
+Use testes de API e, quando houver interface, navegador conforme
+[verificar-trabalho](../../projeto/verificar-trabalho/SKILL.md).
+Não crie contas reais nem use dados de produção para essa prova.
+Sem aplicação executável ou identidades de teste, registre **não verificado**.
+Entregue matriz de permissões, resultados e achados sem segredos em
+`.agent-tests/security/`, usando o [modelo](../../../templates/revisao-seguranca/TEMPLATE.md).

package/.pbai4devs/skills/seguranca/revisar-seguranca/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: revisar-seguranca
+description: Revisa riscos de segurança com análise local, contexto e provas.
+---
+
+# Revisar segurança
+
+Defina o escopo: mudança ou projeto, dados sensíveis, stack e ambiente autorizado.
+Leia as regras de [segurança](../../../rules/seguranca/RULE.md) e
+[execução local](../../../rules/execucao-local/RULE.md). Não amplie o alvo.
+
+Use [auditar-seguranca](../../../commands/auditar-seguranca/COMMAND.md) para
+os scanners disponíveis e o [auditor](../../../agents/auditor-seguranca/AGENT.md)
+para interpretar os resultados. Uma ferramenta ausente ou base indisponível
+gera pendência; resultado vazio não substitui análise de contexto.
+
+Revise também autenticação, autorização por recurso, isolamento de dados,
+segredos e entradas conforme o [guia](../REFERENCE.md).
+Use [revisar-autorizacao](../revisar-autorizacao/SKILL.md) para permissões e
+[modelar-ameacas](../modelar-ameacas/SKILL.md) quando houver novas fronteiras.
+
+Registre achado, evidência, impacto, confiança e estado da triagem, sem valores
+secretos. Diferencie vulnerabilidade confirmada, suspeita e falso positivo.
+Prove cenários de API pelo terminal e fluxos web no navegador local autorizado,
+seguindo [verificar-trabalho](../../projeto/verificar-trabalho/SKILL.md).
+Salve o relatório em `.agent-tests/security/`; não declare o produto seguro
+com base apenas em scanners. Encaminhe correções à skill correspondente.

package/.pbai4devs/templates/README.md

@@ -28,6 +28,7 @@ enquanto o usuário estiver preparando somente a estrutura dos agentes.
 | [Revisão de entrega][revisao] | Implementação | Antes de commit/merge. |
 | [Release][release], [CHANGELOG][changelog] | Primeira entrega | Publicar. |
 | [SECURITY][security] | Suporte público | Política/suporte mudar. |
+| [Revisão de segurança][security-review] | Análise autorizada | Ameaças e provas. |
 | [Comando][comando] | Recurso agêntico | Entrada ou fluxo mudar. |
 
 Antes, inventarie e leia os documentos existentes com `atualizar-documentacao`.
@@ -65,4 +66,5 @@ Modelos, configurações e relatórios não são espelhados nas pastas dos agent
 [release]: release/TEMPLATE.md
 [changelog]: changelog/TEMPLATE.md
 [security]: seguranca/TEMPLATE.md
+[security-review]: revisao-seguranca/TEMPLATE.md
 [comando]: comando/TEMPLATE.md

package/.pbai4devs/templates/revisao-seguranca/TEMPLATE.md

@@ -0,0 +1,33 @@
+---
+description: Modelo de contexto, ameaças, achados e provas de segurança.
+status: modelo
+---
+
+# Revisão de segurança
+
+Preencha com fatos do escopo autorizado. Resultados e rascunhos ficam em
+`.agent-tests/security/`; combine o destino de documentação permanente.
+Este modelo complementa o relatório JSON dos scanners, sem substituir suas provas.
+
+## Contexto
+
+Alvo, alteração, ambiente, ativos, atores, operações e fronteiras de confiança.
+Registre fontes, hipóteses e dúvidas; não preencha lacunas com suposições.
+
+## Ameaças e controles
+
+| Ameaça | Pré-condição | Impacto | Controle existente | Teste necessário |
+| --- | --- | --- | --- | --- |
+| A definir | A confirmar | A confirmar | Evidência | Resultado esperado |
+
+## Achados
+
+| ID | Local | Evidência sem segredo | Confiança | Estado | Próxima ação |
+| --- | --- | --- | --- | --- | --- |
+| SEC-001 | Arquivo/linha | Evidência | A avaliar | A triar | Responsável |
+
+## Validação
+
+Critério, comando ou cenário, resultado, caminho da prova e limitações.
+Separe o que passou, falhou, não se aplica e não foi executado.
+Registre revisão independente e risco residual antes de concluir.

package/.pbai4devs/tools/README.md

@@ -8,8 +8,9 @@ Cada pasta mantém `TOOL.json`, `SCRIPT.mjs` e um guia.
 O catálogo local `catalog.json` relaciona essas definições aos comandos
 de instalação, atualização, verificação e execução. Ao editar definições,
 rode `sincronizar-agentes` e `--check`; versões instaladas ficam no estado local.
-O instalador comum consulta `latest` na origem oficial e instala com
-`--ignore-scripts`. Pacotes e estado ficam em `<nome>/.local/`; cache em
+Para npm, o instalador consulta `latest` e usa `--ignore-scripts`.
+Scanners nativos usam versões e SHA-256 revisados em `TOOL.json`; `update`
+aplica esse pin. Pacotes e estado ficam em `<nome>/.local/`; cache em
 `.cache/` e atalhos em `bin/`, todos ignorados. Tools ficam só em `.pbai4devs`.
 
 | CLI | Grupo | Uso |
@@ -22,9 +23,14 @@ O instalador comum consulta `latest` na origem oficial e instala com
 | [opensrc][source] | source | Fontes de dependências. |
 | [webreel][video] | video | Roteiros e vídeos do navegador. |
 | [portless][proxy] | proxy | Proxy e URLs locais estáveis. |
+| [gitleaks](gitleaks/README.md) | security | Segredos em arquivos e Git. |
+| [osv-scanner](osv-scanner/README.md) | security | Dependências com base local. |
+| [opengrep](opengrep/README.md) | security | Código com regras locais. |
 
 `setup` instala e verifica todos os CLIs compatíveis. O grupo `base` limita a
-seleção a navegador e lint; outros grupos permitem escolher por tarefa.
+seleção a navegador e lint; `security` seleciona os três scanners.
+As bases de vulnerabilidades são preparadas separadamente; instalar o CLI
+não transforma uma base ausente em resultado limpo.
 Confira Node/npm pelo [primeiro uso][manager] antes de executar os scripts.
 O instalador usa o mesmo Node 24+ com npm em todos os sistemas. Plataformas aceitas
 ficam em cada `TOOL.json`; ausência de restrição npm não comprova teste do SO.
@@ -45,6 +51,8 @@ O [instalador comum][manager] aceita nomes ou grupos, como `setup`, `install bas
 `update video`, `check source` e `list`.
 
 O preparo verifica o CLI; fluxos de aplicação precisam de provas específicas.
+O [fluxo de segurança](../commands/auditar-seguranca/COMMAND.md) usa análise
+offline e relatórios redigidos. Downloads públicos exigem rede, não conta.
 Skills usa descoberta sem importação automática ou symlinks. Portless é opt-in:
 o preparo não inicia proxy. Webreel exige executáveis explícitos para gravar
 sem baixar recursos em `~/.webreel`; seu guia lista os overrides. Use caminhos

package/.pbai4devs/tools/gitleaks/README.md

@@ -0,0 +1,22 @@
+---
+description: Instalacao local revisada do gitleaks.
+---
+
+# gitleaks
+
+Procura segredos em arquivos e no historico Git.
+
+Versao revisada: **8.30.1**. Licenca: [MIT](https://github.com/gitleaks/gitleaks/blob/v8.30.1/LICENSE).
+Downloads vem da [release oficial](https://github.com/gitleaks/gitleaks/releases/tag/v8.30.1);
+cada plataforma tem SHA-256 fixado em `TOOL.json`.
+
+`SCRIPT.mjs install` baixa e verifica o executavel. `update` aplica a versao
+revisada do catalogo; nao seleciona `latest` sem revisao. `check` verifica
+integridade e versao sem rede; `run` preserva argumentos e codigo de saida.
+Use `node .pbai4devs/tools/gitleaks/SCRIPT.mjs <acao>`.
+
+Use os comandos de seguranca do kit para obter saida redigida. Resultados
+exigem triagem; revogar credenciais reais continua necessario.
+
+Binarios, caches e resultados ficam locais e ignorados. O CLI nao exige
+conta nem pagamento. Consulte o [gerenciador](../../scripts/preparar-ferramentas/README.md).

package/.pbai4devs/tools/gitleaks/SCRIPT.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../../scripts/preparar-ferramentas/SCRIPT.mjs';
+
+try { process.exitCode = await main(['--tool', "gitleaks", ...process.argv.slice(2)]); }
+catch (error) { console.error(error.message); process.exitCode = 1; }

package/.pbai4devs/tools/gitleaks/TOOL.json

@@ -0,0 +1,67 @@
+{
+  "name": "gitleaks",
+  "description": "Detecta segredos locais e no historico Git.",
+  "group": "security",
+  "source": "https://github.com/gitleaks/gitleaks/releases/tag/v8.30.1",
+  "license": "MIT",
+  "licenseSource": "https://github.com/gitleaks/gitleaks/blob/v8.30.1/LICENSE",
+  "download": {
+    "provider": "github-release",
+    "repository": "gitleaks/gitleaks",
+    "channel": "reviewed",
+    "version": "8.30.1",
+    "tag": "v8.30.1",
+    "assets": {
+      "darwin-arm64": {
+        "file": "gitleaks_8.30.1_darwin_arm64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "b40ab0ae55c505963e365f271a8d3846efbc170aa17f2607f13df610a9aeb6a5"
+      },
+      "darwin-x64": {
+        "file": "gitleaks_8.30.1_darwin_x64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "dfe101a4db2255fc85120ac7f3d25e4342c3c20cf749f2c20a18081af1952709"
+      },
+      "linux-arm64": {
+        "file": "gitleaks_8.30.1_linux_arm64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080"
+      },
+      "linux-x64": {
+        "file": "gitleaks_8.30.1_linux_x64.tar.gz",
+        "format": "tar.gz",
+        "binary": "gitleaks",
+        "sha256": "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+      },
+      "win32-arm64": {
+        "file": "gitleaks_8.30.1_windows_arm64.zip",
+        "format": "zip",
+        "binary": "gitleaks.exe",
+        "sha256": "b95f5e4f5c425cedca7ee203d9afd29597e692c4924a12ed42f970537c72cc0f"
+      },
+      "win32-x64": {
+        "file": "gitleaks_8.30.1_windows_x64.zip",
+        "format": "zip",
+        "binary": "gitleaks.exe",
+        "sha256": "d29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e"
+      }
+    }
+  },
+  "platforms": [
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-arm64",
+    "linux-x64",
+    "win32-arm64",
+    "win32-x64"
+  ],
+  "scripts": {
+    "entry": "SCRIPT.mjs"
+  },
+  "probe": [
+    "version"
+  ]
+}

package/.pbai4devs/tools/opengrep/README.md

@@ -0,0 +1,22 @@
+---
+description: Instalacao local revisada do opengrep.
+---
+
+# opengrep
+
+Executa regras SAST armazenadas no projeto.
+
+Versao revisada: **1.33.1**. Licenca: [LGPL-2.1](https://github.com/opengrep/opengrep/blob/v1.33.1/LICENSE).
+Downloads vem da [release oficial](https://github.com/opengrep/opengrep/releases/tag/v1.33.1);
+cada plataforma tem SHA-256 fixado em `TOOL.json`.
+
+`SCRIPT.mjs install` baixa e verifica o executavel. `update` aplica a versao
+revisada do catalogo; nao seleciona `latest` sem revisao. `check` verifica
+integridade e versao sem rede; `run` preserva argumentos e codigo de saida.
+Use `node .pbai4devs/tools/opengrep/SCRIPT.mjs <acao>`.
+
+Use `--config` com regras locais e `--disable-version-check`. Nao use `auto`
+ou URLs de regras no modo local.
+
+Binarios, caches e resultados ficam locais e ignorados. O CLI nao exige
+conta nem pagamento. Consulte o [gerenciador](../../scripts/preparar-ferramentas/README.md).

package/.pbai4devs/tools/opengrep/SCRIPT.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../../scripts/preparar-ferramentas/SCRIPT.mjs';
+
+try { process.exitCode = await main(['--tool', "opengrep", ...process.argv.slice(2)]); }
+catch (error) { console.error(error.message); process.exitCode = 1; }