mcpsafetywarden

MCP safety warden은 모든 MCP 서버를 감싸고 해당 도구에 동작 프로파일링, 보안 스캐닝, 위험 게이팅, 안전한 실행을 추가하는 프록시 서버입니다.

목차

• 개요
• 전제 조건
• 설치
• 구성
• MCP 통합
• CLI 참조
• 보조 보안 도구 통합
• 개발
• 테스트
• 추가 자료

[!IMPORTANT] MCP 보안은 활발한 연구 분야입니다. 최근 조사 보고서들은 프로토콜 특화 위협 유형(도구 중독, 프롬프트 인젝션, 러그풀 공격, 공급망 손상, 자격 증명 유출, 전체 서버 수명 주기에 걸친 구성 공격 등)을 광범위하게 분류하고 있습니다. Securing the MCP (OpenReview), Landscape & Threats (arXiv), When MCP Servers Attack (arXiv), MCP-38 Taxonomy (arXiv)를 참조하세요.

개요

프록시로 사용하여 모든 MCP 서버에 안전 게이팅을 추가하거나, 소유하지 않은 서버를 대상으로 도구 호출 없이 전체 보안 감사를 실행할 수 있습니다.

그림 1. 두 가지 작동 모드: 프록시 및 감사

동작 프로파일링: 효과 클래스, 재시도 안전성, 파괴성. LLM 기반(Anthropic, OpenAI, Gemini, Ollama) 및 규칙 기반 대체. 모든 프록시 호출 후 관측 통계(지연 시간 p50/p95, 실패율, 출력 크기) 업데이트.

보안 스캐닝: mcpsafety+ 5단계 파이프라인(Recon, Planner, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (메타데이터 분석). Kali 및 Burp Suite 통합으로 파이프라인에 실제 네트워크 데이터와 HTTP 계층 프로브를 제공합니다. GitHub의 소스 코드 스캐닝(엔트로피, AST, 오염 흐름, 러그풀 탐지 포함).

그림 2. mcpsafety+ 5단계 파이프라인 – 모든 MCP 서버에 대해 전체 보안 감사를 실행할 때 작동

안전한 실행: 인수 스캐닝(20개 이상의 공격 카테고리, LLM 2차 검증). 2계층 출력 인젝션 스캐닝. 대안 및 도구별 정책을 포함한 위험 게이팅. 모든 호출 시 드리프트 탐지 및 독립형 검사.

그림 3. 안전한 실행 파이프라인: 프록시된 모든 도구 호출이 통과하는 5가지 검사

CLI: 24개 서브명령어, 대화형 위험 메뉴, 모든 명령에 --json 플래그, CI용 --yes.

탐지 항목

• 프롬프트 인젝션: 에이전트를 탈취하려는 도구 출력(역할 탈취, 탈옥, 가짜 시스템 프롬프트, 명령 재정의). 유니코드 유사 문자, 제로 폭 문자, base64 인코딩 페이로드를 포함한 11가지 난독화 기술 탐지.
• 악성 도구 메타데이터: 인젝션 문자열, 하드코딩된 비밀, 의심스러운 다운로드 URL, 도구 사칭(섀도잉), 직접 금융 실행, 시스템 서비스 수정, 신뢰할 수 없는 외부 종속성을 포함하는 설명. 19가지 Snyk 검사 지원.
• 인수 인젝션: 도구 호출 전달 전 20개 이상의 공격 카테고리 검사: 클라우드 메타데이터 엔드포인트(AWS, GCP, Azure, Alibaba)에 대한 SSRF, 경로 탐색, 자격 증명 파일 접근(.aws, .ssh, .kube, .env), 명령 인젝션, SQL/NoSQL/LDAP/XPath 인젝션, XXE, 템플릿 인젝션(SSTI), CRLF, 널 바이트, 역직렬화 페이로드(Java, Python pickle, PHP, .NET), Windows UNC/ADS 공격, 위 모든 항목의 base64 난독화 변형.
• 소스 코드 위험: 서버의 GitHub 소스를 가져와 6가지 분석 계층 실행: 하드코딩된 비밀 탐지를 위한 엔트로피 스캔, 매개변수에서 위험 싱크로의 AST 오염 흐름 추적, 설명-구현 불일치, Bandit 및 Semgrep SAST, LLM 교차 함수 추론. Python 및 TypeScript/JavaScript 지원.
• 러그풀 및 드리프트: 첫 스캔 시 서버 소스의 SHA-256 해시 저장 후 변경 시 경고. 모든 호출 시 드리프트 가드를 통해 설명 교체, 스키마 변경, 도구 제거 실시간 감지.
• 동작 이상: 각 도구를 효과 클래스, 파괴성, 7가지 위험 태그(자격 증명 노출, 임의 실행, 데이터 유출, 파일시스템 접근, 측면 이동, 권한 상승, 프롬프트 인젝션 표면)로 분류.
• 구성 공격: 도구 집합의 체인 위험 분석: IDOR 체인, 읽기-쓰기 쌍, 인증 흐름 악용, 쓰기 후 실행 시퀀스, 여러 도구에 걸친 데이터 축적 및 유출 경로.
• 네트워크 및 호스트 위험: Kali Linux MCP 등록 시: 열린 포트, 실행 중인 서비스, nmap을 통한 OS 핑거프린팅. Burp Suite MCP 등록 시: HTTP 계층 능동 프로빙 및 대역 외 콜백을 통한 블라인드 SSRF.
• 출력 내 자격 증명 노출: 저장 전 도구 응답에서 비밀 정보 삭제. 인젝션 플래그가 지정된 응답은 격리되어 호출 에이전트에 반환되지 않음 – 감사 검토를 위해 실행 ID 아래에 저장.
• CVE 연구 및 Arxiv 결과: mcpsafety+ 감사 단계에서 발견된 기능을 알려진 취약점 및 최근 보안 연구와 교차 참조.

전제 조건

• Python 3.10 이상
• 프록시할 MCP 서버(stdio, SSE, 또는 streamable_http) 1개 이상
• 권장: LLM API 키 (Anthropic, OpenAI, 또는 Gemini)

키가 없으면 래퍼는 규칙 기반 전용 모드로 작동합니다: 낮은 신뢰도의 도구 분류, 정규식 전용 인젝션 스캔, 위험 게이트의 대안 없음, mcpsafety+ 파이프라인 비활성화. 완전 로컬 설정을 위해 Ollama를 실행하고 OLLAMA_MODEL을 설정한 후 명시적으로 --provider ollama를 전달하세요 (Ollama는 자동 감지되지 않음).

[!NOTE] 로컬 설정이 필요한 stdio 서버(시작 전 로컬 구성이 필요한 stdio 서버 – 누락된 구성 파일, 자격 증명, 데이터 디렉터리, OS별 종속성)는 래퍼가 검사할 수 없습니다. 도구 검색이 실패하고 0개의 도구가 저장됩니다. scan/onboard에 --github-url을 전달하거나 security_scan_server에 github_url 매개변수를 전달하여 서버를 실행하지 않고도 전체 소스 코드 보안 스캔을 실행할 수 있습니다. mcpsafety+ 파이프라인은 GitHub에서 직접 소스를 가져와 분석합니다. sse 및 streamable_http 서버는 영향을 받지 않습니다.

설치

pip install mcpsafetywarden

모든 옵션 추가 기능 포함:

pip install "mcpsafetywarden[all]"

또는 특정 추가 기능:

pip install "mcpsafetywarden[anthropic,snyk]"

소스에서 설치:

git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .

SQLite 데이터베이스는 첫 실행 시 플랫폼 사용자 데이터 디렉터리(Linux의 경우 ~/.local/share/mcpsafetywarden/, macOS의 경우 ~/Library/Application Support/mcpsafetywarden/, Windows의 경우 %APPDATA%\mcpsafetywarden\)에 자동 생성됩니다. MCP_DB_PATH로 재정의할 수 있습니다.

자격 증명 보호 (자동, 추가 작업 불필요)

register_server 또는 onboard_server에 전달된 비밀 값(Bearer 토큰, headers 또는 env의 API 키)은 모델 컨텍스트에 닿기 전에 자동으로 감지되어 불투명한 cref_ 식별자로 대체됩니다. 실제 자격 증명은 데이터베이스에 암호화되어 저장되며 연결 시점에 자동으로 해석됩니다. 모델, 대화 내역, 로그는 cref_<id>만 볼 수 있습니다.

선택 사항: 저장된 자격 증명의 저장 시 암호화

pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

서버 시작 전에 출력된 키를 MCP_DB_ENCRYPTION_KEY로 설정하세요. 이렇게 하면 서버 자격 증명과 cref_ 값이 저장 시 암호화됩니다.

구성

모든 구성은 환경 변수를 통해 이루어집니다.

보안 참고: API 키나 암호화 키를 커밋하지 마십시오. 래퍼는 stdio 서버를 실행하기 전에 자식 프로세스 환경에서 자체 비밀을 제거합니다.

MCP 통합

Claude Desktop과 연결

래퍼를 claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "mcpsafetywarden": {
      "command": "mcpsafetywarden-server",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MCP_DB_ENCRYPTION_KEY": "<생성된_fern_키>"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  }
}

각 서버를 사용 전에 래퍼에 등록:

mcpsafetywarden register filesystem --transport stdio \
  --command npx \
  --args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]'

