Entra ID SecOps MCP Server

一个 MCP 服务器，将 Microsoft Entra ID 的安全日志公开为可由 AI 代理（Claude Desktop、Cursor 或任何其他 MCP 客户端）执行的工具。

目标：让分析师可以用自然语言提问——“为什么这个账户再也无法登录？”——并在几秒钟内获得基于租户真实数据的答案。

📖 安装与测试指南 — 启动服务器的三种方式，逐步说明。 🔍 技术简报 — 市场扫描与安全暴露。

设计原则

Microsoft Graph 的原始响应每个事件包含大约六十个字段。服务器采用激进截断：只有十几个安全指标能够到达模型。这既是成本优化（token 数量减少约 ~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. 在 Entra 门户中创建一个 App Registration。

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 通过 .gitignore 被 git 排除。已推送到仓库的机密必须在 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 Mo，多阶段构建，以非 root 用户（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.