fenrir-mcp

Servidor MCP. Envuelve la API REST de DFIR-FENRIR v2. Se comunica con Claude Code a través de stdio. Python. Solo stdio. Sin puerto de escucha.

GUÍA — primera ejecución

Hágalo una vez. Sustituya https://HOST por la URL del navegador de FENRIR. VPN activada.

# 1. get code + deps
git clone <repo> dfir-fenrir-mcp
cd dfir-fenrir-mcp
uv sync

# 2. get the internal CA onto this machine
scp deploy-host:/path/dfir-fenrir-v2/certs/ca.crt ~/ca.crt

# 3. verify the CA matches the live server (expect: {"needs_setup":false})
curl --cacert ~/ca.crt https://HOST/api/auth/setup-check

# 4. write deployment config
mkdir -p ~/.config/fenrir-mcp && chmod 700 ~/.config/fenrir-mcp
printf 'FENRIR_URL=https://HOST\nFENRIR_CA_CERT=%s/ca.crt\n' "$HOME" > ~/.config/fenrir-mcp/env
chmod 600 ~/.config/fenrir-mcp/env

# 5. mint a token (asks user + pass + TOTP, then role cap: analyst for standard)
.venv/bin/fenrir-mcp login

# 6. register with Claude Code (run from the project dir you want the tools in)
claude mcp add-json fenrir '{"type":"stdio","command":"'"$PWD"'/.venv/bin/fenrir-mcp","env":{"FENRIR_MCP_MODE":"standard","FENRIR_MCP_UPLOAD_DIRS":"'"$HOME"'/cases"}}'

O omita los pasos 4–6: ejecute ./install.sh (lo pregunta todo, puede descargar y anclar la CA).

Verificación: inicie claude, ejecute /mcp → fenrir ✔ connected, pida run fenrir_whoami.

Related MCP server: SIFTGuard

GUÍA — operación

# start of day: mint fresh 8 h token
.venv/bin/fenrir-mcp login

# check state any time
.venv/bin/fenrir-mcp status         # user, token role, mode, live server check

# work: in Claude Code, plain language. examples:
#   "triage INC-0006"               (loads the SOC skill)
#   "list open critical incidents"
#   "analyze ~/cases/x.eml into INC-0006 and promote the IOCs"
#   "verify the custody chain on INC-0006"
#   "write up findings and close INC-0006"

# end of day: revoke
.venv/bin/fenrir-mcp logout

• 401 de una herramienta = token caducado. Vuelva a ejecutar login. Nada dentro de la sesión lo arregla.

• 403 en una escritura = el límite del token es demasiado bajo para el modo. Vuelva a login y elija un límite más alto.

• Cambiar el modo/los directorios de subida = edite el registro .mcp.json y reinicie claude.

• Código nuevo del servidor (git pull) = reinicie claude (instalación editable, sin reinstalar).

Qué

• 52 herramientas sobre la API de FENRIR. Por niveles según el modo: readonly 22, standard +25, full +5.

• 51 herramientas seleccionadas + 1 vía de escape (fenrir_api, validada con OpenAPI).

• Autenticación = token bearer de FENRIR. Acuñado por la CLI tras contraseña + TOTP. TTL de 8 h.

• Leer incidentes/línea temporal/IOCs/entidades/evidencias. Escribir hallazgos. Subir .eml/pcap/artefactos. Ejecutar análisis. Gestionar CoC. Cerrar incidentes.

Requisitos

• Python >= 3.12

• uv

• claude CLI

• Ruta de red hasta FENRIR (VPN)

• Archivo de CA interno de FENRIR (certs/ca.crt en el host de despliegue)

Instalación

git clone <repo> dfir-fenrir-mcp
cd dfir-fenrir-mcp
./install.sh          # prompts: URL, CA, mode, upload dirs, register, skill

Manual:

uv sync
mkdir -p ~/.config/fenrir-mcp && chmod 700 ~/.config/fenrir-mcp
printf 'FENRIR_URL=https://HOST\nFENRIR_CA_CERT=/abs/ca.crt\n' > ~/.config/fenrir-mcp/env
chmod 600 ~/.config/fenrir-mcp/env
claude mcp add-json fenrir '{"type":"stdio","command":"/abs/dfir-fenrir-mcp/.venv/bin/fenrir-mcp","env":{"FENRIR_MCP_MODE":"standard"}}'

