lijianfei.com

随着 Claude Code、Cursor、Codex 等新一代代码编程 Agent 的普及，软件工程的编码与重构效率被大幅刷新。然而，一旦将这些 Agent 置于网络安全、逆向工程、授权渗透或 CTF 竞赛等实战场景下，它们几乎必然陷入混沌：面对一个 APK，Agent 无法抉择该用 JADX、Frida 还是 IDA；面对复杂目标，它们盲目猜测并执行危险的扫描命令，甚至突破授权边界；分析过程充斥着幻觉，输出的漏洞报告缺乏可验证的代码证据与重现命令。

开源项目 reverse-skill（GitHub: zhaoxuya520/reverse-skill）给出了一个工业级的解题范式：它不做庞大臃肿的重型平台，而是定位于客户端中立的“安全技能路由包”（Skill Router Pack）。它通过单一事实源路由矩阵、执行前强制 Scope 授权硬门禁、不可篡改的证据链（EFP 图）以及跨平台按需工具自举机制，彻底将野蛮生长的安全 Agent 驯化为流程严谨、证据扎实、行为可审计的虚拟安全专家。

一、安全与逆向领域中 AI Agent 的“阿喀琉斯之踵”

将通用大模型直接接入终端命令执行环境时，安全研发团队往往会遭遇五大灾难性断层：

flowchart TD
    subgraph AgentChaos ["通用 Agent 的安全作业失控"]
        C1["工具认知迷茫<br/>（面对 APK/ELF/JS 不知选 JADX、Radare2 还是 Frida）"]
        C2["授权范围越界<br/>（在无授权情况下对目标执行主动扫描与利用）"]
        C3["命令幻觉与虚假漏洞<br/>（声称存在 SQL 注入，却无任何复现流量与 Payload）"]
        C4["跨机器环境碎片化<br/>（本地缺失依赖即直接中断报错，无法自愈）"]
        C5["经验无法沉淀<br/>（解决一次 OLLVM 混淆后，下次遇到完全重踩踩坑）"]
    end

    subgraph ReverseSkillSolutions ["reverse-skill 核心治理体系"]
        S1["单一事实源路由矩阵<br/>（routing.json + 44 条严密规则）"]
        S2["Scope 契约硬门禁<br/>（auth.status != granted 严禁向目标 ACT）"]
        S3["Evidence → Finding → Path 证据图<br/>（SHA-256 固化与严格哈希校验）"]
        S4["多平台声明式自举<br/>（按需装配工具链并生成 tool-index）"]
        S5["field-journal 脱敏回写<br/>（沉淀先例库，实现知识自进化）"]
    end

    C1 ==> S1
    C2 ==> S2
    C3 ==> S3
    C4 ==> S4
    C5 ==> S5

    style AgentChaos fill:#ffebee,stroke:#c62828,stroke-width:2px;
    style ReverseSkillSolutions fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;

1. 工具链决策混乱：静态反编译、动态插桩、符号执行与流量重放具有严格的先后时序。没有先验约束的 Agent 常常在 Java 层还未做 triage 时就试图暴力编译 native .so，或者用错误的命令行参数胡乱调用 IDA；
2. 缺乏防线导致的非授权违规：渗透测试与逆向工程的生命线是合法授权。传统 Agent 只要收到一句模糊的 Prompt，就会直接向未授权的外部生产域名发起高频扫描，触发法律与安全红线；
3. “无凭据”的虚假交付：Agent 会输出洋洋洒洒数千字的“渗透结论”，但审视其过程，既没有不可变的日志快照（Artifact），也没有提供能在隔离环境中 100% 重现的 repro_command；
4. 跨系统环境迁移阻力：团队成员有的在 Windows，有的在 macOS，有的在 Kali Linux。工具路径分散、环境变量缺失，Agent 只要找不到可执行文件就彻底卡死；
5. 经验断层与重复踩坑：逆向过程中绕过某个厂商特定的反调试检测后，这些宝贵的经验只留在单次上下文里，随着会话结束而烟消云散。

为了破除这些顽疾，reverse-skill 应运而生。

二、架构灵魂：轻量纯粹的“身份宣言”

