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

Все команды ниже предполагают, что ваша оболочка находится внутри клонированного каталога 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

Hachiman внутри AI-конструкторов (Claude, Codex, Hermes, OpenClaw и другие)

Hachiman спроектирован для установки и эксплуатации изнутри 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 — выдайте сессию для конструктора

Каждый конструктор (или каждая пара человек+конструктор) получает собственную ограниченную по области действия и сроку действия идентичность:

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 — добавьте блок внутрь mcpServers в 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 — из каталога репозитория:

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 (или .cursor/mcp.json в вашем проекте), тот же JSON-блок. Windsurf — Settings → Cascade → MCP servers, тот же блок. 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 показывает строку append-only журнала аудита.

Если вызов возвращает -32088 (BLOCK) или -32089 (REVIEW) — это работает Hachiman: прочитайте reasons в ошибке или откройте Advisor на дашборде, который сопоставляет каждую причину с точным исправлением.

Шаг 5 — (необязательно) наступательный навык изнутри конструктора

Если вы владеете целью и имеете письменное разрешение, тот же AI-конструктор может запустить авторизованный наступательный навык безопасности Hachiman — конструктор следует skill/SKILL.md: файл вовлечения → pentest → находки → AI Repair Contracts → retest до VERIFIED.

Два режима работы

Пред-развёртывание (WF-03)

DISCOVER → SCAN → TEST → SCORE → AUTHORIZE → DEPLOY

• Сканируйте кандидатного MCP до того, как он вообще будет открыт агенту. Сканер обнаруживает поверхность возможностей (исходящий трафик, БД, exec, файловая система, память, модель аутентификации), затем запускает только применимые контролируемые тесты из каталога: ретрансляция prompt-инъекций, цепочки непрямых инъекций→исходящий трафик, чрезмерная агентность, эксфильтрация массового экспорта, неограниченный исходящий трафик, контрабанда параметров, имитация инструментов, уязвимости поддельной аутентификации, дрейф возможностей, поверхность 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 при сбое верификации для чувствительных ресурсов. Сдерживание липкое и append-only. Каждое решение аудируется и объяснимо.

Наступательный навык (только авторизованные цели)

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-эндпоинты, все ОС. Семейства мобильных/игровых/облачных/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%, накладные расходы по задержке P95 порядка пары миллисекунд поверх loopback MCP. Утверждения SPO измеряются для каждой нагрузки и никогда не рекламируются как универсальные гарантии.

Не-цели

Hachiman не пытается быть универсальным межсетевым экраном для LLM, переписчиком промптов или песочницей для выполнения кода. Он управляет доступом к инструментам и перемещением данных для агентов, говорящих на MCP, с детерминированными, объяснимыми и аудируемыми решениями. См. docs/05-FEATURE-BACKLOG.md для явных не-целей и бэклога MoSCoW.

Документы проектирования

План сборки, который реализует этот репозиторий, находится в 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. Авторские права © 2026 Nidhish Guhan.