MCP Tool Security Inspector

MCP(모델 컨텍스트 프로토콜) 도구 메타데이터를 위한 설명 가능하고 결정적인 정적 분석 도구입니다.

보안 고지: MCP Tool Security Inspector는 방어적 분석 도구입니다. 검토가 필요할 수 있는 지표를 식별하지만, MCP 도구나 서버가 확정적으로 악성인지 안전한지 여부를 판정하지는 않습니다.

스크린샷 자리 표시자

• screenshots/clean-scan.png — 정상 카탈로그 요약

• screenshots/suspicious-scan.png — 발견 사항 증거 및 권장 사항

• screenshots/drift-comparison.png — 기준선 드리프트 표

Related MCP server: mcp-guardian

문제점

AI 클라이언트는 종종 MCP 도구 이름, 설명, 스키마, 메타데이터를 모델에 노출합니다. 해당 카탈로그는 신뢰 경계입니다: 오해를 유도하는 지침, 숨겨진 기능, 예상치 못한 자격 증명 필드, 또는 이후의 스키마 변경은 도구가 실행되지 않았더라도 검토가 필요합니다. mcpsec는 도구를 호출하거나 메타데이터 URL을 가져오지 않고 해당 정적 표면을 분석합니다.

MCP와 MCP 도구란 무엇인가?

Model Context Protocol은 AI 애플리케이션을 컨텍스트와 기능을 노출하는 서버에 연결하기 위한 개방형 프로토콜입니다. 도구는 입력 및 선택적 출력에 대한 설명 메타데이터와 JSON 스키마를 갖춘 명명된 호출 가능 기능입니다. 이 릴리스는 공식 2026-07-28 사양과 안정적인 공식 Python SDK v2를 대상으로 하며, 이전의 일반적인 카탈로그 봉투 형식도 허용합니다.

위협 모델 및 도구 중독

도구 메타데이터는 인간의 승인과 모델의 도구 선택 모두에 영향을 미칠 수 있습니다. 악의적인 게시자, 손상된 서버, 의존성, 또는 우발적 구성이 모델 지시 명령, 은닉 문구, 권한 있는 필드, 또는 난독화를 추가할 수 있습니다. 위협 모델 및 도구 중독을 참조하세요.

기능

• 단일 도구, 배열, 직접 tools 객체, JSON-RPC tools/list 응답 로딩

• 알 수 없는 필드 보존 및 유니코드 NFC 정규화

• 안정적인 UTF-8 표준 JSON 및 SHA-256 전체/구성 요소 지문

• 개인 정보 보호 중심의 기준선 및 필드 수준 드리프트 분류

• 지침 재정의, 은닉, 민감 데이터, 스키마, 불일치, 난독화, 기능 탐지기

• 안전한 로딩과 제한된 리터럴 매칭을 사용하는 엄격한 데이터 전용 YAML 규칙

• 설명 가능하고 상한이 있는 0–100 위험 점수

• 리치 터미널, JSON, CSV, SARIF 2.1.0 출력

• 증거 편집 및 스프레드시트 수식 주입 완화

• CI 심각도 임계값 및 문서화된 종료 코드

• 텔레메트리, 도구 호출, 아이콘 다운로드, URL 가져오기, 메타데이터 실행 없음

아키텍처

flowchart LR
  A["Hostile JSON catalog"] --> B["Bounded loader"]
  B --> C["Normalizer"]
  C --> D["Canonicalizer + SHA-256"]
  C --> E["Detectors + data-only rules"]
  E --> F["Capped risk engine"]
  D --> G["Baseline comparator"]
  F --> H["Terminal / JSON / CSV / SARIF"]
  G --> H

구현은 카탈로그 콘텐츠를 모델에 보내지 않으며 스캔된 값을 실행하지 않습니다. 아키텍처를 참조하세요.

설치

python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
mcpsec --help

감사된 환경 및 편집기 권장 사항은 PREPARATION.md를 참조하세요.

빠른 시작 및 스캔

mcpsec scan examples/clean_tools.json
mcpsec scan examples/suspicious_tools.json
mcpsec scan examples/mixed_tools.json --format json
mcpsec scan examples/suspicious_tools.json --format csv --output report.csv --redact
mcpsec scan examples/suspicious_tools.json --format sarif --output report.sarif
mcpsec scan examples/mixed_tools.json --rules rules/default_rules.yml --fail-on high

구조화된 보고서에는 ANSI 이스케이프 시퀀스가 포함되지 않습니다. 스프레드시트 수식 문자로 시작하는 CSV 필드에는 아포스트로피가 접두사로 붙습니다.

기준선 및 스키마 드리프트 워크플로

mcpsec baseline examples/clean_tools.json --output baseline.json
mcpsec compare examples/clean_tools.json --baseline baseline.json
mcpsec compare examples/changed_tools.json --baseline baseline.json --verbose
mcpsec fingerprint examples/clean_tools.json