很多安全自动化项目最终都会走向臃肿：搭建 React 前端、部署 FastAPI 后台、引入 PostgreSQL、配置 Docker 容器池与 WebSocket 通信。然而，随着基建越来越重，真正留给 AI 专注思考的上下文和灵活性却被严重挤压。

reverse-skill 在其 ops/IDENTITY.md 中立下了极其清醒的架构宣言：

我们是：
- Skill 路由包：给任意 AI 客户端（Claude Code / Codex / Cursor / Kiro 等）使用的方法论 + 工具自举；
- 全流程基于纯文本 Markdown 契约与原生 CLI 脚本驱动；
- 零外部数据库、零重型容器池绑定，git clone 即可开箱即用。

我们故意不做：
- ❌ React 前端作战大屏
- ❌ FastAPI 控制面服务
- ❌ PostgreSQL 证据库
- ❌ 多 Agent 独立常驻后台守护进程

flowchart LR
    subgraph ClientAgnostic ["客户端中立层"]
        A1["Claude Code"]
        A2["Cursor"]
        A3["OpenCode / Codex"]
        A4["Antigravity / Cline"]
    end

    subgraph CoreEngine ["reverse-skill 核心治理体系"]
        direction TB
        R["RULES.md / MASTER-ROUTING<br/>（第一入口规范）"]
        SSOT["skills/config/routing.json<br/>（单一事实源路由中枢）"]
        SCOPE["ops/scope-contract.md<br/>（授权与网络沙箱边界）"]
        EFP["ops/evidence-finding-path.md<br/>（不可篡改证据图谱）"]
        BOOT["bootstrap-manifest.json<br/>（平台原生按需自举）"]
        JOURNAL["field-journal/<br/>（脱敏经验持续回写）"]
    end

    subgraph ConcreteWorkspaces ["本地轻量产物"]
        W1["work/case-xxx/scope.md"]
        W2["work/case-xxx/timeline.md"]
        W3["work/case-xxx/evidence/E-*.md"]
        W4["work/case-xxx/report/"]
    end

    ClientAgnostic ==> R
    R --> SSOT
    SSOT --> SCOPE
    SCOPE --> BOOT
    BOOT --> EFP
    EFP --> JOURNAL
    EFP -. 驱动落地 .-> ConcreteWorkspaces

    classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef client fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
    classDef work fill:#fff3e0,stroke:#e65100,stroke-width:2px;

    class CoreEngine,R,SSOT,SCOPE,EFP,BOOT,JOURNAL core;
    class ClientAgnostic,A1,A2,A3,A4 client;
    class ConcreteWorkspaces,W1,W2,W3,W4 work;

这种设计的精妙之处在于：把所有的状态管理完全托付给宿主工程的本地文件系统（work/<case>/ 目录），把所有的约束通过可机读的 Markdown 规范与轻量验证脚本强制锁定。无论开发者使用的是哪一款 AI 编程客户端，它都能在不修改任何内核的前提下无缝接入。

三、单一事实源（SSOT）与三轴路由矩阵

传统 Prompt 提示词最致命的缺陷是“模糊与多义”。如果只是告诉模型“分析 APK 去找 apk-reverse 目录”，当用户输入包含“分析 APK 里的前端 JS 加密与 native .so 调用”时，模型就会陷入分支纠结。

1. routing.json 规则中枢

reverse-skill 将路由规则抽象为一个完全机器可解析的单一事实源：skills/config/routing.json。该配置管理了 44 条严密规则（R0 到 R44），覆盖了从 APK、iOS、JS 逆向、IDA、Radare2、Binary Ninja、.NET、固件 IoT、恶意代码，到攻击链编排、EDR 绕过、API 安全与供应链审计的全场景。

每条规则定义了精确的正向词正则、反向排他规则与上下文语境要求：

