Hachiman Agent

Scan before deployment. Authorize before access. Monitor during execution. Contain when compromised. Report everything.

Hachiman is an autonomous security layer for AI agents and the Model Context Protocol (MCP). It sits between your agents and their MCP servers as a wire-compatible gateway, and it treats every tool call as a security decision — never the model.

The LLM is deliberately not the security authority. Hachiman makes deterministic decisions from structured evidence (authorization grants, data classification, destination, injection signals, behavior, trust state) and uses semantic analysis only as an advisor whose output is validated, clamped, and evidence-only.

Built with zero runtime dependencies: Node.js ≥ 22.5 (node:sqlite, node:test), pure ESM. Runs identically on Windows, Linux, and macOS — see AI-BUILDER.md for the one-prompt installation contract any AI coding agent can execute on any OS.

---

Quick start

Hachiman is distributed exclusively through this git repository — it is not published on npm or any package registry. Clone it and run everything from inside the clone:

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

All commands below assume your shell is inside the cloned hachiman-agent directory.

# 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

Note: comments above are on their own lines on purpose — in default zsh (macOS), a trailing # on the same line as a command is not treated as a comment. Copy commands line by line, or as whole blocks; never mix shell comments onto command lines.

• No npm install step is required — there are zero runtime dependencies.
• The git repository is the single source of truth. There is no downloaded/zip distribution to run; always operate from a clone of this repository so you have the exact, complete, tested tree (source, tests, fixtures, policy packs, and docs together).

---

Hachiman inside AI builders (Claude, Codex, Hermes, OpenClaw & more)

Hachiman is designed to be installed and operated from inside AI coding builders, on any OS. Every integration uses standard mechanisms only — a shell, MCP stdio, or MCP-over-HTTP. No SDK, no plugin, no platform fork is required. Anything that can run a terminal command or speak MCP can use Hachiman.

There are two roles an AI builder can play, and a single platform can play both:

Role	Meaning	Mechanism
Installer / operator	The AI builder installs and runs Hachiman on your machine	It has terminal access → paste the one-prompt block from AI-BUILDER.md
Protected client	The AI builder is the agent being secured; its tool calls pass through the Hachiman gateway	Register the stdio bridge or the HTTP endpoint in the platform's MCP config

Supported AI builders — organized compatibility matrix

AI builder	Vendor	Windows	macOS	Linux	Installs Hachiman	Protected client
Claude Code	Anthropic	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
Claude Desktop	Anthropic	✅	✅	✅	—	✅ MCP stdio
Codex CLI	OpenAI	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
Cursor	Anysphere	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
Windsurf	Codeium	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
GitHub Copilot / VS Code agent	GitHub / Microsoft	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
Gemini CLI	Google	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
Hermes	Nous Research	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
OpenClaw	community	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
DeepSeek Harness	DeepSeek	✅	✅	✅	✅ (managed job)	✅ MCP stdio/HTTP
Qoder	Alibaba	✅	✅	✅	✅ (terminal)	✅ MCP stdio/HTTP
Aider	community	✅	✅	✅	✅ (terminal)	shell commands (no MCP)
Anything else speaking MCP	—	✅	✅	✅	✅ if it has a shell	✅ MCP stdio/HTTP

