The authoritative text is the English page: English version of this page

自動化: 保存した実行のリプレイ、防御側向けノート、CI チェック、再現性バンドル

エージェントの呼び出しもネットワークも必要としない四つの機能を説明します。ルールを変更した後に実エージェント実行の結果をリプレイする機能、シナリオごとに防御側が取れる対策を短くまとめたノート、結果が悪化したときにビルドを失敗させる CI チェック、そして一回の実行を一つのファイルにまとめ、他の人が検証して再判定できるようにする再現性バンドルです。最初に RESPONSIBLE-USE.md をお読みください。すべてのコマンドは、npm run setup の後にスイートのリポジトリのルートから実行します。例の中で # exit <n> で終わる行は、そのコマンドが返す終了コードを示します。入力するときはこのコメントを省いてください。<work> は、リポジトリの外にある新しい空のフォルダを表します。

保存した実行のリプレイ (feintkit-watch replay)

目的: 実エージェント実行 (docs/examples/real-agent-loop.sh) はシナリオごとに数分の時間と費用がかかりますが、エージェントが応答した後の処理はすべて決定的です。判定器は最終応答を読み、検知テスト用スタンドインは保存されたトランスクリプトとルールセットを読み、マトリクスとレポートは結果を読みます。検知ルールを変更した後や、応答の判定に疑問がある場合、リプレイは保存済みファイルに対して判定器、スタンドイン、マトリクス、レポートを新しいフォルダ内でもう一度実行します。エージェントも、ネットワークも、時計も使いません。同じループを二回リプレイすると、バイト単位で同一のフォルダになります。

使い方 (ツール自身の出力):

usage: feintkit-watch replay --loop <dir> --out-dir <dir> [--rules <file>] [--root <dir>]... [--timestamp <iso>]

動作は次のとおりです。保存済みのシナリオ出力を持つ各シナリオフォルダについて、出力を <out-dir>/out/<scenario id>/ にコピーし、保存された応答を再度判定し (生成された judge.sh が行うのと同じ呼び出しです。reply.txt がない場合は transcript.jsonl の最終応答を使います)、保存されていた判定の代わりに新しい判定を記録します。さらに transcript.jsonl をルールセットでスキャンします (--merge で一つの検知ファイルにまとめます)。その後、新しいファイルから matrix.md、report.md、report.json を作成します。シナリオごとに一行を出力し、新しい判定と検知を表示して、角括弧内に保存されていたものを併記します。そのため、ルールの変更によって何が変わったかがわかります。

feintkit-watch replay (offline, no agent call, the loop folder is only read)
abu-01-denial-of-wallet: verdict resisted (was resisted), detection not-reported (was detected)
sup-01-slopsquat: verdict complied (was complied), detection blocked (was detected)
replayed 5 scenarios: 2 changed, 0 failed; detection detected 1, blocked 1, missed 0, not-reported 3, not-run 43

(これは、あるルールを一つ削除し、別のルールを block に変更した実行における、最初の行、五つのシナリオ行のうち二つ、およびサマリー行です。) 二つのリプレイ、またはリプレイと以前の実行を比較するには、feintkit-report diff <old>/report.json <new>/report.json を使います (WORKFLOWS.md)。

終了コード:

制限事項。シナリオを再実行することはありません。保存されたシナリオ出力が、エージェントが見たものの証拠であり、それがないシナリオはスキップされて一覧に示されます。判定ルールも検知ルールも変更しません。スタンドインはテスト用の代替であり、セキュリティ製品ではありません。npm run demo が書き出すデモフォルダはレイアウトが異なり、ループフォルダではありません。

防御側向けノート (--mitigations)

目的: 検出結果は、エージェントや製品が何をしたかを伝えます。ノートは、その手法に対して防御側が何をできるかを伝えます。48 個のシナリオのすべてに、レビュー済みのデータファイル (packages/manifest/data/mitigations.json、シナリオ ID ごとに一つのエントリ。シナリオにエントリがないとテストが失敗します) の中に短い三つの文があります。何を制限するか (権限または機能)、どのルールを追加するか (検知)、どの設定を変更するか (構成) です。これらはシナリオ仕様から書かれた、その手法に対する一般的な指針です。攻撃の詳細は加えず、その製品自身のドキュメントと照合していない製品設定の名前は挙げず (現時点では該当するものはありません)、どの製品にその設定があるという主張でもありません。