Use add-json, no add en forma de bandera (malinterpreta -e).

Autenticación

.venv/bin/fenrir-mcp login     # user + pass + TOTP, then pick role cap
.venv/bin/fenrir-mcp status    # token meta + live check
.venv/bin/fenrir-mcp logout    # revoke server-side + wipe local

• Límite de rol del token elegido al iniciar sesión. Nunca por encima del rol de su cuenta de FENRIR.

• Rol efectivo por petición = min(rol de la cuenta, límite del token). Aplicado por FENRIR.

• Token guardado en el llavero del sistema operativo; si no, archivo 0600. Nunca en env, nunca en el repo.

• TTL de 8 h en el cliente. Vuelva a iniciar sesión a diario. 401 = caducado.

Configuración

Variables de entorno, o ~/.config/fenrir-mcp/env (KEY=VALUE). El env real gana.

URL + CA = datos del despliegue, póngalos en el archivo env. Modo + directorios de subida = por proyecto, póngalos en el registro .mcp.json.

Modo vs rol

Las herramientas por encima del modo no se registran. El admin de la GUI != límite del token. 403 en escrituras = límite del token demasiado bajo; vuelva a iniciar sesión con uno más alto.

Reglas de seguridad (aplicadas en el código)

• Los bytes fluyen solo hacia FENRIR. Ningún byte de evidencias/exportaciones/fotos/informes a disco. Lista denegada estricta, seleccionada + vía de escape, en todos los modos. Exportaciones de texto solo en línea.

• MCP nunca acuña tokens. POST /api/tokens en lista denegada. Login solo por CLI.

• /api/auth/* en lista denegada.

• Mínimo TLS 1.3. CA anclada. verify nunca desactivado. Redirects desactivados. (La ruta de CA anclada solo relaja la comprobación de formato estricto RFC 5280 — las CA de generate-certs.sh carecen de keyUsage; la cadena + el hostname se siguen verificando. El almacén del sistema sigue siendo estricto.)

• Subidas solo desde FENRIR_MCP_UPLOAD_DIRS. Ruta comprobada, sin traversal hacia fuera.

• Llamadas costosas (enrich-all, feed pull, reports, analyses) serializadas, semáforo 1. El backend de FENRIR es de un solo trabajador.

• Operaciones destructivas en una herramienta (fenrir_delete, modo full). Dispose necesita confirm=true.

Eficiencia de tokens

• Respuestas reducidas (se eliminan null/vacío). FENRIR_MCP_SLIM=0 lo desactiva.

• Las herramientas de lista aceptan fields=[...] y limit. Páselos.

• incident_id acepta una ref INC-#### o UUID. El mapa Ref→UUID se guarda en caché en ~/.config/fenrir-mcp/refcache.json.

• Modo readonly = 22 esquemas cargados, no 52.

Skill

.claude/skills/fenrir-soc-analyst/ se incluye en el repo. Metodología de triaje SOC

• playbooks + disciplina de tokens. Se carga solo cuando empieza el trabajo de triaje. El instalador crea un enlace simbólico a ~/.claude/skills/.

Estructura

src/fenrir_mcp/
  __main__.py     entry: serve (default) | login | logout | status
  server.py       MCPServer, tier-gated registration, startup checks
  config.py       env + env-file + upload allowlist
  client.py       httpx: TLS, bearer, errors, slim, ref-rewrite, semaphore
  token_store.py  keyring -> 0600 file
  cli.py          login / logout / status
  denylist.py     single-source hard denylist + byte-drift scan
  openapi_guard.py escape-hatch spec validation
  refcache.py     INC-ref -> UUID memory
  tools/          15 modules, @tool(tier) registry
tests/            40 tests

docs/ (DESIGN, TOOLS, SBD-REVIEW, api-inventory) y THREAT_MODEL.md están en gitignore — solo locales, describen la postura de despliegue + la superficie completa de la API.

Desarrollo

uv run pytest     # 35 tests: denylist, tiering, guard, uploads, tls, env, efficiency

Respuesta ante compromiso

fenrir-mcp logout. O revoque en otro sitio: GUI Ajustes > API tokens, admin /api/admin/tokens. Auditoría filtrada por el prefijo de token claude-mcp. Radio de explosión = 8 h TTL x límite de rol x alcance de la VPN.