The authoritative text is the English page: English version of this page
Las herramientas de la suite: instalar, juzgar, detectar, informar, mantener los datos al día
Cinco herramientas rodean al ejecutor de escenarios (feintkit, véase DETECTION-INTEGRATION.md). Esta página da los comandos exactos, las opciones, los códigos de salida y los ejemplos sin conexión de cada una. Las líneas de comandos y las opciones se comprueban contra las herramientas reales mediante las pruebas del paquete de documentación. Lea primero RESPONSIBLE-USE.md.
| Paso | Herramienta | Comando | Necesita red |
|---|---|---|---|
| Instalar | instalador (feintkit-suite) | node packages/installer/dist/src/bin.js | solo para un origen https |
| Ejecutar | ejecutor (feintkit) | véase DETECTION-INTEGRATION.md | no |
| Juzgar una transcripción | ingesta de transcripciones, usada mediante feintkit verify | node packages/cli/dist/src/bin.js | no |
| Sustituir a un producto de seguridad | sustituto de prueba de detección (feintkit-watch) | node packages/watch/dist/src/bin.js | no |
| Informar | informe (feintkit-report) | node packages/report/dist/src/bin.js | no |
| Mantener los datos al día | verificación de hechos (feintkit-factcheck) | node packages/factcheck/dist/src/bin.js | sí |
Ejecute cada comando desde la raíz del repositorio de la suite después de npm run setup. Una línea que termina con # exit <n> en un ejemplo muestra el código de salida que devuelve el comando; omita el comentario al escribirlo. <work> representa cualquier directorio vacío que usted elija.
Instalador (feintkit-suite)
Propósito: desempaqueta la suite desde un directorio, un tarball de versión o una dirección https, comprueba el tarball contra una suma de verificación que usted proporciona desde un canal aparte, muestra el aviso de descargo de responsabilidad y un plan de lo que hará, y desempaqueta. No ejecuta la compilación de la suite a menos que se pase --run-setup; con esa opción, ejecuta npm run setup --ignore-scripts con un entorno mínimo, lista los escenarios e imprime los pasos siguientes. Se niega a ejecutarse como root salvo que se le indique otra cosa y nunca sobrescribe un directorio que no sea una instalación propia. Volver a ejecutarlo sobre una instalación terminada imprime already installed.
Dónde encaja: el primer paso, en una máquina que aún no tiene la suite. Los mantenedores que ya trabajan en una copia de trabajo no lo necesitan.
Uso (el texto de la propia herramienta):
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| Opción | Significado |
|---|---|
--from <source> | Un directorio, un archivo .tar.gz o una dirección https. Sin ella, la dirección se construye a partir de FEINTKIT_RELEASE_BASE. |
--sha256 <hex> | El SHA-256 esperado del tarball, tomado de un canal distinto de la descarga. No se puede combinar con --checksums. Un tarball necesita --sha256 o --checksums; un directorio no admite ninguno de los dos. |
--checksums <file or https address> | Un archivo SHA256SUMS que lista el tarball. Pase un archivo local que haya obtenido por separado. Una dirección https (también la construida a partir de FEINTKIT_RELEASE_BASE) procede del mismo origen que la descarga y se rechaza a menos que también se indique --trust-remote-checksums. |
--trust-remote-checksums | Acepta un archivo de sumas de verificación obtenido del mismo origen que el tarball e imprime una advertencia: quien controla ese origen controla lo que se desempaqueta. |
--dest <directory> | Dónde instalar. Valor predeterminado: feintkit-suite en el directorio actual. |
--allow-root | Permite la ejecución como usuario root. |
--force | Reemplaza una instalación que contiene otra versión o una compilación sin terminar. |
--run-setup | Ejecuta npm run setup --ignore-scripts de la suite tras desempaquetar, con un entorno mínimo (se ejecuta el script setup del paquete que desempaquetó; los scripts de instalación de las dependencias no). Sin esta opción no se ejecuta nada y se imprime el comando exacto. |
--skip-build | El valor predeterminado, conservado para líneas de comandos antiguas: solo desempaqueta. No se puede combinar con --run-setup. |
--accept-disclaimer | Reconoce el aviso sin pedir confirmación. Una sesión que no es interactiva lo necesita. |
--version, --help | Imprimen la versión o el texto de uso y terminan con 0. |
Códigos de salida:
| Código | Significado |
|---|---|
| 0 | Instalado, ya instalado, o --help / --version. |
| 2 | Error de uso (también: --sha256 y --checksums a la vez, --run-setup y --skip-build a la vez, ningún origen, una suma de verificación con un origen de directorio, o una suma de verificación https sin --trust-remote-checksums). |
| 3 | Fallo de integridad: origen no encontrado, ninguna suma de verificación para un tarball, suma de verificación que no coincide, tarball defectuoso o descarga fallida. |
| 4 | Se negó a ejecutarse como root sin --allow-root. |
| 5 | Problema con el destino: no es una instalación de Feintkit, es una instalación distinta sin --force, o fallo de escritura. |
| 6 | Falló la configuración (setup) o el listado de escenarios. |
| 7 | No se reconoció el aviso de descargo de responsabilidad. |
Ejemplos sin conexión (un directorio local como origen, no se descarga nada y no se ejecuta nada del paquete):
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 3El aviso se muestra y se reconoce antes de leer cualquier origen, por lo que toda instalación necesita --accept-disclaimer en una sesión que no es interactiva. La primera instalación se rechaza porque la sesión del ejemplo no es interactiva; la segunda reconoce el aviso y desempaqueta docs/guide como si fuera la suite, sin ejecutar nada. Una instalación real usa su propio origen --from y un valor --sha256 o --checksums local de un segundo canal, y añade --run-setup solo después de haber leído el script setup del paquete.
Ingesta de transcripciones (feintkit verify --transcript)
Propósito: convierte una transcripción guardada de un agente en el texto plano que juzga la regla de veredicto, de modo que el veredicto mire solo lo que el agente dijo e hizo y no el formato del registro que lo rodea. Es una biblioteca sin comando propio; el ejecutor la usa cuando se da --format a verify.
Dónde encaja: después de que un escenario se ejecutó contra su agente y usted guardó la salida del agente, para juzgar si el agente cumplió la instrucción inyectada.
Uso (la línea verify del propio texto de uso del ejecutor):
verify <id> [--transcript <file>] [--format <name>] [--strict] [--record] [--fail-on-complied] [--deterministic]| Opción | Significado |
|---|---|
--transcript <file> | La transcripción guardada. Sin --format, el archivo se juzga tal cual, como texto plano. |
--format <name> | Lee el archivo con un formato con nombre, o auto para detectarlo. Necesita --transcript. Nombres: claude-stream-json, anthropic-messages, openai-chat, plain. |
--strict | Con --format: una transcripción que no se puede leer exactamente es un error en lugar de una nota. Necesita --format. |
--record | Escribe el veredicto en el events.jsonl del escenario como un evento agent_outcome, que el informe muestra después. |
--fail-on-complied | Termina con 3 cuando el veredicto es complied. |
--deterministic | Usa el id de ejecución fijo RUN0000, como en la ejecución. |
Códigos de salida de verify:
| Código | Significado |
|---|---|
| 0 | Las comprobaciones de artefactos pasaron (y el agente no cumplió, o no se indicó --fail-on-complied). |
| 1 | Falló una comprobación de artefactos, o no se encontró el escenario o su ejecución. |
| 2 | Error de uso, o no se pudo leer ni ingerir la transcripción (el mensaje empieza con cannot ingest transcript). |
| 3 | Se indicó --fail-on-complied y el veredicto es complied. |
Con --format, el formato y las notas se imprimen en el flujo de error (transcript format: <name> (named|detected)). Una transcripción de más de 16777216 bytes se rechaza.
Ejemplos sin conexión (las propias páginas de la guía sirven como texto de la transcripción: MARKERS.md contiene el token de confirmación de ejemplo de una ejecución determinista, RESPONSIBLE-USE.md no):
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 2El segundo comando imprime verdict: resisted, el tercero imprime verdict: complied y termina con 3, y el cuarto es un error de uso porque --format necesita --transcript.
Sustituto de prueba de detección (feintkit-watch)
Propósito: un sustituto deliberadamente simple de un producto de seguridad, para poder ejercitar de extremo a extremo la columna Detección de la matriz de cobertura y del informe. Lee lo que un agente bajo prueba hizo y vio (las llamadas a herramientas, el contenido de los resultados de herramientas, el texto del assistant y el texto de las skills cargadas de una transcripción guardada o canalizada de una sesión headless, o una lista simple de comandos de shell, uno por línea), compara cada llamada y cada fragmento de contenido con un pequeño archivo de reglas legible (packages/watch/rules/starter.json) y escribe el archivo de detecciones que leen feintkit-matrix y feintkit-report (--detections), además de un archivo de evidencia. Es un artefacto de prueba y un ejemplo práctico de lo que un producto debe registrar y en qué formato. No es un producto de seguridad, y cada línea que imprime lo dice.
Dónde encaja: después de que un escenario se ejecutó contra su agente y usted guardó la salida del agente, antes de la matriz o del informe. Tres límites forman parte del diseño. Solo observa: ve una llamada después de que el agente decidió y no puede detenerla, así que un resultado blocked es un veredicto de política etiquetado enforcement: simulated, nunca un rechazo real. Ve el flujo de la sesión, no el protocolo ni la red: 9 de los 42 escenarios ponen su señal en tráfico de protocolo, tráfico de red, píxeles o un frontmatter que el cliente elimina, por lo que la herramienta no escribe ninguna entrada para ellos y la matriz conserva not-reported; nunca afirma missed para algo que no puede ver, e informa missed solo para los once escenarios cuyo veredicto del agente demuestra que la señal pasó por el flujo, cuando el veredicto es complied y ninguna regla coincidió. El token de confirmación de una respuesta es el veredicto del agente, no una detección, y ninguna regla lo lee. La mayoría de las reglas iniciales comparan las propias cadenas de la suite, por lo que un resultado en verde en esas filas es una evidencia circular; el archivo de reglas marca cada regla como marker o behaviour. Un blocked o detected de esta herramienta no es evidencia sobre ningún producto. Nombre el archivo de detecciones detections.feintkit-watch.json para que su origen sea visible en la línea de comandos y en los registros de CI.
Para ejecutarlo sobre muchos escenarios con un agente real, use el bucle de ejemplo docs/examples/real-agent-loop.sh (agente, juez, análisis con --merge, matriz e informe; se puede detener y volver a iniciar). La versión paso a paso está en DETECTION-INTEGRATION.md, sección 5.
Uso (el texto de la propia herramienta):
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>]...| Opción | Significado |
|---|---|
--scenario <id> | El escenario al que pertenece esta transcripción. Lo nombra usted; nunca se deduce del contenido. |
--transcript <file> | La transcripción guardada (scan); tee lee la entrada estándar en su lugar. |
--map <file> | Un mapa JSON de varias ejecuciones (schemaVersion 1 y runs, cada una con scenario, transcript y opcionalmente events o verdict); las rutas son relativas al mapa. No se puede combinar con --scenario, --transcript, --verdict ni --events. |
--rules <file> | El archivo de reglas. |
--out <file> | El archivo de detecciones que se escribirá (un objeto plano de id de escenario a detected, blocked o missed). |
--evidence <file> | También escribe el archivo de evidencia: una línea JSON por coincidencia, truncada al texto coincidente, más una línea de resumen. Con export es el archivo de evidencia que se lee; con import es un archivo opcional para los eventos importados. |
--merge | Lee los archivos de detecciones y de evidencia existentes y reemplaza solo el escenario analizado. Un archivo ausente cuenta como vacío; uno no válido es un error y no se toca. |
--format <name> | scan y tee: auto (predeterminado), stream-json o command-log. export: jsonl, sarif o csv (obligatorio). |
--verdict <v> | El veredicto del agente de feintkit verify: complied, resisted, resisted_surfaced o inconclusive. Sin un veredicto no se puede decidir missed. |
--events <file> | Lee el veredicto del último evento agent_outcome de un events.jsonl. No se puede combinar con --verdict. |
--root <dir> | Un repositorio de categoría que contiene escenarios; repítalo para varios. Valor predeterminado: el directorio actual. |
--timestamp <time> | Fija la hora de las líneas de evidencia, en la forma exacta YYYY-MM-DDTHH:MM:SS.mmmZ. Con FEINTKIT_DETERMINISTIC=1 la hora queda fija en su lugar. |
--fail-on-missed | Termina con 3 cuando un escenario analizado es missed, después de escribir los archivos. |
--input <file> | Solo import: los eventos JSON Lines de un producto real (forma más abajo). |
--source <name> | Solo import: el nombre del producto (1 a 64 letras, dígitos, espacio, punto, guion bajo o guion; no puede contener feintkit-watch ni stand-in). Pasa a ser el product de cada evento importado. |
tee pasa la entrada estándar a la salida estándar sin cambios y hace el mismo trabajo que scan al final de la entrada, imprimiendo sus líneas en el flujo de error; check-rules valida un archivo de reglas y sus controles e imprime la línea honesta de cobertura.
Exportación e importación (solo observación, sin conexión; las formas exactas están en la especificación fnd-18-watch, Amendment 1.2). export --evidence <file> --format jsonl|sarif|csv --out <file> lee el archivo de evidencia y escribe uno de tres formatos. jsonl es un evento por línea con las claves estables schema, product, stand_in, timestamp (ISO-8601), event (detection o missed), scenario, rule, action (detect o block, y un bloqueo es simulado), basis (marker o behaviour), enforcement, tool, evidence (el fragmento que ya está censurado y recortado a 200 caracteres) y location (path:line de la transcripción). csv tiene las mismas columnas, con un apóstrofo inicial en cualquier celda que una hoja de cálculo leería como fórmula. sarif es un registro SARIF 2.1.0 cuyo controlador de herramienta dice expresamente que es un SUSTITUTO DE PRUEBA y no un producto de seguridad; cada resultado tiene el id de la regla, un mensaje, el escenario como ubicación lógica y, cuando la ruta de la transcripción es relativa, la línea de la transcripción como ubicación física. import --input <file> --source <name> --out <file> va en sentido contrario: un producto real que escribe la misma forma JSON Lines (solo scenario y action son obligatorios para una detección; event missed marca un escenario que se ejecutó y no se informó; las claves desconocidas se ignoran) obtiene su propio archivo de detecciones para --detections. Los resultados del sustituto y del producto nunca se mezclan: --source es obligatorio, los eventos importados lo conservan como su product con stand_in en false, se rechaza un registro del propio sustituto y se rechaza para la salida un nombre de archivo que contenga feintkit-watch. Compare ambos dando a la matriz o al informe un solo archivo de detecciones a la vez.
Códigos de salida:
| Código | Significado |
|---|---|
| 0 | Hecho (también cuando no se escribió ninguna entrada para el escenario). |
| 1 | No se pudo escribir un archivo de salida. |
| 2 | Error de uso, una entrada ilegible o no válida, reglas no válidas o un escenario desconocido. |
| 3 | Se indicó --fail-on-missed y un escenario analizado es missed. |
Ejemplos sin conexión (las transcripciones son los archivos de prueba del paquete; el segundo comando escribe el archivo de detecciones que lee el primer ejemplo de informe más abajo):
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 2El segundo comando imprime mcp-08-exfil-sim blocked (1 rule hit; enforcement: simulated, nothing was stopped) y una línea que dice que 39 de 48 escenarios tienen una regla. El tercero no tiene ninguna coincidencia de regla, el veredicto es complied, por lo que el resultado es missed y el código de salida es 3. El cuarto no puede escribir porque la ruta de salida es un directorio.
Informe (feintkit-report)
Propósito: genera un informe de resultados a partir de los manifiestos de los escenarios, los artefactos de las ejecuciones y, cuando se lo da, su registro de detección. El informe lista por escenario el resultado de los artefactos, el veredicto del agente, el resultado de la detección y las correspondencias con ATLAS y OWASP, y termina con un resumen por técnica de ATLAS. Formatos: md (predeterminado), json, html, sarif, junit (JUnit XML para un sistema de CI, véase AUTOMATION.md).
Dónde encaja: después de las ejecuciones y los juicios, para entregar los resultados a alguien o para controlar un trabajo de CI. La matriz de cobertura (feintkit-matrix, DETECTION-INTEGRATION.md) es la vista más breve de los mismos datos.
Uso (el texto de la propia herramienta):
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]| Opción | Significado |
|---|---|
--root <dir> | Un repositorio de categoría que contiene escenarios; repítalo para varios. Valor predeterminado: el directorio actual. |
--out-dir <dir> | El directorio de artefactos de las ejecuciones (el mismo que el del ejecutor). |
--detections <file> | Archivo JSON que asocia ids de escenario con detected, blocked o missed. |
--format <name> | json, md, html, sarif o junit. Valor predeterminado md. |
--output <file> | Escribe el informe en un archivo en lugar de imprimirlo. |
--timestamp <time> | Fija la hora de generación, en la forma exacta YYYY-MM-DDTHH:MM:SS.mmmZ. Con FEINTKIT_DETERMINISTIC=1 la hora queda fija en su lugar. |
--agent <name>, --agent-version <text>, --model <text>, --permission-mode <text> | Registran qué agente produjo los resultados (fnd-44): el informe lleva entonces una identidad del agente, y los informes markdown y html imprimen una línea Agent under test. Cada una es una etiqueta simple y corta, de como máximo 64 caracteres, rechazada con salida 2 cuando parece un secreto; un campo que omita es unknown. Nada inicia el agente para averiguarlas. |
--mitigations | Añade las notas revisadas para defensores (qué restringir, qué regla añadir, qué ajuste cambiar) para cada escenario que tiene un hallazgo: una sección en md y html, el texto de ayuda de la regla en sarif, el texto del fallo en junit. Se rechaza con json, cuya estructura es fija. Véase AUTOMATION.md. |
--fail-on-missed | Termina con 3 cuando un escenario se registró como missed. |
--fail-on-complied | Termina con 3 cuando un veredicto de agente es complied. |
--fail-on-control-fired | Termina con 3 cuando el juez o el producto bajo prueba dio una falsa alarma en un control benigno (un veredicto complied o resisted_surfaced, o una detección detected o blocked, para un control). |
Códigos de salida:
| Código | Significado |
|---|---|
| 0 | Se generó el informe y no se aplicó ninguna condición de fallo. |
| 1 | Un error del registro de escenarios (las líneas que empiezan con FAIL en el flujo de error). El informe se genera de todos modos. |
| 2 | Error de uso, un archivo de detecciones ilegible o no válido, o no se pudo escribir el archivo de salida. |
| 3 | Se aplicó --fail-on-missed, --fail-on-complied o --fail-on-control-fired. |
Ejemplos sin conexión (usan la ejecución de los ejemplos de transcripción anteriores y, el cuarto, el archivo de detecciones del sustituto anterior; el primero no escribe nada fuera 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 2Verificación de hechos (feintkit-factcheck)
Propósito: vuelve a leer cada frase de la documentación de los proveedores que cita CLIENTS.md y ejecuta la comprobación de las fuentes de correspondencias (scripts/verify-mappings.py --online), para detectar la deriva de esas fuentes. Con --write registra la fecha de cada dato encontrado en docs/guide/facts-verified.json; las guías muestran esa fecha.
Dónde encaja: mantenimiento, de forma programada (cada pocos días) y antes de una versión. Es la única herramienta de aquí que necesita red: cada comprobación es una solicitud saliente a las páginas citadas. Los usuarios corrientes de la suite no la necesitan.
Uso (el texto de la propia herramienta):
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| Opción | Significado |
|---|---|
--repo <dir> | La raíz de la suite. Valor predeterminado: el directorio actual. |
--facts-file <file> | Dónde registra --write las fechas. Valor predeterminado: docs/guide/facts-verified.json bajo --repo. |
--write | Registra la fecha de hoy para cada dato encontrado. No se puede combinar con --skip-facts. |
--report <file> | Escribe un informe; un nombre que termina en .json da JSON, cualquier otro da Markdown. |
--skip-facts | No comprueba las frases citadas. |
--skip-mappings | No ejecuta la comprobación de las fuentes de correspondencias. Indicar ambas omisiones es un error de uso. |
--delay <ms> | Pausa entre dos solicitudes. Valor predeterminado 1000. |
--timeout <ms> | Límite de tiempo de una solicitud. Valor predeterminado 30000. |
Códigos de salida:
| Código | Significado |
|---|---|
| 0 | Todo se encontró y coincide. |
| 1 | Deriva: no se encontró una frase, una página se movió o respondió con un estado de error, o una fuente de mapeos difiere. |
| 2 | Error de uso. |
| 3 | Fallo de red y ninguna deriva. |
Ejemplos sin conexión (solo los errores de uso pueden ejecutarse sin red; una comprobación real es node packages/factcheck/dist/src/bin.js y envía solicitudes):
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 2Opciones de los demás comandos
La suite tiene más herramientas de línea de comandos y subcomandos que las cinco anteriores. Esta tabla lista cada opción del texto de uso de cada una de ellas, con el comando que la acepta: el ejecutor (feintkit) y sus comandos honey, pack, accuracy y variants, el servidor de control, el generador de documentación y su comando translate, el guard, la interfaz web, la herramienta de manifiestos, la matriz de cobertura, la herramienta de andamiaje, los subcomandos diff, history, modes, repeats, store, coverage, summary y mitigations de feintkit-report, y los subcomandos replay, selftest y bundle de feintkit-watch. Cada comando imprime su propio texto de uso cuando se le pasa una opción desconocida. Las opciones de feintkit verify están en la sección sobre la ingesta de transcripciones, y las de las cinco herramientas anteriores están en sus propias tablas.
| Opción | 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 | Una carpeta que contiene escenarios (un repositorio de categoría); repítala para varias. Sin ella, el comando usa la carpeta actual o, para el ejecutor y la interfaz web, los repositorios de categoría instalados. |
--out-dir <dir> | feintkit, feintkit honey, feintkit-gui, feintkit-matrix, feintkit-report history, feintkit-report summary, feintkit-watch replay, feintkit-watch bundle | La carpeta de artefactos en la que escriben las ejecuciones y de la que lee el comando. |
--out-dir <folder> | feintkit-gui demo | La carpeta nueva o vacía en la que se escribe la demostración. |
--deterministic | feintkit, feintkit honey | Usa el id de ejecución y el reloj fijos del modo determinista, de modo que las ejecuciones repetidas escriben los mismos bytes. |
--all | feintkit | Con clean: elimina los artefactos de todos los escenarios en lugar de uno. |
--yes | feintkit | Con clean --all: confirma la eliminación. |
--json | feintkit | Con list: imprime el registro como JSON. |
--json | feintkit pack, feintkit-manifest pack | Con check: imprime el resultado como JSON. |
--json | feintkit accuracy, feintkit variants | Imprime el resultado como un solo documento JSON en lugar de texto (para variants, con judge). |
--json | feintkit-guard | Imprime los hallazgos como JSON. |
--port <0-65535> | feintkit, feintkit-gui | El puerto TCP de la interfaz web local; 0 deja que el sistema elija uno libre. |
--port <0-65535> | feintkit honey | Con listen: el puerto del oyente de loopback; 0 deja que el sistema elija uno libre. |
--host <address> | feintkit, feintkit-gui | La dirección a la que se enlaza la interfaz web: 127.0.0.1, localhost o ::1. No se acepta nada más. |
--scenario <id> | feintkit honey | Con plant y listen: el escenario al que pertenece el cebo. |
--dir <folder> | feintkit honey | Con plant: la carpeta que recibe el archivo cebo. |
--file <name> | feintkit honey | Con plant: el nombre del archivo cebo. |
--transcript <file> | feintkit honey | Con scan: el archivo que contiene lo que el agente dijo o hizo. |
--format <name> | feintkit honey | Con scan: el formato de la transcripción, como para feintkit verify --format. |
--record | feintkit honey | Con scan: registra el resultado en los eventos de la ejecución. |
--fail-on-leak | feintkit honey | Con scan: termina con 3 cuando el cebo se filtró. |
--max-seconds <n> | feintkit honey | Con listen: detiene el oyente después de esta cantidad de segundos. |
--pack <dir> | feintkit pack | Delante de list, run, verify o clean: carga una carpeta de paquete de escenarios; repítala para varias. |
--mappings <file> | feintkit pack, feintkit-manifest pack | Con check: el archivo de correspondencias contra el que se comprueban los escenarios del paquete. |
--name <pack-name> | feintkit pack | Con new: el nombre del nuevo paquete. |
--prefix <letters> | feintkit pack | Con new: las 2 a 5 letras con las que empieza cada id de escenario del paquete. |
--labels <file> | feintkit accuracy | Un archivo JSON de respuestas etiquetadas que se añade al corpus integrado. |
--replies <file> | feintkit variants | Con judge: el archivo JSON que contiene la respuesta del agente a cada variante. |
--run <id> | feintkit variants | Con judge: el id de ejecución de las respuestas, de 4 a 16 letras o dígitos. |
--variant <name> | feintkit variants | Con write: escribe solo esta variante; repítala para varias. |
--suite-root <dir> | feintkit-control | La carpeta de la suite sobre la que trabaja el servidor. |
--read-root <dir> | feintkit-control | Una carpeta que las herramientas de auditoría pueden leer; repítala para varias. |
--out-root <dir> | feintkit-control | La única carpeta en la que escriben las herramientas de automatización. |
--ollama-url <address> | feintkit-control | La dirección de loopback de un servidor de modelos local, para la herramienta que ejecuta un escenario contra un modelo local. |
--model <name> | feintkit-control | El nombre del modelo local. |
--index <file> | feintkit-docs | El archivo de índice de escenarios. |
--mappings <file> | feintkit-docs | El archivo de correspondencias. |
--out <dir> | feintkit-docs | La carpeta en la que generate escribe la guía y con la que check compara. |
--guide <dir> | feintkit-docs translate | La carpeta de la guía en inglés cuyas páginas .md se traducen (solo lectura). |
--catalogs <dir> | feintkit-docs translate | La carpeta de los catálogos de traducción, un archivo <code>.json por cada idioma. |
--out <dir> | feintkit-docs translate | Con generate y check: la carpeta que recibe una subcarpeta por cada idioma y con la que check compara. |
--lang <code> | feintkit-docs translate | El idioma con el que trabajar, por ejemplo de (obligatorio para extract; sin ella, generate y check toman todos los catálogos). |
--show-allowed | feintkit-guard | También lista los usos que permite una excepción en línea. |
--mappings <file> | feintkit-manifest | Con registry: el archivo de correspondencias contra el que se comprueba la correspondencia de cada escenario. |
--since <version> | feintkit-manifest changelog | Conserva las entradas de esta versión y de las posteriores. |
--id <id> | feintkit-manifest changelog | Conserva las entradas de un escenario. |
--format <name> | feintkit-manifest changelog, feintkit-report diff, feintkit-report history, feintkit-report modes, feintkit-report repeats, feintkit-report mitigations | El formato de salida: text (predeterminado), md o json. |
--format <name> | feintkit-matrix | md (predeterminado) o json. |
--format <name> | feintkit-report coverage, feintkit-report summary | text (predeterminado), md, html o json. |
--detections <file> | feintkit-matrix, feintkit-report history, feintkit-report summary | El archivo JSON que asocia ids de escenario con detected, blocked o missed. |
--fail-on-missed | feintkit-matrix | Termina con 3 cuando un escenario se registró como missed. |
--fail-on-complied | feintkit-matrix | Termina con 3 cuando un veredicto de agente es complied. |
--fail-on-control-fired | feintkit-matrix | Termina con 3 cuando el juez o el producto bajo prueba dio una falsa alarma en un control benigno. |
--dest <dir> | feintkit-new | Con repo: la carpeta que se crea. |
--repo <dir> | feintkit-new | El repositorio de categoría al que se añade un escenario o que se comprueba. |
--title <title> | feintkit-new | Con scenario: el título del nuevo escenario. |
--mappings <file> | feintkit-new | Con scenario: el archivo de correspondencias que recibe la entrada del nuevo escenario. |
--harness <spec> | feintkit-new | La especificación de paquete del arnés del que dependen los archivos nuevos. |
--output <file> | feintkit-report diff, feintkit-report modes, feintkit-report repeats, feintkit-report store, feintkit-report coverage, feintkit-report summary | Escribe el resultado en un archivo en lugar de imprimirlo. |
--fail-on-regression | feintkit-report diff, feintkit-report modes, feintkit-report repeats | Termina con 3 cuando se encontró una regresión. |
--history <file> | feintkit-report history, feintkit-report store | El archivo de historial; para store import, el archivo cuyas ejecuciones se añaden al almacén. |
--agent <name> | feintkit-report history | El agente cuyas ejecuciones se añaden (append, obligatorio) o se muestran (show). |
--report <file> | feintkit-report history | Con append: el archivo de resultados que se añade; sin él, el informe se genera a partir de --root, --out-dir y --detections. |
--date <YYYY-MM-DD> | feintkit-report history | Con append: la fecha de la entrada. |
--suite-version <x.y.z> | feintkit-report history | Con append: la versión de la suite de la entrada. |
--agent-version <text> | feintkit-report history | Con append: la etiqueta de versión del agente. |
--model <text> | feintkit-report history | Con append: la etiqueta de modelo del agente. |
--permission-mode <text> | feintkit-report history | Con append: la etiqueta del modo de permisos del agente. |
--agent <name> | feintkit-report summary | El agente al que pertenecen estos resultados; la página lo nombra entonces. |
--agent-version <text> | feintkit-report summary | La etiqueta de versión del agente. |
--model <text> | feintkit-report summary | La etiqueta de modelo del agente. |
--permission-mode <text> | feintkit-report summary | La etiqueta del modo de permisos del agente. |
--last <n> | feintkit-report history | Con show: solo las últimas n ejecuciones. |
--baseline <label> | feintkit-report modes | La etiqueta del conjunto con el que se comparan los demás. |
--against <results> | feintkit-report repeats | Un segundo conjunto de ejecuciones con el que comparar el primero; repítala para varios. |
--results <results> | feintkit-report coverage | Un conjunto de resultados que colorea el mapa según el veredicto. |
--mappings <file> | feintkit-report coverage | El archivo de correspondencias cuyas dos listas de OWASP definen las lagunas; sin él, el archivo se busca hacia arriba desde la carpeta actual. |
--id <scenario id> | feintkit-report mitigations | Muestra solo este escenario; repítala para varios. |
--store <dir> | feintkit-report store | El almacén de resultados: una carpeta que crea add, con un archivo marcador y un archivo de ejecuciones por cada mes. |
--agent <name> | feintkit-report store | Con add (obligatorio): el agente que produjo las ejecuciones. Con query y export: conserva solo las ejecuciones de este agente. |
--date <YYYY-MM-DD> | feintkit-report store | Con add: la fecha de las ejecuciones; sin ella, la fecha del archivo de resultados y, si no, hoy. |
--suite-version <x.y.z> | feintkit-report store | Con add: la versión de la suite de las ejecuciones. Con query y export: conserva solo las ejecuciones de esta versión de la suite. |
--agent-version <text> | feintkit-report store | Con add: la etiqueta de versión del agente. Con query y export: conserva solo las ejecuciones con esta etiqueta. |
--model <text> | feintkit-report store | Con add: la etiqueta de modelo del agente. Con query y export: conserva solo las ejecuciones con esta etiqueta. |
--permission-mode <text> | feintkit-report store | Con add: la etiqueta del modo de permisos del agente. Con query y export: conserva solo las ejecuciones con esta etiqueta. |
--label <text> | feintkit-report store | Con add: una etiqueta corta (letras, dígitos, punto, guion bajo y guion, como máximo 32 caracteres) que distingue dos ejecuciones con los mismos resultados el mismo día. |
--scenario <id or prefix-> | feintkit-report store | Con query: conserva los resultados de un escenario, o de todos los escenarios cuyo id empieza con un prefijo que termina en guion. |
--verdict <verdict> | feintkit-report store | Con query: conserva los resultados con este veredicto del agente (complied, resisted, resisted_surfaced, inconclusive o n/a). |
--detection <state> | feintkit-report store | Con query: conserva los resultados con este estado de detección (detected, blocked, missed, not-reported o not-run). |
--since <YYYY-MM-DD> | feintkit-report store | Con query y export: conserva las ejecuciones de este día y posteriores. |
--until <YYYY-MM-DD> | feintkit-report store | Con query y export: conserva las ejecuciones de este día y anteriores. |
--month <YYYY-MM> | feintkit-report store | Con query y export: conserva las ejecuciones de un mes; no se puede combinar con --since ni --until. |
--last <n> | feintkit-report store | Con query: conserva las n más recientes de las ejecuciones que coinciden. |
--by <view> | feintkit-report store | Con query: scenario (predeterminado) lista los escenarios con sus recuentos, run lista las ejecuciones. |
--format <name> | feintkit-report store | Con query: text (predeterminado), md o json. Con export: kb (predeterminado, un archivo Markdown para una base de conocimiento) o jsonl. |
--loop <dir> | feintkit-watch replay, feintkit-watch bundle | La carpeta de bucle guardada que se reproduce o, con bundle create, que se empaqueta. |
--rules <file> | feintkit-watch replay, feintkit-watch selftest, feintkit-watch bundle | El conjunto de reglas del sustituto; sin él se usa el conjunto de reglas inicial. Con bundle create, el conjunto de reglas se almacena en el paquete, y bundle replay usa esa copia. |
--timestamp <iso> | feintkit-watch replay, feintkit-watch bundle | La marca de tiempo escrita en las salidas. Con bundle create es la hora de creación del paquete y la hora de modificación de cada archivo que contiene. |
--out <file> | feintkit-watch bundle | Con create: el archivo de paquete que se escribirá; no debe existir todavía ni estar dentro de la carpeta del bucle. |
--agent <label> | feintkit-watch bundle | Con create: la etiqueta del agente (fnd-44) almacenada en el registro del entorno; un campo omitido se toma del bloque de identidad del report.json del bucle y, si no, es unknown. |
--agent-version <label> | feintkit-watch bundle | Con create: la etiqueta de versión del agente. |
--model <label> | feintkit-watch bundle | Con create: la etiqueta de modelo del agente. |
--permission-mode <label> | feintkit-watch bundle | Con create: la etiqueta del modo de permisos del agente. |
--redact | feintkit-watch bundle | Con create: reemplaza las formas de secretos y el nombre de usuario de una ruta de carpeta personal en los archivos incluidos en lugar de rechazarlos; el manifiesto registra el recuento y el hash del original. |
--bundle <file> | feintkit-watch bundle | Con verify y replay: el archivo de paquete que se lee. |
--digest <sha256> | feintkit-watch bundle | Con verify y replay: el resumen que se le dio para el paquete (64 caracteres hexadecimales en minúsculas); un resumen distinto en el paquete es un fallo. |