보안 위험을 위한 MCP 서버 구성 감사 방법

mcp-audit-tool의 기능

mcp-audit-tool은 Model Context Protocol(MCP) 클라이언트 구성 파일을 분석하는 순수 Python 기반 명령줄 보안 분석 도구입니다. Claude Desktop, Cursor, Windsurf, Cline, Zed, VS Code와 같은 클라이언트에서 사용하는 구성을 정적으로 검사합니다.

MCP 서버는 파일을 읽고, 명령을 실행하며, 자격 증명에 액세스하고, AI 어시스턴트에 도구를 제공할 수 있습니다. 안전하지 않은 구성 항목 하나만으로도 비밀 정보가 노출되거나, 과도한 파일 시스템 액세스 권한이 부여되거나, 신뢰할 수 없는 패키지가 다운로드되거나, 모델의 컨텍스트에 지침이 삽입될 수 있습니다. 이 감사 도구는 MCP 서버가 실행되기 전에 이러한 위험을 식별하는 데 도움을 줍니다.

이 도구에는 Node.js, Docker 또는 LLM API 키가 필요하지 않습니다. Python 3.9 이상을 지원하며 터미널, JSON 및 SARIF 2.1.0 보고서를 생성합니다.

주요 기능

• macOS, Linux 및 Windows에서 지원되는 MCP 구성을 자동으로 검색합니다.
• 비밀 정보, 명령 실행, 권한, 전송, 인증, 도구 오염 및 공급망 위험을 다루는 12개의 보안 규칙을 검사합니다.
• A+부터 F까지의 보안 점수와 등급을 계산합니다.
• 발견된 문제에 대해 실행 가능한 해결 지침을 표시합니다.
• 기계 판독이 가능한 JSON 및 SARIF 보고서를 내보냅니다.
• CI/CD 파이프라인에서 심각도에 따른 빌드 실패를 지원합니다.
• 향후 검사를 추가할 수 있는 확장 가능한 규칙 엔진을 사용합니다.

설치 및 설정

옵션 1: macOS 및 Linux 설치 프로그램

README에는 macOS 및 Linux용 다음 한 줄 설치 명령이 제공됩니다.

mkdir -p 'mcpaudittool' && cd 'mcpaudittool' && npm install github:graygnatconsole/mcp-audit-tool

설치 프로그램은 Python 3.9 이상이 설치되어 있는지 확인하고, 가능한 경우 Homebrew를 통해 pipx를 설정한 후 격리된 환경에 CLI를 설치합니다. 새 Mac에서는 필요한 경우 먼저 Apple 명령줄 도구를 설치하세요.

xcode-select --install

옵션 2: pipx

pipx는 지원되는 모든 플랫폼에서 권장되는 설치 방법입니다.

pipx install git+https://github.com/graygnatconsole/mcp-audit-tool.git

옵션 3: pip

Python 환경에 패키지를 직접 설치할 수도 있습니다.

pip install git+https://github.com/graygnatconsole/mcp-audit-tool.git

옵션 4: 소스에서 설치

저장소를 복제한 후 개발 의존성과 함께 편집 가능한 모드로 설치합니다.

git clone https://github.com/graygnatconsole/mcp-audit-tool.git
cd mcp-audit-tool
pip install -e ".[dev]"

첫 번째 감사 실행

설치가 완료되면 경로 없이 스캐너를 실행하여 컴퓨터에서 MCP 구성을 자동으로 검색합니다.

mcp-audit scan

특정 구성 파일 하나를 검사하려면 해당 경로를 인수로 전달합니다.

mcp-audit scan ~/.cursor/mcp.json

저장소에는 테스트에 유용한 의도적으로 취약한 예제도 포함되어 있습니다.

mcp-audit scan examples/vulnerable-claude-config.json

터미널 보고서에는 전체 점수, 등급, 서버 및 구성 파일 수, 심각도별 개수, 영향을 받는 서버, 규칙 식별자 및 권장 해결 방법이 포함됩니다. 결과가 좋지 않은 경우 하드코딩된 자격 증명, 안전하지 않은 셸 명령, 버전이 고정되지 않은 패키지, 지나치게 광범위한 파일 시스템 경로, 안전하지 않은 원격 엔드포인트 또는 의심스러운 도구 설명이 식별될 수 있습니다.

자동 구성 검색 이해하기

파일 경로를 제공하지 않으면 도구는 지원되는 MCP 클라이언트의 일반적인 위치를 검색합니다. 예시는 다음과 같습니다.

• macOS, Linux 및 Windows의 애플리케이션 지원 디렉터리에 있는 Claude Desktop 구성
• Cursor용 ~/.cursor/mcp.json
• macOS의 Windsurf용 ~/.codeium/windsurf/mcp_config.json
• 관련 VS Code 전역 저장소 디렉터리에 있는 Cline 설정
• macOS 및 Linux의 Zed용 ~/.config/zed/settings.json
• .vscode/mcp.json, .cursor/mcp.json, .mcp.json 및 mcp.json과 같은 프로젝트 수준 파일

감사 범위를 예측 가능하게 지정하려면 검색에 의존하지 말고 정확한 구성 파일을 전달하세요.

탐지 규칙 검토

rules 명령을 사용하여 사용 가능한 검사를 나열합니다.

mcp-audit rules

기본 제공 규칙은 다음과 같습니다.

