kunglao-agent

kunglao-agent 是一套自主逆向工程系统：你给它目标和待解问题，它自己把问题做上几小时到几天 —— 自己规划路径，worker 死了能补位，崩溃了能续跑；只有当每个答案都从原始证据推导出来、并扛过机械校验门控之后，它才收敛交卷。

简体中文 · English

它目前以 Claude Code 插件的形式分发 —— Claude Code 是你对话的界面，但不是产品的本体。产品是这套循环：专家 worker 先做静态分析，独立验证者从原始证据盲重推每一条事实，机械门控决定分析何时算完成。交付物是一个事实库：每条 claim 都有字节锚定、独立验证、证据索引 —— 信任靠机器执行，不靠口头约定。

术语约定：kunglao-agent、PROVEN、RED-CHECKER（独立验证者）、fact、claim、MCP、task_spec.yaml、claim-register.yaml、evidence/_index.json 等已建立术语保留英文原文，其余均为中文。

为什么是 kunglao-agent

• 长时程是设计目标。 一次分析可以无人值守跑上几小时到几天：定时心跳让循环一直活着，死掉的 worker 会被补位、其问题重新排队，崩溃后从落盘状态续跑，卡住的任务能自愈。收敛了你再来读结论 —— 不用一步步盯着。见长时程自主运行。
• 答案值得信。 任何 fact 在独立验证者从原始证据盲重推一致之前都不能叫 PROVEN；每条 fact 都通过 evidence/_index.json 锚定到带 sha256 的原始证据。
• 覆盖完整的逆向光谱。 Windows/Linux 原生二进制、Android APK、Web/JS、协议分析、固件仿真、风控对抗 —— 一套系统，不是单领域工具。
• 静态优先的成本观。 能静态闭环的任务绝不碰动态工具；每一次升级都要显式声明、受门控约束、留下审计。
• 复用知识，而不是重复推导。 内置持续扩充的注册工具目录（crypto 解码、反汇编流水线、图查询），系统优先调用成熟工具而不是临时手搓脚本；每次运行沉淀下来的是可复用的事实库，而不是一段会蒸发掉的聊天记录。
• 会恢复，而不是死掉。 worker 死亡、API 断连、进程崩溃都是一等公民事件：循环检测到它们、快照已完成的产物、从断点续派，而不是从零重来。
• 你的环境你做主。 VMware、ssh、docker、adb、或者纯静态 —— 系统驱动你已有的执行通道，没有哪种是"降级模式"；不需要执行的任务绝不会向你要一台虚拟机。

快速开始

kunglao-agent 跑在 Claude Code 里。从磁盘上的样本到 verdict：

1. 装插件

在任意目录下，进入 Claude Code：

/plugin marketplace add amd2g2zz/kunglao-agent
/plugin install kunglao-agent@kunglao-agent

（开发模式也可以：claude --plugin-dir /path/to/kunglao-agent。）

2. 初始化工作区

/kunglao-agent:init ~/cases/synth-dropper --type windows

kunglao-init 搭好工作区、写好 CLAUDE.md、按你选的 --type 探测工具链、生成 .mcp.json。你选的类型有 HARD 工具缺失时，init 会 HARD-reject —— 修复指引就写在错误块里。

3. 提出任务，启动分析

/kunglao-agent:analysis ~/cases/synth-dropper
> 分析目标：确认这个 dropper 的持久化手段和网络出口，
>   每条结论都要能从原始证据复现。
> 验证逻辑：关键结论必须由独立验证者盲重推一致才算成立。
> 约束：静态优先，样本不许在宿主机执行。

把需求说清楚 —— 分析目标（你要知道什么）、验证逻辑（凭什么信答案）、约束（不许做什么）。写得越具体，结果越可控：只写目标不写验证逻辑，结论就只是模型的口头担保；两者都给，每条结论才有机械背书。约束可选——不写就由系统按静态优先原则自行决定路径。需求记入 task_spec.yaml，之后循环自动推进，不需要你再指挥。常见的口头需求怎么写成合格的任务描述，见怎么写任务描述。