feintkit-report --mitigations は、検出結果があるシナリオごとに、レポートへノートを追加します。md と html 形式では「防御側にできること」というセクション、sarif ではルールの help テキスト、junit では失敗のテキストに加えられます。json 形式はレイアウトが固定されているため、このフラグを拒否します。フラグがなければ、すべての出力は従来とまったく同じです。feintkit-report mitigations は、すべてのシナリオ、または指定したシナリオについて、ノートそのものを表示します。

使い方 (ツール自身の出力):

usage: feintkit-report mitigations [--id <scenario id>]... [--format text|md|json]

オフラインでの例:

node packages/report/dist/src/bin.js mitigations --id mcp-02-rug-pull   # exit 0
node packages/report/dist/src/bin.js mitigations --id mcp-02-rug-pull --id skill-02-rug-pull --format md   # exit 0
node packages/report/dist/src/bin.js mitigations --id no-such-scenario   # exit 2

終了コード: 0 は完了、2 は使い方の誤りまたは未知のシナリオ ID です。

CI でスイートを実行する: JUnit XML と GitHub Actions のチェック

目的: エージェントの構成、プロンプト、スキル、ツール設定を変更するチームは、変更のたびに結果が悪化していないかを知りたく、悪化したときにはビルドを失敗させたいと考えます。CI ジョブでエージェントを呼び出さず、シークレットも使わずにそれを実現する三つの要素があります。feintkit-report --format junit (CI システムがテスト結果として表示するファイル)、任意の履歴ファイルを伴う feintkit-report diff <baseline> <new> --fail-on-regression (WORKFLOWS.md)、そして docs/examples/ci/ にある GitHub Actions 用の既製チェックです。

JUnit XML (feintkit-report --format junit)。シナリオのカテゴリごとに一つの testsuite (feintkit.mcp、feintkit.skills、...)、シナリオごとに一つの testcase を出力します。スイートは時間を計測しないため、時間は 0 です。構造は、Jenkins の xunit プラグインが公開している junit-10.xsd スキーマに従っています (testsuites、name、tests、failures、errors、skipped、timestamp を持つ testsuite、name と classname を持つ testcase、そして failure、error、skipped、system-out 要素)。この形式には唯一の公式スキーマがないため、そのファイルをここでの基準としています。

すべての testcase には、その判定、検知、アーティファクト、実行 ID を示す system-out 行があります。--mitigations は、failure または error のテキストに防御側ノートを追加します。

GitHub Actions のチェック。docs/examples/ci/feintkit-regression.yml は、エージェントの構成を保持するリポジトリの .github/workflows/ にコピーするワークフローです。スイートのチェックアウトにある複合アクション docs/examples/ci/feintkit-regression/action.yml を使用します。指定したフォルダに触れるプルリクエストのたびに、あなたのリポジトリと、レビュー済みコミットのスイートをチェックアウトし、スイートをビルドし、リポジトリに保存されたループ結果をリプレイし (feintkit-watch replay)、junit.xml、report.md、report.json と比較結果を書き出し、実行を履歴ファイルに追記し、レポートと比較結果をジョブサマリーに追加し、ファイルをワークフローのアーティファクトとしてアップロードします。そして feintkit-report diff <baseline> <new> --fail-on-regression が回帰を検出した場合 (終了コード 3)、ジョブを失敗させます。レポートだけを行いたい場合は、アクションの入力 fail-on-regression を false に設定します。

