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。

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