Hachiman Agent

部署前扫描。访问前授权。执行中监控。 受损时遏制。报告一切。

Hachiman 是面向 AI 智能体与模型上下文协议（Model Context Protocol，MCP）的自主安全层。它以线缆兼容网关的形式位于你的智能体与其 MCP 服务器之间，并将每一次工具调用都视为一次安全决策——而非由模型决定。

LLM 刻意不作为安全权威。Hachiman 依据结构化证据（授权许可、数据分类、目的地、注入信号、行为、信任状态）做出确定性决策，仅将语义分析用作顾问，其输出经过验证、钳制，且仅基于证据。

零运行时依赖构建：Node.js ≥ 22.5（node:sqlite、node:test），纯 ESM。在 Windows、Linux 和 macOS 上运行完全一致——参见 AI-BUILDER.md 了解单提示词安装契约，任何 AI 编码智能体都可在任何操作系统上执行。

快速开始

Hachiman 仅通过此 git 仓库分发——未发布到 npm 或任何包注册表。克隆它并在克隆目录内运行一切：

git clone https://github.com/nidhish28guhan-netizen/hachiman-agent.git
cd hachiman-agent

以下所有命令均假定你的 shell 位于克隆的 hachiman-agent 目录内。

# Requirement: Node.js >= 22.5 (Hachiman uses node:sqlite and node:test)
node --version

# Universal installer: health check + config + engine self-test (any OS)
node scripts/install.js

# Full suite: unit + golden + corpus + property + e2e
npm test

# The A→Z story: scan → authorize → block → quarantine → report
npm run demo

# Security Protection Overhead benchmark (micro)
npm run spo

# CLI reference
node bin/hachiman.js help

注意： 上面的注释特意独占一行——在默认的 zsh（macOS）中，命令同一行末尾的 # 不会被当作注释。请逐行或整块复制命令；切勿将 shell 注释混入命令行。

• 无需 npm install 步骤——零运行时依赖。

• git 仓库是唯一事实来源。 没有可运行的下载版/zip 发行版；始终从本仓库的克隆进行操作，这样你拥有精确、完整、经过测试的目录树（源码、测试、fixtures、策略包和文档在一起）。

Related MCP server: Guardpost MCP Server

AI 构建器中的 Hachiman（Claude、Codex、Hermes、OpenClaw 等）

Hachiman 设计为在 AI 编码构建器内部、任何操作系统上安装和运行。每个集成仅使用标准机制——shell、MCP stdio 或 MCP-over-HTTP。无需 SDK、无需插件、无需平台分支。 任何能运行终端命令或能说 MCP 的工具都可以使用 Hachiman。

AI 构建器可以扮演两个角色，同一平台可以同时扮演两者：

受支持的 AI 构建器——组织化兼容性矩阵

（各处要求：Node.js ≥ 22.5。MCP 配置文件名和模式会随平台版本演变；当平台自身文档不同时，以平台文档为准——下面的桥接命令和环境变量永不改变。）

第 0 步——每个平台相同的起点

git clone https://github.com/nidhish28guhan-netizen/hachiman-agent.git
cd hachiman-agent
node scripts/install.js

第 1 步——让 AI 构建器安装并验证它（粘贴一个提示词）

在克隆目录中打开你的 AI 构建器（或告诉它路径），并逐字粘贴来自 AI-BUILDER.md §1 的单提示词块。构建器检查 Node、运行安装程序、启动守卫，并运行完整测试套件——带有机器可读的成功标准（RESULT: READY on <os>、HACHIMAN GUARD ACTIVE、# fail 0）。这在 Claude Code、Codex CLI、Cursor、Windsurf、Copilot、Gemini CLI、Hermes、OpenClaw、DeepSeek Harness、Qoder 和 Aider 中完全相同——它们都有终端访问权限。

第 2 步——为构建器签发会话

每个构建器（或每个人类+构建器组合）获得其自己的、有作用域且过期的身份：

node bin/hachiman.js agent add claude-code --allow notes,search --ttl 24

这会打印一个 sessionToken（hsm_…）。将其放入第 3 步的平台配置中。

第 3 步——将构建器接入网关（按平台指南）

通用桥接块（JSON 主体处处相同——只是存放位置不同）：

"hachiman-notes": {
  "command": "node",
  "args": ["/full/path/to/hachiman-agent/bin/hachiman.js", "bridge", "notes"],
  "env": {
    "HACHIMAN_GATEWAY": "http://127.0.0.1:7420",
    "HACHIMAN_SESSION": "hsm_XXXXXXXXXXXX.XXXXXXXXXXXX"
  }
}

Claude Desktop——将块添加到 claude_desktop_config.json 的 mcpServers 内（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{ "mcpServers": { "hachiman-notes": { "command": "node", "args": ["/full/path/to/hachiman-agent/bin/hachiman.js", "bridge", "notes"], "env": { "HACHIMAN_GATEWAY": "http://127.0.0.1:7420", "HACHIMAN_SESSION": "hsm_XXXXXXXXXXXX.XXXXXXXXXXXX" } } } }

Claude Code——从仓库目录：

