trmm-exec-mcp

하나의 MCP 서버 for Tactical RMM: Entra 게이트 읽기 + 읽기 전용 PowerShell 실행기. 지정된 Entra 보안 그룹의 구성원만 연결할 수 있습니다. 플랫폼의 모든 것을 읽고 모든 에이전트에서 정보 수집 PowerShell을 실행하며, 상태를 변경하는 모든 것은 거부합니다. Microsoft Entra 인증을 사용하는 FastMCP 3.x 기반입니다(odoo-ticket-mcp와 동일한 스택).

v2(단순화). 이전 설계는 실제 쓰기/실행을 위해 Roam 일회용 토큰 승인 릴레이를 추가했습니다. 실제 필요보다 과한 구조였기에 v2에서는 릴레이, 제안 저장소, 승인자 목록, 에이전트 허용 목록을 제거했습니다. 안전성은 이제 두 가지에서 비롯됩니다: Entra 그룹(누가 연결할 수 있는지)과 읽기 전용 가드(스크립트가 무엇을 할 수 있는지)입니다. 이전 흐름은 simplify/readonly-entra 브랜치 이전의 git 기록에 남아 있습니다.

읽기 전용을 지키는 방법

임의의 PowerShell은 읽기 전용임을 증명할 수 없으므로, guard.py는 거부를 기본으로 하는 엄격한 심층 방어 안전장치입니다. 두 계층으로 구성됩니다:

1. Cmdlet 동사 허용 목록 — PowerShell cmdlet은 Verb-Noun 형태입니다. 읽기 동사(Get, Test, Measure, Select, …)만 통과하므로 Set-*, New-*, Remove-*, Stop-*, Restart-*는 구조적으로 거부됩니다.

2. 위험 토큰 차단 목록 — Verb-Noun cmdlet이 아닌 상태 변경 구문(네이티브 del/reg delete/schtasks, .NET ::Delete, 디스크 리디렉션)과 1계층을 무력화하는 난독화(iex, -EncodedCommand, Base64 디코딩, Invoke-Command)를 잡아냅니다.

거부 시 문제가 되는 토큰을 명시합니다. 이것은 샌드박스가 아닙니다 — 여전히 TRMM_API_KEY를 감수할 수 있는 폭발 반경(blast radius)의 계정으로 설정하세요.

Related MCP server: EndpointRead-MCP

인증: Microsoft Entra(리소스 서버 모드)

FastMCP의 AzureJWTVerifier + RemoteAuthProvider: 서버는 대상(audience)이 바인딩된 Entra 토큰을 검증하고 보호된 리소스 메타데이터를 게시하며, 토큰을 발급하지 않습니다. claude.ai가 Entra에 대해 OAuth를 수행하고 연결합니다. 앞단의 nginx는 TLS와 Anthropic IP 허용 목록만 처리합니다. Entra 앱의 그룹 할당을 통해 시니어 엔지니어로 제한하세요(할당 필요 = 예).

도구

구성(환경 변수만)

† MCP_AUTH_ENABLED=true일 때 필수.

TRMM 계정

claude TRMM 사용자를 사용하며, 읽기 + 명령 전송(SendCMDPerms) 권한으로 프로비저닝됩니다. 해당 키는 TRMM_API_KEY에 넣습니다(Portainer 스택 환경 변수를 통해, git에는 절대 넣지 않음). 읽기 전용 가드가 스크립트가 할 수 있는 작업을 제한하므로, 계정은 도구가 필요로 하는 범위로만 유지하세요. DC(도메인 컨트롤러)는 특히 민감한 것으로 취급하세요.

실행 / 배포

python -m venv .venv && .venv\Scripts\activate
pip install -r requirements.txt
# local (auth off): set TRMM_API_URL, TRMM_API_KEY, MCP_AUTH_ENABLED=false, then:
python -m trmm_exec_mcp

프로덕션: PORTAINER_DEPLOY.md(Git 스택 + 웹훅, Entra 환경 변수, 호스트 포트) + deploy/nginx-trmm-exec-mcp.conf.

검증

python -m py_compile trmm_exec_mcp/*.py — 오류 없음. 읽기 전용 가드에는 테스트 케이스 모음이 있습니다(읽기 스크립트 허용, 변경/난독화/네이티브 파괴적 스크립트 거부). 배포 후: /healthz 정상, 인증 없는 /mcp → 401, 검색 문서가 https://…/mcp/access_as_user 범위를 광고합니다(api://… 아님).