4. 看交付物

claim-register.yaml   # 每条 claim 都 terminal，带验证者签核
facts/F<NNN>.md       # 字节锚定、可复现、frontmatter 契约
evidence/_index.json  # 每个 fact 对应一份原始证据（sha256 + 路径）
runs/                 # 会话审计轨迹

怎么写任务描述

循环的完成判据 —— oracle —— 是从你写下的最终状态机械推导出来的。写得含糊，oracle 就含糊，分析就会漂向"能证明什么"，而不是"你要什么"。下面四种说法覆盖了大部分漂移场景：用户原话是什么、通常的真实含义是什么、一个合格的任务描述长什么样、oracle 据此锚定什么。

"我要纯算"

通常的真实含义： 离线复现 App 的签名/加密算法 —— 一个 unidbg harness 或一份独立重写，运行时既不要设备也不要 App。不是"分析这个 App"；App 只是算法的宿主。

> 样本：v7.2 APK；行为：给 api.example.com/v2/* 请求生成 `sign`
>   头的那个签名函数。
> 判据：独立复现（unidbg 或重写）对全部抓包 (input → sign) 对
>   逐字节重放一致 —— 含扣留对 —— 运行时不依赖设备和 App。
> 附证据：captures/sign-pairs.jsonl —— 从真机会话抓到的 20 组
>   输入/输出对，其中 10 组扣留、不参与分析。

oracle 锚定在： 每一对都逐字节重放一致（包括扣留对），且复现可独立运行。

"我要解密"

这话说的是两个不同目标里的一个 —— 先说清是哪个：

• (a) 解开一段抓到的数据 —— 一次性答案："把这个抓到的缓存文件解出明文"。
• (b) 要一个解密能力 —— 算法 + 密钥还原，明天抓到新数据也能用。

合格的描述 (a)：

> 样本：v7.2 APK；行为：本地配置缓存 files/.cfg/v2.dat 落盘即加密。
> 判据：给出抓到的 v2.dat 的明文，并与 App 实际渲染的内容对得上
>   （字段名和取值与随包截图一致）。

合格的描述 (b)：

> 样本：v7.2 APK；行为：api.example.com/v2/* 的请求体用静态密钥加密。
> 判据：定位算法和密钥，然后做 canary 回环 —— 用还原出的密钥加密
>   已知明文，与设备产出的密文逐字节一致。
> 附证据：captures/request-bodies.jsonl —— 从设备抓到的密文请求体，
>   连同产生它们的请求。

oracle 锚定在： (a) 明文与 App 实际渲染的内容对得上；(b) 算法 + 密钥定位成功，且 canary 回环与设备产出的密文逐字节一致。"解出来过一次"两条都不满足。

"帮我分析这个协议"

通常的真实含义： 还原线上格式（wire format）—— 帧定界、字段语义，外加一个能跑的编解码器。

> 样本：某安卓聊天 App；行为：gateway.example.com:443 上的 TCP 协议，
>   抓包见 gateway-session.pcap。
> 判据：编解码器对每一帧抓包逐字节回环一致，且对扣留帧解出的字段
>   与观察到的 App 行为吻合。
> 附证据：captures/gateway-session.pcap —— 40 帧，另留 1 帧扣留、
>   不参与分析。

oracle 锚定在： 编解码器对每帧抓包逐字节回环一致；扣留帧解出的字段与观察到的 App 行为吻合。

"这个 sign 在哪算的"

通常的真实含义： 要的是"位置 + 证明"。指认一个代码位置很便宜；答案只有在证明"就是这里"之后才有用。

> 样本：v7.2 APK；行为：每个请求附带的 `sign` 头。
> 判据：指认计算 `sign` 的类/方法（或 native 函数），并在该点 hook，
>   用相同输入复现出抓包里的 `sign` 值。
> 附证据：captures/sign-session.jsonl —— 抓到的 `sign` 值及其请求输入。

oracle 锚定在： 指名道姓的类/方法/native 函数，加上该点的 hook 能复现抓包值。

这四个场景的共同点

• 点名样本和行为 —— 哪个参数、哪个入口、哪条流程 —— 别只报类目。"我要纯算"是类目；"给 api.example.com/v2/* 生成 sign 头的签名函数"才是目标。
• 成功必须是数据。 附上抓到的输入/输出对；扣留对让检查诚实 —— 复现没法过拟合没见过的数据。
• oracle 从你写的最终状态推导。 写得含糊，验证就含糊，分析就漂。
• 约束改变路线。 只能静态？有没有设备？走哪个 channel？提前说清楚，循环开工前就把路线定下来（见自带分析环境）。

子命令

典型顺序：init 建工作区 → analysis 提需求开跑 → （中途出岔子用 resume）→ 收敛读报告 → 插件升级后对旧工作区跑一次 upgrade。

一次分析长什么样

一次分析的"形状" —— 你敲什么、拿到什么、去哪看。 一个小型 Windows dropper 落在 ~/cases/synth-dropper：

/kunglao-agent:init ~/cases/synth-dropper --type windows   # 探测 Ghidra、VM 可达性
/kunglao-agent:analysis ~/cases/synth-dropper
> "这个二进制干了什么，回连到哪里？"

接下来循环自己跑 —— 路线随样本实际情况调整，不是固定剧本。你可以走开（见长时程自主运行）。收敛之后读下面的交付物。

场景演练

再给两条端到端的路径 —— 挑一条匹配你的目标（普通 Windows PE / Linux ELF 二进制就走上面的示范案例）。

/kunglao-agent:init ~/cases/sample.apk --type android
/kunglao-agent:analysis ~/cases/sample.apk
> "capability / persistence / network entry points"

/kunglao-agent:init ~/cases/sample.apk --type android
/kunglao-agent:analysis ~/cases/sample.apk
> "这个 APK 有没有动态加载和反调试？如果有，代码藏在哪，做了什么？"

/kunglao-agent:init ~/cases/example-site.com --type web
/kunglao-agent:analysis ~/cases/example-site.com
> "XHR 签名是怎么算的，nonce 从哪来？"

你得到什么

一个声明登记加事实库，信任靠机器执行，不靠口头约定：

• 验证式收敛 —— PROVEN 要求独立盲验证者逐字节重推一致；CONVERGED 要求每个主问题都有字节级证据、零孤立 claim、不空转。
• 证据完整性 —— 每条 fact 都能通过 evidence/_index.json 追到原始证据（capture / trace / dump / 二进制）。按设计排除派生摘要。
• Maker-checker —— worker（maker）写事实，redteam 验证者（checker）盲重推。永远是不同的 agent。

没有任何 claim 能靠作者自己说了算：必须由独立验证者盲重推一致，并通过一组机械门控。完整门控设计见 docs/design/loop-engineering.md。

跑完之后，各文件回答不同的问题：

fact 样例：

id: F061
status: VERIFIED-BY-W01-static-byte-recheck
claim_id: C-401
provenance:
  - {role: sample, path: bins/<sha>}
  - {role: capture_log, path: runs/c329-inner-pe.bin}   # 经 evidence/_index.json 引用
reproduce: python -c "import struct; ..."               # 对着引用的证据跑
verifier_sign_off: {verifier: kunglao-redteam, verdict: CONFIRMED}

长时程自主运行

真实的分析不是二十分钟的聊天。kunglao-agent 能一直钉在问题上，不需要人一步步带着走：

• 一跑几小时到几天，无人值守 —— 定时心跳让循环在你的两次到访之间持续干活；循环停摆会被标记出来，而不是无声烂掉。
• 失败能自愈 —— 死掉或卡住的 worker 会被补位，其问题重新排队；被阻塞的任务走自愈流程，不会干等。
• 崩溃和重启之后能续 —— /kunglao-agent:resume <工作区> 从落盘状态重建断点现场，并给出下一步动作。
• 记忆在磁盘上，不在聊天里 —— claims、facts、证据索引、完整审计轨迹都落在工作区，任何会话都能把分析接回去。

你给它目标和问题；它把问题做上几小时到几天，从故障里恢复，收敛了你来读结论。

用好它

• 喂静态可解的目标。 循环是静态优先的：已解包的 APK、未混淆的 bundle、未剥符号的二进制收敛得快得多；逼它走动态就慢。
• 提前把动态那条腿搭好。 如果主问题注定要执行样本，先选好 channel（见自带分析环境）—— 动态任务配 local 会被 init HARD-reject。
• 分清"在干活"和"卡住了" —— runs/ 里有新条目说明循环活着；心跳死了、或同一决策反复出现而没有新 fact，就是卡了 —— /kunglao-agent:resume <工作区> 给出诊断和下一步。

按目标类型分工具链

init 时选的 --type 决定哪些 HARD 工具必须装。指引默认折叠 —— 展开你的目标。所有类型都需要两个 MCP server： ghidra（claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe）和 sequential-thinking（claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking）。

以上所有内容的统一真源 —— 随时可探测：python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos>（退出码 1 = HARD 缺失）。

自带分析环境

动态调试需要一个 agent 能驱动的执行控制平面。KUNGLAO_CHANNEL 在五个一等公民 channel 里选一个 —— 你环境里已有什么就用什么，没有降级模式：

local 红线： local 只为静态工作准备 —— 绝不在主机上执行、调试、注入样本。任何动态需求都把 KUNGLAO_CHANNEL 切到 vmr/ssh/docker/adb；动态任务配 local 会被 init HARD-reject。

channel 探测只对动态任务跑（纯静态任务直接跳过）。ssh channel 上的执行流过 ssh-mcp 控制平面（npm i -g ssh-mcp）；裸 CLI ssh 是兜底。远程 docker 走 ssh 时，设 KUNGLAO_DOCKER_CONTAINER。

配置

四个变量覆盖大多数场景：

很少用到：KUNGLAO_DOCKER_CONTAINER（ssh/docker channel 的 docker 执行目标）、KUNGLAO_FRIDA_PORT（默认 1337）、KUNGLAO_DIE（DIE 路径，兜底 PATH）、KUNGLAO_CLAUDE_JSON（用户级 MCP 注册表的测试覆盖）。

安全

• 样本绝不在主机上执行 —— block_malware_exec hook 强制；动态只跑在 VM/容器/设备里，且要求逐会话授权。
• 真相等级：原始证据 > 本地工具 > 沙箱 > 威胁情报（CTI 是可证伪的假设，不是真相）。
• Maker-checker：worker 永不自我验证；验证者永不读 maker 的结论。
• bins、settings、hooks 永不入库；密钥与工作区、仓库隔离。

开发

欢迎贡献。流程：从 dev 切分支，一个改动一个分支，PR 回 dev。

git worktree add .worktrees/<name> -b <name> dev
uv sync --locked
uv run python -m pytest -q
gh pr create --base dev

设计文档在 docs/ 与 specs/。见许可证。

内部

<workspace>/
├── bins/<sha256>              # 样本（gitignore）
├── task_spec.yaml             # primary_questions / scope / constraints / success_criteria
├── claim-register.yaml        # claim C-NN（OPEN/PROVEN/STAMP/...）
├── claim_deps.yaml            # claim DAG
├── facts/                     # 字节锚定 fact F-NNN.md + _INDEX.md
├── evidence/                  # 原始证据 + _index.json（eid → 路径 + sha256）
├── runs/                      # worker-status、plan、ledger、.heartbeat.json
├── blockers/                  # 每个 claim 的失败归因记录
└── CLAUDE.md                  # 工作区规则，kunglao-init 生成

许可证

双协议许可：AGPL-3.0 用于个人、学术、内部使用（免费 —— 见 LICENSE）；闭源或 SaaS 商业使用需要商业许可 —— 见 LICENSE-commercial.md。