claude mcp add hachiman-notes \
  --env HACHIMAN_GATEWAY=http://127.0.0.1:7420 \
  --env HACHIMAN_SESSION=hsm_XXXXXXXXXXXX.XXXXXXXXXXXX \
  -- node /full/path/to/hachiman-agent/bin/hachiman.js bridge notes

Codex CLI——~/.codex/config.toml：

[mcp_servers.hachiman_notes]
command = "node"
args = ["/full/path/to/hachiman-agent/bin/hachiman.js", "bridge", "notes"]

[mcp_servers.hachiman_notes.env]
HACHIMAN_GATEWAY = "http://127.0.0.1:7420"
HACHIMAN_SESSION = "hsm_XXXXXXXXXXXX.XXXXXXXXXXXX"

Cursor——设置 → MCP → 添加服务器（或项目中的 .cursor/mcp.json），相同的 JSON 块。Windsurf——设置 → Cascade → MCP 服务器，相同块。Gemini CLI——~/.gemini/settings.json，mcpServers 键，相同块。GitHub Copilot / VS Code——.vscode/mcp.json：

{
  "servers": {
    "hachiman-notes": {
      "type": "stdio",
      "command": "node",
      "args": ["/full/path/to/hachiman-agent/bin/hachiman.js", "bridge", "notes"],
      "env": {
        "HACHIMAN_GATEWAY": "http://127.0.0.1:7420",
        "HACHIMAN_SESSION": "hsm_XXXXXXXXXXXX.XXXXXXXXXXXX"
      }
    }
  }
}

Hermes / OpenClaw / Qoder / DeepSeek Harness——两个选项，均受支持：

1. HTTP 端点（当平台支持 MCP-over-HTTP 时）：将其指向 http://127.0.0.1:7420/mcp/<server>，并在每个请求中发送标头 x-hachiman-session: hsm_XXXXXXXXXXXX.XXXXXXXXXXXX。

2. Stdio 桥（当平台生成 MCP 子进程时）：在平台的 MCP 配置中注册上面的桥接块——与 Claude/Cursor 完全相同。

完整的按平台细节、实测示例和操作者清单：Hachiman-Agnent-Guide.md §7–§10。

第 4 步——从构建器内部验证

让 AI 构建器通过其新的 hachiman-* 服务器调用任意工具，并检查：

• 工具执行（ALLOW）——Hachiman 记录了该决策，

• 仪表板（http://127.0.0.1:7420/，Mission Control）显示带有风险/置信度的决策，

• node bin/hachiman.js audit --tail 20 显示仅追加的审计行。

如果调用返回 -32088（BLOCK）或 -32089（REVIEW），那是 Hachiman 在起作用：阅读错误中的 reasons，或打开仪表板 Advisor，它会将每个原因映射到其确切修复方法。

第 5 步——（可选）从构建器内部使用攻击性技能

如果你拥有目标并已书面授权，同一个 AI 构建器可以运行 Hachiman 的授权攻击性安全技能——构建器遵循 skill/SKILL.md：参与文件 → pentest → 发现 → AI 修复契约 → retest 直到 VERIFIED。

两种运行模式

部署前（WF-03）

DISCOVER → SCAN → TEST → SCORE → AUTHORIZE → DEPLOY

• 扫描候选 MCP，在其暴露给智能体之前。扫描器发现能力面（外发、数据库、执行、文件系统、内存、认证模型），然后仅运行目录中适用的受控测试：提示注入中继、间接注入→外发链、过度代理、批量导出窃取、无限制外发、参数走私、工具冒充、伪造认证缺陷、能力漂移、SQLi 面、路径遍历、秘密暴露。

• 评分：使用 11 维生产安全评分（0–100）和状态门：PRODUCTION_READY、PRODUCTION_READY_WITH_RESTRICTIONS、NOT_PRODUCTION_READY。

• 授权：只有操作者才能将已扫描的 MCP 提升为 TRUSTED，并且只有人类授权才能赋予智能体任何能力。

运行时（WF-05/06）

MONITOR → DETECT → DECIDE → RESPOND → REPORT → REASSESS

• 通过网关的每个 tools/call 都由固定管道规范化并评估：IDENTITY → AUTHORIZATION (hard gate) → LEGITIMACY → CLASSIFY → INJECTION → POLICY → CACHE → RISK → DECIDE → (SEMANTIC) → AUDIT。

• 三个值保持分离且绝不混淆：risk（0–100）、confidence（0–100%）、trust（0–100）。

• 敏感资源验证失败时故障关闭。遏制是粘性的且仅追加。每个决策都被审计且可解释。

攻击性技能（仅限授权目标）

docs/06-MASTER-SECURITY-SKILL-ARCHITECTURE.md + docs/07-OFFENSIVE-SKILL-IMPLEMENTATION-PLAN.md

守望者也会像攻击者一样思考。在授权目标上（带有 authorized_by、范围、预算的参与文件——全部在代码中强制执行），Hachiman 运行：

DISCOVER → MAP → HYPOTHESIZE → ATTACK → ADAPT → CHAIN → VALIDATE → EXPLAIN → FIX → RETEST