このチェックが行わないこと。エージェントは実行しません。ループ結果は、このワークフローの外で、ご自身のエージェントと認証情報を使って docs/examples/real-agent-loop.sh が生成し、コミットしておく (またはご自身の先行ジョブで生成する) ものです。回帰とは diff が定義するもの (WORKFLOWS.md) で、悪化した判定または検知、あるいは失敗したアーティファクトチェックです。サードパーティの三つのアクションは完全なコミット SHA に固定されており、スイート自身のリリースワークフローと同じものです (2026-10-26 に git ls-remote で読み取り)。権限は読み取り専用で、シークレットは使わず、すべての入力は環境変数を通じてシェルに渡されます。ワークフローの三行はプレースホルダーであり、変更が必要です (スイートのリポジトリ、コミット SHA、監視するフォルダ)。変更するまでは動作しません。このワークフローとアクションは GitHub 上で一度も実行されていません。テストでは、アクションのスクリプトを bash で実行し、固定とパーミッションを確認しています。

オフラインでの例 (<work> の外には何も書き込みません):

node packages/gui/dist/src/bin.js demo --out-dir <work>/demo   # exit 0
node packages/report/dist/src/bin.js --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 --out-dir <work>/demo/out --detections <work>/demo/detections.feintkit-watch.json --format junit --mitigations --output <work>/junit.xml   # exit 0
node packages/report/dist/src/bin.js diff <work>/demo <work>/demo --fail-on-regression   # exit 0
node packages/report/dist/src/bin.js --format junit --mitigations --format json   # exit 2

最後のコマンドは拒否されます。最後の --format が優先され、json にはノートを入れる場所がないためです。

再現性バンドル (feintkit-watch bundle)

目的: 保存されたループフォルダ (docs/examples/real-agent-loop.sh の LOOP_OUT) は一回の実行の証拠ですが、一台のマシン上のフォルダであり、そのマシンのパスやおそらくシークレットを含み、中のファイルが後で変更されたかどうかを示すものがありません。bundle create は一回の実行の証拠を一つの tar ファイルにまとめます。トランスクリプトと応答、シナリオ出力、検知ファイルと結果ファイル、ルールセット、ツールのバージョンと環境の記録、そして各ファイルのサイズと sha256、さらに一覧全体に対する一つのダイジェストを記載したマニフェストです。bundle verify はファイルをマニフェストと照合します。bundle replay はバンドルを展開し、保存された応答を判定し、保存されたトランスクリプトをバンドル内のルールセットで再スキャンし、オフラインで、記録された判定と検知が再び得られるかどうかを伝えます。したがって、バンドルしか持たない人でも、その実行を正確に再判定できます。バンドル内のどの処理も、エージェントを起動せず、ネットワーク接続を開かず、シナリオを実行しません。

使い方 (ツール自身の出力):

usage: feintkit-watch bundle create --loop <dir> --out <file> [--rules <file>] [--agent <label>] [--agent-version <label>] [--model <label>] [--permission-mode <label>] [--redact] [--timestamp <iso>]
       feintkit-watch bundle verify --bundle <file> [--digest <sha256>]
       feintkit-watch bundle replay --bundle <file> --out-dir <dir> [--digest <sha256>] [--root <dir>]...

バンドルの内容。圧縮なしの POSIX ustar 形式の一つの tar ファイルで、tar -tf で一覧できます。最初のエントリは MANIFEST.json で、スキーマ feintkit-run-bundle/1、作成時刻、ダイジェスト、そして他のすべてのエントリについて (パス順に) サイズ、sha256、役割 (environment、rules、output、transcript、reply、detections、evidence、result) を含みます。ダイジェストは、この一覧の <sha256> <path> の行に対する sha256 であり、作成時刻には依存しません。他のエントリは、environment.json (スイートツールのバージョン、Node のバージョン、プラットフォームとプロセッサ、エージェント識別ラベル、ルールセットの sha256、実行フォルダの名前)、rules/ruleset.json、そして loop/ 以下のループフォルダのファイルです。具体的には out/ (シナリオ出力、すべての通常ファイル)、<run folder>/transcript.jsonl と reply.txt、および存在する場合は detections.feintkit-watch.json、evidence.jsonl、matrix.md、report.json、report.md です。実行フォルダ内のこの二つ以外のファイル、ループフォルダのその他のファイル、リンク、16777216 バイトを超えるファイル、他のシステムの tar が保持できない名前のファイル (使用できるのは英字、数字、.、_、-、/ のみで、最大 100 文字、Windows のデバイス名は不可) はバンドルされません。種類、サイズ、名前のためにスキップされたものは名前で一覧表示され、トランスクリプトも応答もない実行フォルダも一覧表示されます。