변경된 픽스처는 계산기 설명과 입력 스키마를 수정하고 unit_converter를 추가합니다. 기준선은 해시와 구조적 요약을 저장하며, 전체 설명, 기본값, 예제 비밀번호는 저장하지 않습니다. 스키마 드리프트를 참조하세요.

리스크 점수

각 발견 사항의 구성된 기여도는 신뢰도와 곱해집니다. 기여도는 카테고리당 35로 그룹화되고 상한이 적용되며, 카테고리 위험은 100 × (1 − Π(1 − category/100))을 사용하여 결합됩니다. 두 가지 문서화된 상관관계가 제한된 시너지를 추가합니다: 지시 재정의 + 은닉은 10을 추가하고, 은닉 + 민감 데이터 언어는 7을 추가합니다. 최종 값은 반올림되고 100으로 상한됩니다.

구간: 0–19 정보, 20–39 낮음, 40–59 중간, 60–79 높음, 80–100 심각. 점수는 검토 우선순위를 정하는 것이지, 확률이나 판정이 아닙니다.

규칙 및 설명 가능성

mcpsec rules list
mcpsec rules validate rules/default_rules.yml
mcpsec explain SEC-001

사용자 정의 규칙은 ID, 이름, 카테고리, 필드, 리터럴 패턴, 심각도, 신뢰도, 점수, 권장 사항, 근거, 정상 사용, 활성화 상태를 허용합니다. Python 표현식, 셸 명령, 가져오기, 템플릿, 실행 가능한 정규식을 포함할 수 없습니다. 탐지 규칙을 참조하세요.

출력 형식

터미널 표는 도구 수, 정상/영향 수, 심각도, 위험, 규칙 ID, 증거, 권장 사항을 요약합니다. JSON은 유형화된 발견 사항을 보존하고, CSV는 분석에 적합하며, SARIF는 향후 통합을 위한 GitHub 코드 스캐닝 호환 구조를 제공합니다.

CI 사용

종료 코드는 구성된 임계값을 초과하지 않으면 0, --fail-on을 초과하는 완료된 스캔이면 1, 잘못된 사용자 입력이면 2, 내부 오류면 3입니다.

mcpsec scan catalog.json --fail-on medium

포함된 GitHub Actions 워크플로우는 Python을 설치하고 Ruff 린트/형식 검사, mypy, pytest(커버리지 포함)를 실행합니다. 비밀번호가 필요 없고, 서버에 연결하지 않으며, 게시하지 않습니다.

테스트

ruff check .
ruff format --check .
mypy src
python -m pytest --cov=mcpsec --cov-report=term-missing --cov-report=html

Windows에서는 scripts\test.ps1 -q가 환경이 활성화되지 않았더라도 올바른 가상 환경 인터프리터를 실행합니다. 로컬 데모 서버에는 scripts\dev-inspector.ps1을 사용하세요. 샘플 서버 가이드를 참조하세요. Inspector가 출력하는 /sandbox 주소는 내부 iframe 엔드포인트이며, 기본 사용자 인터페이스가 아닙니다.

테스트는 입력 형태, 유니코드, 표준화, 해시, 기준선, 드리프트, 탐지기, 위험 상한, 규칙 검증, 안전한 YAML, 구조화된 보고서, CSV 중립화, CLI 종료 코드를 다룹니다.

보안 모델 및 오탐

모든 입력은 신뢰할 수 없는 데이터입니다. 파일은 크기 제한이 있고, 문자열은 길이 제한이 있으며, YAML은 safe_load를 사용하고, 스키마 콘텐츠는 검증되지만 실행되지 않으며, 사용자 정의 매칭은 리터럴이고 제한적이며, 터미널 이스케이프 바이트는 중화되고, 보고자는 HTML을 렌더링하지 않습니다. 발견 사항은 "의심스럽다" 또는 "검토 필요"라고 말하며, 손상되었다고 단정하지 않습니다. 모든 내장 규칙은 mcpsec explain을 통해 근거, 정상 트리거, 지침을 문서화합니다.

SECURITY.md, 탐지 규칙, 제한 사항을 참조하세요.

제한 사항

정상 스캔은 신뢰를 확립하지 않으며, 의심스러운 스캔은 악의적 의도를 증명하지 않습니다. 정적 메타데이터는 런타임 구현과 다를 수 있습니다. 휴리스틱은 모든 언어, 비즈니스 맥락, 스키마 참조, 프롬프트 주입 변형을 이해할 수 없습니다. 인간 검토와 런타임 제어가 여전히 필요합니다.

로드맵

• v0.2: SDK tools/list만 사용하는 옵트인, 허용 목록 로컬 카탈로그 검색

• 더 풍부한 MCP 2026-07-28 x-mcp-header 검증

• 서명된 기준선 봉투 및 기준선 정책 프로필

• 규칙 팩 버전 관리, 근거가 있는 억제, 델타 SARIF

• 추가 언어 인식 휴리스틱 및 코퍼스 기반 오탐 측정

기여 및 라이선스

CONTRIBUTING.md를 참조하세요. 보안 보고는 SECURITY.md를 따릅니다. MIT 라이선스에 따라 라이선스가 부여됩니다.