dsh-armorbreak
ArmorBreak (破甲模式)：适用于 DeepSeek Harness 的授权逆向工程与安全研究代理预设——46 项离线能力、L0–L3 策略引擎、证据链报告
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:LYL-Z/dsh-armorbreak#a866597134e11c830420099ab5bbb0e9fe368975Armorbreak 以 dsh-armorbreak 发布，当前版本为 2.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Evidence-first security research for AI agents.
ArmorBreak is an open-source toolkit for authorized reverse engineering, static analysis, digital forensics, and security research. It combines a host-neutral Core, MCP tools, agent skills, and an optional native DeepSeek Harness integration with scoped permissions and traceable reports.
破甲（ArmorBreak）为不同 AI Agent 提供授权安全研究能力：受控本地分析、权限边界、证据记录、MCP / Skills 接入，以及 DeepSeek Harness 原生模式。它面向已授权目标，不代替使用者获得授权。
V2.2 Stable scope:
2.2.0is defined as Verified Core / Experimental Provider Integrations. Stable acceptance covers the Core, MCP, Skills, Offline Golden, local-model verification, and only the hosts and install/rollback paths supported by current evidence. OpenAI, Anthropic, and Gemini commercial endpoints remainLIVE_UNVERIFIED; live certification is not a Stable prerequisite. The project accepts AI-assisted security review as AI review, not as human certification. The separate historical Full GA contract and its blockers remain unchanged;gaReady:falsestill means Full GA has not passed.Documentation baseline:
9172f7b50352bbe152a0bd001678cfd271fd65bb（2026-10-23）
Start here: Quick Start · Generic MCP integration · Security Policy · Verification evidence
Languages: English · 中文说明
observed facts from hypothesis/unverified leads.Current baseline facts:
| Domain | Capabilities | Typical use |
|---|---|---|
binary | 7 | PE/ELF/Mach-O structure, strings, entropy, IOC |
forensics | 6 | Hashing, file typing, metadata, timeline, IOC |
network | 8 | PCAP/PCAPng sessions, DNS/TLS/HTTP, flows, anomalies |
sast | 8 | Dangerous sinks, secrets, dependencies, SBOM |
android | 6 | APK structure, Manifest/AXML, DEX, signing |
web | 4 | HAR/OpenAPI/header/HTTP-message review |
ctf | 5 | Encoding/classical crypto, flag scanning |
live | 2 | Authorized L1/L2 active checks, denied by default |
Risk profile in the current registry: 44 L0, 1 L1, 1 L2. L3 remains always denied.
See Core API contract, generated API matrix, and generated skill list.
| Path | Best for | What you install | First safe task |
|---|---|---|---|
| A. DeepSeek Harness native | Existing DSH Desktop/Web users | ArmorBreak bundle + armorbreak preset | armorbreak_health, then L0 armorbreak_analyze |
| B. Generic MCP Agent | Claude-style JSON, Cursor-style JSON, Codex TOML, Hermes YAML hosts | MCP server entry via CLI dry-run/apply | agent doctor, then L0 forensics.hash |
| C. Independent Core / local model | Custom tooling, Node services, local Ollama experiments | Import packages/core in your app | createCore() + capabilities() |
All three paths share the same Core, policy boundary, and evidence format. They differ in transport and installation, not in security semantics.
Default path is offline L0. It does not require a commercial model API key and does not touch public network targets.
Use this when you already run DeepSeek Harness.
<BUNDLE_PATH> with your local repository path.plugin_manager action=install_bundle target="<BUNDLE_PATH>"
application and warnings. If a restart is required, fully quit and reopen DSH.armorbreak_health returns the capability list;First L0 task, using a harmless file inside your workspace:
armorbreak_analyze capability=forensics.hash target="<WORKSPACE>\README.md" workspace="<WORKSPACE>"
armorbreak_report taskId=<returned-task-id> format=markdown
The real Desktop L0 evidence is recorded in desktop E2E.
Use this for MCP-capable hosts. The CLI never guesses a host config path; you must pass --config.
Prerequisite for the current CLI: set ARMORBREAK_STATE_ROOT and ARMORBREAK_WORKSPACE before running commands. Use an isolated non-production directory.
$dir = Join-Path $env:TEMP 'armorbreak-docs'
New-Item -ItemType Directory -Force -Path "$dir\state", "$dir\workspace" | Out-Null
[System.IO.File]::WriteAllText("$dir\mcp.json", '{}')
$env:ARMORBREAK_STATE_ROOT = "$dir\state"
$env:ARMORBREAK_WORKSPACE = "$dir\workspace"
$env:ARMORBREAK_PRINCIPAL_ID = 'docs-l0-test'
# 1. Dry-run only. No host config is written.
node packages/cli/index.js agent install `
--target generic `
--config "$dir\mcp.json" `
--scope project `
--state-root $env:ARMORBREAK_STATE_ROOT `
--workspace $env:ARMORBREAK_WORKSPACE `
--principal docs-l0-test `
--json
# 2. Review the printed before/after diff, then apply only if it matches your intent.
node packages/cli/index.js agent install `
--target generic `
--config "$dir\mcp.json" `
--scope project `
--state-root $env:ARMORBREAK_STATE_ROOT `
--workspace $env:ARMORBREAK_WORKSPACE `
--principal docs-l0-test `
--apply --json
# 3. Diagnose the entry.
node packages/cli/index.js agent doctor --config "$dir\mcp.json" --json
PowerShell note: write JSON without a BOM. Set-Content -Encoding utf8 on Windows PowerShell 5 can add a BOM and make the CLI report invalid JSON.
Host config formats differ. Use the matching target:
generic / claude: JSON mcpServerscodex: TOML with managed markershermes: YAML managed blockDo not copy one JSON shape into every host and call it universal. See generic MCP adapter and generated host matrix.
Uninstall without deleting evidence:
node packages/cli/index.js agent install `
--target generic --config "$dir\mcp.json" --scope project --uninstall --json
Uninstall removes the ArmorBreak MCP entry and leaves .armorbreak/ task evidence in the workspace.
The Core is the execution kernel. MCP is a tool-access protocol. Provider Router is the model-service layer. They are not three names for the same binary.
import { createCore } from './packages/core/index.js'
const stateRoot = process.env.ARMORBREAK_STATE_ROOT
const workspace = process.env.ARMORBREAK_WORKSPACE
const core = await createCore({ stateRoot })
const ctx = {
principal: { id: 'local-researcher', kind: 'local-user', workspaces: [workspace] },
workspaceId: workspace,
requestId: 'docs-l0',
traceId: 'docs-l0',
}
const capabilities = await core.capabilities(ctx)
console.log(capabilities.length)
await core.close()
Run it with the same two required environment variables. In the documented QA run, this returned version: 0.1.0-p1 and capabilities: 46.
A recorded local Ollama scenario with qwen3.5:4b exercised chat, SSE, tool call, and a multi-turn tool loop. See Ollama live evidence. That result is not official OpenAI, Anthropic, or Gemini certification.
flowchart LR
Host["AI Host / Agent<br/>DSH · Codex · Cursor · Claude · ZCode · Pi · TRAE"] -->|MCP stdio/HTTP| MCP["MCP Server<br/>7 armorbreak_* tools"]
Host -->|native Cordis preset| DSH["DSH Adapter<br/>10 model-facing tools + 7 skills"]
MCP --> Core["Universal Core<br/>Policy · Scope · Approvals"]
DSH --> Core
Core --> Analyzers["Analyzers<br/>46 L0-first capabilities"]
Analyzers --> Evidence["Evidence store<br/>JSONL hash chain"]
Evidence --> Report["Reports<br/>Markdown / HTML / JSON / SARIF / PDF"]
The Core validates invocation, resolves workspace scope, records task transitions, runs analyzers, appends evidence, and generates reports. Provider Router is only involved when a model service is used; it never becomes an approval authority.
ArmorBreak separates implementation from verification.
| Level | Meaning | Current status |
|---|---|---|
SOURCE_CONFIRMED | Code and contract exist | Core, MCP, DSH adapter, Provider Router, SDK |
MOCK_GOLDEN_PASS | Four protocol families pass local mock/golden tests | PASS |
LOCAL_MODEL_PASS | Recorded local Ollama tool loop and controlled Core L0 | PASS |
LIVE_GOLDEN_PASS | Official paid endpoints with real calls | EXTERNAL_UNVERIFIED |
EXTERNAL_UNVERIFIED | Blocked by credentials, balance, or independent review | OpenAI / Anthropic / Gemini / independent review |
Recorded test result at this baseline: 400 tests / 399 pass / 0 fail / 1 skipped. Treat this as a baseline record, not a live badge.
Host matrix summary: 12 entries, 10 L0 completions, 9 third-party L0 entries. Claude Code MCP and Claude Cowork CLI are separate rows. Gemini CLI and Antigravity are separate rows. Pi uses a native TypeScript extension, not MCP.
ArmorBreak is for authorized security research. A scan finding is not a confirmed vulnerability. Authorization scope cannot be created by a model saying it is allowed.
This is a status statement, not a security certification.
No exploit details for unresolved findings are published here. Do not read this section as a comprehensive security guarantee.
Read security model, threat model, and SECURITY.md before deployment. Do not use ArmorBreak against systems you are not authorized to test.
| Question | Document |
|---|---|
| Install / enable / uninstall in DSH | docs/installation.md |
| Run analysis and read reports | docs/usage.md |
| Connect another Agent | docs/v2/host-generic.md |
| Core programming interface | docs/v2/core/public-api.md |
| Provider support level | docs/v2/provider-matrix.md |
| Security boundaries | docs/security-model.md |
| Benchmarks and reproducibility | docs/benchmarks.md |
| Upgrade / rollback | docs/v2/release/upgrade-guide.md |
| V2.2 Stable release policy | docs/v2/release/v2.2-stable-policy-v1.md |
| Historical Full GA contract | docs/v2/release/v2.2-ga-review.md |
| Known limitations | docs/known-issues.md |
Common failures:
KEY_MISSING: provider credential environment variable is absent.MODEL_NOT_FOUND: the requested model is not advertised by the configured provider.ISOLATION_UNAVAILABLE: L1 stays denied; L0 still works.format=html/markdown.2.2.0 uses the versioned Verified Core / Experimental Provider Integrations contract. The Stable release must pass node scripts/v2/stable-gate.mjs against the exact main source, CI run, artifact, SBOM, security review, and GitHub attestation before publication.gaReady:false and the original Full GA blockers remain in the historical readiness record. Stable is a separate, narrower release scope and does not mean Full GA passed.LIVE_UNVERIFIED. Offline Golden, mock, and local-model results do not establish official commercial endpoint compatibility.| Previous long-form README content | docs/readme-archive-v2.2.md |