ArmorBreak · 破甲模式

DeepSeek Harness 原生「授权逆向工程与安全研究」Agent 模式：46 个真实可执行的离线分析能力、L0–L3 代码级权限引擎、逐任务证据哈希链与可复核报告。以 Cordis Bundle + Agent preset 形式嵌入 DeepSeek Harness，不修改 Harness 核心。

Authorized Reverse Engineering & Security Research Agent — a native Agent preset for DeepSeek Harness / Cordis.

Slogan：Evidence or it didn't happen. 每一个安全结论，都必须能回到证据。

徽章说明：不展示未接入的服务指标（Docker 拉取量、第三方生态评分等）；测试数/覆盖率来自本仓库可复现的 node --test 结果，CI 徽章以 GitHub Actions 实际运行为准。

---

目录

• 一、项目概览 Overview
• 二、设计哲学与原则 Design Philosophy
• 三、核心架构 Core Architecture
• 四、核心技术原理 Technical Principles
• 五、安全设计 Security
• 六、关键特性 Key Features
• 七、技术栈 Tech Stack
• 八、性能基准 Benchmarks
• 九、快速开始 Quick Start
• 十、安装与部署 Installation
• 十一、使用指南 Usage
• 十二、治理与社区 Governance
• 十三、路线图 Roadmap
• 十四、架构决策记录 ADR
• 十五、故障排查与 FAQ
• 十六、生态与集成 Ecosystem
• 十七、案例研究 Case Studies
• 十八、许可证 License
• 十九、致谢 Acknowledgments
• 附录：文件结构与文档索引

---

一、项目概览 Overview

1.1 背景与痛点

安全研究 Agent 在 2024–2026 年快速从「调用几个工具的聊天机器人」演进为「带规划与执行闭环的智能体」。但把它真正放进授权研究现场时，四类结构性缺陷会立刻暴露：

维度	现有方案的典型做法	后果
通用性	把几十个安全 CLI 用自然语言包一层	工具说明挤占上下文、依赖冲突、模型混淆参数
正确性	LLM 自己「总结」工具输出	无法区分观测事实与猜测；扫描告警常被当成漏洞
可追溯性	日志散落在临时目录	报告无法回到原始证据；复测条件不可复现
安全性	只在系统提示词里写「不要越界」	权限边界不落在执行层，提示注入/提示词漂移即可绕过

技术层面，DSH/Cordis 生态提供了原生扩展点（bundle patch、Agent preset、工具/技能注册、审批服务），但缺少一个把「专业能力 + 权限 + 证据」组合起来的参考实现。 工程层面，安全分析工具链普遍重依赖（JVM/原生库/规则包），在受限主机和宿主进程内不可移植。 业务层面，授权研究者需要的是可复核的结论，而不是更大声的告警；违反授权范围的自动化哪怕只有一次，也会让研究失去合法性。

ArmorBreak 的设计目标因此不是「再加一个安全 AI」，而是：

把授权边界、真实执行、证据链、可复核报告，做成 DeepSeek Harness 里一个可安装、可卸载、可审计的 Agent 模式。

1.2 项目定位

维度	定位
技术层级	平台扩展（Platform Extension）：Cordis Bundle + Agent preset + 可选 Web 面板
运行位置	DeepSeek Harness Host 进程内（与 Harness 同生命周期）
目标用户	软件安全研究员、逆向工程学习者、CTF 选手、代码审计/安全开发人员、DFIR 分析人员
适用场景	本地样本离线静态分析、APK 审计、PCAP 取证、源码/SBOM 审计、CTF/靶场、授权范围内的受控主动测试
不适用	未授权目标的扫描/攻击、凭据窃取、隐蔽持久化、恶意代码投递、破坏性操作（L3 永久拒绝）
运行时依赖	0（仅 Node 内置模块；无构建步骤、无安装脚本）

1.3 核心价值（全部可量化）

指标	数值	来源
真实可执行能力（capabilities）	46（8 个域）	armorbreak_capabilities / registry.list()
模型可见工具	10（工具目录而非 42 个适配器逐一暴露）	tools.js
内置技能	7	skills.js
可复用工作流模板	9	lib/core/workflows.js
自动化测试	385 tests / 384 pass / 1 skipped	node --test + raw TAP evidence
代码覆盖率	历史 v1.2.0 数据；本分支以 test-report.json 为准	node --test --experimental-test-coverage
运行时依赖	0（node:* only）	package.json
360 KiB PE 静态解析（p50）	binary.identify 1.72 ms / forensics.hash 0.84 ms	benchmarks
PCAP 解析吞吐	≈ 0.54–0.64 M packets/s（5,000 包 p50 7.8–9.6 ms）	同上
目录扫描	≈ 2,272 files/s（200 个 JS 文件 p50 88 ms）	同上
报告生成（50 findings / 100 evidence）	Markdown 4.1 ms / SARIF 3.7 ms	同上
权限级别	L0/L1/L2/L3 四级，代码强制；L3 无自动执行通道	lib/core/scope.js、runner.js

1.4 可视化展示

① 模式状态面板（真实截图，注册在 conversation.composer.dock，读取只读路由 /armorbreak/state）：

② 报告交付物（同一模式下多任务、多格式产出，文件名即工作流+时间戳）：

③ 架构全景（数据流见 §三）：

                 ┌──────────────────────── DeepSeek Harness Host ────────────────────────┐
                 │  Loader composition: dsh-base → dsh-web-app → [dsh-armorbreak layer]  │
                 │                                                                        │
  Agent preset ──┼─► 破甲模式 (persona)                                                   │
  「破甲模式」    │      ├─ 8 model-facing tools  (armorbreak_*)                            │
                 │      ├─ 7 bundled skills      (ctx.skills.register)                    │
                 │      └─ standard fs/shell/compaction tooling                            │
                 │                                                                        │
                 │  Host row: armorbreak ──► 运行时单例                                     │
                 │     ├─ Capability Registry (46, contract-validated)                     │
                 │     ├─ Scope Policy (L0–L3, approvals, allowlists, rate limit)          │
                 │     ├─ Execution Runner (bounded I/O, timeout, evidence, audit)         │
                 │     ├─ Task Engine (15 states, 9 workflows)                             │
                 │     ├─ Evidence/Audit hash chains (.armorbreak/)                        │
                 │     └─ GET /armorbreak/state (read-only, redacted) ──► browser card     │
                 └────────────────────────────────────────────────────────────────────────┘

---

二、设计哲学与原则 Design Philosophy

2.1 核心设计理念

1. Fail-closed（默认拒绝）：没有授权就没有网络，没有审批就没有动态执行，L3 永远拒绝。
2. Evidence-first（证据优先）：任务不是一个聊天回合，而是一份可复核的工件：状态轨迹、步骤结果、证据哈希链、审计哈希链。
3. Zero-dependency（零依赖可移植）：模式必须能在任意 DSH 主机上安装即用；能力实现只使用 Node 标准库。
4. Additive extension（增量扩展）：只 insert 自己的行与 preset，不覆盖、不重构 Harness 核心；卸载后既有模式完整保留。
5. Untrusted-by-default（被分析内容不可信）：样本、日志、PCAP payload、源码注释中的「指令」一律视为数据，不改变任务/范围/安全规则。
6. Honest verification（诚实的验证等级）：observed / corroborated / hypothesis / unverified 四级；扫描告警永远不自动升级为确认漏洞。

