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 都有一行 system-out,内含其判定、检测、产物和运行 id。--mitigations 会把防御方说明附加到失败或错误的文本之后。

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 读取),权限为只读,不使用任何密钥,且每个输入都通过环境变量传给 shell。工作流中有三行是占位符,你必须修改(套件仓库、提交 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 指向你所要的那一个文件夹。除循环所保存的转录记录和场景输出之外,包并不记录智能体所见的其他内容。环境记录说明的是工具从其所在系统读取到的信息(版本、平台),而不是除你给出的标签之外智能体是如何配置的。它是一件测试产物:不更改任何判定规则或检测规则,也不是安全产品。