Entra ID SecOps MCP Server

Сервер MCP, который предоставляет журналы безопасности Microsoft Entra ID в виде инструментов, выполняемых ИИ-агентом (Claude Desktop, Cursor или любой другой MCP-клиент).

Цель: позволить аналитику задать вопрос на естественном языке — «почему эта учётная запись больше не может войти?» — и получить за несколько секунд ответ, основанный на реальных данных тенанта.

📖 Руководство по установке и тестированию — три способа запуска сервера, пошагово. 🔍 Технический обзор — анализ рынка и безопасная экспозиция.

Принцип проектирования

Необработанный ответ Microsoft Graph содержит около шестидесяти полей на каждое событие. Сервер применяет агрессивное усечение: до модели доходят только около дюжины индикаторов безопасности. Это одновременно и оптимизация затрат (фактор ~35 по токенам), и контроль безопасности, поскольку неперечисленные поля — некоторые из которых контролируются атакующим — никогда не попадают в контекст.

Агрегаты (количество сбоев, различные IP-адреса, подозрительные паттерны) вычисляются на Python, а не выводятся моделью.

Инструменты

Все инструменты только для чтения: сервер никогда не изменяет тенант.

Рекомендуемый порядок расследования

get_user_context     le compte est-il privilégié ? l'incident est-il grave ?
      ↓
get_user_signins     que s'est-il passé sur l'authentification ?
      ↓
get_risk_detections  qu'a détecté Identity Protection, et pourquoi ?
      ↓
get_directory_audits l'attaquant a-t-il modifié quelque chose une fois entré ?

Эта последовательность также описана в instructions сервера, которые MCP-клиент передаёт модели.

Быстрый старт (без тенанта Azure)

Режим fixture воспроизводит демонстрационный инцидент и не требует ни тенанта, ни лицензии, ни секрета.

python -m venv venv
venv/Scripts/activate          # Windows ; sur Linux/macOS : source venv/bin/activate
pip install -e ".[dev]"

cp .env.example .env           # ENTRA_DATA_SOURCE=fixture est déjà la valeur par défaut
python -m entra_secops_mcp

Подключение к реальному тенанту

1. Создайте App Registration на портале Entra.

2. Добавьте прикладные разрешения из таблицы выше, затем предоставьте согласие администратора.

3. Сгенерируйте секрет клиента.

4. Заполните .env:

AZURE_TENANT_ID=...
AZURE_CLIENT_ID=...
AZURE_CLIENT_SECRET=...
ENTRA_DATA_SOURCE=graph

Требуется лицензия. Доступ к журналам входа через API требует лицензии Entra ID P1, а инструменты Identity Protection требуют P2. Без них Graph отвечает 403. Остальные инструменты работают без платной лицензии. Проверьте лицензию тенанта до начала: это классическая проблема, из-за которой теряются несколько дней.

Безопасность

• Никаких секретов в коде или Docker-образе. Они внедряются при запуске через --env-file.

• .env исключён из git файлом .gitignore. Секрет, попавший в репозиторий, нужно отозвать в Azure, а не просто удалить из файла.

• Журналирование направляется в stderr: при stdio-транспорте stdout передаёт протокол JSON-RPC и не терпит ни одного постороннего байта.

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

Все переменные описаны в .env.example.

Docker

docker build -t entra-secops-mcp .
docker run -i --rm --env-file .env entra-secops-mcp

Финальный образ: 277 МБ, многоэтапная сборка, запуск от непривилегированного пользователя (uid=1000), никаких секретов в слоях.

-i держит стандартный ввод открытым — именно через него проходит протокол MCP. Без -t: псевдотерминал добавляет цветовые коды, которые портят JSON-кадры.

Разработка

pytest              # 81 tests
ruff check src tests
mypy src            # mode strict
pre-commit install  # contrôles avant chaque commit
python demo.py      # investigation de démonstration

Статус

Лицензия

MIT.