2.2 核心设计准则（6 条，含工程落地）

#	准则	工程化落地
1	权限必须由代码而非提示词强制	ScopePolicy 校验路径/网络/审批；ExecutionRunner 是唯一执行入口；测试覆盖允许与拒绝分支
2	每次执行都必须可重放	每条证据记录目标 SHA-256 + 摘录；JSONL 哈希链（prevHash）防篡改；报告引用 evidence id
3	输入与输出都必须有界	输入默认 32 MiB、单文件 4 MiB、结果 256 KiB、findings 200、字符串 1,000；超限标注 truncated
4	命令必须参数化，不拼 shell	外部进程只用 execFile(argv)；镜像/命令模板固定；子进程环境变量白名单
5	目录读取必须 realpath 收敛	目录根与读取目标均 realpath 双向校验；符号链接/junction 逃逸拒绝；listFiles 不枚举符号链接
6	模式必须可拆卸	bundle 只 insert 两行；remove_bundle 后 4 个 shipped preset 完整保留（生命周期测试覆盖）

2.3 技术选型与 Trade-off

决策	选型	备选方案	取舍理由
实现语言	纯 ESM JavaScript（Node 24）	TypeScript + 构建	DSH 直接加载源码，零构建链意味着安装/升级/审计路径最短；JSDoc 提供类型信息
运行时依赖	0	js-yaml / schema 校验库 / SQLite	profile 安装时会执行 pnpm，依赖会引入网络/版本冲突；用内置实现换取可移植性
持久化	工作区内 JSONL + 原子写	SQLite / 外部 DB	无原生模块依赖；证据按工作区存储、可直接审计；用哈希链补偿无事务
权限边界	进程内策略引擎 + 平台审批	依赖 OS 沙箱	Host 进程本身在宿主沙箱内；ArmorBreak 在宿主之上再加任务级范围与审批，纵深防御
外部工具	探测 + 安装指引（v1）	立即封装 Ghidra/JADX 等	外部工具版本/许可证/输出格式差异大；先把纯 JS 能力与证据链接通，再逐个适配
UI	composer dock 状态卡	独立全屏工作台	不替换 app root、不独占导航；v1 只读展示，操作通过对话工具完成
目录型能力	显式 targetKind 契约	运行时猜测	v1.0.2 的真实缺陷证明猜测会静默失败；显式声明 + 规划期校验

---

三、核心架构 Core Architecture

3.1 分层架构