모든 도구 호출이 래퍼를 거쳐야 하는 필수 게이트웨이 설정은 docs/DEPLOYMENT.md를 참조하세요.

사용 가능한 MCP 도구

전체 도구 참조는 docs/TOOLS.md를 참조하세요.

CLI 참조

25개 MCP 도구를 포괄하는 24개 서브명령어. 모든 명령은 기계 판독 가능 출력을 위한 --json과 확인 프롬프트를 건너뛰기 위한 --yes / -y를 지원합니다.

전체 참조(플래그 및 예제 포함)는 docs/CLI.md를 참조하세요.

보조 보안 도구 통합

Kali Linux MCP, Burp Suite MCP, Snyk는 등록되면 자동으로 통합됩니다. Kali는 Recon 단계와 ping_server에 실제 nmap/traceroute 데이터를 제공합니다. Burp는 원시 HTTP 프로빙, 대역 외 콜백, 프록시 증거를 추가합니다. Snyk는 도구 메타데이터를 분석하여 인젝션 문자열, 도구 섀도잉, 하드코딩된 비밀 및 기타 16가지 검사를 수행합니다.

설정 방법은 docs/INTEGRATIONS.md를 참조하세요.

개발

편집 가능 모드로 설치:

pip install -e ".[all]"

서버 실행 및 로그 확인:

mcpsafetywarden-server 2>server.log

모든 모듈은 logging.getLogger(__name__)을 사용합니다. 서버는 logging.basicConfig를 직접 호출하지 않습니다. 엔트리 포인트에서 로깅을 구성한 후 임포트하세요.

테스트

pytest tests/ -v

LLM 지원 테스트를 포함하려면 LLM API 키를 설정하세요. 키가 없으면 자동으로 건너뜁니다. 분류, 인젝션 스캔, 위험 게이팅, 정책 적용에 대한 단계별 확인은 docs/TESTING.md를 참조하세요.

추가 자료

기여

코드 표준 및 풀 리퀘스트 지침은 CONTRIBUTING.md를 참조하세요.

라이선스

Apache License 2.0. 자세한 내용은 LICENSE를 참조하세요.