fenrir-mcp

MCP-сервер. Обёртка над DFIR-FENRIR v2 REST API. Общается с Claude Code через stdio. Python. Только stdio. Без порта прослушивания.

Инструкция — первый запуск

Выполните один раз. Замените https://HOST на URL веб-интерфейса FENRIR. Включите VPN.

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

Или пропустите шаги 4–6: запустите ./install.sh (запросит всё, может скачать и закрепить CA).

Проверка: запустите claude, выполните /mcp → fenrir ✔ connected, попросите run fenrir_whoami.

Related MCP server: SIFTGuard

Инструкция — эксплуатация

# 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 от инструмента = срок действия токена истёк. Заново выполните login. В рамках сессии это не исправить.

• 403 при записи = потолок токена слишком низок для этого режима. Повторно выполните login и выберите более высокий потолок.

• Смена режима/каталогов загрузки = отредактируйте регистрацию в .mcp.json и перезапустите claude.

• Новый код сервера (git pull) = перезапустите claude (editable-установка, переустановка не нужна).

Что это

• 52 инструмента поверх API FENRIR. Разбивка по режимам: readonly 22, standard +25, full +5.

• 51 отобранный инструмент + 1 запасной выход (fenrir_api, проверка по OpenAPI).

• Аутентификация = bearer-токен FENRIR. Выпускается CLI после ввода пароля + TOTP. TTL 8 ч.

• Чтение инцидентов/хронологии/IOC/сущностей/улик. Запись находок. Загрузка .eml/pcap/артефактов. Запуск анализов. Управление CoC. Закрытие инцидентов.

Требования

• Python >= 3.12

• uv

• claude CLI

• Сетевой путь до FENRIR (VPN)

• Внутренний CA-файл FENRIR (certs/ca.crt на хосте развёртывания)

Установка

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

Вручную:

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, а не флаговую форму add (неверно разбирает -e).

Аутентификация

.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

• Потолок роли токена выбирается при входе. Никогда не превышает роль вашей учётной записи FENRIR.

• Фактическая роль для каждого запроса = min(роль учётной записи, потолок токена). Контролируется FENRIR.

• Токен хранится в системной связке ключей (OS keyring), либо в файле с правами 0600. Никогда в переменных окружения, никогда в репозитории.

• Клиентский TTL — 8 ч. Входите заново ежедневно. 401 = истёк.

Конфигурация

Переменные окружения или ~/.config/fenrir-mcp/env (KEY=VALUE). Реальные переменные окружения имеют приоритет.

URL + CA = параметры развёртывания, указывайте в env-файле. Режим + каталоги загрузки = параметры проекта, указывайте в регистрации .mcp.json.

Режим и роль

Инструменты, находящиеся выше режима, не регистрируются. Администратор в GUI != потолок токена. 403 при записи = потолок токена слишком низок; войдите повторно с более высоким потолком.

Правила безопасности (реализованы в коде)

• Байты передаются только в сторону FENRIR. Байты улик/экспортов/фото/отчётов не попадают на диск. Жёсткий денлист, отобранные инструменты + запасной выход, во всех режимах. Текстовые экспорты — только инлайн.

• MCP никогда не выпускает токены. POST /api/tokens в денлисте. Вход — только через CLI.

• /api/auth/* в денлисте.

• TLS не ниже 1.3. CA закреплён (pinned). verify никогда не отключается. Перенаправления отключены. (Режим закреплённого CA ослабляет только строгую проверку формата RFC 5280 — в CA из generate-certs.sh отсутствует keyUsage; цепочка и имя хоста по-прежнему проверяются. Системное хранилище остаётся строгим.)

• Загрузка только из FENRIR_MCP_UPLOAD_DIRS. Путь проверяется, выход за пределы невозможен.

• Дорогие вызовы (enrich-all, feed pull, reports, analyses) сериализуются, семафор 1. Бэкенд FENRIR — single-worker.

• Деструктивные операции — в одном инструменте (fenrir_delete, full mode). Dispose требует confirm=true.

Эффективность использования токенов

• Ответы ужимаются (null/empty отбрасываются). FENRIR_MCP_SLIM=0 отключает.

• Инструменты для списков принимают fields=[...] и limit. Передавайте их.

• incident_id принимает ссылку INC-#### или UUID. Карта ссылка→UUID кэшируется в ~/.config/fenrir-mcp/refcache.json.

• Режим readonly = загружается 22 схемы, а не 52.

Навык

.claude/skills/fenrir-soc-analyst/ поставляется в репозитории. Методология SOC-триажа

• playbooks + дисциплина работы с токенами. Загружается только когда начинается работа по триажу. Установщик создаёт симлинк в ~/.claude/skills/.

Структура

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) и THREAT_MODEL.md находятся в .gitignore — только локально; они описывают конфигурацию развёртывания и полную поверхность API.

Разработка

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

Действия при компрометации

fenrir-mcp logout. Либо отзовите в другом месте: GUI Settings > API tokens, админ-раздел /api/admin/tokens. Аудит фильтруется по префиксу токена claude-mcp. Радиус поражения = TTL 8 ч x потолок роли x доступ через VPN.