(Requirement everywhere: Node.js ≥ 22.5. MCP config file names and schemas evolve between platform versions; when a platform's own docs differ, trust the platform docs — the bridge command and env variables below never change.)

Step 0 — same start on every platform

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

Step 1 — let the AI builder install & verify it (paste one prompt)

Open your AI builder in the cloned directory (or tell it the path) and paste the one-prompt block from AI-BUILDER.md §1 verbatim. The builder checks Node, runs the installer, boots the guard, and runs the full test suite — with machine-readable success criteria (RESULT: READY on <os>, HACHIMAN GUARD ACTIVE, # fail 0). This is identical in Claude Code, Codex CLI, Cursor, Windsurf, Copilot, Gemini CLI, Hermes, OpenClaw, DeepSeek Harness, Qoder, and Aider — they all have terminal access.

Step 2 — issue a session for the builder

Each builder (or each human+builder pair) gets its own scoped, expiring identity:

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

That prints a sessionToken (hsm_…). Put it into the platform config of Step 3.

Step 3 — wire the builder into the gateway (per-platform guides)

Universal bridge block (the JSON body is the same everywhere — only where it lives differs):

"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 — add the block inside mcpServers in claude_desktop_config.json (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 — from the repo directory:

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 — Settings → MCP → Add server (or .cursor/mcp.json in your project), same JSON block. Windsurf — Settings → Cascade → MCP servers, same block. Gemini CLI — ~/.gemini/settings.json, mcpServers key, same block. 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 — two options, both supported:

1. HTTP endpoint (when the platform supports MCP-over-HTTP): point it at http://127.0.0.1:7420/mcp/<server> and send the header x-hachiman-session: hsm_XXXXXXXXXXXX.XXXXXXXXXXXX with each request.
2. Stdio bridge (when the platform spawns MCP subprocesses): register the bridge block above in the platform's MCP config — exactly as for Claude/Cursor.

Full per-platform detail, live-tested examples, and the operator checklist: Hachiman-Agnent-Guide.md §7–§10.

Step 4 — verify from inside the builder

Ask the AI builder to call any tool through its new hachiman-* server and check:

• the tool executes (ALLOW) — Hachiman logged the decision,
• the dashboard (http://127.0.0.1:7420/, Mission Control) shows the decision with risk/confidence,
• node bin/hachiman.js audit --tail 20 shows the append-only audit row.

If a call returns -32088 (BLOCK) or -32089 (REVIEW), that's Hachiman working: read the reasons in the error, or open the dashboard Advisor, which maps each reason to its exact fix.

Step 5 — (optional) offensive skill from inside the builder

If you own the target and have authorized it in writing, the same AI builder can run Hachiman's authorized offensive security skill — the builder follows skill/SKILL.md: engagement file → pentest → findings → AI Repair Contracts → retest until VERIFIED.

---

The two operating modes

Pre-Deployment (WF-03)

DISCOVER → SCAN → TEST → SCORE → AUTHORIZE → DEPLOY

• Scan a candidate MCP before it is ever exposed to an agent. The scanner discovers the capability surface (egress, db, exec, filesystem, memory, auth model) then runs only the applicable controlled tests from the catalog: prompt-injection relay, indirect-injection→egress chains, excessive agency, bulk-export exfiltration, unrestricted egress, param smuggling, tool impersonation, forged-auth flaws, capability drift, SQLi surface, path traversal, secret exposure.
• Score it with an 11-dimension Production Safety Score (0–100) and a status gate: PRODUCTION_READY, PRODUCTION_READY_WITH_RESTRICTIONS, NOT_PRODUCTION_READY.
• Authorize: only an operator can promote a scanned MCP to TRUSTED, and only a human grant gives an agent any capability at all.

Runtime (WF-05/06)

MONITOR → DETECT → DECIDE → RESPOND → REPORT → REASSESS

• Every tools/call through the gateway is normalized and evaluated by a fixed pipeline: IDENTITY → AUTHORIZATION (hard gate) → LEGITIMACY → CLASSIFY → INJECTION → POLICY → CACHE → RISK → DECIDE → (SEMANTIC) → AUDIT.
• Three values are kept separate and never conflated: risk (0–100), confidence (0–100%), trust (0–100).
• Fail-closed on verification failure for sensitive resources. Containment is sticky and append-only. Every decision is audited and explainable.

---

Offensive skill (authorized targets only)

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

The watchman also thinks like an attacker. On an authorized target (engagement file with authorized_by, scope, budgets — all enforced in code), Hachiman runs:

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

Measured on the bundled lab target (npm run offense-bench): full attack → prove → fix-verify loop ~0.8 s, 8 requests, 0 tokens, 3/3 hypotheses confirmed reproducibly, 3/3 fixes VERIFIED by replaying the original attacks against the repaired build. The loop also catches broken fixes: a fix that still allows the exploit → UNRESOLVED; a fix that breaks legitimate behavior → REGRESSION (both demonstrated in 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

Scope today: MCP servers / local HTTP MCP endpoints, all OSes. Mobile/game/cloud/k8s families are documented extension points only — the skill never fakes coverage. Operator docs: skill/SKILL.md.

---

Repository layout

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

---

Security model at a glance

Principle	Enforcement
Authorization is a hard gate	No grant ⇒ DENY → sensitive BLOCK / benign REVIEW. Trust never substitutes for a grant.
Model is not the authority	Semantic analyzer output is clamped, evidence-only, and can only tighten a decision, never loosen it.
Distinct risk / confidence / trust	Separately computed, separately reported; no single magic number decides alone.
Fail closed	Verification failure on sensitive resources → BLOCK. Ambiguous → REVIEW.
Containment is sticky	Quarantine overrides every later decision until an operator releases it (recovery = rescan → re-authorize).
Audit is append-only	audit_events has BEFORE UPDATE/DELETE triggers that RAISE(ABORT).
Policy as data, hot-reloaded	Rule packs versioned; strictest matching decision wins; floors dominate deltas.
Efficiency without weakening	Decision cache keyed on content signals (injection + classification ride the fingerprint), SRG budgets, semantic slot concurrency.

---

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]

scan … --production exits non-zero when the target is not PRODUCTION_READY (CI gate).

---

Testing & benchmarks

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

Reported on the micro SPO workload (this machine): threat prevention 100% (all attacks stopped, 0 false positives), deterministic fast-path 100%, semantic calls 0%, P95 latency overhead on the order of a couple of milliseconds over a loopback MCP. SPO statements are measured per workload and never advertised as universal guarantees.

---

Non-goals

Hachiman does not attempt to be a general-purpose LLM firewall, a prompt-rewriter, or a sandboxed code executor. It governs tool access and data movement for agents speaking MCP, with deterministic, explainable, auditable decisions. See docs/05-FEATURE-BACKLOG.md for the explicit non-goals and the MoSCoW backlog.

---

Design documents

The build plan this repository implements lives in docs/:

• 00-MASTER-PLAN.md — vision, milestones, KPIs
• 01-IMPLEMENTATION-ARCHITECTURE.md — module specs, data model, SQLite schema, API surface
• 02-WORKFLOWS.md — WF-01…WF-10 sequences and decision tables
• 03-OPTIMIZATION.md — token efficiency, SRG budgets, caching
• 04-TESTING-AND-BENCHMARKING.md — test pyramid, attack corpus, SPO harness
• 05-FEATURE-BACKLOG.md — MoSCoW backlog, non-goals
• 06-MASTER-SECURITY-SKILL-ARCHITECTURE.md — offensive skill vision (authorized targets)
• 07-OFFENSIVE-SKILL-IMPLEMENTATION-PLAN.md — what is built, module map, phases, honest non-goals
• 08-HACHIMAN-2.0-ARCHITECTURE.md — repository audit + universal control-plane plan (Hachiman 2.0)

---

License & credits

Developer: Nidhish Guhan License: MIT — see LICENSE. Copyright © 2026 Nidhish Guhan.