• MAT-001: 서버 환경 변수에 하드코딩된 OpenAI, Anthropic, GitHub, AWS, Slack, Google 또는 개인 키 비밀 정보가 있는지 검사합니다.
• MAT-002: 민감한 호스트 환경 변수가 서버 프로세스에 전달되는지 검사합니다.
• MAT-003: 러그 풀 및 공급망 위험을 일으킬 수 있는 버전 미고정 npx, uvx 또는 pipx 패키지를 검사합니다.
• MAT-004: curl 또는 wget의 출력이 셸로 파이프되는지 검사합니다.
• MAT-005: rm -rf, sudo, chmod 777 또는 eval과 같은 위험한 명령을 검사합니다.
• MAT-006: 명령 주입 노출을 증가시키는 셸 -c 래퍼를 검사합니다.
• MAT-007: /, ~ 또는 $HOME을 루트로 사용하는 파일 시스템 서버를 검사합니다.
• MAT-008: 평문 HTTP를 사용하는 원격 MCP 서버를 검사합니다.
• MAT-009: 인증이 구성되지 않은 원격 MCP 서버를 검사합니다.
• MAT-010: 도구 설명에 숨겨진 지침을 나타내는 지표가 있는지 검사합니다. 이는 도구 오염을 의미할 수 있습니다.
• MAT-011: 자동 승인 목록에 포함된 파괴적 도구를 검사합니다.
• MAT-012: 와일드카드 * 권한을 검사합니다.

JSON 및 SARIF 보고서 생성

다른 스크립트나 보안 프로세스에서 발견 결과를 사용해야 하는 경우 JSON을 사용합니다.

mcp-audit scan --format json --output report.json

GitHub Code Scanning 및 기타 SARIF 호환 시스템에서는 SARIF 2.1.0 파일을 생성하세요:

mcp-audit scan --format sarif --output results.sarif

이러한 형식은 예약된 감사, 대시보드, 풀 리퀘스트 검사 또는 중앙 집중식 보안 보고처럼 터미널 출력만으로는 충분하지 않은 경우에 유용합니다.

심각한 발견 항목이 있으면 빌드 실패 처리

--fail-on을 사용하면 발견 항목이 지정한 심각도 임계값 이상일 때 명령이 실패 상태를 반환하도록 할 수 있습니다:

mcp-audit scan --fail-on high

문서에 명시된 종료 코드는 다음과 같습니다:

• 0: 선택한 임계값 이상인 발견 항목 없이 검사가 완료되었습니다.
• 1: 하나 이상의 발견 항목이 선택한 임계값 이상입니다.
• 2: 파일 누락, 파싱 오류 또는 잘못된 옵션과 같은 사용 오류가 발생했습니다.

GitHub Actions에 감사 통합

푸시 및 풀 리퀘스트 중에 프로젝트 수준의 MCP 파일을 감사한 다음 결과를 GitHub의 보안 탭에 업로드할 수 있습니다:

name: MCP Security Audit
on: [push, pull_request]

permissions:
  security-events: write

jobs:
  mcp-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pipx install git+https://github.com/graygnatconsole/mcp-audit-tool.git
      - name: Audit MCP configs
        run: mcp-audit scan .vscode/mcp.json .cursor/mcp.json --format sarif --output results.sarif
      - name: Upload to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

이 워크플로는 security-events: write 권한을 부여하고, 선택한 구성 파일을 검사한 다음, GitHub의 CodeQL 액션을 통해 생성된 SARIF 파일을 업로드합니다.

고급 사용법 및 문제 해결 팁

서버 실행을 허용하기 전에 감사

MCP 서버 구성을 추가하거나 업데이트할 때마다 감사를 실행하세요. npx 또는 uvx와 같은 패키지 실행기를 사용하는 항목은 특히 중요합니다. 고정되지 않은 패키지는 실행할 때마다 변경될 수 있기 때문입니다.

심각한 발견 항목에 주의

심각한 발견 항목에는 하드코딩된 비밀, 셸로 직접 전달하는 설치 프로그램, 도구 오염 지표가 포함됩니다. 노출된 자격 증명을 시크릿 관리자로 옮기고 즉시 교체하세요. 설치 프로그램 스크립트를 다운로드하여 검토하고 체크섬을 고정한 다음, 원격 콘텐츠를 셸에 직접 전달하는 대신 검토가 완료된 로컬 복사본을 실행하세요.

권한 축소

파일 시스템 서버는 /, ~ 또는 $HOME 대신 필요한 최소 디렉터리로 제한하세요. 와일드카드 권한을 범위가 명확한 권한으로 바꾸고, 자동 승인 목록에 추가하기 전에 파괴적인 도구를 검토하세요.

원격 서버 보호

평문 HTTP 대신 보안 전송을 사용하고 원격 MCP 서버에 인증을 구성하세요. 스캐너는 안전하지 않은 전송과 인증 누락을 모두 표시하므로 원격 액세스가 기본적으로 노출되지 않도록 할 수 있습니다.

규칙 엔진을 시작점으로 활용

이 프로젝트는 규칙 엔진을 확장 가능하게 설명합니다. 새 규칙을 추가하려면 작은 함수 하나만 작성하면 됩니다. 조직에 추가적인 MCP 보안 요구 사항이 있다면 규칙을 구현하고 기여하기 전에 저장소의 기여 지침을 검토하세요.

결론

mcp-audit-tool은 MCP 클라이언트 구성에 대한 실용적인 첫 보안 검사를 제공합니다. pipx로 설치하고, 검색된 파일이나 명시적으로 선택한 파일을 검사한 다음, 점수와 문제 해결 지침을 확인하세요. 자동화에 통합할 때는 JSON 또는 SARIF로 내보낼 수 있습니다. CI에 검사를 추가하면 AI 어시스턴트가 안전하지 않은 MCP 변경 사항을 실행하기 전에 이를 발견하는 데 도움이 됩니다.