Hachiman Agent

Vor der Bereitstellung scannen. Vor dem Zugriff autorisieren. Während der Ausführung überwachen. Bei Kompromittierung eindämmen. Alles melden.

Hachiman ist eine autonome Sicherheitsschicht für KI-Agenten und das Model Context Protocol (MCP). Es sitzt zwischen Ihren Agenten und ihren MCP-Servern als drahtkompatibles Gateway und behandelt jeden Tool-Aufruf als Sicherheitsentscheidung – niemals das Modell.

Das LLM ist bewusst nicht die Sicherheitsinstanz. Hachiman trifft deterministische Entscheidungen aus strukturierten Beweisen (Autorisierungsgewährungen, Datenklassifizierung, Ziel, Injektionssignale, Verhalten, Vertrauensstatus) und verwendet semantische Analyse nur als Berater, dessen Ausgabe validiert, begrenzt und nur auf Beweisen basierend ist.

Gebaut mit null Laufzeitabhängigkeiten: Node.js ≥ 22.5 (node:sqlite, node:test), reines ESM. Läuft identisch auf Windows, Linux und macOS – siehe AI-BUILDER.md für den Ein-Prompt- Installationsvertrag, den jeder KI-Codierungsagent auf jedem Betriebssystem ausführen kann.

Schnellstart

Hachiman wird ausschließlich über dieses Git-Repository verteilt – es ist nicht auf npm oder in einer Paketregistrierung veröffentlicht. Klonen Sie es und führen Sie alles aus dem Klon aus:

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

Alle folgenden Befehle setzen voraus, dass sich Ihre Shell im geklonten hachiman-agent-Verzeichnis befindet.

# 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

Hinweis: Kommentare oben sind absichtlich auf eigenen Zeilen – in der Standard-zsh (macOS) wird ein nachgestelltes # auf derselben Zeile wie ein Befehl nicht als Kommentar behandelt. Kopieren Sie Befehle zeilenweise oder als ganze Blöcke; mischen Sie niemals Shell-Kommentare in Befehlszeilen.

• Kein npm install-Schritt erforderlich – es gibt null Laufzeitabhängigkeiten.

• Das Git-Repository ist die einzige Quelle der Wahrheit. Es gibt keine heruntergeladene/Zip-Distribution zum Ausführen; arbeiten Sie immer aus einem Klon dieses Repositorys, damit Sie den exakten, vollständigen, getesteten Baum (Quellcode, Tests, Fixtures, Policy-Pakete und Dokumentation zusammen) haben.

Related MCP server: Guardpost MCP Server

Hachiman in KI-Buildern (Claude, Codex, Hermes, OpenClaw & mehr)

Hachiman ist dafür ausgelegt, aus KI-Codierungs-Buildern heraus auf jedem Betriebssystem installiert und betrieben zu werden. Jede Integration verwendet nur Standardmechanismen – eine Shell, MCP stdio oder MCP über HTTP. Kein SDK, kein Plugin, kein Plattform-Fork erforderlich. Alles, was einen Terminalbefehl ausführen oder MCP sprechen kann, kann Hachiman verwenden.

Es gibt zwei Rollen, die ein KI-Builder spielen kann, und eine einzelne Plattform kann beide spielen:

Unterstützte KI-Builder – organisierte Kompatibilitätsmatrix

(Anforderung überall: Node.js ≥ 22.5. MCP-Konfigurationsdateinamen und -Schemata entwickeln sich zwischen Plattformversionen; wenn die eigene Dokumentation einer Plattform abweicht, vertrauen Sie der Plattformdokumentation – der Brückenbefehl und die Umgebungsvariablen unten ändern sich nie.)

Schritt 0 – gleicher Start auf jeder Plattform

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

Schritt 1 – den KI-Builder installieren und verifizieren lassen (einen Prompt einfügen)

