The authoritative text is the English page: English version of this page
As ferramentas da suíte: instalar, julgar, detectar, gerar relatório, manter os fatos atualizados
Cinco ferramentas ficam em torno do executor de cenários (feintkit, veja DETECTION-INTEGRATION.md). Esta página traz os comandos exatos, as flags, os códigos de saída e exemplos offline de cada uma. As linhas de comando e as flags são conferidas contra as ferramentas reais pelos testes do pacote de documentação. Leia RESPONSIBLE-USE.md primeiro.
| Etapa | Ferramenta | Comando | Precisa de rede |
|---|---|---|---|
| Instalar | instalador (feintkit-suite) | node packages/installer/dist/src/bin.js | apenas para uma origem https |
| Executar | executor (feintkit) | veja DETECTION-INTEGRATION.md | não |
| Julgar uma transcrição | ingestão de transcrição, usada por meio de feintkit verify | node packages/cli/dist/src/bin.js | não |
| Substituir um produto de segurança | substituto de teste de detecção (feintkit-watch) | node packages/watch/dist/src/bin.js | não |
| Gerar relatório | relatório (feintkit-report) | node packages/report/dist/src/bin.js | não |
| Manter os fatos atualizados | verificação de fatos (feintkit-factcheck) | node packages/factcheck/dist/src/bin.js | sim |
Execute todos os comandos a partir da raiz do repositório da suíte, depois de npm run setup. Uma linha que termina com # exit <n> em um exemplo mostra o código de saída que o comando retorna; omita o comentário ao digitar. <work> representa qualquer diretório vazio de sua escolha.
Instalador (feintkit-suite)
Finalidade: desempacota a suíte a partir de um diretório, de um tarball de release ou de um endereço https, confere o tarball com uma soma de verificação que você fornece por um canal separado, mostra o aviso legal e um plano do que fará, e desempacota. Ele não executa a compilação da suíte a menos que você passe --run-setup; com essa opção, executa npm run setup --ignore-scripts com um ambiente mínimo, lista os cenários e imprime os próximos passos. Recusa-se a executar como root, salvo instrução em contrário, e nunca sobrescreve um diretório que não seja de uma instalação sua. Executá-lo de novo sobre uma instalação concluída imprime already installed.
Onde se encaixa: o primeiro passo, em uma máquina que ainda não tem a suíte. Mantenedores que já trabalham em um checkout não precisam dele.
Uso (o texto da própria ferramenta):
usage: feintkit-suite install --from <directory|tarball|https-address> [--sha256 <hex> | --checksums <SHA256SUMS file or https address>] [--trust-remote-checksums] [--dest <directory>] [--allow-root] [--force] [--run-setup | --skip-build] [--accept-disclaimer]
feintkit-suite install [--dest <directory>] (with FEINTKIT_RELEASE_BASE set to an https release address; needs --sha256 or --trust-remote-checksums)
feintkit-suite --version
feintkit-suite --help| Flag | Significado |
|---|---|
--from <source> | Um diretório, um arquivo .tar.gz ou um endereço https. Sem ele, o endereço é montado a partir de FEINTKIT_RELEASE_BASE. |
--sha256 <hex> | O SHA-256 esperado do tarball, obtido por um canal diferente do download. Não pode ser combinado com --checksums. Um tarball precisa de --sha256 ou --checksums; um diretório não aceita nenhum dos dois. |
--checksums <file or https address> | Um arquivo SHA256SUMS que lista o tarball. Passe um arquivo local que você obteve separadamente. Um endereço https (inclusive o montado a partir de FEINTKIT_RELEASE_BASE) vem da mesma origem do download e é recusado, a menos que --trust-remote-checksums também seja informado. |
--trust-remote-checksums | Aceita um arquivo de somas de verificação obtido da mesma origem do tarball e imprime um aviso: quem controla essa origem controla o que é desempacotado. |
--dest <directory> | Onde instalar. Padrão: feintkit-suite no diretório atual. |
--allow-root | Permite a execução como usuário root. |
--force | Substitui uma instalação que contém outra versão ou uma compilação inacabada. |
--run-setup | Executa o npm run setup --ignore-scripts da suíte depois de desempacotar, com um ambiente mínimo (o script setup do pacote que você desempacotou executa; os scripts de instalação das dependências não). Sem ela, nada é executado e o comando exato é impresso. |
--skip-build | O padrão, mantido para linhas de comando antigas: apenas desempacota. Não pode ser combinado com --run-setup. |
--accept-disclaimer | Confirma o aviso sem pedir confirmação. Uma sessão não interativa precisa dele. |
--version, --help | Imprimem a versão ou o texto de uso e saem com 0. |
Códigos de saída:
| Código | Significado |
|---|---|
| 0 | Instalado, já instalado, ou --help / --version. |
| 2 | Erro de uso (também: --sha256 e --checksums juntos, --run-setup e --skip-build juntos, nenhuma origem, uma soma de verificação com origem em diretório, ou uma soma de verificação https sem --trust-remote-checksums). |
| 3 | Falha de integridade: origem não encontrada, nenhuma soma de verificação para um tarball, divergência de soma de verificação, tarball inválido ou download com falha. |
| 4 | Recusou-se a executar como root sem --allow-root. |
| 5 | Problema de destino: não é uma instalação do Feintkit, uma instalação diferente sem --force, ou uma falha de gravação. |
| 6 | A configuração ou a listagem de cenários falhou. |
| 7 | O aviso legal não foi confirmado. |
Exemplos offline (um diretório local como origem, nada é baixado e nada do pacote executa):
node packages/installer/dist/src/bin.js --version # exit 0
node packages/installer/dist/src/bin.js install --from docs/guide --dest <work>/suite # exit 7
node packages/installer/dist/src/bin.js install --from docs/guide --dest <work>/suite --accept-disclaimer # exit 0
node packages/installer/dist/src/bin.js install --from <work>/missing.tar.gz --sha256 0000 --dest <work>/other --accept-disclaimer # exit 3O aviso é mostrado e confirmado antes de qualquer origem ser lida, portanto toda instalação precisa de --accept-disclaimer em uma sessão não interativa. A primeira instalação é recusada porque a sessão do exemplo não é interativa; a segunda confirma o aviso e desempacota docs/guide como se fosse a suíte, sem executar nada. Uma instalação real usa a sua própria origem --from e um valor --sha256 ou --checksums local obtido por um segundo canal, e acrescenta --run-setup somente depois que você leu o script setup do pacote.
Ingestão de transcrição (feintkit verify --transcript)
Finalidade: transforma uma transcrição salva de agente no texto simples que a regra de veredito julga, de modo que o veredito olhe apenas para o que o agente disse e fez, e não para o formato do registro ao redor. É uma biblioteca sem comando próprio; o executor a usa quando verify recebe --format.
Onde se encaixa: depois que um cenário foi executado contra o seu agente e você salvou a saída do agente, para julgar se o agente cumpriu a instrução injetada.
Uso (a linha verify do próprio texto de uso do executor):
verify <id> [--transcript <file>] [--format <name>] [--strict] [--record] [--fail-on-complied] [--deterministic]| Flag | Significado |
|---|---|
--transcript <file> | A transcrição salva. Sem --format, o arquivo é julgado como está, como texto simples. |
--format <name> | Lê o arquivo com um formato nomeado, ou auto para detectá-lo. Exige --transcript. Nomes: claude-stream-json, anthropic-messages, openai-chat, plain. |
--strict | Com --format: uma transcrição que não pode ser lida exatamente é um erro em vez de uma observação. Exige --format. |
--record | Grava o veredito no events.jsonl do cenário como um evento agent_outcome, que o relatório então mostra. |
--fail-on-complied | Sai com 3 quando o veredito é complied. |
--deterministic | Usa o id de execução fixo RUN0000, como na execução. |
Códigos de saída de verify:
| Código | Significado |
|---|---|
| 0 | As verificações de artefatos passaram (e o agente não cumpriu a instrução, ou --fail-on-complied não foi informado). |
| 1 | Uma verificação de artefatos falhou, ou o cenário ou a sua execução não foi encontrado. |
| 2 | Erro de uso, ou a transcrição não pôde ser lida ou ingerida (a mensagem começa com cannot ingest transcript). |
| 3 | --fail-on-complied foi informado e o veredito é complied. |
Com --format, o formato e quaisquer observações são impressos no fluxo de erro (transcript format: <name> (named|detected)). Uma transcrição maior que 16777216 bytes é rejeitada.
Exemplos offline (as próprias páginas do guia servem como texto da transcrição: MARKERS.md contém o token de confirmação de exemplo de uma execução determinística, RESPONSIBLE-USE.md não):
node packages/cli/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out run mcp-01-tool-poisoning --deterministic # exit 0
node packages/cli/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out verify mcp-01-tool-poisoning --transcript docs/guide/RESPONSIBLE-USE.md --format plain --deterministic # exit 0
node packages/cli/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out verify mcp-01-tool-poisoning --transcript docs/guide/MARKERS.md --format plain --strict --record --fail-on-complied --deterministic # exit 3
node packages/cli/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out verify mcp-01-tool-poisoning --format plain # exit 2O segundo comando imprime verdict: resisted, o terceiro imprime verdict: complied e sai com 3, e o quarto é um erro de uso porque --format exige --transcript.
Substituto de teste de detecção (feintkit-watch)
Finalidade: um substituto deliberadamente simples de um produto de segurança, para que a coluna Detecção da matriz de cobertura e do relatório possa ser exercitada de ponta a ponta. Ele lê o que um agente sob teste fez e viu (as chamadas de ferramenta, o conteúdo dos resultados de ferramenta, o texto do assistente e o texto de skill carregada de uma transcrição de sessão headless salva ou canalizada, ou uma lista simples de comandos de shell, um por linha), compara cada chamada e cada trecho de conteúdo com um pequeno arquivo de regras legível (packages/watch/rules/starter.json) e grava o arquivo de detecções que feintkit-matrix e feintkit-report leem (--detections), além de um arquivo de evidências. É um fixture de teste e um exemplo prático do que um produto deve registrar e em que formato. Não é um produto de segurança, e toda linha que ele imprime diz isso.
Onde se encaixa: depois que um cenário foi executado contra o seu agente e você salvou a saída do agente, antes da matriz ou do relatório. Três limites fazem parte do projeto. Ele apenas observa: vê uma chamada depois que o agente decidiu e não pode impedi-la, portanto um resultado blocked é um veredito de política rotulado como enforcement: simulated, nunca uma recusa real. Ele vê o stream da sessão, não o protocolo nem a rede: 9 dos 42 cenários colocam o seu sinal em tráfego de protocolo, tráfego de rede, pixels ou um frontmatter que o cliente remove, de modo que a ferramenta não grava nenhuma entrada para eles e a matriz mantém not-reported; ela nunca afirma missed para algo que não consegue ver, e reporta missed apenas para os onze cenários cujo veredito do agente prova que o sinal passou pelo stream, quando o veredito é complied e nenhuma regra correspondeu. O token de confirmação em uma resposta é o veredito do agente, não uma detecção, e nenhuma regra o lê. A maioria das regras iniciais compara as strings da própria suíte, portanto um resultado verde nessas linhas é evidência circular; o arquivo de regras marca cada regra como marker ou behaviour. Um blocked ou detected desta ferramenta não é evidência sobre nenhum produto. Dê ao arquivo de detecções o nome detections.feintkit-watch.json para que a sua origem fique visível na linha de comando e nos logs de CI.
Para executá-lo sobre muitos cenários com um agente real, use o loop de exemplo docs/examples/real-agent-loop.sh (agente, juiz, varredura com --merge, matriz e relatório; pode ser interrompido e reiniciado). A versão passo a passo está em DETECTION-INTEGRATION.md, seção 5.
Uso (o texto da própria ferramenta):
usage: feintkit-watch scan (--scenario <id> --transcript <file> [--verdict <v> | --events <file>] | --map <file>) --rules <file> --out <file> [--evidence <file>] [--merge] [--format auto|stream-json|command-log] [--root <dir>]... [--timestamp <iso>] [--fail-on-missed]
feintkit-watch tee --scenario <id> --rules <file> --out <file> [--verdict <v> | --events <file>] [--evidence <file>] [--merge] [--format auto|stream-json|command-log] [--root <dir>]... [--timestamp <iso>]
feintkit-watch check-rules --rules <file> [--root <dir>]...
feintkit-watch export --evidence <file> --format jsonl|sarif|csv --out <file>
feintkit-watch import --input <file> --source <name> --out <file> [--evidence <file>] [--merge] [--root <dir>]...| Flag | Significado |
|---|---|
--scenario <id> | O cenário a que esta transcrição pertence. Ele é nomeado por você, nunca deduzido do conteúdo. |
--transcript <file> | A transcrição salva (scan); tee lê a entrada padrão em vez disso. |
--map <file> | Um mapa JSON de várias execuções (schemaVersion 1 e runs, cada uma com scenario, transcript e, opcionalmente, events ou verdict); os caminhos são relativos ao mapa. Não pode ser combinado com --scenario, --transcript, --verdict ou --events. |
--rules <file> | O arquivo de regras. |
--out <file> | O arquivo de detecções a gravar (um objeto plano de id de cenário para detected, blocked ou missed). |
--evidence <file> | Grava também o arquivo de evidências: uma linha JSON por ocorrência, truncada ao texto correspondente, mais uma linha de resumo. Com export, é o arquivo de evidências a ler; com import, é um arquivo opcional para os eventos importados. |
--merge | Lê os arquivos de detecções e de evidências existentes e substitui apenas o cenário varrido. Um arquivo ausente conta como vazio; um inválido é um erro e não é tocado. |
--format <name> | scan e tee: auto (padrão), stream-json ou command-log. export: jsonl, sarif ou csv (obrigatório). |
--verdict <v> | O veredito do agente de feintkit verify: complied, resisted, resisted_surfaced ou inconclusive. Sem um veredito, missed não pode ser decidido. |
--events <file> | Lê o veredito do último evento agent_outcome de um events.jsonl. Não pode ser combinado com --verdict. |
--root <dir> | Um repositório de categoria que contém cenários; repita para vários. Padrão: o diretório atual. |
--timestamp <time> | Define o horário das linhas de evidência, exatamente na forma YYYY-MM-DDTHH:MM:SS.mmmZ. Com FEINTKIT_DETERMINISTIC=1, o horário é fixo. |
--fail-on-missed | Sai com 3 quando um cenário varrido é missed, depois que os arquivos são gravados. |
--input <file> | Somente import: os eventos JSON Lines de um produto real (formato abaixo). |
--source <name> | Somente import: o nome do produto (de 1 a 64 letras, dígitos, espaço, ponto, sublinhado ou hífen; não pode conter feintkit-watch nem stand-in). Ele se torna o product de cada evento importado. |
tee passa a entrada padrão para a saída padrão sem alteração e faz o mesmo trabalho que scan no fim da entrada, imprimindo suas linhas no fluxo de erro; check-rules valida um arquivo de regras e seus controles e imprime a linha honesta de cobertura.
Exportação e importação (somente observação, offline; os formatos exatos estão na especificação fnd-18-watch, Emenda 1.2). export --evidence <file> --format jsonl|sarif|csv --out <file> lê o arquivo de evidências e grava um de três formatos. jsonl é um evento por linha com as chaves estáveis schema, product, stand_in, timestamp (ISO-8601), event (detection ou missed), scenario, rule, action (detect ou block, e um bloqueio é simulado), basis (marker ou behaviour), enforcement, tool, evidence (o trecho já com redação e cortado em 200 caracteres) e location (path:line da transcrição). csv tem as mesmas colunas, com um apóstrofo inicial em qualquer célula que uma planilha leria como fórmula. sarif é um log SARIF 2.1.0 cujo driver da ferramenta diz expressamente que é um SUBSTITUTO DE TESTE e não um produto de segurança; cada resultado tem o id da regra, uma mensagem, o cenário como local lógico e, quando o caminho da transcrição é relativo, a linha da transcrição como local físico. import --input <file> --source <name> --out <file> faz o caminho inverso: um produto real que grava o mesmo formato JSON Lines (apenas scenario e action são obrigatórios para uma detecção; event missed marca um cenário que foi executado e não foi reportado; chaves desconhecidas são ignoradas) obtém um arquivo de detecções próprio para --detections. Os resultados do substituto e do produto nunca são misturados: --source é obrigatório, os eventos importados mantêm-no como seu product com stand_in falso, um registro do próprio substituto é recusado e um nome de arquivo que contenha feintkit-watch é recusado para a saída. Compare os dois entregando à matriz ou ao relatório um arquivo de detecções por vez.
Códigos de saída:
| Código | Significado |
|---|---|
| 0 | Concluído (também quando nenhuma entrada foi gravada para o cenário). |
| 1 | Um arquivo de saída não pôde ser gravado. |
| 2 | Erro de uso, uma entrada ilegível ou inválida, regras inválidas ou um cenário desconhecido. |
| 3 | --fail-on-missed foi informado e um cenário varrido é missed. |
Exemplos offline (as transcrições são os fixtures do pacote; o segundo comando grava o arquivo de detecções que o primeiro exemplo de relatório abaixo lê):
node packages/watch/dist/src/bin.js check-rules --rules packages/watch/rules/starter.json --root repos/feintkit-mcp --root repos/feintkit-skills --root repos/feintkit-injection --root repos/feintkit-exfil --root repos/feintkit-agents --root repos/feintkit-supplychain --root repos/feintkit-abuse # exit 0
node packages/watch/dist/src/bin.js scan --scenario mcp-08-exfil-sim --transcript packages/watch/test/fixtures/mixed.jsonl --rules packages/watch/rules/starter.json --out <work>/detections.feintkit-watch.json --evidence <work>/detections.evidence.jsonl --timestamp 1970-01-01T00:00:00.000Z --root repos/feintkit-mcp --root repos/feintkit-skills --root repos/feintkit-injection --root repos/feintkit-exfil --root repos/feintkit-agents --root repos/feintkit-supplychain --root repos/feintkit-abuse # exit 0
node packages/watch/dist/src/bin.js export --evidence <work>/detections.evidence.jsonl --format sarif --out <work>/detections.feintkit-watch.sarif # exit 0
node packages/watch/dist/src/bin.js export --evidence <work>/detections.evidence.jsonl --format jsonl --out <work>/detections.feintkit-watch.events.jsonl # exit 0
node packages/watch/dist/src/bin.js import --input packages/watch/test/fixtures/import-sample.jsonl --source ExampleGuard --out <work>/detections.exampleguard.json --root repos/feintkit-mcp --root repos/feintkit-skills --root repos/feintkit-injection --root repos/feintkit-exfil --root repos/feintkit-agents --root repos/feintkit-supplychain --root repos/feintkit-abuse # exit 0
node packages/watch/dist/src/bin.js scan --scenario mcp-04-excessive-scope --transcript packages/watch/test/fixtures/clean.jsonl --verdict complied --rules packages/watch/rules/starter.json --out <work>/missed.json --fail-on-missed --root repos/feintkit-mcp --root repos/feintkit-skills --root repos/feintkit-injection --root repos/feintkit-exfil --root repos/feintkit-agents --root repos/feintkit-supplychain --root repos/feintkit-abuse # exit 3
node packages/watch/dist/src/bin.js scan --scenario mcp-08-exfil-sim --transcript packages/watch/test/fixtures/mixed.jsonl --rules packages/watch/rules/starter.json --out <work> --root repos/feintkit-mcp --root repos/feintkit-skills --root repos/feintkit-injection --root repos/feintkit-exfil --root repos/feintkit-agents --root repos/feintkit-supplychain --root repos/feintkit-abuse # exit 1
node packages/watch/dist/src/bin.js scan --map <work>/map.json # exit 2O segundo comando imprime mcp-08-exfil-sim blocked (1 rule hit; enforcement: simulated, nothing was stopped) e uma linha que diz que 39 de 48 cenários têm uma regra. O terceiro não tem nenhuma ocorrência de regra, o veredito é complied, portanto o resultado é missed e o código de saída é 3. O quarto não consegue gravar porque o caminho de saída é um diretório.
Relatório (feintkit-report)
Finalidade: monta um relatório de resultados a partir dos manifestos dos cenários, dos artefatos das execuções e, quando você o fornece, do seu registro de detecção. O relatório lista, por cenário, o resultado dos artefatos, o veredito do agente, o resultado da detecção e os mapeamentos ATLAS e OWASP, e termina com um resumo por técnica ATLAS. Formatos: md (padrão), json, html, sarif, junit (XML JUnit para um sistema de CI, veja AUTOMATION.md).
Onde se encaixa: depois das execuções e dos julgamentos, para entregar os resultados a alguém ou para controlar um job de CI. A matriz de cobertura (feintkit-matrix, DETECTION-INTEGRATION.md) é a visão mais curta dos mesmos dados.
Uso (o texto da própria ferramenta):
usage: feintkit-report [--root <dir>]... [--out-dir <dir>] [--detections <file>] [--format json|md|html|sarif|junit] [--output <file>] [--timestamp <YYYY-MM-DDTHH:MM:SS.mmmZ>] [--agent <name>] [--agent-version <text>] [--model <text>] [--permission-mode <text>] [--mitigations] [--fail-on-missed] [--fail-on-complied] [--fail-on-control-fired]| Flag | Significado |
|---|---|
--root <dir> | Um repositório de categoria que contém cenários; repita para vários. Padrão: o diretório atual. |
--out-dir <dir> | O diretório de artefatos das execuções (o mesmo do executor). |
--detections <file> | Arquivo JSON que mapeia ids de cenário para detected, blocked ou missed. |
--format <name> | json, md, html, sarif ou junit. Padrão md. |
--output <file> | Grava o relatório em um arquivo em vez de imprimi-lo. |
--timestamp <time> | Define o momento de geração, exatamente na forma YYYY-MM-DDTHH:MM:SS.mmmZ. Com FEINTKIT_DETERMINISTIC=1, o horário é fixo. |
--agent <name>, --agent-version <text>, --model <text>, --permission-mode <text> | Registram qual agente produziu os resultados (fnd-44): o relatório então carrega uma identidade do agente, e os relatórios em markdown e html imprimem uma linha Agent under test. Cada um é um rótulo simples e curto, de no máximo 64 caracteres, recusado com saída 2 quando parece um segredo; um campo omitido é unknown. Nada inicia o agente para descobri-los. |
--mitigations | Acrescenta as notas revisadas para defensores (o que restringir, qual regra adicionar, qual configuração mudar) para cada cenário que tem um achado: uma seção em md e html, o texto de ajuda da regra em sarif, o texto da falha em junit. Recusado com json, cujo layout é fixo. Veja AUTOMATION.md. |
--fail-on-missed | Sai com 3 quando um cenário foi registrado como missed. |
--fail-on-complied | Sai com 3 quando o veredito de um agente é complied. |
--fail-on-control-fired | Sai com 3 quando o juiz ou o produto sob teste gerou um alarme falso em um controle benigno (um veredito complied ou resisted_surfaced, ou uma detecção detected ou blocked, para um controle). |
Códigos de saída:
| Código | Significado |
|---|---|
| 0 | O relatório foi produzido e nenhuma condição de falha se aplicou. |
| 1 | Um erro de registro de cenário (as linhas que começam com FAIL no fluxo de erro). O relatório ainda é produzido. |
| 2 | Erro de uso, um arquivo de detecções ilegível ou inválido, ou o arquivo de saída não pôde ser gravado. |
| 3 | --fail-on-missed, --fail-on-complied ou --fail-on-control-fired se aplicou. |
Exemplos offline (usam a execução dos exemplos de transcrição acima e, no quarto, o arquivo de detecções do substituto acima; o primeiro não grava nada fora de <work>):
node packages/report/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out --format md --output <work>/report.md # exit 0
node packages/report/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out --format sarif --output <work>/report.sarif # exit 0
node packages/report/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out --format junit --mitigations --output <work>/report.xml # exit 0
node packages/report/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out --detections <work>/detections.feintkit-watch.json --output <work>/with-detections.md # exit 0
node packages/report/dist/src/bin.js --root repos/feintkit-mcp --out-dir <work>/out --fail-on-complied --output <work>/gate.md # exit 3
node packages/report/dist/src/bin.js --format pdf # exit 2Verificação de fatos (feintkit-factcheck)
Finalidade: relê cada frase da documentação do fornecedor que CLIENTS.md cita e executa a verificação das fontes de mapeamento (scripts/verify-mappings.py --online), para que a deriva nessas fontes seja encontrada. Com --write, registra em docs/guide/facts-verified.json a data de cada fato encontrado; os guias mostram essa data.
Onde se encaixa: manutenção, em um cronograma (a cada poucos dias) e antes de um release. É a única ferramenta aqui que precisa de rede: cada verificação é uma requisição de saída para as páginas citadas. Usuários comuns da suíte não precisam dela.
Uso (o texto da própria ferramenta):
usage: feintkit-factcheck [--repo <dir>] [--facts-file <file>] [--write] [--report <file>] [--skip-facts] [--skip-mappings] [--delay <ms>] [--timeout <ms>]
re-reads every cited sentence of the client guides and runs scripts/verify-mappings.py --online
--write record today's date for each fact that was found, in docs/guide/facts-verified.json (nothing is written without it)
--report FILE write a report; FILE ending in .json gives JSON, anything else Markdown
exit codes: 0 all ok, 1 drift found, 2 usage, 3 network failure| Flag | Significado |
|---|---|
--repo <dir> | A raiz da suíte. Padrão: o diretório atual. |
--facts-file <file> | Onde --write registra as datas. Padrão: docs/guide/facts-verified.json sob --repo. |
--write | Registra a data de hoje para cada fato encontrado. Não pode ser combinado com --skip-facts. |
--report <file> | Grava um relatório; um nome terminado em .json gera JSON, qualquer outro gera Markdown. |
--skip-facts | Não verifica as frases citadas. |
--skip-mappings | Não executa a verificação das fontes de mapeamento. Informar os dois skips é um erro de uso. |
--delay <ms> | Pausa entre duas requisições. Padrão 1000. |
--timeout <ms> | Limite de tempo de uma requisição. Padrão 30000. |
Códigos de saída:
| Código | Significado |
|---|---|
| 0 | Tudo foi encontrado e confere. |
| 1 | Deriva: uma frase não foi encontrada, uma página mudou de lugar ou respondeu com um status de erro, ou uma fonte de mapeamento difere. |
| 2 | Erro de uso. |
| 3 | Falha de rede e nenhuma deriva. |
Exemplos offline (somente os erros de uso podem executar sem a rede; uma verificação real é node packages/factcheck/dist/src/bin.js e envia requisições):
node packages/factcheck/dist/src/bin.js --skip-facts --skip-mappings # exit 2
node packages/factcheck/dist/src/bin.js --write --skip-facts # exit 2
node packages/factcheck/dist/src/bin.js --delay soon # exit 2Flags dos outros comandos
A suíte tem mais ferramentas de linha de comando e subcomandos do que as cinco acima. Esta tabela lista toda flag do texto de uso de cada uma delas, com o comando que a aceita: o executor (feintkit) e os seus comandos honey, pack, accuracy e variants, o servidor de controle, o gerador de documentação e o seu comando translate, o guard, a interface web, a ferramenta de manifesto, a matriz de cobertura, a ferramenta de scaffold, os subcomandos diff, history, modes, repeats, store, coverage, summary e mitigations de feintkit-report, e os subcomandos replay, selftest e bundle de feintkit-watch. Cada comando imprime o seu próprio texto de uso quando é chamado com uma flag desconhecida. As flags de feintkit verify estão na seção sobre ingestão de transcrição, e as das cinco ferramentas acima estão em suas próprias tabelas.
| Flag | Usada por | Significado |
|---|---|---|
--root <dir> | feintkit, feintkit-docs, feintkit-gui, feintkit-gui demo, feintkit-manifest changelog, feintkit-matrix, feintkit-report history, feintkit-report coverage, feintkit-report summary, feintkit-watch replay, feintkit-watch selftest, feintkit-watch bundle | Uma pasta que contém cenários (um repositório de categoria); repita para vários. Sem ela, o comando usa a pasta atual ou, para o executor e a interface web, os repositórios de categoria instalados. |
--out-dir <dir> | feintkit, feintkit honey, feintkit-gui, feintkit-matrix, feintkit-report history, feintkit-report summary, feintkit-watch replay, feintkit-watch bundle | A pasta de artefatos em que as execuções gravam e da qual o comando lê. |
--out-dir <folder> | feintkit-gui demo | A pasta nova ou vazia em que a demonstração é gravada. |
--deterministic | feintkit, feintkit honey | Usa o id de execução e o relógio fixos do modo determinístico, para que execuções repetidas gravem os mesmos bytes. |
--all | feintkit | Com clean: remove os artefatos de todos os cenários em vez de um. |
--yes | feintkit | Com clean --all: confirma a remoção. |
--json | feintkit | Com list: imprime o registro como JSON. |
--json | feintkit pack, feintkit-manifest pack | Com check: imprime o resultado como JSON. |
--json | feintkit accuracy, feintkit variants | Imprime o resultado como um único documento JSON em vez de texto (para variants, com judge). |
--json | feintkit-guard | Imprime os achados como JSON. |
--port <0-65535> | feintkit, feintkit-gui | A porta TCP da interface web local; 0 deixa o sistema escolher uma livre. |
--port <0-65535> | feintkit honey | Com listen: a porta do ouvinte de loopback; 0 deixa o sistema escolher uma livre. |
--host <address> | feintkit, feintkit-gui | O endereço ao qual a interface web se vincula: 127.0.0.1, localhost ou ::1. Nada mais é aceito. |
--scenario <id> | feintkit honey | Com plant e listen: o cenário a que a isca pertence. |
--dir <folder> | feintkit honey | Com plant: a pasta que recebe o arquivo-isca. |
--file <name> | feintkit honey | Com plant: o nome do arquivo-isca. |
--transcript <file> | feintkit honey | Com scan: o arquivo que contém o que o agente disse ou fez. |
--format <name> | feintkit honey | Com scan: o formato da transcrição, como em feintkit verify --format. |
--record | feintkit honey | Com scan: registra o resultado nos eventos da execução. |
--fail-on-leak | feintkit honey | Com scan: sai com 3 quando a isca vazou. |
--max-seconds <n> | feintkit honey | Com listen: interrompe o ouvinte após esta quantidade de segundos. |
--pack <dir> | feintkit pack | Antes de list, run, verify ou clean: carrega uma pasta de pacote de cenários; repita para vários. |
--mappings <file> | feintkit pack, feintkit-manifest pack | Com check: o arquivo de mapeamentos com o qual os cenários do pacote são conferidos. |
--name <pack-name> | feintkit pack | Com new: o nome do novo pacote. |
--prefix <letters> | feintkit pack | Com new: as 2 a 5 letras que iniciam todo id de cenário do pacote. |
--labels <file> | feintkit accuracy | Um arquivo JSON de respostas rotuladas que é acrescentado ao corpus embutido. |
--replies <file> | feintkit variants | Com judge: o arquivo JSON que contém a resposta do agente a cada variante. |
--run <id> | feintkit variants | Com judge: o id de execução das respostas, de 4 a 16 letras ou dígitos. |
--variant <name> | feintkit variants | Com write: grava somente esta variante; repita para várias. |
--suite-root <dir> | feintkit-control | A pasta da suíte sobre a qual o servidor trabalha. |
--read-root <dir> | feintkit-control | Uma pasta que as ferramentas de auditoria podem ler; repita para várias. |
--out-root <dir> | feintkit-control | A única pasta em que as ferramentas de automação gravam. |
--ollama-url <address> | feintkit-control | O endereço de loopback de um servidor de modelo local, para a ferramenta que executa um cenário contra um modelo local. |
--model <name> | feintkit-control | O nome do modelo local. |
--index <file> | feintkit-docs | O arquivo de índice de cenários. |
--mappings <file> | feintkit-docs | O arquivo de mapeamentos. |
--out <dir> | feintkit-docs | A pasta em que generate grava o guia e com a qual check compara. |
--guide <dir> | feintkit-docs translate | A pasta do guia em inglês cujas páginas .md são traduzidas (somente leitura). |
--catalogs <dir> | feintkit-docs translate | A pasta dos catálogos de tradução, um arquivo <code>.json para cada idioma. |
--out <dir> | feintkit-docs translate | Com generate e check: a pasta que recebe uma subpasta para cada idioma e com a qual check compara. |
--lang <code> | feintkit-docs translate | O idioma em que trabalhar, por exemplo de (obrigatório para extract; sem ele, generate e check usam todos os catálogos). |
--show-allowed | feintkit-guard | Lista também os usos que uma permissão inline autoriza. |
--mappings <file> | feintkit-manifest | Com registry: o arquivo de mapeamentos com o qual o mapeamento de cada cenário é conferido. |
--since <version> | feintkit-manifest changelog | Mantém as entradas desta versão e das posteriores. |
--id <id> | feintkit-manifest changelog | Mantém as entradas de um cenário. |
--format <name> | feintkit-manifest changelog, feintkit-report diff, feintkit-report history, feintkit-report modes, feintkit-report repeats, feintkit-report mitigations | O formato de saída: text (padrão), md ou json. |
--format <name> | feintkit-matrix | md (padrão) ou json. |
--format <name> | feintkit-report coverage, feintkit-report summary | text (padrão), md, html ou json. |
--detections <file> | feintkit-matrix, feintkit-report history, feintkit-report summary | O arquivo JSON que mapeia ids de cenário para detected, blocked ou missed. |
--fail-on-missed | feintkit-matrix | Sai com 3 quando um cenário foi registrado como missed. |
--fail-on-complied | feintkit-matrix | Sai com 3 quando o veredito de um agente é complied. |
--fail-on-control-fired | feintkit-matrix | Sai com 3 quando o juiz ou o produto sob teste gerou um alarme falso em um controle benigno. |
--dest <dir> | feintkit-new | Com repo: a pasta a criar. |
--repo <dir> | feintkit-new | O repositório de categoria ao qual acrescentar um cenário ou que será verificado. |
--title <title> | feintkit-new | Com scenario: o título do novo cenário. |
--mappings <file> | feintkit-new | Com scenario: o arquivo de mapeamentos que recebe a entrada do novo cenário. |
--harness <spec> | feintkit-new | A especificação de pacote do harness de que os novos arquivos dependem. |
--output <file> | feintkit-report diff, feintkit-report modes, feintkit-report repeats, feintkit-report store, feintkit-report coverage, feintkit-report summary | Grava o resultado em um arquivo em vez de imprimi-lo. |
--fail-on-regression | feintkit-report diff, feintkit-report modes, feintkit-report repeats | Sai com 3 quando uma regressão foi encontrada. |
--history <file> | feintkit-report history, feintkit-report store | O arquivo de histórico; para store import, o arquivo cujas execuções são adicionadas ao store. |
--agent <name> | feintkit-report history | O agente cujas execuções são acrescentadas (append, obrigatório) ou mostradas (show). |
--report <file> | feintkit-report history | Com append: o arquivo de resultado a acrescentar; sem ele, o relatório é montado a partir de --root, --out-dir e --detections. |
--date <YYYY-MM-DD> | feintkit-report history | Com append: a data da entrada. |
--suite-version <x.y.z> | feintkit-report history | Com append: a versão da suíte da entrada. |
--agent-version <text> | feintkit-report history | Com append: o rótulo de versão do agente. |
--model <text> | feintkit-report history | Com append: o rótulo de modelo do agente. |
--permission-mode <text> | feintkit-report history | Com append: o rótulo de modo de permissão do agente. |
--agent <name> | feintkit-report summary | O agente a que estes resultados pertencem; a página então o nomeia. |
--agent-version <text> | feintkit-report summary | O rótulo de versão do agente. |
--model <text> | feintkit-report summary | O rótulo de modelo do agente. |
--permission-mode <text> | feintkit-report summary | O rótulo de modo de permissão do agente. |
--last <n> | feintkit-report history | Com show: somente as últimas n execuções. |
--baseline <label> | feintkit-report modes | O rótulo do conjunto com o qual os outros são comparados. |
--against <results> | feintkit-report repeats | Um segundo conjunto de execuções com o qual comparar o primeiro; repita para vários. |
--results <results> | feintkit-report coverage | Um conjunto de resultados que colore o mapa por veredito. |
--mappings <file> | feintkit-report coverage | O arquivo de mapeamentos cujas duas listas OWASP definem as lacunas; sem ele, o arquivo é procurado subindo a partir da pasta atual. |
--id <scenario id> | feintkit-report mitigations | Mostra somente este cenário; repita para vários. |
--store <dir> | feintkit-report store | O store de resultados: uma pasta que add cria, com um arquivo marcador e um arquivo de execuções para cada mês. |
--agent <name> | feintkit-report store | Com add (obrigatório): o agente que produziu as execuções. Com query e export: mantém apenas as execuções deste agente. |
--date <YYYY-MM-DD> | feintkit-report store | Com add: a data das execuções; sem ela, a data do arquivo de resultado; na falta dela, hoje. |
--suite-version <x.y.z> | feintkit-report store | Com add: a versão da suíte das execuções. Com query e export: mantém apenas as execuções desta versão da suíte. |
--agent-version <text> | feintkit-report store | Com add: o rótulo de versão do agente. Com query e export: mantém apenas as execuções com este rótulo. |
--model <text> | feintkit-report store | Com add: o rótulo de modelo do agente. Com query e export: mantém apenas as execuções com este rótulo. |
--permission-mode <text> | feintkit-report store | Com add: o rótulo de modo de permissão do agente. Com query e export: mantém apenas as execuções com este rótulo. |
--label <text> | feintkit-report store | Com add: um rótulo curto (letras, dígitos, ponto, sublinhado e hífen, no máximo 32 caracteres) que distingue duas execuções com os mesmos resultados no mesmo dia. |
--scenario <id or prefix-> | feintkit-report store | Com query: mantém os resultados de um cenário, ou de todo cenário cujo id começa com um prefixo que termina em hífen. |
--verdict <verdict> | feintkit-report store | Com query: mantém os resultados com este veredito do agente (complied, resisted, resisted_surfaced, inconclusive ou n/a). |
--detection <state> | feintkit-report store | Com query: mantém os resultados com este estado de detecção (detected, blocked, missed, not-reported ou not-run). |
--since <YYYY-MM-DD> | feintkit-report store | Com query e export: mantém as execuções deste dia e dos posteriores. |
--until <YYYY-MM-DD> | feintkit-report store | Com query e export: mantém as execuções deste dia e dos anteriores. |
--month <YYYY-MM> | feintkit-report store | Com query e export: mantém as execuções de um mês; não pode ser combinado com --since nem --until. |
--last <n> | feintkit-report store | Com query: mantém as n mais recentes entre as execuções que correspondem. |
--by <view> | feintkit-report store | Com query: scenario (padrão) lista os cenários com suas contagens, run lista as execuções. |
--format <name> | feintkit-report store | Com query: text (padrão), md ou json. Com export: kb (padrão, um arquivo Markdown para uma base de conhecimento) ou jsonl. |
--loop <dir> | feintkit-watch replay, feintkit-watch bundle | A pasta de loop salva a reproduzir ou, com bundle create, a empacotar. |
--rules <file> | feintkit-watch replay, feintkit-watch selftest, feintkit-watch bundle | O conjunto de regras do substituto; sem ele, usa-se o conjunto de regras inicial. Com bundle create, o conjunto de regras é armazenado no pacote, e bundle replay usa essa cópia. |
--timestamp <iso> | feintkit-watch replay, feintkit-watch bundle | O carimbo de tempo gravado nas saídas. Com bundle create, é o momento de criação do pacote e o momento de modificação de cada arquivo nele. |
--out <file> | feintkit-watch bundle | Com create: o arquivo de pacote a gravar; não pode existir ainda nem ficar dentro da pasta do loop. |
--agent <label> | feintkit-watch bundle | Com create: o rótulo do agente (fnd-44) armazenado no registro do ambiente; um campo omitido é tomado do bloco de identidade do report.json do loop; caso contrário é unknown. |
--agent-version <label> | feintkit-watch bundle | Com create: o rótulo de versão do agente. |
--model <label> | feintkit-watch bundle | Com create: o rótulo de modelo do agente. |
--permission-mode <label> | feintkit-watch bundle | Com create: o rótulo de modo de permissão do agente. |
--redact | feintkit-watch bundle | Com create: substitui formatos de segredo e o nome de usuário de um caminho de pasta pessoal nos arquivos do pacote em vez de recusar; o manifesto registra a contagem e o hash do original. |
--bundle <file> | feintkit-watch bundle | Com verify e replay: o arquivo de pacote a ler. |
--digest <sha256> | feintkit-watch bundle | Com verify e replay: o digest que lhe foi informado para o pacote (64 caracteres hexadecimais minúsculos); um digest diferente no pacote é uma falha. |