Hachiman Agent

Escanea antes del despliegue. Autoriza antes del acceso. Supervisa durante la ejecución. Contén cuando esté comprometido. Reporta todo.

Hachiman es una capa de seguridad autónoma para agentes de IA y el Protocolo de Contexto de Modelo (MCP). Se sitúa entre tus agentes y sus servidores MCP como una puerta de enlace compatible por cable, y trata cada llamada a herramienta como una decisión de seguridad — nunca el modelo.

El LLM deliberadamente no es la autoridad de seguridad. Hachiman toma decisiones deterministas a partir de evidencia estructurada (concesiones de autorización, clasificación de datos, destino, señales de inyección, comportamiento, estado de confianza) y utiliza el análisis semántico solo como un asesor cuyo resultado se valida, se limita y se basa únicamente en evidencia.

Construido con cero dependencias en tiempo de ejecución: Node.js ≥ 22.5 (node:sqlite, node:test), ESM puro. Funciona de manera idéntica en Windows, Linux y macOS — consulta AI-BUILDER.md para el contrato de instalación de un solo prompt que cualquier agente de codificación de IA puede ejecutar en cualquier sistema operativo.

Inicio rápido

Hachiman se distribuye exclusivamente a través de este repositorio git — no está publicado en npm ni en ningún registro de paquetes. Clónalo y ejecuta todo desde dentro del clon:

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

Todos los comandos a continuación asumen que tu shell está dentro del directorio clonado 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

Nota: los comentarios anteriores están en líneas propias a propósito — en zsh predeterminado (macOS), un # al final en la misma línea que un comando no se trata como comentario. Copia los comandos línea por línea, o como bloques completos; nunca mezcles comentarios de shell en líneas de comando.

• No se requiere paso de npm install — hay cero dependencias en tiempo de ejecución.

• El repositorio git es la única fuente de verdad. No hay distribución descargada/zip para ejecutar; opera siempre desde un clon de este repositorio para tener el árbol exacto, completo y probado (fuente, pruebas, fixtures, paquetes de políticas y documentación juntos).

Related MCP server: Guardpost MCP Server

Hachiman dentro de constructores de IA (Claude, Codex, Hermes, OpenClaw y más)

Hachiman está diseñado para instalarse y operarse desde dentro de constructores de codificación de IA, en cualquier sistema operativo. Cada integración utiliza solo mecanismos estándar — un shell, MCP stdio o MCP sobre HTTP. No se requiere SDK, ni plugin, ni fork de plataforma. Cualquier cosa que pueda ejecutar un comando de terminal o hablar MCP puede usar Hachiman.

Hay dos roles que un constructor de IA puede desempeñar, y una sola plataforma puede desempeñar ambos:

Constructores de IA compatibles — matriz de compatibilidad organizada

(Requisito en todas partes: Node.js ≥ 22.5. Los nombres de archivo y esquemas de configuración MCP evolucionan entre versiones de plataforma; cuando la documentación de una plataforma difiera, confía en la documentación de la plataforma — el comando del puente y las variables de entorno a continuación nunca cambian.)

Paso 0 — mismo inicio en cada plataforma

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

Paso 1 — deja que el constructor de IA lo instale y verifique (pega un prompt)