{
  "schemaVersion": "1.0",
  "routes": {
    "R1": {
      "label": "APK reverse",
      "skill": "apk-reverse/SKILL.md",
      "keywords": [
        { 
          "must": "\\bapk\\b|smali|jadx|apktool|\\bandroid\\b|android.?reverse|安卓|反编译.?apk|apk.?加固|重打包|root.?detect|root.?检测|证书.?校验|certificate.?pinning|pinning.?绕过|签名.?校验", 
          "note": "android 裸词/root 检测/证书校验/pinning 绕过 均为 APK 分析常见诉求" 
        }
      ]
    },
    "R2": {
      "label": "Mobile reverse (Android+iOS)",
      "skill": "mobile-reverse/SKILL.md",
      "keywords": [
        { "must": "\\bipa\\b|ios.?reverse|objection|mobsf|mobile.?reverse|ios.?逆向" },
        { "must": "越狱", "exclude": "模型|提示词|llm|prompt|jailbreak|garak|红队.?ai|ai.?红队", "note": "越狱 裸词分给 iOS 侧；LLM/模型上下文归 R14" },
        { "must": "jailbreak", "mustAll": ["ios|iphone|ipad|mobile|objection|ipa"], "note": "jailbreak 仅当带 iOS 语境才归移动端" }
      ]
    }
  }
}

[!NOTE]
注意规则中的细致度：同样是“越狱/jailbreak”，当出现大语言模型相关上下文时，规则会自动将其分流到“LLM 安全（R14）”；只有在明确移动端 iOS 语境时，才会归属到移动逆向（R2）。这种排他判定彻底杜绝了关键词歧义引发的路由漂移。

2. 三轴匹配与优先级决胜机制

Agent 执行路由决策时，严格遵循“目标载体类型 + 操作意图 + 本机工具能力”的三轴坐标系：

flowchart TD
    Task["用户输入任务目标<br/>（例如：逆向某路由器固件并提取解密 key）"]
    
    subgraph TriAxis ["三轴交叉判定矩阵"]
        Axis1["目标类型：固件镜像 (bin/squashfs)"]
        Axis2["操作意图：文件系统解包 + 提取秘钥"]
        Axis3["工具支撑：binwalk / emba / qemu"]
    end

    Router["master-route.ps1 / master-route.sh<br/>（读取 routing.json 并打分）"]
    Winner["决出 PRIMARY Skill：<br/>skills/firmware-pentest/SKILL.md"]
    Action["强制加载该 Skill 的 ACTION REQUIRED 块"]

    Task --> TriAxis
    TriAxis --> Router
    Router --> Winner
    Winner --> Action

• 高灵敏度打分：每个命中项累加权重，若存在多个候选模块，严格按照 routing.json 中声明的 priority 数组顺序决胜；
• 全平台一致性保障：项目提供了 175 条回归测试用例，通过 GitHub Actions 在 Windows（PowerShell）与 Ubuntu（Bash）上同步执行校验，保证无论是在哪个系统环境调用 master-route，其决策逻辑与输出格式 100% 保持一致。

四、Ops 契约：未经授权，严禁向目标发出任何包

在传统安全工具或自主 Agent 中，最让人提心吊胆的是“AI 跑偏”。如果 Agent 自作主张执行了目录爆破、暴力破解或向未知外部 IP 发送了载荷，后果不堪设想。

reverse-skill 在架构上设立了铁一般的 Scope 契约硬门禁（ops/scope-contract.md）。

sequenceDiagram
    autonumber
    participant U as 用户 / Operator
    participant A as AI Agent
    participant Guard as case-guard 守卫
    participant Target as 目标资产 (Target)

    U->>A: 下发渗透测试或分析指令
    A->>A: 运行 master-route 确定 PRIMARY Skill
    A->>A: 运行 case-init 初始化 work/case-001/
    Note over A: 生成 scope.md（此时 auth.status 默认为 pending）
    
    rect rgb(255, 235, 238)
        A->>Guard: 试图执行主动探测 / 漏洞验证
        Guard-->>A: [Exit Code 2] 拦截！auth.status != granted，禁止对目标执行 ACT！
    end

    U->>A: 提供正式授权凭据（书面许可 / 合法离线样本证明）
    A->>A: 更新 scope.md: auth.status=granted, network_profile=authorized_target_only
    
    rect rgb(232, 245, 233)
        A->>Guard: 再次触发验证
        Guard-->>A: [Pass] 准许进入 ACT 阶段
        A->>Target: 在严格约束的资产范围内执行探测
    end

1. scope.md 字段约束

在向目标采取任何主动动作（扫描、Hook、渗透利用）前，必须在项目的 work/<case>/ 目录下实例化该文件：