Öffnen Sie Ihren KI-Builder im geklonten Verzeichnis (oder geben Sie ihm den Pfad) und fügen Sie den Ein-Prompt-Block aus AI-BUILDER.md §1 wörtlich ein. Der Builder prüft Node, führt den Installateur aus, startet die Wache und führt die vollständige Testsuite aus – mit maschinenlesbaren Erfolgskriterien (RESULT: READY on <os>, HACHIMAN GUARD ACTIVE, # fail 0). Dies ist identisch in Claude Code, Codex CLI, Cursor, Windsurf, Copilot, Gemini CLI, Hermes, OpenClaw, DeepSeek Harness, Qoder und Aider – sie alle haben Terminalzugriff.

Schritt 2 – eine Sitzung für den Builder ausstellen

Jeder Builder (oder jedes Mensch+Builder-Paar) erhält seine eigene, begrenzte, ablaufende Identität:

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

Das gibt einen sessionToken (hsm_…) aus. Fügen Sie ihn in die Plattformkonfiguration von Schritt 3 ein.

Schritt 3 – den Builder in das Gateway einbinden (plattformspezifische Anleitungen)

Universeller Brückenblock (der JSON-Body ist überall gleich – nur wo er lebt, unterscheidet sich):

"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 – fügen Sie den Block in mcpServers in claude_desktop_config.json ein (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 – aus dem Repository-Verzeichnis:

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 – Einstellungen → MCP → Server hinzufügen (oder .cursor/mcp.json in Ihrem Projekt), gleicher JSON-Block. Windsurf – Einstellungen → Cascade → MCP-Server, gleicher Block. Gemini CLI – ~/.gemini/settings.json, mcpServers-Schlüssel, gleicher 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 – zwei Optionen, beide unterstützt:

1. HTTP-Endpunkt (wenn die Plattform MCP über HTTP unterstützt): Zeigen Sie darauf http://127.0.0.1:7420/mcp/<server> und senden Sie den Header x-hachiman-session: hsm_XXXXXXXXXXXX.XXXXXXXXXXXX mit jeder Anfrage.

2. Stdio-Brücke (wenn die Plattform MCP-Subprozesse startet): Registrieren Sie den Brückenblock oben in der MCP-Konfiguration der Plattform – genau wie für Claude/Cursor.

Vollständige plattformspezifische Details, live getestete Beispiele und die Betreiber-Checkliste: Hachiman-Agnent-Guide.md §7–§10.

Schritt 4 – von innen aus dem Builder verifizieren

Bitten Sie den KI-Builder, ein beliebiges Tool über seinen neuen hachiman-*-Server aufzurufen, und prüfen Sie:

• das Tool wird ausgeführt (ALLOW) – Hachiman hat die Entscheidung protokolliert,

• das Dashboard (http://127.0.0.1:7420/, Mission Control) zeigt die Entscheidung mit Risiko/Konfidenz,

• node bin/hachiman.js audit --tail 20 zeigt die append-only Audit-Zeile.

Wenn ein Aufruf -32088 (BLOCK) oder -32089 (REVIEW) zurückgibt, ist das Hachiman bei der Arbeit: Lesen Sie die reasons im Fehler oder öffnen Sie den Advisor im Dashboard, der jeden Grund seiner genauen Lösung zuordnet.

Schritt 5 – (optional) offensive Fähigkeit von innen aus dem Builder

Wenn Sie das Ziel besitzen und es schriftlich autorisiert haben, kann derselbe KI-Builder Hachimans autorisierte offensive Sicherheitsfähigkeit ausführen – der Builder folgt skill/SKILL.md: Engagement-Datei → pentest → Ergebnisse → KI-Reparaturverträge → retest bis VERIFIED.

Die zwei Betriebsmodi

Vor der Bereitstellung (WF-03)

DISCOVER → SCAN → TEST → SCORE → AUTHORIZE → DEPLOY

• Scannen Sie ein Kandidaten-MCP, bevor es jemals einem Agenten ausgesetzt wird. Der Scanner entdeckt die Fähigkeitsoberfläche (Egress, DB, Exec, Dateisystem, Speicher, Auth-Modell) und führt dann nur die anwendbaren kontrollierten Tests aus dem Katalog aus: Prompt-Injection-Relay, indirekte Injection→Egress- Ketten, übermäßige Agency, Bulk-Export-Exfiltration, uneingeschränkter Egress, Parameter-Schmuggel, Tool-Identitätsvortäuschung, gefälschte Auth-Schwachstellen, Fähigkeitsdrift, SQLi-Oberfläche, Pfad-Traversal, Geheimnis-Exposition.

• Bewerten Sie es mit einem 11-dimensionalen Produktionssicherheits-Score (0–100) und einem Status-Gate: PRODUCTION_READY, PRODUCTION_READY_WITH_RESTRICTIONS, NOT_PRODUCTION_READY.

• Autorisieren: Nur ein Betreiber kann ein gescanntes MCP auf TRUSTED befördern, und nur eine menschliche Gewährung gibt einem Agenten überhaupt eine Fähigkeit.

Laufzeit (WF-05/06)

MONITOR → DETECT → DECIDE → RESPOND → REPORT → REASSESS

• Jeder tools/call durch das Gateway wird normalisiert und von einer festen Pipeline bewertet: IDENTITY → AUTHORIZATION (harte Sperre) → LEGITIMACY → CLASSIFY → INJECTION → POLICY → CACHE → RISK → DECIDE → (SEMANTIC) → AUDIT.

• Drei Werte werden getrennt und nie vermischt gehalten: risk (0–100), confidence (0–100%), trust (0–100).

• Fail-closed bei Verifikationsfehler für sensible Ressourcen. Eindämmung ist klebrig und append-only. Jede Entscheidung wird geprüft und erklärbar.

Offensive Fähigkeit (nur autorisierte Ziele)

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

Der Wächter denkt auch wie ein Angreifer. Auf einem autorisierten Ziel (Engagement-Datei mit authorized_by, Umfang, Budgets – alles im Code erzwungen) führt Hachiman aus:

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

Gemessen am gebündelten Laborziel (npm run offense-bench): vollständige Angriffs- → Beweis- → Fix-Verify- Schleife ~0,8 s, 8 Anfragen, 0 Tokens, 3/3 Hypothesen reproduzierbar bestätigt, 3/3 Fixes VERIFIED durch Wiederholung der ursprünglichen Angriffe gegen den reparierten Build. Die Schleife erkennt auch kaputte Fixes: ein Fix, der den Exploit weiterhin erlaubt → UNRESOLVED; ein Fix, der legitimes Verhalten bricht → REGRESSION (beide in test/e2e/offensive-loop.test.js demonstriert).

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

Umfang heute: MCP-Server / lokale HTTP-MCP-Endpunkte, alle Betriebssysteme. Mobile/Spiel/Cloud/k8s-Familien sind nur dokumentierte Erweiterungspunkte – die Fähigkeit täuscht niemals Abdeckung vor. Betreiberdokumentation: skill/SKILL.md.

Repository-Struktur

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

Sicherheitsmodell auf einen Blick

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 beendet mit einem Nicht-Null-Exitcode, wenn das Ziel nicht PRODUCTION_READY ist (CI-Gate).

Tests & 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

Gemeldet für die Micro-SPO-Workload (diese Maschine): Bedrohungsprävention 100% (alle Angriffe gestoppt, 0 Fehlalarme), deterministischer Fast-Path 100%, semantische Aufrufe 0%, P95-Latenz-Overhead in der Größenordnung von ein paar Millisekunden über ein Loopback-MCP. SPO-Aussagen werden pro Workload gemessen und niemals als universelle Garantien beworben.

Nicht-Ziele

Hachiman versucht nicht, eine Allzweck-LLM-Firewall, ein Prompt-Rewriter oder ein Sandbox-Code-Executor zu sein. Es regelt Tool-Zugriff und Datenbewegung für Agenten, die MCP sprechen, mit deterministischen, erklärbaren, auditierbaren Entscheidungen. Siehe docs/05-FEATURE-BACKLOG.md für die expliziten Nicht-Ziele und das MoSCoW-Backlog.

Designdokumente

Der Build-Plan, den dieses Repository implementiert, befindet sich in docs/:

• 00-MASTER-PLAN.md — Vision, Meilensteine, KPIs

• 01-IMPLEMENTATION-ARCHITECTURE.md — Modulspezifikationen, Datenmodell, SQLite-Schema, API-Oberfläche

• 02-WORKFLOWS.md — WF-01…WF-10-Sequenzen und Entscheidungstabellen

• 03-OPTIMIZATION.md — Token-Effizienz, SRG-Budgets, Caching

• 04-TESTING-AND-BENCHMARKING.md — Testpyramide, Angriffskorpus, SPO-Harness

• 05-FEATURE-BACKLOG.md — MoSCoW-Backlog, Nicht-Ziele

• 06-MASTER-SECURITY-SKILL-ARCHITECTURE.md — offensive Skill-Vision (autorisierte Ziele)

• 07-OFFENSIVE-SKILL-IMPLEMENTATION-PLAN.md — was gebaut wird, Modulkarte, Phasen, ehrliche Nicht-Ziele

• 08-HACHIMAN-2.0-ARCHITECTURE.md — Repository-Audit + universeller Control-Plane-Plan (Hachiman 2.0)

Lizenz & Credits

Entwickler: Nidhish Guhan Lizenz: MIT — siehe LICENSE. Copyright © 2026 Nidhish Guhan.