The authoritative text is the English page: English version of this page
Les outils de la suite : installer, juger, détecter, rapporter, garder les faits à jour
Cinq outils entourent l'exécuteur de scénarios (feintkit, voir DETECTION-INTEGRATION.md). Cette page donne les commandes exactes, les options, les codes de sortie et des exemples hors ligne pour chacun. Les lignes de commande et les options sont vérifiées par rapport aux vrais outils par les tests du paquet de documentation. Lisez d'abord RESPONSIBLE-USE.md.
| Étape | Outil | Commande | Nécessite le réseau |
|---|---|---|---|
| Installer | installeur (feintkit-suite) | node packages/installer/dist/src/bin.js | uniquement pour une source https |
| Exécuter | exécuteur (feintkit) | voir DETECTION-INTEGRATION.md | non |
| Juger une transcription | ingestion de transcription, utilisée via feintkit verify | node packages/cli/dist/src/bin.js | non |
| Remplacer un produit de sécurité | substitut de test de détection (feintkit-watch) | node packages/watch/dist/src/bin.js | non |
| Rapporter | rapport (feintkit-report) | node packages/report/dist/src/bin.js | non |
| Garder les faits à jour | vérification des faits (feintkit-factcheck) | node packages/factcheck/dist/src/bin.js | oui |
Exécutez chaque commande depuis la racine du dépôt de la suite après npm run setup. Une ligne qui se termine par # exit <n> dans un exemple indique le code de sortie renvoyé par la commande ; omettez ce commentaire lorsque vous la saisissez. <work> désigne n'importe quel répertoire vide de votre choix.
Installeur (feintkit-suite)
Objectif : décompresse la suite à partir d'un répertoire, d'une archive de publication ou d'une adresse https, vérifie l'archive par rapport à une somme de contrôle que vous fournissez par un canal distinct, affiche l'avis de non-responsabilité et un plan de ce qu'il va faire, puis décompresse. Il n'exécute pas la compilation de la suite sauf si vous passez --run-setup ; avec cette option, il exécute npm run setup --ignore-scripts avec un environnement minimal, liste les scénarios et affiche les étapes suivantes. Il refuse de s'exécuter en tant que root sauf instruction contraire et n'écrase jamais un répertoire qui n'est pas sa propre installation. L'exécuter à nouveau sur une installation terminée affiche already installed.
Où il s'inscrit : la première étape, sur une machine qui n'a pas encore la suite. Les mainteneurs qui travaillent déjà dans un checkout n'en ont pas besoin.
Utilisation (le texte propre à l'outil) :
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| Option | Signification |
|---|---|
--from <source> | Un répertoire, un fichier .tar.gz ou une adresse https. Sans cette option, l'adresse est construite à partir de FEINTKIT_RELEASE_BASE. |
--sha256 <hex> | Le SHA-256 attendu de l'archive, obtenu par un canal autre que le téléchargement. Ne peut pas être combiné avec --checksums. Une archive nécessite --sha256 ou --checksums ; un répertoire n'accepte ni l'un ni l'autre. |
--checksums <file or https address> | Un fichier SHA256SUMS qui liste l'archive. Passez un fichier local obtenu séparément. Une adresse https (y compris celle construite à partir de FEINTKIT_RELEASE_BASE) provient de la même origine que le téléchargement et est refusée sauf si --trust-remote-checksums est également indiqué. |
--trust-remote-checksums | Accepte un fichier de sommes de contrôle récupéré à la même origine que l'archive et affiche un avertissement : quiconque contrôle cette origine contrôle ce qui est décompressé. |
--dest <directory> | Où installer. Par défaut : feintkit-suite dans le répertoire courant. |
--allow-root | Autorise l'exécution en tant qu'utilisateur root. |
--force | Remplace une installation qui contient une version différente ou une compilation inachevée. |
--run-setup | Exécute le npm run setup --ignore-scripts de la suite après la décompression, avec un environnement minimal (le script setup du paquet décompressé s'exécute ; les scripts d'installation des dépendances, non). Sans cette option, rien n'est exécuté et la commande exacte est affichée. |
--skip-build | Valeur par défaut, conservée pour d'anciennes lignes de commande : décompresse seulement. Ne peut pas être combiné avec --run-setup. |
--accept-disclaimer | Reconnaît l'avis sans demande de confirmation. Une session non interactive en a besoin. |
--version, --help | Affichent la version ou le texte d'utilisation et se terminent avec le code 0. |
Codes de sortie :
| Code | Signification |
|---|---|
| 0 | Installé, déjà installé, ou --help / --version. |
| 2 | Erreur d'utilisation (aussi : --sha256 et --checksums ensemble, --run-setup et --skip-build ensemble, aucune source, une somme de contrôle avec une source de type répertoire, ou une somme de contrôle https sans --trust-remote-checksums). |
| 3 | Échec d'intégrité : source introuvable, aucune somme de contrôle pour une archive, somme de contrôle non concordante, archive défectueuse, ou téléchargement échoué. |
| 4 | Refus d'exécuter en tant que root sans --allow-root. |
| 5 | Problème de destination : ce n'est pas une installation de Feintkit, une installation différente sans --force, ou un échec d'écriture. |
| 6 | Le setup ou la liste des scénarios a échoué. |
| 7 | L'avis de non-responsabilité n'a pas été reconnu. |
Exemples hors ligne (un répertoire local comme source, rien n'est téléchargé et rien du paquet ne s'exécute) :
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 3L'avis est affiché et reconnu avant la lecture de toute source ; chaque installation nécessite donc --accept-disclaimer dans une session non interactive. La première installation est refusée parce que la session de l'exemple n'est pas interactive ; la seconde reconnaît l'avis et décompresse docs/guide comme s'il s'agissait de la suite, sans rien exécuter. Une vraie installation utilise votre propre source --from et une valeur --sha256 ou --checksums locale issue d'un second canal, et n'ajoute --run-setup qu'après que vous avez lu le script setup du paquet.
Ingestion de transcription (feintkit verify --transcript)
Objectif : transforme une transcription d'agent enregistrée en texte brut que la règle de verdict juge, de sorte que le verdict ne porte que sur ce que l'agent a dit et fait et non sur le format d'enregistrement qui l'entoure. C'est une bibliothèque sans commande propre ; l'exécuteur l'utilise lorsque --format est passé à verify.
Où elle s'inscrit : après l'exécution d'un scénario contre votre agent et l'enregistrement de la sortie de l'agent, pour juger si l'agent s'est conformé à l'instruction injectée.
Utilisation (la ligne verify du texte d'utilisation propre à l'exécuteur) :
verify <id> [--transcript <file>] [--format <name>] [--strict] [--record] [--fail-on-complied] [--deterministic]| Option | Signification |
|---|---|
--transcript <file> | La transcription enregistrée. Sans --format, le fichier est jugé tel quel, comme du texte brut. |
--format <name> | Lit le fichier avec un format nommé, ou auto pour le détecter. Nécessite --transcript. Noms : claude-stream-json, anthropic-messages, openai-chat, plain. |
--strict | Avec --format : une transcription qui ne peut pas être lue exactement est une erreur au lieu d'une remarque. Nécessite --format. |
--record | Écrit le verdict dans le events.jsonl du scénario sous forme d'événement agent_outcome, que le rapport affiche ensuite. |
--fail-on-complied | Se termine avec le code 3 lorsque le verdict est complied. |
--deterministic | Utilise l'identifiant d'exécution fixe RUN0000, comme dans l'exécution. |
Codes de sortie de verify :
| Code | Signification |
|---|---|
| 0 | Les contrôles d'artefacts ont réussi (et l'agent ne s'est pas conformé, ou --fail-on-complied n'était pas indiqué). |
| 1 | Un contrôle d'artefacts a échoué, ou le scénario ou son exécution est introuvable. |
| 2 | Erreur d'utilisation, ou la transcription n'a pas pu être lue ni ingérée (le message commence par cannot ingest transcript). |
| 3 | --fail-on-complied était indiqué et le verdict est complied. |
Avec --format, le format et les éventuelles remarques sont affichés sur le flux d'erreur (transcript format: <name> (named|detected)). Une transcription de plus de 16777216 octets est rejetée.
Exemples hors ligne (les propres pages du guide servent de texte de transcription : MARKERS.md contient l'exemple de jeton d'accusé de réception d'une exécution déterministe, RESPONSIBLE-USE.md n'en contient pas) :
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 2La deuxième commande affiche verdict: resisted, la troisième affiche verdict: complied et se termine avec le code 3, et la quatrième est une erreur d'utilisation car --format nécessite --transcript.
Substitut de test de détection (feintkit-watch)
Objectif : un substitut volontairement simple d'un produit de sécurité, afin que la colonne Détection de la matrice de couverture et du rapport puisse être exercée de bout en bout. Il lit ce qu'un agent testé a fait et vu (les appels d'outils, le contenu des résultats d'outils, le texte de l'assistant et le texte du skill chargé d'une transcription de session headless enregistrée ou transmise par tube, ou une simple liste de commandes shell, une par ligne), compare chaque appel et chaque élément de contenu à un petit fichier de règles lisible (packages/watch/rules/starter.json) et écrit le fichier de détections que lisent feintkit-matrix et feintkit-report (--detections), ainsi qu'un fichier de preuves. C'est un artefact de test et un exemple concret de ce qu'un produit doit consigner et dans quel format. Ce n'est pas un produit de sécurité, et chaque ligne qu'il affiche le dit.
Où il s'inscrit : après l'exécution d'un scénario contre votre agent et l'enregistrement de la sortie de l'agent, avant la matrice ou le rapport. Trois limites font partie de la conception. Il ne fait qu'observer : il voit un appel après que l'agent l'a décidé et ne peut pas l'arrêter, de sorte qu'un résultat blocked est un verdict de politique étiqueté enforcement: simulated, jamais un véritable refus. Il voit le flux de la session, pas le protocole ni le réseau : 9 des 42 scénarios placent leur signal dans du trafic de protocole, du trafic réseau, des pixels ou un frontmatter que le client retire, l'outil n'écrit donc aucune entrée pour eux et la matrice conserve not-reported ; il ne déclare jamais missed pour ce qu'il ne peut pas voir, et ne signale missed que pour les onze scénarios dont le verdict d'agent prouve que le signal est passé par le flux, lorsque le verdict est complied et qu'aucune règle n'a correspondu. Le jeton d'accusé de réception d'une réponse est le verdict de l'agent, pas une détection, et aucune règle ne le lit. La plupart des règles de démarrage recherchent les chaînes propres à la suite, un résultat vert sur ces lignes est donc une preuve circulaire ; le fichier de règles marque chaque règle marker ou behaviour. Un blocked ou un detected issu de cet outil n'est pas une preuve concernant un produit quelconque. Nommez le fichier de détections detections.feintkit-watch.json afin que sa source soit visible dans la ligne de commande et dans les journaux de CI.
Pour l'exécuter sur de nombreux scénarios avec un agent réel, utilisez la boucle d'exemple docs/examples/real-agent-loop.sh (agent, juge, analyse avec --merge, matrice et rapport ; elle peut être arrêtée puis relancée). La version pas à pas se trouve dans DETECTION-INTEGRATION.md, section 5.
Utilisation (le texte propre à l'outil) :
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>]...| Option | Signification |
|---|---|
--scenario <id> | Le scénario auquel appartient cette transcription. Il est nommé par vous, jamais deviné à partir du contenu. |
--transcript <file> | La transcription enregistrée (scan) ; tee lit l'entrée standard à la place. |
--map <file> | Une table JSON de plusieurs exécutions (schemaVersion 1 et runs, chacune avec scenario, transcript et éventuellement events ou verdict) ; les chemins sont relatifs à la table. Ne peut pas être combiné avec --scenario, --transcript, --verdict ou --events. |
--rules <file> | Le fichier de règles. |
--out <file> | Le fichier de détections à écrire (un objet plat associant un identifiant de scénario à detected, blocked ou missed). |
--evidence <file> | Écrit aussi le fichier de preuves : une ligne JSON par correspondance, tronquée au texte trouvé, plus une ligne de synthèse. Avec export, c'est le fichier de preuves à lire ; avec import, c'est un fichier facultatif pour les événements importés. |
--merge | Lit les fichiers de détections et de preuves existants et ne remplace que le scénario analysé. Un fichier manquant compte comme vide ; un fichier invalide est une erreur et n'est pas modifié. |
--format <name> | scan et tee : auto (par défaut), stream-json ou command-log. export : jsonl, sarif ou csv (obligatoire). |
--verdict <v> | Le verdict d'agent de feintkit verify : complied, resisted, resisted_surfaced ou inconclusive. Sans verdict, missed ne peut pas être décidé. |
--events <file> | Lit le verdict dans le dernier événement agent_outcome d'un events.jsonl. Ne peut pas être combiné avec --verdict. |
--root <dir> | Un dépôt de catégorie qui contient des scénarios ; à répéter pour en indiquer plusieurs. Par défaut : le répertoire courant. |
--timestamp <time> | Définit l'heure des lignes de preuves, sous la forme exacte YYYY-MM-DDTHH:MM:SS.mmmZ. Avec FEINTKIT_DETERMINISTIC=1, l'heure est fixe à la place. |
--fail-on-missed | Se termine avec le code 3 lorsqu'un scénario analysé est missed, une fois les fichiers écrits. |
--input <file> | import uniquement : les événements JSON Lines d'un vrai produit (forme ci-dessous). |
--source <name> | import uniquement : le nom du produit (1 à 64 lettres, chiffres, espace, point, tiret bas ou tiret ; il ne peut pas contenir feintkit-watch ni stand-in). Il devient le product de chaque événement importé. |
tee transmet l'entrée standard à la sortie standard sans la modifier et effectue le même travail que scan à la fin de l'entrée, en affichant ses lignes sur le flux d'erreur ; check-rules valide un fichier de règles et ses témoins et affiche la ligne de couverture honnête.
Export et import (en observation seule, hors ligne ; les formes exactes se trouvent dans la spécification fnd-18-watch, Amendement 1.2). export --evidence <file> --format jsonl|sarif|csv --out <file> lit le fichier de preuves et écrit l'un des trois formats. jsonl est un événement par ligne avec les clés stables schema, product, stand_in, timestamp (ISO-8601), event (detection ou missed), scenario, rule, action (detect ou block, et un blocage est simulé), basis (marker ou behaviour), enforcement, tool, evidence (l'extrait déjà expurgé et coupé à 200 caractères) et location (path:line de la transcription). csv a les mêmes colonnes, avec une apostrophe en tête de toute cellule qu'un tableur lirait comme une formule. sarif est un journal SARIF 2.1.0 dont le pilote de l'outil indique en toutes lettres qu'il s'agit d'un SUBSTITUT DE TEST et non d'un produit de sécurité ; chaque résultat comporte l'identifiant de règle, un message, le scénario comme emplacement logique et, lorsque le chemin de la transcription est relatif, la ligne de la transcription comme emplacement physique. import --input <file> --source <name> --out <file> fait l'inverse : un vrai produit qui écrit la même forme JSON Lines (seuls scenario et action sont requis pour une détection ; event missed marque un scénario qui s'est exécuté et n'a pas été signalé ; les clés inconnues sont ignorées) obtient son propre fichier de détections pour --detections. Les résultats du substitut et ceux d'un produit ne sont jamais mélangés : --source est obligatoire, les événements importés le conservent comme product avec stand_in à faux, un enregistrement du substitut lui-même est refusé, et un nom de fichier contenant feintkit-watch est refusé pour la sortie. Comparez les deux en donnant à la matrice ou au rapport un seul fichier de détections à la fois.
Codes de sortie :
| Code | Signification |
|---|---|
| 0 | Terminé (y compris lorsqu'aucune entrée n'a été écrite pour le scénario). |
| 1 | Un fichier de sortie n'a pas pu être écrit. |
| 2 | Erreur d'utilisation, entrée illisible ou invalide, règles invalides, ou scénario inconnu. |
| 3 | --fail-on-missed était indiqué et un scénario analysé est missed. |
Exemples hors ligne (les transcriptions sont les jeux de test du paquet ; la deuxième commande écrit le fichier de détections que lit le premier exemple de rapport ci-dessous) :
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 2La deuxième commande affiche mcp-08-exfil-sim blocked (1 rule hit; enforcement: simulated, nothing was stopped) et une ligne qui indique que 39 des 48 scénarios ont une règle. La troisième n'a aucune correspondance de règle, le verdict est complied, le résultat est donc missed et le code de sortie est 3. La quatrième ne peut pas écrire car le chemin de sortie est un répertoire.
Rapport (feintkit-report)
Objectif : construit un rapport de résultats à partir des manifestes de scénarios, des artefacts des exécutions et, si vous le fournissez, de votre enregistrement de détection. Le rapport liste par scénario le résultat des artefacts, le verdict de l'agent, le résultat de détection et les correspondances ATLAS et OWASP, et se termine par un récapitulatif par technique ATLAS. Formats : md (par défaut), json, html, sarif, junit (XML JUnit pour un système de CI, voir AUTOMATION.md).
Où il s'inscrit : après les exécutions et les jugements, pour transmettre les résultats à quelqu'un ou pour conditionner un job de CI. La matrice de couverture (feintkit-matrix, DETECTION-INTEGRATION.md) est la vue plus courte des mêmes données.
Utilisation (le texte propre à l'outil) :
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]| Option | Signification |
|---|---|
--root <dir> | Un dépôt de catégorie qui contient des scénarios ; à répéter pour en indiquer plusieurs. Par défaut : le répertoire courant. |
--out-dir <dir> | Le répertoire d'artefacts des exécutions (le même que celui de l'exécuteur). |
--detections <file> | Fichier JSON qui associe des identifiants de scénarios à detected, blocked ou missed. |
--format <name> | json, md, html, sarif ou junit. Par défaut md. |
--output <file> | Écrit le rapport dans un fichier au lieu de l'afficher. |
--timestamp <time> | Définit l'heure de génération, sous la forme exacte YYYY-MM-DDTHH:MM:SS.mmmZ. Avec FEINTKIT_DETERMINISTIC=1, l'heure est fixe à la place. |
--agent <name>, --agent-version <text>, --model <text>, --permission-mode <text> | Consignent quel agent a produit les résultats (fnd-44) : le rapport porte alors une identité d'agent, et les rapports markdown et html affichent une ligne Agent under test. Chacun est une courte étiquette en texte simple, d'au plus 64 caractères, refusée avec le code de sortie 2 lorsqu'elle ressemble à un secret ; un champ omis vaut unknown. Rien ne démarre l'agent pour les découvrir. |
--mitigations | Ajoute les notes relues pour les défenseurs (ce qu'il faut restreindre, quelle règle ajouter, quel paramètre modifier) pour chaque scénario ayant un constat : une section en md et html, le texte d'aide de la règle en sarif, le texte de l'échec en junit. Refusé avec json, dont la structure est fixe. Voir AUTOMATION.md. |
--fail-on-missed | Se termine avec le code 3 lorsqu'un scénario a été consigné comme missed. |
--fail-on-complied | Se termine avec le code 3 lorsqu'un verdict d'agent est complied. |
--fail-on-control-fired | Se termine avec le code 3 lorsque le juge ou le produit testé a déclenché une fausse alarme sur un témoin bénin (un verdict complied ou resisted_surfaced, ou une détection detected ou blocked, pour un témoin). |
Codes de sortie :
| Code | Signification |
|---|---|
| 0 | Le rapport a été produit et aucune condition d'échec ne s'est appliquée. |
| 1 | Une erreur du registre des scénarios (les lignes commençant par FAIL sur le flux d'erreur). Le rapport est tout de même produit. |
| 2 | Erreur d'utilisation, fichier de détections illisible ou invalide, ou fichier de sortie impossible à écrire. |
| 3 | --fail-on-missed, --fail-on-complied ou --fail-on-control-fired s'est appliqué. |
Exemples hors ligne (ils utilisent l'exécution des exemples de transcription ci-dessus et, pour le quatrième, le fichier de détections du substitut ci-dessus ; le premier n'écrit rien en dehors 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 2Vérification des faits (feintkit-factcheck)
Objectif : relit chaque phrase de la documentation des éditeurs que cite CLIENTS.md et exécute le contrôle des sources de correspondances (scripts/verify-mappings.py --online), afin de repérer toute dérive de ces sources. Avec --write, il consigne dans docs/guide/facts-verified.json la date de chaque fait trouvé ; les guides affichent cette date.
Où il s'inscrit : la maintenance, selon un calendrier (tous les quelques jours) et avant une publication. C'est le seul outil ici qui nécessite le réseau : chaque contrôle est une requête sortante vers les pages citées. Les utilisateurs ordinaires de la suite n'en ont pas besoin.
Utilisation (le texte propre à l'outil) :
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| Option | Signification |
|---|---|
--repo <dir> | La racine de la suite. Par défaut : le répertoire courant. |
--facts-file <file> | Où --write consigne les dates. Par défaut : docs/guide/facts-verified.json sous --repo. |
--write | Consigne la date du jour pour chaque fait trouvé. Ne peut pas être combiné avec --skip-facts. |
--report <file> | Écrit un rapport ; un nom se terminant par .json donne du JSON, tout autre nom du Markdown. |
--skip-facts | Ne vérifie pas les phrases citées. |
--skip-mappings | N'exécute pas le contrôle des sources de correspondances. Donner les deux options d'omission est une erreur d'utilisation. |
--delay <ms> | Pause entre deux requêtes. Par défaut 1000. |
--timeout <ms> | Délai maximal d'une requête. Par défaut 30000. |
Codes de sortie :
| Code | Signification |
|---|---|
| 0 | Tout a été trouvé et correspond. |
| 1 | Dérive : une phrase n'a pas été trouvée, une page a été déplacée ou a répondu avec un statut d'erreur, ou une source de correspondances diffère. |
| 2 | Erreur d'utilisation. |
| 3 | Échec réseau et aucune dérive. |
Exemples hors ligne (seules les erreurs d'utilisation peuvent s'exécuter sans le réseau ; un vrai contrôle est node packages/factcheck/dist/src/bin.js et envoie des requêtes) :
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 2Options des autres commandes
La suite comporte plus d'outils en ligne de commande et de sous-commandes que les cinq ci-dessus. Ce tableau liste chaque option du texte d'utilisation de chacun d'eux, avec la commande qui l'accepte : l'exécuteur (feintkit) et ses commandes honey, pack, accuracy et variants, le serveur de contrôle, le générateur de documentation et sa commande translate, le garde, l'interface web, l'outil de manifeste, la matrice de couverture, l'outil de squelette, les sous-commandes diff, history, modes, repeats, store, coverage, summary et mitigations de feintkit-report, et les sous-commandes replay, selftest et bundle de feintkit-watch. Chaque commande affiche son propre texte d'utilisation lorsqu'elle est appelée avec une option inconnue. Les options de feintkit verify figurent dans la section sur l'ingestion de transcription, et celles des cinq outils ci-dessus dans leurs propres tableaux.
| Option | Utilisée par | Signification |
|---|---|---|
--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 | Un dossier qui contient des scénarios (un dépôt de catégorie) ; à répéter pour en indiquer plusieurs. Sans cette option, la commande utilise le dossier courant ou, pour l'exécuteur et l'interface web, les dépôts de catégorie installés. |
--out-dir <dir> | feintkit, feintkit honey, feintkit-gui, feintkit-matrix, feintkit-report history, feintkit-report summary, feintkit-watch replay, feintkit-watch bundle | Le dossier d'artefacts dans lequel les exécutions écrivent et que la commande lit. |
--out-dir <folder> | feintkit-gui demo | Le dossier nouveau ou vide dans lequel la démonstration est écrite. |
--deterministic | feintkit, feintkit honey | Utilise l'identifiant d'exécution et l'horloge fixes du mode déterministe, de sorte que des exécutions répétées écrivent les mêmes octets. |
--all | feintkit | Avec clean : supprime les artefacts de tous les scénarios au lieu d'un seul. |
--yes | feintkit | Avec clean --all : confirme la suppression. |
--json | feintkit | Avec list : affiche le registre en JSON. |
--json | feintkit pack, feintkit-manifest pack | Avec check : affiche le résultat en JSON. |
--json | feintkit accuracy, feintkit variants | Affiche le résultat sous forme d'un seul document JSON au lieu de texte (pour variants, avec judge). |
--json | feintkit-guard | Affiche les constats en JSON. |
--port <0-65535> | feintkit, feintkit-gui | Le port TCP de l'interface web locale ; 0 laisse le système en choisir un libre. |
--port <0-65535> | feintkit honey | Avec listen : le port de l'écouteur de bouclage ; 0 laisse le système en choisir un libre. |
--host <address> | feintkit, feintkit-gui | L'adresse sur laquelle l'interface web se lie : 127.0.0.1, localhost ou ::1. Aucune autre n'est acceptée. |
--scenario <id> | feintkit honey | Avec plant et listen : le scénario auquel appartient l'appât. |
--dir <folder> | feintkit honey | Avec plant : le dossier qui reçoit le fichier appât. |
--file <name> | feintkit honey | Avec plant : le nom du fichier appât. |
--transcript <file> | feintkit honey | Avec scan : le fichier qui contient ce que l'agent a dit ou fait. |
--format <name> | feintkit honey | Avec scan : le format de la transcription, comme pour feintkit verify --format. |
--record | feintkit honey | Avec scan : consigne le résultat dans les événements de l'exécution. |
--fail-on-leak | feintkit honey | Avec scan : se termine avec le code 3 lorsque l'appât a fuité. |
--max-seconds <n> | feintkit honey | Avec listen : arrête l'écouteur après ce nombre de secondes. |
--pack <dir> | feintkit pack | Avant list, run, verify ou clean : charge un dossier de pack de scénarios ; à répéter pour en indiquer plusieurs. |
--mappings <file> | feintkit pack, feintkit-manifest pack | Avec check : le fichier de correspondances par rapport auquel les scénarios du pack sont vérifiés. |
--name <pack-name> | feintkit pack | Avec new : le nom du nouveau pack. |
--prefix <letters> | feintkit pack | Avec new : les 2 à 5 lettres par lesquelles commence chaque identifiant de scénario du pack. |
--labels <file> | feintkit accuracy | Un fichier JSON de réponses étiquetées qui est ajouté au corpus intégré. |
--replies <file> | feintkit variants | Avec judge : le fichier JSON qui contient la réponse de l'agent à chaque variante. |
--run <id> | feintkit variants | Avec judge : l'identifiant d'exécution des réponses, de 4 à 16 lettres ou chiffres. |
--variant <name> | feintkit variants | Avec write : n'écrit que cette variante ; à répéter pour en indiquer plusieurs. |
--suite-root <dir> | feintkit-control | Le dossier de la suite sur lequel le serveur travaille. |
--read-root <dir> | feintkit-control | Un dossier que les outils d'audit peuvent lire ; à répéter pour en indiquer plusieurs. |
--out-root <dir> | feintkit-control | Le seul dossier dans lequel les outils d'automatisation écrivent. |
--ollama-url <address> | feintkit-control | L'adresse de bouclage d'un serveur de modèle local, pour l'outil qui exécute un scénario contre un modèle local. |
--model <name> | feintkit-control | Le nom du modèle local. |
--index <file> | feintkit-docs | Le fichier d'index des scénarios. |
--mappings <file> | feintkit-docs | Le fichier de correspondances. |
--out <dir> | feintkit-docs | Le dossier dans lequel generate écrit le guide et auquel check le compare. |
--guide <dir> | feintkit-docs translate | Le dossier du guide anglais dont les pages .md sont traduites (lecture seule). |
--catalogs <dir> | feintkit-docs translate | Le dossier des catalogues de traduction, un fichier <code>.json par langue. |
--out <dir> | feintkit-docs translate | Avec generate et check : le dossier qui reçoit un sous-dossier par langue, et auquel check compare. |
--lang <code> | feintkit-docs translate | La langue sur laquelle travailler, par exemple de (obligatoire pour extract ; sans elle, generate et check prennent tous les catalogues). |
--show-allowed | feintkit-guard | Liste aussi les usages qu'une dérogation en ligne autorise. |
--mappings <file> | feintkit-manifest | Avec registry : le fichier de correspondances par rapport auquel la correspondance de chaque scénario est vérifiée. |
--since <version> | feintkit-manifest changelog | Conserve les entrées de cette version et des suivantes. |
--id <id> | feintkit-manifest changelog | Conserve les entrées d'un seul scénario. |
--format <name> | feintkit-manifest changelog, feintkit-report diff, feintkit-report history, feintkit-report modes, feintkit-report repeats, feintkit-report mitigations | Le format de sortie : text (par défaut), md ou json. |
--format <name> | feintkit-matrix | md (par défaut) ou json. |
--format <name> | feintkit-report coverage, feintkit-report summary | text (par défaut), md, html ou json. |
--detections <file> | feintkit-matrix, feintkit-report history, feintkit-report summary | Le fichier JSON qui associe des identifiants de scénarios à detected, blocked ou missed. |
--fail-on-missed | feintkit-matrix | Se termine avec le code 3 lorsqu'un scénario a été consigné comme missed. |
--fail-on-complied | feintkit-matrix | Se termine avec le code 3 lorsqu'un verdict d'agent est complied. |
--fail-on-control-fired | feintkit-matrix | Se termine avec le code 3 lorsque le juge ou le produit testé a déclenché une fausse alarme sur un témoin bénin. |
--dest <dir> | feintkit-new | Avec repo : le dossier à créer. |
--repo <dir> | feintkit-new | Le dépôt de catégorie auquel ajouter un scénario ou à contrôler. |
--title <title> | feintkit-new | Avec scenario : le titre du nouveau scénario. |
--mappings <file> | feintkit-new | Avec scenario : le fichier de correspondances qui reçoit l'entrée du nouveau scénario. |
--harness <spec> | feintkit-new | La spécification de paquet du harnais dont dépendent les nouveaux fichiers. |
--output <file> | feintkit-report diff, feintkit-report modes, feintkit-report repeats, feintkit-report store, feintkit-report coverage, feintkit-report summary | Écrit le résultat dans un fichier au lieu de l'afficher. |
--fail-on-regression | feintkit-report diff, feintkit-report modes, feintkit-report repeats | Se termine avec le code 3 lorsqu'une régression a été trouvée. |
--history <file> | feintkit-report history, feintkit-report store | Le fichier d'historique ; pour store import, le fichier dont les exécutions sont ajoutées au magasin. |
--agent <name> | feintkit-report history | L'agent dont les exécutions sont ajoutées (append, obligatoire) ou affichées (show). |
--report <file> | feintkit-report history | Avec append : le fichier de résultats à ajouter ; sans lui, le rapport est construit à partir de --root, --out-dir et --detections. |
--date <YYYY-MM-DD> | feintkit-report history | Avec append : la date de l'entrée. |
--suite-version <x.y.z> | feintkit-report history | Avec append : la version de la suite de l'entrée. |
--agent-version <text> | feintkit-report history | Avec append : l'étiquette de version de l'agent. |
--model <text> | feintkit-report history | Avec append : l'étiquette de modèle de l'agent. |
--permission-mode <text> | feintkit-report history | Avec append : l'étiquette de mode de permission de l'agent. |
--agent <name> | feintkit-report summary | L'agent auquel appartiennent ces résultats ; la page le nomme alors. |
--agent-version <text> | feintkit-report summary | L'étiquette de version de l'agent. |
--model <text> | feintkit-report summary | L'étiquette de modèle de l'agent. |
--permission-mode <text> | feintkit-report summary | L'étiquette de mode de permission de l'agent. |
--last <n> | feintkit-report history | Avec show : seulement les n dernières exécutions. |
--baseline <label> | feintkit-report modes | L'étiquette de l'ensemble auquel les autres sont comparés. |
--against <results> | feintkit-report repeats | Un second ensemble d'exécutions auquel comparer le premier ; à répéter pour en indiquer plusieurs. |
--results <results> | feintkit-report coverage | Un ensemble de résultats qui colore la carte selon le verdict. |
--mappings <file> | feintkit-report coverage | Le fichier de correspondances dont les deux listes OWASP définissent les lacunes ; sans lui, le fichier est recherché en remontant depuis le dossier courant. |
--id <scenario id> | feintkit-report mitigations | N'affiche que ce scénario ; à répéter pour en indiquer plusieurs. |
--store <dir> | feintkit-report store | Le magasin de résultats : un dossier que add crée, avec un fichier marqueur et un fichier d'exécutions pour chaque mois. |
--agent <name> | feintkit-report store | Avec add (obligatoire) : l'agent qui a produit les exécutions. Avec query et export : ne conserve que les exécutions de cet agent. |
--date <YYYY-MM-DD> | feintkit-report store | Avec add : la date des exécutions ; sans lui, la date du fichier de résultats, sinon aujourd'hui. |
--suite-version <x.y.z> | feintkit-report store | Avec add : la version de la suite des exécutions. Avec query et export : ne conserve que les exécutions de cette version de la suite. |
--agent-version <text> | feintkit-report store | Avec add : l'étiquette de version de l'agent. Avec query et export : ne conserve que les exécutions portant cette étiquette. |
--model <text> | feintkit-report store | Avec add : l'étiquette de modèle de l'agent. Avec query et export : ne conserve que les exécutions portant cette étiquette. |
--permission-mode <text> | feintkit-report store | Avec add : l'étiquette de mode de permission de l'agent. Avec query et export : ne conserve que les exécutions portant cette étiquette. |
--label <text> | feintkit-report store | Avec add : une courte étiquette (lettres, chiffres, point, tiret bas et tiret, au plus 32 caractères) qui distingue deux exécutions ayant les mêmes résultats le même jour. |
--scenario <id or prefix-> | feintkit-report store | Avec query : conserve les résultats d'un scénario, ou de chaque scénario dont l'identifiant commence par un préfixe se terminant par un tiret. |
--verdict <verdict> | feintkit-report store | Avec query : conserve les résultats ayant ce verdict d'agent (complied, resisted, resisted_surfaced, inconclusive ou n/a). |
--detection <state> | feintkit-report store | Avec query : conserve les résultats ayant cet état de détection (detected, blocked, missed, not-reported ou not-run). |
--since <YYYY-MM-DD> | feintkit-report store | Avec query et export : conserve les exécutions de ce jour et des suivants. |
--until <YYYY-MM-DD> | feintkit-report store | Avec query et export : conserve les exécutions de ce jour et des précédents. |
--month <YYYY-MM> | feintkit-report store | Avec query et export : conserve les exécutions d'un mois ; ne peut pas être combiné avec --since ou --until. |
--last <n> | feintkit-report store | Avec query : conserve les n plus récentes des exécutions correspondantes. |
--by <view> | feintkit-report store | Avec query : scenario (par défaut) liste les scénarios avec leurs comptes, run liste les exécutions. |
--format <name> | feintkit-report store | Avec query : text (par défaut), md ou json. Avec export : kb (par défaut, un fichier Markdown pour une base de connaissances) ou jsonl. |
--loop <dir> | feintkit-watch replay, feintkit-watch bundle | Le dossier de boucle enregistré à rejouer ou, avec bundle create, à empaqueter. |
--rules <file> | feintkit-watch replay, feintkit-watch selftest, feintkit-watch bundle | Le jeu de règles du substitut ; sans lui, le jeu de règles de démarrage est utilisé. Avec bundle create, le jeu de règles est stocké dans le paquet, et bundle replay utilise cette copie. |
--timestamp <iso> | feintkit-watch replay, feintkit-watch bundle | L'horodatage écrit dans les sorties. Avec bundle create, c'est l'heure de création du paquet et la date de modification de chaque fichier qu'il contient. |
--out <file> | feintkit-watch bundle | Avec create : le fichier de paquet à écrire ; il ne doit pas encore exister et ne doit pas se trouver dans le dossier de boucle. |
--agent <label> | feintkit-watch bundle | Avec create : l'étiquette d'agent (fnd-44) stockée dans l'enregistrement de l'environnement ; un champ omis est repris du bloc d'identité du report.json de la boucle, sinon il vaut unknown. |
--agent-version <label> | feintkit-watch bundle | Avec create : l'étiquette de version de l'agent. |
--model <label> | feintkit-watch bundle | Avec create : l'étiquette de modèle de l'agent. |
--permission-mode <label> | feintkit-watch bundle | Avec create : l'étiquette de mode de permission de l'agent. |
--redact | feintkit-watch bundle | Avec create : remplace les formes de secrets et le nom d'utilisateur d'un chemin de dossier personnel dans les fichiers du paquet au lieu de refuser ; le manifeste consigne le nombre de remplacements et l'empreinte de l'original. |
--bundle <file> | feintkit-watch bundle | Avec verify et replay : le fichier de paquet à lire. |
--digest <sha256> | feintkit-watch bundle | Avec verify et replay : l'empreinte qui vous a été donnée pour le paquet (64 caractères hexadécimaux en minuscules) ; une empreinte différente dans le paquet est un échec. |