jar-audit-agent

jar-audit-agent（Fail-Closed / Evidence+Coverage）

数据源

• DB(SQLite)：Freeze/coverage/entry/graph 输入（必须）
• MCP(:20032 SSE)：推荐用于取证（agent 可直接调用 get_code_cfr/get_code_fernflower）

禁止事项（防止"自作聪明"导致调用错误）

• 禁止ai重新写 Python/正则/临时脚本去解析 curl 输出、拼 SQL、拼 HTTP URL 例如python3 - <<；只能调用已经存在的 <python> scripts/cli.py <subcommand>（<python> 为 init 输出中检测到的命令）。
• 禁止手写 curl/HTTP 调用：本技能不使用 HTTP 通道；取证只允许走 MCP。
• 禁止用 grep/自写脚本从 MCP tool-results 抽代码：必须用 evidence --mcp-tool-result-file <path>（优先）或 --code-json-file/--code-text-file。
• 禁止在错误目录执行 cli：任何 <python> scripts/cli.py ... 之前，必须先进入技能根目录。
• 禁止"猜路径/临时注入"取证：禁止扫描 /tmp//var/folders、禁止 find 猜 tool-results、禁止 /dev/stdin/here-doc/echo 注入 JSON；一旦出现 "Do you want to proceed?" / "allow reading from tmp/ …" 立即取消。取证只允许两条路径：--mcp-tool-result-file <Claude 提示的绝对路径> 或把 JSON 写入 runs/<run_id>/inputs/ 再 --code-json-file。
• 遇到工具不支持/候选未覆盖时必须停下：只能输出"需要扩展 skill（新增向量 sink/规则）"，不得写脚本绕过、不得手改 verify_*.jsonl。

环境约束（Environment Constraints）

• Python 命令自动检测：
  • init 命令会自动检测当前系统可用的 Python 命令（优先 python，其次 python3）。
  • init 输出中会显示检测到的 Python 命令，后续所有命令都应使用相同的命令。
  • 例如：如果 init 输出 python scripts/cli.py ...，则后续都用 python；如果输出 python3 scripts/cli.py ...，则后续都用 python3。
• Windows 上下文：
  • 如果看到路径类似 C:\...，说明你在 Windows 环境。
  • 引号：路径参数必须用双引号包裹（例如：--db "C:\target path\db"），避免空格/特殊字符导致解析错误。
• Unix/Linux/macOS 上下文：
  • 如果看到路径类似 /home/... 或 /Users/...，说明你在 Unix 环境。
• Session 连续性：
  • 当 init 完成时，立即捕获输出中的 Run ID 和 Python 命令。
  • 所有后续命令（freeze、reach、next、evidence、submit）必须：
    1. 使用 init 输出中显示的 Python 命令（保持一致）
    2. 完整复制 init 输出中显示的命令（包含 --run <ID> 参数）
  • 关键：init 命令会在输出中打印下一条完整命令（用 = 分隔线标记），必须完整复制整行命令，不要只复制部分参数。
  • 常见错误：如果看到 "error: the following arguments are required: --run"，说明命令被截断了，需要重新查看 init 输出并完整复制命令。

操作细则（避免卡点）

• 详细操作门禁（MCP 文件路径/anchor/SAFE-NEEDS_DEEPER 边界/扩展 sink/结束判定/工作目录）见：
  • references/TACTICS_LIBRARY.md

MCP 取证（唯一推荐）

• MCP 工具名：
  • get_code_cfr / get_code_fernflower（返回 JSON，含 fullClassCode）
• 取证方式：
  • 先调用 MCP get_code_*（不要阅读/解析返回内容；输出过大时系统会自动落盘到 tool-results 文件）
  • 立刻调用 <python> scripts/cli.py evidence --mcp-tool-result-file <tool-results/xxx.txt>（<python> 为 init 输出中检测到的命令，自动抽 fullClassCode 并完成切片+hash 落盘）
  • 注意：evidence 不会自己去找代码；如果没提供 --mcp-tool-result-file/--code-json-file/--code-text-file，工具会 fail-closed 直接报 “missing code input”
  • 若 MCP 输出未自动落盘且可手动保存：将 MCP 返回 JSON 保存到 runs/<run_id>/inputs/mcp_<candidate_id>.json，然后用 --code-json-file

铁律

• Fact：节点=四元组 (jar_id,class,method,desc)；禁止只用名字 join/追链
• Evidence：submit 必须带 snippet_ref 或 chain_trace 或 sql_proof，否则拒绝写入
• Report：报告只读 artifacts 编译；--strict 未完成 coverage 直接 fail

状态机（唯一入口）

用 <python> scripts/cli.py（等价 scripts/jaudit.py，<python> 为 init 自动检测的命令）：

• init：创建 runs/<id>/session.json inventory.json rules/ graph_cache/ ...
• profile --cwd <jar-analyzer>：写 profile 并快照 vulnerability.yaml/dfs-sink.json 到 runs/<id>/rules/
• freeze --vector <v> --cwd <jar-analyzer>：圈地+降噪+sink_resolution
• graph→reach --vector <v>：可达性/最短链回写 candidates
• next --vector <v> --limit 5：生成 batch（默认按向量 batch.size，推荐 5）；NEEDS_DEEPER 优先
• evidence --candidate-id <CID> --batch-id <BID> --code-json-file <mcp.json> --auto-fallback：WARN/BAD 自动 expand→method
• submit --candidate-id <CID> --batch-id <BID> --status VULN|SAFE|NEEDS_DEEPER：严格模式 VULN 需 GOOD 证据
• report [--strict]：只读编译 audit_report.md（含 Remaining TopK 下一批计划）
• status：机器可算进度（final=VULN/SAFE；NEEDS_DEEPER 仍算 remaining）

强制运行规程（防“一条就结束”）

你是驾驶员：必须按批次循环，直到满足停止条件才允许 report。

Full Audit（覆盖表 67-84 对应的全套类别）

• 入口：优先用默认队列（vectors/default_queue.yaml），不要只跑单个向量就下结论。
• 流程：
  • init
  • profile --cwd <jar-analyzer>
  • graph（每个 run 只需一次）
  • 对默认队列里每个 vector 执行：
    • freeze --vector <v> --cwd <jar-analyzer>
    • reach --vector <v>
    • VERIFY LOOP（必须循环，不许只做一条）：
      • next --vector <v> --limit 5
      • 对 batch 里的每个 candidate：evidence ... --auto-fallback → submit ...
      • 继续 next 取下一批，直到：
        • 该向量没有可取候选（next 输出为空/或触发 no candidates），或
        • 你已经把所有候选都提交为 final（VULN/SAFE），或
        • 你把剩余的全部标记为 NEEDS_DEEPER（并在 reasoning 里写明阻断原因：例如入口不可达/证据不可用/缺少环境信息）。
  • 全部向量跑完后再 report（必要时 --strict）

什么时候允许生成报告

• 只有在 至少完成一次完整的 VERIFY LOOP（next→evidence→submit→next…） 后才允许 report。
• report 不是“结束”，只是“当前台账快照”；如果存在 Remaining TopK，你必须继续循环。