层	组件	职责边界	交互协议
L-Agent Persona	cordis.patch.yml → @deepseek-ai/dsh-persona	身份、硬边界、证据纪律、工作方法	system prompt sections
L-Skills	skills.js + skills/*.md	7 个专业领域方法论，按需加载	ctx.skills.register
L-Tools	tools.js	10 个模型工具：参数校验、审批桥、结果渲染	ctx.tools.register
L-Core	lib/core/*	能力注册、策略、任务状态机、执行、证据、报告、健康	纯 JS API（无 Cordis 依赖）
L-Analyzers	lib/analyzers/<domain>/manifest.js	46 个能力实现，统一 run(input) 契约	进程内函数调用
L-Host	index.js	运行时单例接线 + 只读状态路由	ctx.webServer.register
L-UI	client.js	状态卡（能力/隔离/策略/任务）	window.__ModuleLoader__ + Slot
L-Storage	工作区 .armorbreak/	任务、证据、发现、报告、审计	原子写 + JSONL

3.2 核心数据流（一次真实分析的生命周期）

sequenceDiagram
    autonumber
    participant U as Operator / Model
    participant T as Tool (armorbreak_analyze/workflow)
    participant R as ExecutionRunner
    participant P as ScopePolicy
    participant A as ApprovalService
    participant C as Capability
    participant E as EvidenceStore
    participant D as AuditLog
    participant F as Files (.armorbreak)

    U->>T: capability + target + workspace
    T->>R: runCapability(task, capabilityId, ...)
    R->>R: prepareTask: CREATED→SCOPE_VALIDATION→ENVIRONMENT_CHECK→PLANNING
    alt L0 offline
        R->>P: checkFile(realpath containment)
    else L1 dynamic
        R->>P: checkExecution(isolation available?)
        R->>A: request(allowed-once)
        A-->>R: grant / reject
    else L2 active
        R->>P: checkNetwork(target, authorization, approval, rate)
    else L3
        R-->>T: PolicyDenied(L3_DENIED)
    end
    R->>C: run(boundedInput)
    C-->>R: {summary, data, findings, evidence}
    R->>E: appendEvidence (SHA-256 + hash chain)
    R->>E: addFinding (fingerprint dedupe)
    R->>D: append capability.run.start/end (redacted)
    R->>F: atomic writes
    R-->>T: normalized result
    T-->>U: bounded Markdown + structured data
    Note over R,F: finalize: VERIFYING→REPORTING→COMPLETED/PARTIAL_SUCCESS

异常路径：策略拒绝 → 任务 REJECTED（不执行）；能力抛错 → 步骤 FAILED，其余独立步骤继续， 最终 PARTIAL_SUCCESS 且证据保留；超时/取消 → TIMED_OUT / CANCELLED。

3.3 核心模块拆解

模块	文件	职责	关键实现
Runtime	runtime.js	进程级单例、工作区上下文、状态快照	globalThis[Symbol.for('dsh.armorbreak.runtime')] 防重复模块代际
Registry	capabilities.js	扫描/校验 manifest、诊断、依赖描述	契约校验：id/title/description/riskLevel/params/run；失败不阻断其他域
Scope	scope.js	授权记录签名、路径/网络校验、审批、限速	realpath 边界、CIDR/通配符/端口匹配、token bucket
Runner	runner.js	唯一执行入口	策略门 → 有界输入 → 超时/取消 → 结果归一化 → 证据/审计
Tasks	tasks.js	15 状态机、步骤、持久化	合法迁移表；非法迁移抛错；原子写 + 文件互斥
Evidence	evidence.js	证据链、发现去重/验证	指纹 `sha256(title
Audit	audit.js	审计哈希链、脱敏	prevHash 链；敏感键/值统一 REDACT
Reports	reports.js	MD/HTML/JSON/SARIF/PDF	SARIF 2.1.0；PDF 经本地 LibreOffice；时间戳命名不覆盖
Health	health.js	外部工具探测、隔离检测、环境快照	PATH/GHIDRA_HOME 探测；Docker daemon 探活；版本探测超时 1.5s
Workflows	workflows.js	9 个可复用模板	目录/文件/无目标三类；规划期 target-kind 校验

3.4 关键时序：审批与拒绝

flowchart TD
    A[工具调用 L1/L2 能力] --> B{审批服务可用?}
    B -- 否 --> R1[FAIL CLOSED: APPROVAL_REJECTED]
    B -- 是 --> C[ctx.approval.request]
    C --> D{outcome == allowed-once?}
    D -- 否 --> R1
    D -- 是 --> E[ScopePolicy.recordApproval]
    E --> F{scope 校验通过?}
    F -- 否 --> R2[PolicyDenied: OUT_OF_SCOPE / APPROVAL_MISMATCH]
    F -- 是 --> G[consume approval + rate token]
    G --> H[execute capability]

---

四、核心技术原理 Technical Principles

4.1 创新点总览

创新点	与业界现有方案的本质差异
Capability Contract + Runner 单一咽喉	大多数 Agent 工具直接调 CLI；这里所有执行经过一个可测试的策略/证据管线
证据哈希链 + 审计哈希链	扫描器通常只有日志；这里每个结论可回到带 SHA-256 的不可静默篡改记录
L0–L3 四级能力闸	常见做法是 shell 审批 + 提示词；这里按能力风险级别做结构化策略（路径/网络/隔离/审批/限速）
Directory-target 规划期校验	从真实缺陷中提炼：能力显式声明 targetKind，规划阶段 fail-fast，而不是运行时猜
零依赖纯 JS 解析器族	在 Harness 进程内直接可用，无 JVM/原生依赖；外部工具作为可选增强

4.2 策略引擎的代数模型

风险格：能力风险 r ∈ {L0, L1, L2, L3}，任务风险取步骤最大值：

riskMax = max_{s ∈ steps} risk(capability(s))        // L0 < L1 < L2 < L3

执行许可（allow(task, cap)）：

allow = 
  (r = L0) ∧ (pathAllowed(target) ∨ authorizedPath(target))
∨ (r = L1) ∧ isolationAvailable ∧ approvalGranted(task, target) ∧ pathAllowed(sample)
∨ (r = L2) ∧ authorizedNetwork(target) ∧ approvalGranted(task, target) ∧ rateToken(target)
∨ false                                    // r = L3 恒 false

路径约束（防符号链接/目录穿越）：

resolved = realpath(target exists ? target : resolve(target))
allowedPath ⇔ inside(realpath(workspace), resolved) ∨ ∃ a ∈ authorizations: inside(realpath(a.path), resolved)
denySensitive(resolved) ⇔ resolved ∈ {System32, SysWOW64, /proc, /sys, /dev, /etc/shadow, …}

网络匹配支持精确主机、*.domain、IPv4/IPv6 CIDR、可选端口；端口作用域模式不匹配端口未知的目标：

match(pattern, target) =
  portOK(pattern.ports, target.port)
  ∧ ( target ∈ CIDR(pattern)                      if pattern is CIDR
      ∨ target.host = pattern.host                 if exact
      ∨ target.host endswith "." + pattern.domain  if "*.domain" )
portOK(ports, p) = ports = ∅ ∨ (p ≠ null ∧ p ∈ ports)

令牌桶限速（每 host，容量 20，补充 0.5 token/s）：

tokens(t) = min(C, tokens(t₋₁) + elapsed × ρ)
allow = tokens ≥ 1; tokens -= 1

4.3 哈希链结构

审计与证据都是追加 JSONL；第 n 条记录：

record_n = { seq:n, at, prevHash: hash_{n-1}, payload }
hash_n   = SHA256(prevHash + "\n" + canonicalJSON(record_n \ {hash}))

verify: ∀n: record_n.prevHash = hash_{n-1} ∧ SHA256(...) = hash_n

canonicalJSON 对对象键排序，避免序列化差异导致误判。并发安全由按文件互斥队列保证：

mutex(file):  tail = prior.then(() => gate)
append:       await prior; tail' = readTail + compute + write; release

4.4 无损 JSON 净化（Tool Output Contract）

Harness 的审计通道只接受无损 JSON。工具输出在出口执行深度投影：

toLosslessJson(value):
  null | string | finite number | boolean | array | plain object → 保留
  function | symbol | undefined → 丢弃
  bigint → decimal string
  Date → ISO string
  TypedArray → { type:'bytes', length }
  cycle → "[circular]";   depth > 12 → "[depth-limit]"

该函数由 tests/tools-lossless.test.mjs 递归验证；它也是真实故障（value is not lossless JSON）的修复产物。

4.5 有界解析与复杂度

能力族	算法	复杂度	硬上限
哈希	crypto.createHash 流式	O(n)	输入 32 MiB
PE/ELF/Mach-O	头/节表线性扫描 + 字符串提取/排序	O(n log n)	字符串 1,000
PCAP/PCAPNG	单遍包解析 + 5 元组哈希表	O(packets + flows)	items 300
SAST	逐行 59 条规则 × 文件	O(files × rules)	files 2,000 / file 4 MiB
CTF 解码	变换链，深度上限	O(depth × n)	depth 8
YAML 子集	递归下降，深度上限	O(tokens)	flow 64 / node 128

4.6 性能优化（含实测收益）

优化	机制	实测效果
单遍解析	binary.identify 一次扫描完成格式/节/导入/字符串索引	360 KiB PE 1.72 ms
哈希复用	forensics.hash 一次遍历喂多个 hash 实例	360 KiB 0.84 ms ≈ 417 MB/s
目录扫描按需读取	env.listFiles 只枚举、env.readFile 按文件大小上限读取	200 文件 88 ms ≈ 2,272 files/s
有界结果	输出 256 KiB 截断 + 深度裁剪，避免大对象序列化	报告生成 4 ms 级
原子写	<file>.tmp + rename，避免半写文件	崩溃后 JSON 可解析
进程内互斥	按文件 promise 队列，取代跨进程锁	并发 30 次审计 append 链仍连续（测试）
惰性能力加载	manifest 动态 import，按域加载	冷启动 62.8 ms（39 能力）

已知性能瓶颈（诚实记录）：一次完整的 runner 调用约 36 ms，其中解析仅 0.8 ms， 其余是任务状态/证据/审计的持久化。批量场景应复用任务而非每样本建任务（路线图 R1）。

4.7 高可用与一致性（单进程语义）

ArmorBreak 不是分布式服务；它的一致性模型是单 Host 进程内的顺序持久化：

• 任务状态机非法迁移直接抛错，不会产生「不可能状态」；
• 证据/审计链只追加，篡改可检测；链损坏会在报告与工具结果中显著标注；
• 原子写保证崩溃后文件要么是旧版要么是新版；
• 进程内互斥保证并发工具调用不 fork 链；
• 不支持多 Host 进程同时写同一工作区（未加跨进程文件锁）；已知限制见 docs/known-issues.md。

---

五、安全设计 Security

5.1 威胁模型

资产	威胁	等级	缓解
宿主文件系统	路径穿越 / 符号链接 / junction 逃逸	高	realpath 双向校验、敏感路径拒绝、目录枚举跳过链接
宿主网络	未授权主动探测	高	L2 授权目标白名单 + 平台审批 + 限速；默认拒绝
样本执行	未知样本在宿主执行	高	L0 不执行；L1 仅一次性容器（network none/read-only/cap-drop）+ 审批
模型上下文	被分析内容提示注入	高	内容视为数据；persona 约束；输出控制字符剥离；工具不做内容驱动的范围变更
证据/审计完整性	静默篡改、并发断链	中高	哈希链 + 并发互斥 + 链校验
凭据/敏感数据	日志、报告、UI 泄露	中高	统一脱敏 [REDACTED]；状态路由只读脱敏；无凭据入参设计
审批伪造	模型自我批准	高	只有平台 ctx.approval.request 的 allowed-once 才记录；无通道 fail-closed
L3 能力误用	破坏/外传/持久化	严重	无授权路径、恒拒绝、无自动通道

5.2 纵深防御体系

1. 身份层：mode 选择 + persona 硬边界（但边界执行不依赖它）。
2. 策略层：ScopePolicy 路径/网络/审批/限速。
3. 执行层：ExecutionRunner 单一咽喉；能力无法绕过 runner 获得输入。
4. 数据层：有界读取、输出截断、脱敏、哈希链、原子写。
5. 展示层：只读路由 + 脱敏快照；不提供任何执行入口。
6. 宿主层（委托）：DSH 自身的 sandbox/approval/persistence；ArmorBreak 不替代宿主沙箱。

5.3 安全审计与合规

• 代码审计：node --test（146 用例）覆盖策略允许/拒绝、路径逃逸、并发链、脱敏、YAML 原型污染；
• 依赖漏洞：零运行时依赖，无第三方供应链面；
• 数据合规：全部数据留在本机工作区，不上传；报告可导出；
• 参考标准映射：OWASP ASVS（输入校验/访问控制/日志）、CWE 映射、CVSS 4.0 评分依据、SARIF 2.1.0 输出； 不宣称通过等保/GDPR/SOC2 认证（本地工具，无云服务）。

5.4 漏洞披露

见 SECURITY.md：GitHub 私密安全公告或邮件；72h 确认、7 天分诊、高危 30 天内修复计划、默认 90 天协调披露；致谢机制。

---

六、关键特性 Key Features

6.1 基础能力层（离线、零依赖）

能力	技术实现要点	适用场景
PE/ELF/Mach-O 识别	头/节/架构/入口/导入导出/加壳启发式/overlay	样本初筛、格式确认
字符串与熵	ASCII + UTF-16LE 分类提取；块/节熵	加壳/混淆判断（hypothesis）
哈希与元数据	MD5/SHA-1/SHA-256/SHA-512；PE/ELF/ZIP/PNG/JPEG/PDF 元数据	证据固定、时间线
APK 审计	ZIP 中央目录 + AXML + DEX + v1/v2/v3 签名块	移动应用静态评估
PCAP 取证	pcap/pcapng、Ethernet/raw-IP/SLL、TCP/UDP、DNS/TLS 元数据/明文 HTTP	流量取证、IOC
HAR/OpenAPI	安全头/Cookie/CORS/认证/参数审计；YAML 子集解析	Web API 审计
SAST/供应链	59 条规则、7 语言、密钥检测、依赖盘点、CycloneDX SBOM、补丁建议	代码审计
CTF	编码分类/递归解码/哈希识别/古典密码/flag 扫描	CTF/靶场

# 例：单能力执行（模型工具调用）
armorbreak_analyze {
  "capability": "binary.identify",
  "target": "D:\\work\\sample.exe",
  "workspace": "D:\\work"
}

6.2 高级能力层（差异化）

• 9 个工作流：BinaryStaticAnalysis、AndroidAPKReview、WebCodeSecurityReview、 PCAPInvestigation、DependencyAudit、CTFArtifactAnalysis、ForensicFileReview、 WebAPIReview、SecurityReportGeneration。
• 15 状态任务机：规划期 target-kind 校验、失败保留、部分成功、取消/超时。
• 证据/审计双哈希链：报告自动附带链校验结果。
• 授权 + 平台审批：真实 ctx.approval.request 桥接，无通道 fail-closed。
• 状态卡：宿主 Web UI 内展示能力/隔离/最近任务（只读、脱敏）。

armorbreak_workflow action=start workflow=WebCodeSecurityReview \
  target="D:\\repo" workspace="D:\\work"
→ plan: 4 steps (sast.scan/secrets/deps/sbom), targetKind=directory
armorbreak_workflow action=run taskId=task_...
→ 4/4 DONE, evidence N, findings M, report path

6.3 企业级特性（可运维、可审计）

特性	实现
可复核性	任务 JSON + 证据 JSONL + 审计 JSONL + 报告（时间戳命名，不覆盖）
可运维性	健康检查（环境/隔离/外部工具/策略）、能力诊断、清理脚本
可扩展性	新增能力只需新增 manifest + 测试（契约校验自动接入）
可拆卸性	bundle remove 后既有 preset 完整保留
升级安全	源码安装语义清晰：link/reinstall + 重启模块代际

6.4 生态扩展能力

• DSH 生态：作为 Cordis Bundle / Agent preset 注册，见 docs/marketplace.md。
• 外部工具适配：探测 + 安装指引（当前版本）；适配器接口已在契约中预留。
• UI 扩展：dsh.client + Slot 注册；可继续扩展任务工作台/工具中心。
• 报告互操作：SARIF 2.1.0（CI/代码扫描平台）、CycloneDX SBOM、Markdown/HTML/JSON。

---

七、技术栈 Tech Stack

层	技术	版本	选用原因
语言/运行时	JavaScript (ESM) / Node.js	Node ≥ 22（验证于 24.21 / 24.16）	DSH 同运行时；零构建；node: 内置即可完成所有解析
扩展框架	Cordis	4.0.x	DSH Host 的组合/服务/生命周期模型；只用其稳定契约
Harness 集成	@deepseek-ai/dsh-agent-preset, dsh-tools, dsh-skill, dsh-host-webserver, dsh-user-approval	0.2.1-rc.2	官方扩展点：preset、工具、技能、审批、Web 路由
持久化	文件系统 JSON/JSONL + 原子 rename	—	无原生模块；可直接审计；工作区自包含
测试	node:test + node --experimental-test-coverage	24	与运行时同栈；零依赖；CI 无安装步骤
CI/CD	GitHub Actions	actions/checkout@v4, setup-node@v4	双平台（Ubuntu/Windows）跑测试、覆盖率与基准
可观测性	审计/证据 JSONL、任务状态轨迹、报告、/armorbreak/state	—	本地优先：无外部 APM/遥测依赖；数据不出机器
UI	dsh.client 浏览器模块（React from module table）	—	与官方 UI 同栈、同 Slot 机制；主题 token 自动适配
外部工具（可选）	Ghidra / Rizin / YARA / JADX / apktool / adb / Frida / Semgrep / CodeQL / Trivy / Syft / Gitleaks / TShark / Zeek / Suricata / Nmap / Volatility3 / capa / FLOSS / Docker / LibreOffice	探测	不打包、不静默安装；缺失时给出安装指引与内置替代

---

八、性能基准 Benchmarks

完整方法、环境与复现命令见 docs/benchmarks.md；原始数据 benchmarks/results.json。

8.1 测试环境

Intel Core Ultra 9 290HX Plus（24C/24T，2.70 GHz）· 63.68 GiB RAM · Windows 11 x64 · Node v24.16.0 · ArmorBreak v1.0.3（39 capabilities / 8 domains）· 样本 notepad.exe 360,448 B · 合成 PCAP 5,000 包/700,024 B · 合成 JS 项目 200 文件。

8.2 核心结果（p50，parser 级）

路径	p50	p95	吞吐	推导单位成本
forensics.hash 360 KiB	0.842 ms	0.956 ms	1,157 ops/s	≈ 417 MB/s
binary.identify 360 KiB PE	1.718 ms	2.349 ms	545 ops/s	≈ 210 MB/s
binary.strings	1.631 ms	2.309 ms	569 ops/s	≈ 221 MB/s
binary.entropy	2.558 ms	2.878 ms	386 ops/s	≈ 139 MB/s
network.pcap_overview 5k 包	7.770 ms	10.605 ms	121 ops/s	≈ 643k packets/s
network.flows 5k 包	9.592 ms	11.201 ms	108 ops/s	≈ 540k packets/s
sast.scan 200 文件	88.020 ms	123.599 ms	10.7 ops/s	≈ 2,272 files/s

8.3 端到端与报告

路径	p50	p95	说明
forensics.hash 经 runner	36.379 ms	40.448 ms	含任务状态/证据/审计持久化
BinaryStaticAnalysis（7 步）	483.186 ms	492.990 ms	含默认报告生成
能力注册表冷启动	62.83 ms	—	39 能力契约校验
报告 Markdown / HTML / SARIF	4.1 / 4.0 / 3.7 ms	≤5.2 ms	50 findings + 100 evidence
进程内存	RSS 257.3 MiB / heap 26.3 MiB	—	全量基准后

8.4 横向与纵向对比

• 横向：本机未安装 Ghidra/Semgrep/TShark 等外部工具，因此只做架构维度定性对比（依赖、离线默认、证据链、策略、可移植性），不伪造性能数字；见 benchmarks 文档 §5。
• 纵向：v1.0.0 → v1.0.3 测试 128→146，核心覆盖率 84.9%→85.6%，runner 覆盖率 88.55%→93.65%，并发互斥引入的额外开销为每次 append 一次 promise 队列（µs 级，低于文件 I/O 抖动）。

8.5 复现

node benchmarks/bench.mjs --sample /path/to/sample.exe --out benchmarks/results.json
node --test --experimental-test-coverage

---

九、快速开始 Quick Start

9.1 环境要求

• DeepSeek Harness Desktop 0.2.1-rc.2（或同版本 CLI profile）；Node 24 随 Harness 提供。
• 本机文件系统可写（任务数据写在工作区 .armorbreak/）。
• 可选：Docker（L1）、LibreOffice（PDF）、外部安全工具（增强）。

9.2 一分钟安装（Desktop）

git clone https://github.com/LYL-Z/dsh-armorbreak.git D:\tools\dsh-armorbreak
# 打开 DeepSeek Harness → 设置 → 插件 → 添加插件 → 选择 D:\tools\dsh-armorbreak
# 或让 Agent 执行：plugin_manager action=install_bundle target="D:\\tools\\dsh-armorbreak"

新建会话 → 模式选择 → 破甲模式。输入框下方会出现状态卡。

9.3 第一个分析

调用 armorbreak_health 检查环境；
然后创建任务并用 BinaryStaticAnalysis 工作流分析 D:\samples\hello.exe；
最后生成 markdown 报告并汇报：任务 id、状态、证据数、发现数、报告路径。

预期（真实输出形状）：

任务 task_xxx → COMPLETED；证据 ≥7；发现 ≥0；
报告：D:\work\.armorbreak\tasks\task_xxx\reports\binarystaticanalysis_<ts>.md

9.4 常见启动问题

症状	原因	处理
模式列表没有「破甲模式」	bundle 未安装/未选择，或未重启加载新模块代际	plugin_manager list_bundles；安装返回 applied；完全重启 Harness
状态卡不出现	非 Web 组合（headless/TUI）或路由未注册	桌面/Web profile 才有该卡片；/armorbreak/state 应 200
安装报 already-installed	同版本已安装	先 remove_bundle 再安装新版本
目录工作流失败	v1.0.0 的已知缺陷	升级到 v1.0.2（TARGET_KIND_MISMATCH 规划期校验 + 目录能力声明）

---

十、安装与部署 Installation & Deployment

10.1 多形态安装

形态	命令/入口	说明
DSH 面板	设置 → 插件 → 添加插件 → 本地目录 / github:LYL-Z/dsh-armorbreak	推荐；安装后 applied 即可用
plugin_manager	plugin_manager action=install_bundle target=...	Agent 会话内安装；返回 application 为准
CLI（非 desktop profile）	dsh plugin --profile <p> add github:LYL-Z/dsh-armorbreak	开发/测试 profile
本地源码（开发）	克隆后 install_bundle/link:	零构建步骤，改完重启即生效

为什么没有 Docker / Kubernetes / Helm 部署：本项目是 Agent 宿主进程内的扩展， 不是独立网络服务。它的「部署拓扑」就是 DSH 本身的拓扑（单 Host 进程 + 一个 profile）。 容器化的合理形态是把「DeepSeek Harness + profile + 本 bundle」整体放进容器，而不是单独容器化本 bundle； 本仓库不发布 Docker 镜像，也不宣称支持 K8s——这是设计边界，不是待办事项。

10.2 生产部署建议（单机研究工作站）

┌─────────────── Workstation ───────────────┐
│ DeepSeek Harness Desktop (single process) │
│  ├─ profile: desktop                      │
│  ├─ dsh-armorbreak bundle (source-linked) │
│  ├─ workspace: D:\research\case-001       │
│  │    └─ .armorbreak/{tasks,audit.jsonl}  │
│  ├─ isolation: Docker (optional, L1)      │
│  └─ reports: per-task reports/ (MD/HTML/…)│
│                                            │
│ external tools: optional, PATH-detected    │
└────────────────────────────────────────────┘

• 数据目录：任务/证据属于用户资产，随工作区管理；不要把 .armorbreak/ 提交到仓库。
• 权限：L1/L2 依赖平台审批策略；桌面默认权限预设可能为 danger-full-access，但 ArmorBreak 的 L0–L3 闸门独立生效（不继承宽松策略）。
• 容量规划：每任务证据/报告通常为 KB–MB 级；批量分析需定期清理旧任务（见 known issues）。
• 灾备：备份工作区即可；证据哈希链可独立校验（armorbreak_evidence action=chain）。

10.3 配置全解

配置	位置	默认	说明
Persona	cordis.patch.yml → persona.prefix	内置	专业身份、硬边界、证据纪律
工具集	cordis.patch.yml → preset plugins	fs/shell/skills/compaction + armorbreak	可按需裁剪/扩展
客户端面板	package.json → dsh.client	web/immediately	client.js 状态卡
Runner 限制	lib/core/runtime.js → limits	32 MiB / 4 MiB / 256 KiB / 60s	输入、单文件、结果、超时
策略状态	$DSH_HOME/armorbreak/policy.json	空	授权与审批记录（带签名）
工作区	工具参数 / process.cwd()	会话目录回退	任务数据根
外部工具	PATH / GHIDRA_HOME	自动探测	缺失仅提示，不阻断 L0

10.4 升级与回滚

1. 升级：remove_bundle → install_bundle（或替换源码后重启）；新版本会保留既有工作区数据。
2. 回滚：重新安装旧 tag 源码；任务/证据格式向后兼容（JSON），报告可重新生成。
3. 兼容性：docs/compatibility-matrix.md 记录已验证的 DSH/Cordis/Node 版本；低版本 DSH 缺少 dsh-agent-preset 时 preset 行无法加载（明确失败，不静默降级）。

---

十一、使用指南 Usage

11.1 9 个模型工具（API 摘要）

工具	关键参数	行为
armorbreak_health	workspace?, probeVersions?	环境/隔离/策略/外部工具探测
armorbreak_capabilities	domain?, capability?, probeDependencies?	能力目录/单能力 schema
armorbreak_scope	action=list/authorize/revoke, purpose, operator, paths?, networkTargets?, riskCeiling?	授权记录管理
armorbreak_task	action=create/list/get/cancel/note/finalize, targetPath?, workflow?	任务生命周期
armorbreak_analyze	capability, target?, options?, taskId?, workspace?	单能力执行（L0 自动 / L1-L2 需审批）
armorbreak_workflow	action=list/start/run/status/cancel, workflow, target, maxSteps?	多步骤模板执行
armorbreak_evidence	action=list/get/verify/chain, taskId, findingId?, verification?	证据/发现/链校验
armorbreak_report	taskId, format=markdown/html/json/sarif/pdf	报告导出

11.2 工作流清单

工作流	目标类型	步骤	输出重点
BinaryStaticAnalysis	file	7	格式/结构/符号/字符串/熵/哈希/IOC
AndroidAPKReview	file	5	APK 结构/Manifest/DEX/签名/发现
WebCodeSecurityReview	directory	4	危险调用/密钥/依赖/SBOM
PCAPInvestigation	file	7	总览/会话/DNS/TLS/HTTP/IOC/异常
DependencyAudit	directory	3	依赖盘点/SBOM/密钥
CTFArtifactAnalysis	file	4	分类/哈希/古典密码/flag
ForensicFileReview	file	6	类型/哈希/元数据/时间线/IOC/规则
WebAPIReview	file	2	OpenAPI/HAR
SecurityReportGeneration	none	0	报告生成

扫描降噪（v1.0.3+）：sast.scan / sast.secrets / sast.deps / sast.sbom 支持可选 excludePaths（按路径子串、大小写不敏感），用于排除规则文件、测试夹具、文档示例等已知噪声，例如：

{ "capability": "sast.scan", "target": "D:\\repo", "workspace": "D:\\work",
  "options": { "excludePaths": ["tests/", "lib/analyzers/sast/rules.js", "docs/known-issues.md"] } }

排除只影响文件枚举，不改变规则、不降低其他文件的覆盖；被排除数量可在结果 data.excludedCount 核对。

11.3 典型场景

场景 A：恶意样本初筛（离线，不执行）

1) armorbreak_workflow action=start workflow=BinaryStaticAnalysis target="D:\samples\x.exe" workspace="D:\cases\001"
2) armorbreak_workflow action=run taskId=<id>
3) armorbreak_report taskId=<id> format=markdown

关注：加壳启发式（hypothesis）、导入 API 组合、IOC、overlay；报告会标注 verification。

场景 B：Web 源码与依赖审计

armorbreak_workflow action=start workflow=WebCodeSecurityReview target="D:\repo" workspace="D:\cases\repo-audit"
armorbreak_workflow action=run taskId=<id> maxSteps=4
armorbreak_report taskId=<id> format=sarif

目录型能力会扫描多文件并给出 CWE 映射；扫描告警默认 hypothesis，需在 armorbreak_evidence action=verify 中复核后才升级。

场景 C：授权内主动验证（L2）

armorbreak_scope action=request purpose="authorized lab validation" operator="alice" \
  networkTargets=["10.20.0.0/16"] riskCeiling=L2
# 平台向用户确认并返回 allowed-once 后：
armorbreak_scope action=activate requestId=<authreq_id>
armorbreak_analyze capability=live.http_probe taskId=<id> options={"url":"http://10.20.0.5/health"}

无授权 → NETWORK_OUT_OF_SCOPE；无平台审批 → NETWORK_APPROVAL_REQUIRED；超限 → NETWORK_RATE_LIMITED。

11.4 报告格式

格式	用途	备注
Markdown	人读、仓库内审阅	默认，含证据附录/审计摘要
HTML	浏览器阅读	自包含、深浅色
JSON	机器处理	armorbreak/report/v1 schema
SARIF 2.1.0	CI/代码扫描平台	每条 finding 一个 result + rule
PDF	归档交付	依赖本地 LibreOffice；缺失时明确报错，不伪造

11.5 错误码体系（策略与执行）

Code	含义	处理建议
OUT_OF_SCOPE	文件目标在工作区外且无授权	armorbreak_scope authorize 或复制进工作区
SENSITIVE_PATH_DENIED	宿主敏感路径	不允许直接分析，复制样本
TARGET_KIND_MISMATCH	任务 targetKind 与能力声明不符	换匹配工作流/能力（v1.0.2 规划期拦截）
TARGET_NOT_FILE / TARGET_NOT_DIRECTORY	目标类型错误	按提示选择目录/文件能力
ISOLATION_UNAVAILABLE	无隔离提供者	启动 Docker 或保持离线分析
APPROVAL_REJECTED / NETWORK_APPROVAL_REQUIRED	审批拒绝/缺失	通过平台审批；不要用其他工具绕过
NETWORK_OUT_OF_SCOPE	网络目标未授权	先授权精确目标
NETWORK_RATE_LIMITED	触发限速	等待补充或减少请求
TIMEOUT / CANCELLED	超时/取消	拆分任务/调整预算
PATH_ESCAPE	目录读取越界（含链接）	视为安全事件，检查样本目录
L3_DENIED	L3 操作	永远拒绝，无替代通道

---

十二、治理与社区 Governance

• 贡献流程：阅读 CONTRIBUTING.md → fork → 分支 → node --test 全绿 → PR； PR 必须包含问题、根因、修复、验证命令与真实结果、剩余限制。
• 提交规范：Conventional Commits（feat(domain): / fix(core): / docs: / test:）。
• 贡献者阶梯：Contributor（被合并 PR）→ Reviewer（持续高质量评审）→ Maintainer（发布与安全响应）； 安全修复遵循 SECURITY.md 私有渠道。
• 行为准则：CODE_OF_CONDUCT.md（Contributor Covenant 2.1）。
• 交流渠道：GitHub Issues（缺陷/功能）、Discussions（问答/设计讨论）、安全公告（私密）。
• 响应期望：issue 首次响应 ≤ 3 个工作日；安全报告按 SECURITY.md 时效。
• 版本策略：SemVer；PATCH=修复，MINOR=新能力，MAJOR=破坏性契约变更；每个 release 附验证结果。

---

十三、路线图 Roadmap

13.1 已完成

版本	主题	关键结果
v1.0.0	最小可用模式 + 离线能力核心	bundle/preset/工具/技能/39 能力/策略/证据/报告/状态卡；128 测试
v1.0.1	真实会话缺陷修复	无损 JSON、会话工作区解析；132 测试
v1.0.2	目录路由 + 并发 + 加固	目录工作流可用、targetKind 规划校验、哈希链并发安全、UTF-8/realpath/端口/YAML 加固；145 测试
v1.0.3	扫描降噪	sast.* 新增可选 excludePaths（按路径子串排除规则文件/测试夹具/文档示例）；146 测试，向后兼容
v1.0.4	安全维护（Stage A）	移除绕过 L0–L3 的通用工具、新增策略内 armorbreak_files、授权 request→平台审批→activate、HTTP 固定 IP/流式截断、容器镜像 digest/allowlist、状态接口 loopback-only；153 测试
v1.1.0 Stage B（分支）	外部工具适配器首批	sast.semgrep / sast.trivy JSON 归一化；L1 Docker 真机验证通过（busybox digest，非 root/只读/无网络）；160 测试
v1.1.0 Stage C/D/E（分支）	DAG/后台任务/恢复 + 只读工作台 + CI/E2E	依赖图、队列、取消/恢复、任务/工具路由、三页签状态卡、Docker CI job、mock-model E2E；174 测试
v1.1.0 Stage D2（分支）	工作台写操作/证据/报告/工具探测	L0 新建/取消/重试/恢复、证据中心、报告预览、工具版本探测；177 测试
v1.1.0（发布）	Research Workbench	A/B/C/D/D2 全部合并；会话级工作区绑定（首次工具调用后生效）；178 测试；真实模型 GUI/浏览器视觉验证未完成
v1.2.0（发布）	Advanced Research	4 个真实适配器、provider-backed L1 门、真实 L2 loopback、工作台环境/证据/报告、190 测试
v2.0.0（发布）	Security Research V2	L0–L3 策略网关、46 能力/9 工作流、真实 Garak/PyRIT/JailbreakBench、Ed25519 供应链、事务化安装/回滚、真实 Desktop GUI E2E；278 测试
v2.2.0-rc.1（main，未发布）	V2.2 GA 工程候选；未打正式 tag
v2.0.1（分支）	V2 证据硬化	commit-bound Gate、raw TAP、evidence manifest、docs consistency、IsolationVerified 持久化；284 测试
v1.1.1（发布）	热修复	修复状态卡 TDZ 崩溃与 external 分析器诊断；真实模型 GUI 验证 armorbreak_health 成功；178 测试

13.2 当前规划（v1.1）

• 模型驱动 E2E：headless + 本地 LLM mock（OpenAI-compatible SSE）验证「模式选择 → 工具调用 → 证据/报告」全链路。
• 外部工具适配器 v1：Ghidra/JADX/Semgrep/TShark/Trivy/Syft 的 argv 数组调用 + JSON 输出解析 + 版本依赖检查。
• UI 工作台：任务/工具/证据中心页面（基于现有 Slot 体系），报告预览。
• 批量分析：一个任务多目标，减少 per-sample 任务持久化开销（当前 36 ms/次）。
• 报告 i18n：英文报告模板。

13.3 中长期

• 隔离提供者抽象（Docker/Podman/WSL2/VM），容器网络 egress 白名单；
• L2 主动测试能力扩展（模板化 HTTP 探测、速率/并发策略、Nmap/Nuclei 适配）；
• 可选的离线漏洞库接入（OSV/NVD），在此之前永不输出「已确认 CVE」；
• 跨平台真机验证（macOS/Linux）、Windows junction/reparse point 完整语义；
• 证据包导出（可独立验证的审计包）与团队审批记录。

13.4 待探索

• 与 DSH 上游的 dsh-plugin-market 索引标准化；插件签名/来源校验；
• 模型侧上下文预算自适应（按任务复杂度选择能力描述粒度）；
• 结构化「假设 → 验证」记录（把 hypothesis 的复核过程也纳入证据链）。

---

十四、架构决策记录 ADR

ADR-001：零依赖纯 ESM JavaScript，而不是 TypeScript + 构建

• 背景：DSH profile 安装会执行 pnpm；插件在被加载前需要可预测的模块形态。
• 备选：TypeScript + 打包（类型安全）；纯 JS + JSDoc（零构建）。
• 决策：纯 ESM + JSDoc + node --test。
• 影响：安装/升级/审计路径最短、无供应链面；代价是类型检查弱于 tsc（以契约测试补偿）。

ADR-002：Host 服务 + preset 子插件分层，而不是单插件

• 背景：工具必须只对「破甲模式」可见；运行时状态需要进程级共享。
• 备选：全部放 preset（每会话重复实例化）；全部放 Host（污染标准模式工具目录）。
• 决策：Host 行提供运行时/状态路由；preset 子插件注册模式专属工具/技能。
• 影响：标准模式零污染；代价是跨作用域解析需遵循 Cordis 服务规则（已验证）。

ADR-003：代码级策略引擎，而不是提示词约定

• 背景：安全研究的核心风险是越权；提示词可被注入/漂移绕过。
• 决策：ScopePolicy + ExecutionRunner 作为唯一执行咽喉；L3 无代码路径。
• 影响：模型无法通过换工具/换参数绕过；代价是策略变更需要发版（而非改提示词）。

ADR-004：工作区 JSONL + 哈希链，而不是数据库

• 背景：需要可审计、可携带、零依赖的持久化。
• 备选：SQLite（事务/查询）vs JSONL（可读/可校验）。
• 决策：原子写 JSON/JSONL + 哈希链 + 进程内互斥。
• 影响：证据可直接审计/迁移；代价是复杂查询需工具层聚合、跨进程并发不支持。

ADR-005：目录型能力显式 targetKind + 规划期校验

• 背景：v1.0.0 因隐式默认 file 导致目录工作流 4/4 步失败（真实会话复现）。
• 决策：能力必须声明 targetKind；规划阶段校验任务与步骤的兼容性，TARGET_KIND_MISMATCH fail-fast。
• 影响：缺陷在规划期暴露而非运行期；代价是新能力必须正确声明类型。

---

十五、故障排查与 FAQ

15.1 日志与数据定位

位置	内容	用途
<workspace>/.armorbreak/audit.jsonl	工作区审计（哈希链、脱敏）	谁在何时执行了什么、策略拒绝
<workspace>/.armorbreak/tasks/<id>/task.json	任务/步骤/状态轨迹	失败点、耗时、计划
<workspace>/.armorbreak/tasks/<id>/evidence.jsonl	证据（哈希链）	结论溯源、篡改检测
<workspace>/.armorbreak/tasks/<id>/findings.json	发现（验证状态）	报告与复核
<workspace>/.armorbreak/tasks/<id>/reports/	报告文件	交付/归档

15.2 常见问题

Q1：为什么 `armorbreak_health` 曾报 “value is not lossless JSON”？

v1.0.0 的状态快照含 registry.list()（capability 对象携带函数），违反 Harness 的无损 JSON 校验。 v1.0.1 已从快照移除该字段，并在工具出口增加 toLosslessJson() 深度净化；有回归测试。

Q2：为什么目录工作流全部 TARGET_NOT_FILE？

v1.0.0 的 sast 能力未声明 targetKind，runner 默认按文件处理。v1.0.2 已声明目录能力、 规划期校验、并修正 env.readFile 返回 Buffer；真实多文件工作流测试 4/4 步通过。

Q3：为什么并发执行偶尔导致证据链断裂？

v1.0.1 及之前 read-tail → append 无序列化。v1.0.2 引入按文件互斥；并发 30 次 append 的链完整性测试通过。 仍不建议多 Host 进程同时写同一工作区（未实现跨进程锁）。

Q4：为什么需要 Docker 才能做动态分析？

L1 的执行语义是「未知样本不得在宿主执行」。没有隔离提供者时一律拒绝（ISOLATION_UNAVAILABLE）， 不会降级为宿主执行。容器参数固定为无网络、只读根、丢能力、非特权。

Q5：扫描器报告了很多“漏洞”，能直接提交吗？

不能。规则命中默认 hypothesis；需要在 armorbreak_evidence action=verify 中记录复核依据后升级。 扫描自身仓库时还会命中规则定义/测试夹具（known issue），属于已知噪声。

Q6：报告 PDF 失败怎么办？

PDF 依赖本机 LibreOffice（soffice）。未安装时明确报错并建议 html/markdown；也可以安装后重试。

Q7：状态卡显示“0 个任务 / 隔离环境：docker”是什么情况？

v1.0.1 之前：隔离未可用仍显示提供者；任务按默认 cwd 统计。v1.0.2 修复为「不可用」+ 最近使用工作区。

15.3 性能排查

• 解析慢：先用 benchmarks/bench.mjs 定位是 parser 还是持久化；
• runner 调用慢（≈36 ms）：属设计内持久化成本，批量场景复用任务；
• 大文件：检查 truncated 标记与 limits.maxInputBytes（默认 32 MiB）；
• 目录扫描慢：调整 maxFiles/maxBytes，排除 node_modules/.git/dist（默认已排除）。

---

十六、生态与集成 Ecosystem & Integrations

16.1 DeepSeek Harness 生态

ArmorBreak 是 DSH 的 原生扩展：Cordis Bundle（dsh.bundle.patch）+ Agent preset （@deepseek-ai/dsh-agent-preset）+ 可选 Web 面板（dsh.client）。安装、市场指引与上游链接见 docs/marketplace.md，包括：

• 官方发布指南：https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/publish
• 官方源码：https://github.com/deepseek-ai/deepseek-harness
• 社区市场/精选列表（第三方）：awesome-deepseek-harness-plugins、awesome-dsh-plugin、 dsh-plugin-market、dshbase/dshplugin.store

16.2 外部工具矩阵（可选增强）

工具	用途	当前接入	缺失时
Ghidra / Rizin / radare2	反编译/反汇编	探测 + 安装指引	内置结构/字符串/熵分析
YARA	规则匹配	探测	内置简化规则匹配（hypothesis）
JADX / apktool / adb / Frida	Android	探测	内置 ZIP/AXML/DEX/签名解析
Semgrep / CodeQL / Trivy / Syft / Gitleaks	SAST/供应链	探测	内置 59 规则/依赖盘点/SBOM/密钥检测
TShark / Zeek / Suricata / Nmap	网络	探测	内置 pcap/pcapng 解析；Nmap 未接入
Volatility3 / capa / FLOSS	取证	探测	内置文件级取证/启发式
Docker	L1 隔离	实际使用（需审批）	L1 拒绝
LibreOffice	PDF	实际使用	其他报告格式

16.3 扩展点

新增能力 = 新增 lib/analyzers/<domain>/manifest.js + 测试；核心通过契约自动发现。 详见 docs/CONTRACT.md。

---

十七、案例研究 Case Studies

以下为真实会话/路由执行记录（参考主机，非企业生产环境）；数据来自任务证据与报告， 不做匿名化之外的夸张修饰。

案例 1：真实 PE 样本的 7 步静态分析

• 目标：notepad.exe（360,448 B，SHA-256 468ffe12…4577e）
• 路径：armorbreak_workflow BinaryStaticAnalysis
• 结果：7/7 步 DONE，证据 21 条，发现 6 条（全部 hypothesis 或 info），报告生成； 上下文补证（Authenticode 有效、Microsoft 签名）用于降低误报而非制造结论。
• 经验：证据链 + 验证等级让「合法系统组件」与「可疑行为组合」的区分可复核。

案例 2：目录型工作流缺陷的发现与修复

• 现场：对源码目录执行 WebCodeSecurityReview，4 步全部 TARGET_NOT_FILE。
• 根因：sast 能力未声明 targetKind；规划器默认 file；错误提示自相矛盾。
• 修复：目录声明 + 规划期 TARGET_KIND_MISMATCH + env.readFile Buffer 契约 + 集成测试。
• 经验：隐式默认值在安全工具中是缺陷源；契约显式化 + 规划期 fail-fast 比运行期试错更可靠。

案例 3：工具输出无损 JSON 故障

• 现场：armorbreak_health 连续 3 次失败，value is not lossless JSON。
• 根因：状态快照携带 capability 函数字段，Harness 审计通道拒绝非 JSON 值。
• 修复：移除冗余字段 + 工具出口深度净化 + 4 个回归测试。
• 经验：工具输出是安全边界的一部分；无损 JSON/循环引用/undefined 必须在出口统一治理。

---

十八、许可证 License

• MIT License — 见 LICENSE。Copyright (c) 2026 LYL-Z。
• 第三方组件：本项目零运行时依赖，不打包第三方库；外部工具（Ghidra/JADX/…）由用户自行安装， 各自遵循其许可证，本项目不重新分发。
• 文档截图：docs/media/ 中的截图由项目作者/测试环境提供，随 MIT 文档许可使用。
• 徽章服务（shields.io）与 GitHub Actions 为外部服务，不在本仓库许可范围内。

---

十九、致谢 Acknowledgments

• DeepSeek Harness / Cordis 团队：提供了可扩展的 Host、Agent preset、工具/技能/审批、Web 插件体系； 本项目的全部集成点均来自其公开源码与文档。
• 真实会话测试者 LYL-Z：在安装后的真实会话中报告了目录型工作流、并发哈希链、UTF-8、realpath、 端口匹配、YAML 原型污染等缺陷；这些反馈直接塑造了 v1.0.2。
• 并行分析能力实现小组：binary/forensics、android/network、web/sast/ctf 三个域的实现与测试由 子代理协作完成（按 Lead 契约集成与复核）。
• 社区生态：awesome-deepseek-harness-plugins、awesome-dsh-plugin、dsh-plugin-market 等 社区索引与市场为本项目的分发路径提供参考。
• 灵感来源：Cordis 组合模型、OWASP ASVS/CWE/CVSS/SARIF 标准、DFIR 工具链的「证据优先」实践。

---

附录：文件结构与文档索引

dsh-armorbreak/
├── package.json              # Bundle 清单 + dsh.bundle/topic metadata
├── cordis.patch.yml          # Host 行 + preset-armorbreak 声明
├── index.js                  # Host：/armorbreak/state 只读路由
├── client.js                 # 浏览器：composer dock 状态卡
├── tools.js                  # 9 个模型工具 + 审批桥 + 无损 JSON 出口
├── skills.js                 # 7 个内置技能注册
├── lib/core/                 # 运行时（策略/任务/证据/审计/执行/报告/健康）
├── lib/analyzers/            # 8 个域、39 个能力（各自 manifest.js）
├── skills/*.md               # 技能正文
├── locale/{en,zh}.json       # 插件显示元数据
├── icon.svg
├── docs/                     # 审计/架构/安全模型/验收/兼容性/已知问题/路线图/市场/基准
├── benchmarks/               # 可复现基准脚本与结果
├── scripts/                  # 文件清单生成、测试临时目录清理
├── tests/                    # 385 个 node:test 用例
└── .github/workflows/ci.yml  # 双平台 CI

文档	内容
环境与架构审计	0.2.1-rc.2 实测 API 基线、兼容性事实
架构设计	分层、Cordis 组合、执行管线、数据模型
安全模型	L0–L3、授权/审批、路径/命令、隔离、审计
验收报告	v1.0.3 基线：146 测试、覆盖率、安装/运行实测
v1.0.4 / Stage A 验收	153 测试、P0 安全边界修复、未实现项
安全边界审计	权限覆盖矩阵、SB-1..6、残余限制
迁移 v1.0.3→v1.0.4	升级、回滚、兼容性
适配器契约 v2 · 工作流 v2 · 隔离提供者	v1.1.0 B–E 设计（未实现）
兼容性矩阵	运行时/API/平台/外部工具
已知问题	25 条已确认限制与运营注意事项
性能基准	环境、数据、方法、复现、限制
安装/卸载	三种安装路径、故障排查
使用指南	工具/工作流/场景/证据约定
市场与生态	DSH 生态、市场提交、版本策略
适配器契约	新增能力的接口与测试要求
版本说明	v1.0.0 / v1.0.1 / v1.0.2 / v1.0.3 / v1.0.4 里程碑
贡献指南 · 安全政策	贡献流程、漏洞披露
变更记录 · 文件清单	版本变更、全量文件

---

ArmorBreak · 破甲模式
Authorized reverse engineering & security research, native to DeepSeek Harness.
Evidence or it didn't happen.

MIT © 2026 LYL-Z