# Case Scope

## meta
- case_id: 20260914-demo
- created: 2026-09-14T12:14:00+08:00
- primary_skill: apk-reverse/SKILL.md
- lead_role: lead
- specialist_roles: [cre, cpe]

## auth
- status: granted            # 仅在 granted 时允许 ACT；pending 或 denied 时硬性阻断
- basis: written_contract    # written_contract | bug_bounty_scope | ctf_public | own_system | lab_only
- evidence_of_auth: "Ticket #SEC-88219"

## in_scope
- assets: ["com.target.app", "192.168.10.15"]
- surfaces: [mobile, api]
- activities: [recon, reverse, exploit_validate]

## out_of_scope
- assets: ["*.payment.target.com"]
- activities: [dos, data_exfiltration, brute_force_account]

## network_profile
- mode: authorized_target_only  # offline | lab_only | authorized_target_only | unrestricted_lab

2. --force 无法穿透的硬门禁

项目内置了轻量守卫脚本 case-guard.ps1 和 case-guard.sh。即使使用者或 Agent 试图通过添加 -Force 或 --force 参数强行推进行动，脚本内部也做了绝对拦截：强制参数只用于跳过辅助检查，绝对不能绕过授权状态与资产范围的硬门。只要 auth.status != granted，脚本必定退出并返回状态码 2。

五、Evidence → Finding → Path：证据链的工程闭环

任何严肃的安全审计或漏洞报告，核心价值都在于 “可防御性（Defensibility）” 与 “绝对可复现”。许多 AI 助手生成的渗透总结往往是“经排查，该系统存在反序列化漏洞，建议升级组件”，却给不出受影响的文件行数、网络报文与重现命令。

reverse-skill 将工业级取证理念精炼为 EFP 证据图（Evidence → Finding → Path）：

graph TD
    subgraph EvidenceLayer ["不可变证据层 (Evidence)"]
        E1["E-001: smali 反编译代码片段<br/>(SHA-256 固化, 离线快照)"]
        E2["E-002: Frida Hook 动态捕获的明文密钥<br/>(repro_command: frida -U -f ... -s hook.js)"]
        E3["E-003: 重放 HTTP 请求获得的 200 OK 响应包<br/>(网络抓包证据)"]
    end

    subgraph FindingLayer ["安全/逆向结论层 (Findings)"]
        F1["F-001: 客户端硬编码 AES 秘钥导致数据解密<br/>(severity: high, status: validated)<br/>绑定证据: [E-001, E-002]"]
        F2["F-002: API 接口未校验签名导致越权篡改<br/>(severity: critical, status: validated)<br/>绑定证据: [E-003]"]
    end

    subgraph PathLayer ["调用链与攻击路径 (Path)"]
        P1["P-001: 完整绕过与未授权利用链路<br/>Step 1: 静态提取盐值 (E-001)<br/>Step 2: 动态伪造签名 (E-002)<br/>Step 3: 越权接口下发 (E-003)"]
    end

    E1 --> F1
    E2 --> F1
    E3 --> F2
    F1 --> P1
    F2 --> P1

    style EvidenceLayer fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    style FindingLayer fill:#fff8e1,stroke:#f57f17,stroke-width:2px;
    style PathLayer fill:#ede7f6,stroke:#512da8,stroke-width:2px;

1. 结构化契约定义

• Evidence（E-xxx）：不可变的底层事实。必须包含 observed_at、source_type、针对本地文件的 content_hash（SHA-256 值）以及关键的 repro_command。任何第三方安全人员拿到 repro_command 必须能在隔离环境中无障碍复现；
• Finding（F-xxx）：提炼出的安全缺陷或算法还原结论。强制要求 evidence_ids 字段非空。没有任何证据支撑的观点会被自动化审查工具直接判定为非法结论；
• Path（P-xxx）：由多个证据与结论串联而成的调用流（Call Flow）、攻击链（Attack Path）或 CTF 解题步骤。

2. 严苛的只读复核器：review_case.py

在输出最终交付成果前，项目提供了一个纯标准库构建的只读检查工具 skills/case-review/scripts/review_case.py。

在严格模式下运行：

