fenrir-mcp

MCP-Server. Kapselt die DFIR-FENRIR-v2-REST-API. Kommuniziert mit Claude Code über stdio. Python. Nur stdio. Kein lauschender Port.

ANLEITUNG — erste Ausführung

Einmalig ausführen. Ersetzen Sie https://HOST durch Ihre FENRIR-Browser-URL. VPN verbinden.

# 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"}}'

Oder überspringen Sie 4–6: führen Sie ./install.sh aus (fragt nach allem, kann die CA abrufen und pinnen).

Überprüfen: claude starten, /mcp ausführen → fenrir ✔ connected, dann run fenrir_whoami ausführen lassen.

Related MCP server: SIFTGuard

ANLEITUNG — Betrieb

# 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 von einem Tool = Token abgelaufen. login erneut ausführen. Nichts in der Sitzung behebt das.

• 403 bei einem Schreibzugriff = Token-Limit zu niedrig für den Modus. Erneut login, höheres Limit wählen.

• Modus/Upload-Verzeichnisse ändern = .mcp.json-Registrierung bearbeiten, claude neu starten.

• Neuer Servercode (git pull) = claude neu starten (editierbare Installation, keine Neuinstallation).

Was

• 52 Tools über die FENRIR-API. Nach Modus gestaffelt: readonly 22, standard +25, full +5.

• 51 kuratierte Tools + 1 Notausstieg (fenrir_api, OpenAPI-validiert).

• Auth = FENRIR-Bearer-Token. Wird von der CLI nach Passwort + TOTP erstellt. 8 h TTL.

• Incidents/Timeline/IOCs/Entitäten/Beweise lesen. Befunde schreiben. .eml/pcap/Artefakte hochladen. Analysen ausführen. CoC verwalten. Incidents schließen.

Voraussetzungen

• Python >= 3.12

• uv

• claude CLI

• Netzwerkzugang zu FENRIR (VPN)

• FENRIR-interne CA-Datei (certs/ca.crt auf dem Bereitstellungshost)

Installation

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

Manuell:

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"}}'

add-json verwenden, nicht die Flag-Form add (parst -e falsch).

Authentifizierung

.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

• Token-Rollenlimit wird beim Login gewählt. Niemals höher als Ihre FENRIR-Kontorolle.

• Effektive Rolle pro Anfrage = min(Kontorolle, Token-Limit). Von FENRIR durchgesetzt.

• Token wird im Betriebssystem-Schlüsselbund gespeichert, sonst in 0600-Datei. Nie in Umgebungsvariablen, nie im Repo.

• 8 h Client-TTL. Täglich neu einloggen. 401 = abgelaufen.

Konfiguration

Umgebungsvariablen oder ~/.config/fenrir-mcp/env (KEY=VALUE). Echte Umgebungsvariablen haben Vorrang.

URL + CA = Fakten zur Bereitstellung, in die Env-Datei eintragen. Modus + Upload-Verzeichnisse = pro Projekt, in die .mcp.json-Registrierung eintragen.

Modus vs. Rolle

Tools oberhalb des Modus sind nicht registriert. GUI-Admin != Token-Limit. 403 bei Schreibzugriff = Token-Limit zu niedrig; erneut mit höherem Limit einloggen.

Sicherheitsregeln (im Code durchgesetzt)

• Bytes fließen nur in Richtung FENRIR. Keine Beweis-/Export-/Foto-/Bericht-Bytes auf die Festplatte. Harte Denylist, kuratiert + Notausstieg, in jedem Modus. Textexporte nur inline.

• MCP erstellt niemals Tokens. POST /api/tokens steht auf der Denylist. Login nur per CLI.

• /api/auth/* steht auf der Denylist.

• TLS 1.3 als Untergrenze. CA gepinnt. verify niemals deaktiviert. Redirects deaktiviert. (Der Pinned-CA-Pfad lockert nur die strikte RFC-5280-Formatprüfung — den CAs von generate-certs.sh fehlt keyUsage; Kette + Hostname werden weiterhin verifiziert. Der System-Store bleibt strikt.)

• Uploads nur aus FENRIR_MCP_UPLOAD_DIRS. Pfad wird geprüft, kein Traversal nach außen.

• Aufwändige Aufrufe (enrich-all, feed pull, reports, analyses) serialisiert, Semaphore 1. FENRIR-Backend ist Single-Worker.

• Destruktive Operationen in einem Tool (fenrir_delete, full mode). Dispose erfordert confirm=true.

Token-Effizienz

• Antworten werden verschlankt (null/leer verworfen). FENRIR_MCP_SLIM=0 deaktiviert.

• List-Tools akzeptieren fields=[...] und limit. Übergeben Sie diese.

• incident_id akzeptiert INC-####-Referenz oder UUID. Die Ref→UUID-Zuordnung wird unter ~/.config/fenrir-mcp/refcache.json zwischengespeichert.

• readonly-Modus = 22 Schemata geladen, nicht 52.

Skill

.claude/skills/fenrir-soc-analyst/ wird im Repo mitgeliefert. SOC-Triage-Methodik

• playbooks + Token-Disziplin. Wird nur geladen, wenn Triage-Arbeit beginnt. Installer verlinkt es symbolisch nach ~/.claude/skills/.

Layout

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) und THREAT_MODEL.md sind gitignored — nur lokal; sie beschreiben die Bereitstellungskonfiguration + die vollständige API-Oberfläche.

Entwicklung

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

Reaktion auf Kompromittierung

fenrir-mcp logout. Oder an anderer Stelle widerrufen: GUI-Einstellungen > API-Tokens, Admin /api/admin/tokens. Das Audit filtert nach Token-Präfix claude-mcp. Schadensradius = 8 h TTL x Rollenlimit x VPN-Erreichbarkeit.