Abre tu constructor de IA en el directorio clonado (o indícale la ruta) y pega el bloque de un solo prompt de AI-BUILDER.md §1 textualmente. El constructor verifica Node, ejecuta el instalador, inicia el guardián y ejecuta la suite de pruebas completa — con criterios de éxito legibles por máquina (RESULT: READY on <os>, HACHIMAN GUARD ACTIVE, # fail 0). Esto es idéntico en Claude Code, Codex CLI, Cursor, Windsurf, Copilot, Gemini CLI, Hermes, OpenClaw, DeepSeek Harness, Qoder y Aider — todos tienen acceso a terminal.

Paso 2 — emite una sesión para el constructor

Cada constructor (o cada par humano+constructor) obtiene su propia identidad con alcance y caducidad:

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

Eso imprime un sessionToken (hsm_…). Ponlo en la configuración de plataforma del Paso 3.

Paso 3 — conecta el constructor a la puerta de enlace (guías por plataforma)

Bloque de puente universal (el cuerpo JSON es el mismo en todas partes — solo dónde vive difiere):

"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 — agrega el bloque dentro de mcpServers en 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 — desde el directorio del repositorio:

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 — Configuración → MCP → Agregar servidor (o .cursor/mcp.json en tu proyecto), mismo bloque JSON. Windsurf — Configuración → Cascade → Servidores MCP, mismo bloque. Gemini CLI — ~/.gemini/settings.json, clave mcpServers, mismo bloque. 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 — dos opciones, ambas compatibles:

1. Endpoint HTTP (cuando la plataforma soporta MCP sobre HTTP): apúntalo a http://127.0.0.1:7420/mcp/<server> y envía el encabezado x-hachiman-session: hsm_XXXXXXXXXXXX.XXXXXXXXXXXX con cada solicitud.

2. Puente stdio (cuando la plataforma lanza subprocesos MCP): registra el bloque de puente anterior en la configuración MCP de la plataforma — exactamente como para Claude/Cursor.

Detalle completo por plataforma, ejemplos probados en vivo y la lista de verificación del operador: Hachiman-Agnent-Guide.md §7–§10.

Paso 4 — verifica desde dentro del constructor

Pide al constructor de IA que llame a cualquier herramienta a través de su nuevo servidor hachiman-* y verifica:

• la herramienta se ejecuta (ALLOW) — Hachiman registró la decisión,

• el panel de control (http://127.0.0.1:7420/, Mission Control) muestra la decisión con riesgo/confianza,

• node bin/hachiman.js audit --tail 20 muestra la fila de auditoría de solo anexión.

Si una llamada devuelve -32088 (BLOCK) o -32089 (REVIEW), eso es Hachiman funcionando: lee los reasons en el error, o abre el Advisor del panel de control, que mapea cada razón a su corrección exacta.

Paso 5 — (opcional) habilidad ofensiva desde dentro del constructor

Si eres dueño del objetivo y lo has autorizado por escrito, el mismo constructor de IA puede ejecutar la habilidad de seguridad ofensiva autorizada de Hachiman — el constructor sigue skill/SKILL.md: archivo de compromiso → pentest → hallazgos → Contratos de Reparación de IA → retest hasta VERIFIED.

Los dos modos de operación

Pre-despliegue (WF-03)

DISCOVER → SCAN → TEST → SCORE → AUTHORIZE → DEPLOY

• Escanea un MCP candidato antes de que se exponga a un agente. El escáner descubre la superficie de capacidades (egreso, db, exec, sistema de archivos, memoria, modelo de autenticación) y luego ejecuta solo las pruebas controladas aplicables del catálogo: retransmisión de inyección de prompt, cadenas de inyección indirecta→egreso, agencia excesiva, exfiltración de exportación masiva, egreso sin restricciones, contrabando de parámetros, suplantación de herramientas, fallas de autenticación falsificada, deriva de capacidades, superficie SQLi, traversal de ruta, exposición de secretos.

• Puntúa con una Puntuación de Seguridad de Producción de 11 dimensiones (0–100) y una puerta de estado: PRODUCTION_READY, PRODUCTION_READY_WITH_RESTRICTIONS, NOT_PRODUCTION_READY.

• Autoriza: solo un operador puede promover un MCP escaneado a TRUSTED, y solo una concesión humana da a un agente cualquier capacidad.

Tiempo de ejecución (WF-05/06)

MONITOR → DETECT → DECIDE → RESPOND → REPORT → REASSESS

• Cada tools/call a través de la puerta de enlace se normaliza y evalúa mediante un pipeline fijo: IDENTITY → AUTHORIZATION (puerta dura) → LEGITIMACY → CLASSIFY → INJECTION → POLICY → CACHE → RISK → DECIDE → (SEMANTIC) → AUDIT.

• Tres valores se mantienen separados y nunca se confunden: risk (0–100), confidence (0–100%), trust (0–100).

• Cierre por fallo en la verificación de recursos sensibles. La contención es pegajosa y de solo anexión. Cada decisión se audita y es explicable.

Habilidad ofensiva (solo objetivos autorizados)

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

El vigilante también piensa como un atacante. En un objetivo autorizado (archivo de compromiso con authorized_by, alcance, presupuestos — todo aplicado en código), Hachiman ejecuta:

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

Medido en el objetivo de laboratorio incluido (npm run offense-bench): bucle completo de ataque → probar → verificar corrección ~0.8 s, 8 solicitudes, 0 tokens, 3/3 hipótesis confirmadas de manera reproducible, 3/3 correcciones VERIFIED reproduciendo los ataques originales contra la compilación reparada. El bucle también detecta correcciones rotas: una corrección que aún permite la explotación → UNRESOLVED; una corrección que rompe el comportamiento legítimo → REGRESSION (ambos demostrados en 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

Alcance actual: servidores MCP / endpoints HTTP MCP locales, todos los sistemas operativos. Las familias móvil/juego/nube/k8s son solo puntos de extensión documentados — la habilidad nunca finge cobertura. Documentación del operador: skill/SKILL.md.

Estructura del repositorio

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

Modelo de seguridad de un vistazo

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 sale con código distinto de cero cuando el objetivo no está PRODUCTION_READY (puerta de CI).

Pruebas y 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

Reportado en la carga de trabajo micro SPO (esta máquina): prevención de amenazas 100% (todos los ataques detenidos, 0 falsos positivos), ruta rápida determinista 100%, llamadas semánticas 0%, sobrecarga de latencia P95 del orden de un par de milisegundos sobre un MCP de bucle local. Las declaraciones SPO se miden por carga de trabajo y nunca se promocionan como garantías universales.

No objetivos

Hachiman no intenta ser un firewall LLM de propósito general, un reescritor de prompts ni un ejecutor de código en sandbox. Gobierna el acceso a herramientas y el movimiento de datos para agentes que hablan MCP, con decisiones deterministas, explicables y auditables. Consulte docs/05-FEATURE-BACKLOG.md para los no objetivos explícitos y el backlog MoSCoW.

Documentos de diseño

El plan de construcción que implementa este repositorio vive en docs/:

• 00-MASTER-PLAN.md — visión, hitos, KPIs

• 01-IMPLEMENTATION-ARCHITECTURE.md — especificaciones de módulos, modelo de datos, esquema SQLite, superficie de API

• 02-WORKFLOWS.md — secuencias WF-01…WF-10 y tablas de decisión

• 03-OPTIMIZATION.md — eficiencia de tokens, presupuestos SRG, caché

• 04-TESTING-AND-BENCHMARKING.md — pirámide de pruebas, corpus de ataques, arnés SPO

• 05-FEATURE-BACKLOG.md — backlog MoSCoW, no objetivos

• 06-MASTER-SECURITY-SKILL-ARCHITECTURE.md — visión de habilidad ofensiva (objetivos autorizados)

• 07-OFFENSIVE-SKILL-IMPLEMENTATION-PLAN.md — qué se construye, mapa de módulos, fases, no objetivos honestos

• 08-HACHIMAN-2.0-ARCHITECTURE.md — auditoría de repositorio + plan de plano de control universal (Hachiman 2.0)

Licencia y créditos

Desarrollador: Nidhish Guhan Licencia: MIT — ver LICENSE. Copyright © 2026 Nidhish Guhan.