python3 skills/case-review/scripts/review_case.py work/<case> --verify-hashes --strict

审查脚本会自动执行五大层面的逻辑一致性审计：

1. 范围完整性：检查 scope.md 是否存在、授权状态是否为 granted、资产范围是否覆盖；
2. 证据孤岛检查：查找是否存在被 Finding 引用但未在 evidence/ 中声明的幽灵 E-ID；
3. 空浮结论拦截：拦截所有缺少 evidence_ids 的 Finding；
4. 哈希抗篡改校验（Fixity Verification）：对所有声明了 content_hash 的证据文件，现场计算其 SHA-256 并与元数据比对。只要工作区文件被误改动哪怕一个字节，审查立即熔断；
5. 置信度校验：状态标记为 validated 的结论，其置信度（Confidence）绝对不允许为 low。

六、按需自举（On-Demand Bootstrap）与跨平台工具适配

安全工具生态繁杂庞大：Java 环境依赖（JADX、Apktool）、Python 动态插桩（Frida、Pwntools）、C/C++ 二进制底层（Radare2、Binwalk）、专有 MCP 服务器（Reqable MCP、IDA MCP、Ghidra MCP）。如果让开发者或用户在一开始手动将这几十种工具一一装齐，阻力极大。

reverse-skill 采取了 “按需声明式自举（On-Demand Bootstrapping）” 机制：

flowchart TD
    RunSkill["Agent 进入目标 Skill (如 apk-reverse)"]
    CheckTool["读取 skills/tool-index.md<br/>（检查本地环境状态）"]
    
    CheckTool --> Exists{工具存在且可用?}
    Exists -->|是| DirectExec["直接调用真实绝对路径执行"]
    Exists -->|否| ManifestCheck{"在 bootstrap-manifest.json 中已登记?"}
    
    ManifestCheck -->|已登记自动化工具| AutoInstall["调用原生 bootstrap 脚本<br/>(Windows: .ps1 / Linux & Mac: .sh)<br/>自动拉取二进制 / pip 安装"]
    ManifestCheck -->|登记为商业许可证件| ManualNotice["向用户输出官方规范安装引导<br/>（拒绝破解与非法规避）"]
    
    AutoInstall --> Refresh["执行 refresh-tool-index<br/>更新 tool-index.md 与 tool-index.json"]
    Refresh --> DirectExec

1. 显式能力清单：bootstrap-manifest.json

项目严格抵制“Agent 在终端里随意用 curl 管道给 bash”的高危安装行为。所有支持自动下载或编译的工具能力，全部登记在固定版本的 JSON 清单中：

• 自动化能力：jadx、apktool、radare2、frida、binwalk、pwntools 等；
• 商用/合规隔离：对于 JEB Pro、IDA Pro、Reqable 等需要商业授权的软件，自举脚本明确将其标注为 manual-license，绝不提供破解补丁，而是引导用户配置既有授权。

2. 动态事实索引：tool-index.md

在每个运行环境初次初始化时，项目脚本（refresh-tool-index.ps1 或 refresh-tool-index.sh）会全盘探测当前机器上的依赖状态，并将结果写入被 .gitignore 保护的 skills/tool-index.md。

Agent 在执行命令前，只允许信任 tool-index 中提供的真实绝对路径，彻底告别盲猜 which 或硬编码固定路径带来的执行崩溃。

七、实战推演：从接收 APK 到生成合规审计报告

为了更清晰地展现 reverse-skill 的运行全貌，我们模拟一次真实的 Android 应用逆向与接口越权验证流程。

