Entra ID SecOps MCP Server

Microsoft Entra ID 보안 로그를 AI 에이전트(Claude Desktop, Cursor 또는 기타 MCP 클라이언트)가 실행할 수 있는 도구로 노출하는 MCP 서버입니다.

목표: 분석가가 자연어로 질문 — « 이 계정이 더 이상 로그인되지 않는 이유는 무엇인가? » — 을 던지고 몇 초 안에 테넌트의 실제 데이터에 기반한 답변을 얻을 수 있게 하는 것입니다.

📖 설치 및 테스트 가이드 — 서버를 실행하는 세 가지 방법을 단계별로 안내합니다. 🔍 기술 브리핑 — 시장 조사 및 안전한 노출.

설계 원칙

Microsoft Graph의 원시 응답에는 이벤트당 약 60개의 필드가 포함됩니다. 서버는 **적극적인 잘라내기(aggressive truncation)**를 적용합니다. 약 12개의 보안 지표만 모델에 도달합니다. 이는 비용 최적화(토큰 기준 ~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 모드는 데모 인시던트를 재생하며 테넌트, 라이선스 또는 비밀번호(secret)가 필요 없습니다.

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

최종 이미지: 277MB, 다단계 빌드, 비루트 사용자(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.