Hachiman Agent

배포 전에 스캔하라. 접근 전에 승인하라. 실행 중에 모니터링하라. 침해 시 격리하라. 모든 것을 보고하라.

Hachiman은 AI 에이전트와 Model Context Protocol(MCP)을 위한 자율 보안 계층입니다. 에이전트와 MCP 서버 사이에 와이어 호환 게이트웨이로 위치하며, 모든 도구 호출을 보안 결정으로 취급합니다 — 모델이 아니라.

LLM은 의도적으로 보안 권한자(authority)가 아닙니다. Hachiman은 구조화된 증거(권한 부여, 데이터 분류, 목적지, 주입 신호, 동작, 신뢰 상태)를 기반으로 결정적인 결정을 내리며, 의미론적 분석은 검증되고, 제한되며, 증거 기반으로만 사용되는 조언자로만 활용합니다.

런타임 의존성 제로로 구축됨: Node.js ≥ 22.5 (node:sqlite, node:test), 순수 ESM. Windows, Linux, macOS에서 동일하게 실행됨 — 모든 OS에서 모든 AI 코딩 에이전트가 실행할 수 있는 원프롬프트 설치 계약은 AI-BUILDER.md를 참조하세요.

빠른 시작

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 빌더가 수행할 수 있는 두 가지 역할이 있으며, 단일 플랫폼이 둘 다 수행할 수 있습니다:

지원되는 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단계 — 빌더용 세션 발급

각 빌더(또는 각 인간+빌더 쌍)는 자체 범위가 지정되고 만료되는 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 — 두 가지 옵션, 둘 다 지원됨:

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가 에이전트에 노출되기 전에 스캔합니다. 스캐너는 기능 표면(이그레스, DB, exec, 파일시스템, 메모리, 인증 모델)을 발견한 다음 카탈로그에서 적용 가능한 통제된 테스트만 실행합니다: 프롬프트 주입 릴레이, 간접 주입→이그레스 체인, 과도한 에이전시, 대량 내보내기 유출, 무제한 이그레스, 매개변수 밀수, 도구 사칭, 위조 인증 결함, 기능 드리프트, 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.

• 세 가지 값은 분리되어 유지되며 절대 혼동되지 않습니다: risk (0–100), confidence (0–100%), trust (0–100).

• 민감한 리소스에 대한 검증 실패 시 fail-closed. 격리는 고정적이고 추가 전용입니다. 모든 결정은 감사되고 설명 가능합니다.

공격 스킬 (승인된 대상만)

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가 아닐 때 0이 아닌 종료 코드를 반환합니다(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.