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 コーディングエージェントが任意の OS で実行できます。

クイックスタート

Hachiman はこの git リポジトリ経由でのみ配布されています — npm やパッケージレジストリには公開されていません。 クローンして、クローン内からすべてを実行してください:

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

以下のすべてのコマンドは、シェルがクローンした 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) では、コマンドと同じ行にある末尾の # はコメントとして扱われません。コマンドは行単位、またはブロック全体でコピーしてください。シェルのコメントをコマンド行に混在させないでください。

• npm install ステップは不要です — ランタイム依存関係はゼロです。

• git リポジトリが唯一の情報源です。 ダウンロード/zip 配布物はありません。常にこのリポジトリのクローンから操作してください。正確で完全なテスト済みツリー（ソース、テスト、フィクスチャ、ポリシーパック、ドキュメントが一体となったもの）を保持できます。

Related MCP server: Guardpost MCP Server

AI ビルダー内での Hachiman（Claude、Codex、Hermes、OpenClaw など）

Hachiman は、あらゆる OS 上の AI コーディングビルダー内からインストールおよび操作できるように設計されています。 すべての統合は標準的なメカニズムのみを使用します — シェル、MCP stdio、または MCP-over-HTTP。SDK も、プラグインも、プラットフォームのフォークも不要です。 ターミナルコマンドを実行できるもの、または MCP を話せるものはすべて Hachiman を使用できます。

AI ビルダーが果たせる役割は2つあり、単一のプラットフォームが両方を果たせます:

対応 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 ビルダーにインストールと検証を任せる（プロンプトを1つ貼り付ける）

クローンしたディレクトリ内で 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 — ビルダー用のセッションを発行する

各ビルダー（または各人間+ビルダーのペア）は、独自のスコープ付き・期限付き ID を取得します:

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 — 2つのオプションがあり、両方ともサポートされています:

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 になるまで。

2つの運用モード

デプロイ前 (WF-03)

DISCOVER → SCAN → TEST → SCORE → AUTHORIZE → DEPLOY

• 候補の MCP がエージェントに公開される前にスキャンします。スキャナーは機能面（egress、db、exec、filesystem、memory、auth model）を発見し、カタログから該当する制御されたテストのみを実行します: プロンプトインジェクションリレー、間接インジェクション→egress チェーン、過剰なエージェンシー、一括エクスポートの外部持ち出し、無制限の egress、パラメータスマイグリング、ツール偽装、偽造認証の欠陥、機能ドリフト、SQLi 面、パストラバーサル、シークレット露出。

• 11 次元の Production Safety Score（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 (ハードゲート) → LEGITIMACY → CLASSIFY → INJECTION → POLICY → CACHE → RISK → DECIDE → (SEMANTIC) → AUDIT。

• 3つの値は分離され、決して混同されません: 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 トークン、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 エンドポイント、全 OS。モバイル/ゲーム/クラウド/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]

scan … --production は、ターゲットが PRODUCTION_READY でない場合に非ゼロで終了する（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 — トークン効率、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 を参照。Copyright © 2026 Nidhish Guhan。