在捆绑的实验室目标上测量（npm run offense-bench）：完整攻击 → 证明 → 修复验证循环约 0.8 秒、8 个请求、0 个 token、3/3 假设可复现地确认、3/3 修复通过针对修复后构建重放原始攻击而 VERIFIED。该循环还能捕获损坏的修复：仍允许利用的修复 → UNRESOLVED；破坏合法行为的修复 → REGRESSION（两者均在 test/e2e/offensive-loop.test.js 中演示）。

node bin/hachiman.js pentest examples/engagement.vuln-notes.json
node bin/hachiman.js findings | explain <id> | fix <id> | retest <id> --fixed vuln-notes-fixed
npm run offense-bench

当前范围：MCP 服务器 / 本地 HTTP MCP 端点，所有操作系统。移动/游戏/云/k8s 系列仅是文档化的扩展点——该技能从不伪造覆盖。操作者文档：skill/SKILL.md。

仓库布局

bin/hachiman.js                 CLI entry
lib/hachiman.js                 Root composition: assemble storage+engines+gateway+runtime+SRG
policies/*.hachiman.json        Policy packs (default, high-security, strict) — hot-reload by version
packages/
  core/        storage (SQLite/WAL, append-only audit), EventBus (bounded, shed ladder), utils
  engines/     classifier, injection, identity (Ed25519+HMAC sessions), authorization (grants),
               policy, risk, trust, semantic (validated advisory), decision pipeline
  gateway/     MCP client (stdio/HTTP), normalize, metrics, the McpGateway itself
  runtime/     BehaviorMonitor, ResponseEngine (6-level containment ladder)
  srg/         Security Resource Governor (SENTINEL→WATCH→THREAT→INCIDENT→RECOVERY, budgets)
  scanner/     surface mapper, test catalog, scoring, Scanner
  reporting/   scan / incident / SPO statement renderers
  benchmark/   scenario runner + SPO harness
  cli/         `hachiman <command>`
  dashboard/   local HTTP server + zero-dep SPA (SSE live events)
fixtures/      benign + malicious fixture MCPs, sink, attack corpus, golden decision set
docs/          00 master plan → 05 feature backlog (the build plan this implements)
test/          unit, golden, corpus, property, e2e

安全模型一览

CLI

hachiman init
hachiman guard [--port N] [--once]          # protect configured MCPs (gateway + runtime + dashboard)
hachiman status
hachiman scan <target> --fixture <name> [--production] [--suite AI,MCP,APP]
hachiman mcp list | allow <mcp> | deny <mcp>
hachiman trust <subject>
hachiman threats | quarantine <mcp:subj> [--reason R] | quarantine release <mcp:subj>
hachiman audit [--tail N] | report scan <id> | report incident <id> | report production <target>
hachiman dashboard [--port N]
hachiman config get|set <dotted.key> [json]

当目标不是 PRODUCTION_READY 时，scan … --production 以非零状态退出（CI 门禁）。

测试与基准

npm run test:unit       # engines + core + srg
npm run test:golden     # locked deterministic decisions (regression guards)
npm run test:corpus     # attack corpus + benign baseline: detection ≥95%, FP ≤2%
npm run test:e2e        # scanner + guarded gateway end-to-end
npm run test:property   # fuzz determinism + structural invariants
npm run spo             # Security Protection Overhead statement

在微型 SPO 工作负载（本机）上报告：威胁防护 100%（所有攻击均被阻止，0 误报），确定性快速路径 100%，语义调用 0%，回环 MCP 上的 P95 延迟开销约为几毫秒。SPO 声明是按工作负载测量的，绝不宣称是通用保证。

非目标

Hachiman 不试图成为通用 LLM 防火墙、提示词重写器或沙箱代码执行器。它管理使用 MCP 通信的代理的工具访问和数据流动，做出确定性、可解释、可审计的决策。明确的非目标和 MoSCoW 待办事项见 docs/05-FEATURE-BACKLOG.md。

设计文档

本仓库实现的构建计划位于 docs/：

• 00-MASTER-PLAN.md — 愿景、里程碑、KPI

• 01-IMPLEMENTATION-ARCHITECTURE.md — 模块规格、数据模型、SQLite 模式、API 表面

• 02-WORKFLOWS.md — WF-01…WF-10 序列和决策表

• 03-OPTIMIZATION.md — token 效率、SRG 预算、缓存

• 04-TESTING-AND-BENCHMARKING.md — 测试金字塔、攻击语料库、SPO 测试框架

• 05-FEATURE-BACKLOG.md — MoSCoW 待办事项、非目标

• 06-MASTER-SECURITY-SKILL-ARCHITECTURE.md — 攻击性技能愿景（授权目标）

• 07-OFFENSIVE-SKILL-IMPLEMENTATION-PLAN.md — 构建内容、模块映射、阶段、诚实的非目标

• 08-HACHIMAN-2.0-ARCHITECTURE.md — 仓库审计 + 通用控制平面计划（Hachiman 2.0）

许可证与致谢

开发者： Nidhish Guhan 许可证： MIT — 见 LICENSE。版权所有 © 2026 Nidhish Guhan。