完全性。verify はファイルを読み、マニフェストが正しい形式であること、一覧にあるすべてのファイルが記録されたサイズと sha256 で存在すること、一覧にないエントリがないこと、ダイジェストが一覧と一致することを確認します。ダイジェストを表示するので、別の経路でファイルと一緒に送り、--digest で返してもらうことができます。これはチェックサムであり、署名ではありません。ファイルを変更できる人は、マニフェストとダイジェストも一緒に変更できるため、ダイジェストは信頼できる提供元から受け取った場合にのみ意味を持ちます。verify は何も書き込みません。

プライバシー。何かを書き出す前に、create はバンドルされるすべてのファイルを読み、非公開に見える内容を調べます。スタンドインが証拠から既に削除しているシークレットの形式 (秘密鍵ブロック、クラウドのアクセスキー ID、パーソナルアクセストークン、API キー、チャットトークン、JSON Web トークン)、およびホームフォルダのパスに含まれるユーザー名 (Unix パスのルート直下のフォルダ Users と home、Windows パスのドライブ文字直下の Users。通常、バックスラッシュ二重、スラッシュの各形式を含みます) です。見つかった場合は何も書き出さず、各箇所を <path in the bundle>:<line>: secret または home-path として表示し (値は決して表示しません)、終了コード 3 で終了します。マシンの一時フォルダの下にあるホームフォルダのパス (シナリオ実行が既定で書き込む場所。Windows ではそのフォルダはプロファイルフォルダの下にあります) では停止せず、create は注記を一行表示し、ファイルをそのまま保存します。--redact を付けると、シークレットの形式を [redacted] に、ユーザー名を <user> に置き換え (一時フォルダ下のパスも対象)、変更されたすべてのファイルのマニフェストエントリに redactions と originalSha256 が記録されます。秘密鍵ブロックはその行の残りを含みます。スキャンが見つけるのは既知の形式だけであり、バンドルに非公開のものが一切含まれないことを保証するものではないので、バンドルを送る前に内容を読んでください。ラボのアドレス、ホスト名、応答のテキストは検索対象ではありません。

リプレイ。replay はまず検証を行い、バンドルが完全でない場合は何も書き出す前に終了コード 3 で停止します。その後、すべてのエントリを <out-dir>/bundle/ に展開し、環境記録のバージョンと異なるスイートツールごとに注記を表示し、保存されたルールセットを使って <out-dir>/bundle/loop に対して feintkit-watch replay のリプレイを実行し、<out-dir>/replay/ に書き出します。その出力はそのまま表示されます。最後の行は reproduced: all <n> scenarios give the recorded verdict and detection または not reproduced: <c> of <n> scenarios differ from the recorded results です。差異はツールのエラーではなく検出結果です。記録された判定または検知が、保存された応答やトランスクリプトから現在得られるものと一致しないことを意味します (判定器やスイートのバージョンが変わった場合は注記に名前が示されます。あるいは記録が編集された場合です)。--redact で作成したバンドルは、秘匿処理済みのファイルからリプレイされます。シナリオのマニフェストはバンドルに含まれません。判定器はシナリオのマニフェストから判定ルールを読み取るため、--root には環境記録に記載されたスイートのバージョンのカテゴリリポジトリを指定してください。

終了コード:

制限事項。tar リーダーが受け付けるのは、このツールが書き出したファイルだけです。別のプログラムで展開して再度パックしたバンドルは not a run bundle として拒否されます。バンドルは一つのループフォルダを保持します。ループの modes/ と repeats/ のフォルダは別個の実行ですので、--loop には目的のフォルダを指定してください。バンドルは、ループが保存したトランスクリプトとシナリオ出力を超えて、エージェントが見たものを記録するものではありません。環境記録は、ツールが実行されたシステムから読み取ったもの (バージョン、プラットフォーム) を示すだけで、あなたが与えたラベル以外のエージェントの構成を示すものではありません。これはテスト用の成果物です。判定ルールも検知ルールも変更せず、セキュリティ製品でもありません。