sequenceDiagram
    autonumber
    actor Dev as 安全研究员
    participant Agent as AI Coding Agent
    participant RS as reverse-skill 架构底座
    participant Env as 宿主操作系统 / 终端

    Dev->>Agent: "分析这个 app-release.apk，确认其 API 请求签名的加密算法并验证是否存在重放漏洞"
    
    rect rgb(240, 248, 255)
        Note over Agent, RS: 阶段一：意图识别与安全路由
        Agent->>RS: bash skills/scripts/master-route.sh --hint "分析 app-release.apk API 签名与重放"
        RS-->>Agent: PRIMARY: skills/apk-reverse/SKILL.md (匹配规则 R1 + R3)
    end

    rect rgb(255, 243, 224)
        Note over Agent, RS: 阶段二：作战空间与授权初始化
        Agent->>RS: bash skills/scripts/case-init.sh --hint "apk-sign-audit" --case-name "sec-case-01" --preset offline-sample --sample ./app-release.apk
        RS-->>Agent: 初始化完成！生成 work/sec-case-01/scope.md (auth=granted, mode=offline)
    end

    rect rgb(232, 245, 233)
        Note over Agent, Env: 阶段三：静态反编译与证据固化
        Agent->>Env: 调用 tool-index 中的 jadx: jadx -d work/sec-case-01/decompiled app-release.apk
        Agent->>Env: 在 com.example.net.SignUtil 中定位到 native signRequest()
        Agent->>RS: 写入 E-001 (录入 Smali 与 Java 源码切片，记录 SHA-256)
    end

    rect rgb(243, 229, 245)
        Note over Agent, Env: 阶段四：动态插桩与解密验证
        Note over Agent: 需要网络对齐，更新 scope.md 为 authorized_target_only
        Agent->>Env: 编写并在后台运行 Frida 脚本 hook native 密钥拓展函数
        Env-->>Agent: 捕获到固定 HMAC-SHA256 盐值 "k8s!Sec_2026"
        Agent->>RS: 写入 E-002 (记录 Frida 命令与抓取的内存 Hex Dump)
    end

    rect rgb(255, 235, 238)
        Note over Agent, RS: 阶段五：严谨性复核与报告输出
        Agent->>RS: python3 skills/case-review/scripts/review_case.py work/sec-case-01 --verify-hashes --strict
        RS-->>Agent: 审查通过！0 Errors, 0 Warnings, 2 Evidence verified.
        Agent->>Dev: 交付结构化 Markdown 报告 + 经脱敏的 field-journal 避坑心得
    end

1. 意图快速分诊

收到任务后，Agent 不会直接开始写 Python 脚本，而是首先执行平台原生分诊脚本：

bash skills/scripts/master-route.sh --hint "分析 app-release.apk API 签名与重放"

系统迅速输出决策：命中核心规则 R1（APK 逆向），同时提示关联 R3（接口重放与数据流）。

2. 确立作战空间与 Scope

Agent 执行案例初始化：

bash skills/scripts/case-init.sh \
  --hint "apk-sign-audit" \
  --case-name "sec-case-01" \
  --preset offline-sample \
  --sample ./app-release.apk

系统在 work/sec-case-01/ 下生成整套作战资产。由于使用了 offline-sample 预设，network_profile 自动设置为 offline，杜绝任何外部发包风险。

3. 证据闭环录入

在分析过程中，Agent 捕获了关键签名代码，通过内置辅助指令录入证据：

# 写入静态代码分析证据
powershell -File skills/scripts/append-evidence.ps1 \
  -CaseRoot work/sec-case-01 \
  -Id E-001 \
  -Title "SignUtil JNI 声明代码" \
  -ReproCommand "jadx -d out app-release.apk && grep -rn 'signRequest' out/" \
  -ArtifactPath "decompiled/com/example/net/SignUtil.java"

4. 自动进化与经验回写

当任务成功完成、报告交付给用户之后，Agent 还会触发最后一步：经验沉淀。
在 field-journal/ 中，Agent 将本次逆向遇到的特定 Android NDK 混淆绕过技巧以完全脱敏的形式记录下来。在未来的任务中，当其他 Agent 检索到相似场景时，可以直接复用这份经验，实现真正的模型工作流自进化。

八、架构启示：为自治 Agent 构筑“确定性护栏”

观察 reverse-skill 的设计理念，我们可以提炼出面向下一代高风险领域 AI Agent 开发的三条普适性架构哲学：

在大模型推理能力突飞猛进的今天，给 AI“松绑”并不意味着任其失控。特别是在网络攻防、逆向分析、金融风控与系统底层运维等高容错代价的垂直领域，用确定性的工程契约（Contracts）、单一事实源（SSOT）与物理门禁（Gates）去约束和引导大模型，才是让 AI 从“好玩的玩具”蜕变为“生产力重器”的必由之路。