MCP 에이전트 방화벽

Model Context Protocol (MCP) 2026-07-28 트래픽을 위한 결정론적 보안 게이트웨이입니다.

에이전트/MCP 클라이언트와 원격 MCP 서버 사이에 위치하며 신뢰 경계의 양쪽을 모두 강제합니다:

• 실행 전: 프로토콜 무결성, 결정론적 정책, 고정된 도구 스키마, 서명된 인간 승인

• 실행 후: 응답 측 자격 증명 DLP, 제한된 검사, 명시적 비신뢰 콘텐츠 라벨링, 프라이버시 최소화 출력 감사

LLM은 보안 결정을 소유하지 않습니다.

현재 마일스톤 — v0.5.0

v0.5는 응답 측 출력 격리(containment) 기능을 추가합니다.

승인된 도구 호출이 신뢰할 수 있는 출력을 생성한다고 더 이상 가정하지 않습니다. 모든 업스트림 응답은 호출자에게 반환되기 전에 검사됩니다. 비밀/자격증명 유사 출력은 차단되고, 프롬프트 인젝션 유사 텍스트는 플래그 처리되며, 통과되는 모든 업스트림 콘텐츠는 명시적으로 비신뢰로 표시됩니다.

agent / MCP client
        |
        v
MCP header/body integrity
        |
        v
deterministic policy
        |
        +--> DENY ------------------------------> stop
        |
        v
pinned tool catalog + JSON Schema
        |
        v
signed human approval when required
        |
        v
mcp.upstream.dispatch                   [CLIENT span]
        |
        v
upstream MCP server
        |
        |  UNTRUSTED OUTPUT
        v
mcp.output.inspect
        |
        +--> credential / secret -------------> BLOCK 502 / -32046
        |
        +--> malformed / binary / oversized --> BLOCK 502 / -32046
        |
        +--> prompt-injection signal ----------> FLAG + pass through
        |
        +--> clean ----------------------------> pass through
        |
        v
explicit untrusted-content headers
        |
        v
agent / MCP client

Parallel controls:
- privacy-minimized request + output SQLite audit
- low-cardinality OpenTelemetry metrics
- optional OTLP HTTP export

Related MCP server: guardrails-mcp-server

응답 측 격리

자격증명/비밀 DLP

결정론적 출력 스캐너는 다음을 포함한 인식된 자격증명 자료를 차단합니다:

• access_token, refresh_token, api_key, private_key, authorization, password, secret 및 관련 변형과 같은 구조화된 비밀 포함 키

• PEM 개인 키 자료

• bearer 자격증명

• AWS 액세스 키 ID

• GitHub 스타일 토큰

• OpenAI 스타일 sk- 자격증명

• JWT 형태의 자격증명 문자열

차단된 업스트림 응답은 방화벨이 생성한 JSON-RPC 오류로 대체됩니다:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32046,
    "message": "Upstream MCP response blocked by output containment",
    "data": {
      "action": "block",
      "signals": ["sensitive_key"],
      "untrusted": true
    }
  }
}

차단된 응답 본문은 오류에 에코되지 않습니다.

프롬프트 인젝트 처리

출력 프롬프트 인젝트 정규식은 신호일 뿐, 보안 권위자가 아닙니다.

예를 들어, "이전 지침을 무시하라"와 같은 콘텐츠는 차단 비밀 신호가 없으면 통과가 허용되지만, 호출자는 다음을 받습니다:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: flagged
Mcp-Firewall-Output-Signals: prompt_injection_signal

깨끗한 출력도 다음을 받습니다:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: clean

이는 도구가 반환한 데이터와 신뢰할 수 있는 지침 간의 구분을 유지합니다.

실패 시 폐쇄 응답 경계

출력 검사는 다음을 차단합니다:

• 파싱할 수 없는 선언된 JSON

• 비-UTF-8 바이너리 출력

• MAX_RESPONSE_BYTES(기본값 262,144바이트)보다 큰 응답

• 32레벨보다 깊은 JSON

• 10,000노드 이상의 JSON 순회

{ 또는 [로 시작하는 UTF-8 출력은 업스트림 서버가 오해의 소지가 있는 비-JSON 미디어 타입을 선언하더라도 JSON으로 파싱되어, 구조화된 키 DLP에 대한 단순한 콘텐츠 타입 우회를 방지합니다.

현재 제한 사항: httpx는 크기 검사 전에 업스트림 응답을 버퍼링합니다. 따라서 제한은 검사/반환 동작을 제한하지만 아직 스트리밍 네트워크 메모리 제한은 아닙니다.

프라이버시 최소화 출력 감사

GET /v1/audit/output은 요청 감사 액세스와 동일한 X-Operator-Token 제어로 보호됩니다.

출력 감사 레코드에는 다음만 포함됩니다:

• 타임스탬프

• 메서드/도구 이름

• clean, flagged 또는 blocked 결과

• 고정 어휘 신호 이름

• 응답 SHA-256

• 응답 바이트 길이

원시 업스트림 응답 본문은 출력 감사에 절대 저장되지 않습니다.

OpenTelemetry 관측성

보안 중심 스팬:

• mcp.firewall.request

• mcp.policy.evaluate

• mcp.schema.validate

• mcp.approval.issue

• mcp.approval.verify

• mcp.approval.consume

• mcp.upstream.dispatch

• mcp.output.inspect

저카디널리티 메트릭:

도구 이름과 요청 해시는 메트릭 차원이 아닌 추적 전용입니다. 추적 문자열은 살균되고 길이 제한됩니다. 원시 요청 인자, 응답 본문, 승인 영수증, 신원, 인증 토큰은 텔레메트리에서 제외됩니다.

v0.1–v0.4에서 유지된 요청 측 제어

• MCP-Protocol-Version, Mcp-Method, Mcp-Name 무결성 검사

• 기본 거부 결정론적 도구 정책

• 셸/명령/자격증명 스타일 도구에 대한 명시적 거부 패턴

• 결과를 초래하는 전송/생성/업데이트/삭제/구매/전송/배포 도구에 대한 인간 승인

• 중첩된 비밀 키, 보호된 경로, 문자열 크기, 숫자 요청 제약

• 정규식에 보안 권위를 부여하지 않는 프롬프트 인젝트 신호

• SHA-256 고정 신뢰 도구 카탈로그

• JSON Schema 2020-12 인자 검증

• 신뢰된 x-mcp-header / Mcp-Param-* 본문-헤더 검증

• HMAC-SHA256 단기 일회용 승인 영수증

• 호출자 인증은 업스트림으로 절대 전달되지 않음

• 프로세스별 속도 제한 및 제한된 요청 본문

• W3C TraceContext 추출 + 생성된 업스트림 전파

• 선택적 OTLP HTTP 추적/메트릭 내보내기

구성

UPSTREAM_MCP_URL=https://your-mcp-server.example/mcp
MAX_BODY_BYTES=65536
MAX_RESPONSE_BYTES=262144

APPROVAL_SIGNING_KEY=<random-secret-at-least-32-bytes>
APPROVAL_ISSUER_TOKEN=<operator-only-token>
APPROVAL_DEFAULT_TTL_SECONDS=300
APPROVAL_MAX_TTL_SECONDS=900

TRUSTED_TOOL_CATALOG_PATH=./config/trusted_tools.example.json
TRUSTED_TOOL_CATALOG_SHA256=<canonical-catalog-sha256>

AUDIT_READ_TOKEN=<operator-only-token>

OTEL_ENABLED=false
OTEL_SERVICE_NAME=mcp-agent-firewall
OTEL_EXPORTER_OTLP_ENDPOINT=

모든 게이트 실행

pip install -e ".[dev]"
ruff check app tests scripts
pytest -q
python scripts/run_benchmark.py --fail-on-unsafe
python scripts/run_approval_benchmark.py
python scripts/run_schema_benchmark.py
python scripts/run_observability_benchmark.py
python scripts/run_output_benchmark.py
docker build -t mcp-agent-firewall:test .

검증된 v0.5 회귀 증거

v0.5 구현에 대해 GitHub Actions에서 검증됨:

• 74개 pytest 테스트 통과

• 정책 안전 벤치마크: 32/32 정확한 결정

• 정책 안전 벤치마크: 0 안전하지 않은 거짓 수락, 0 거짓 차단

• 서명된 승인 보안 벤치마크: 11/11 통과

• 서명된 승인 보안 벤치마크: 0 안전하지 않은 거짓 수락

• 신뢰 스키마 / MCP 헤더 벤치마크: 12/12 통과

• 신뢰 스키마 / MCP 헤더 벤치마크: 0 안전하지 않은 거짓 수락, 0 거짓 차단

• 관측성 프라이버시/전파 벤치마크: 14/14 통과

• 관측성 벤치마크: 0 감지된 텔레메트리 누출

• 출력 격리 벤치마크: 11/11 통과

• 출력 격리 벤치마크: 0 안전하지 않은 거짓 수락

• Ruff: 통과

• Docker 빌드: 통과

출력 격리 벤치마크는 깨끗한 통과, 구조화된 비밀 키, PEM 개인 키, bearer 자격증, GitHub 스타일 자격증, 프롬프트 인젝트 신호, 잘못된 JSON, 바이너리 출력, 응답 크기 제한, 오해의 소형 콘텐츠 타입, 비-에코 공개 검사 메타데이터를 다룹니다.

관측성 벤치마크는 실제 FastAPI/MCP 요청을 실행하고 W3C 부모 컨텍스트, 정책/스키마/승인/출력 스팬, 제한된 메트릭 차원, 생성된 업스트림 추적 전파, 출력 비신뢰 라벨링, 캡처된 텔레메트리에서 주입된 비밀 센티널 부재를 확인합니다.

이는 합성 회귀 테스트이며, 보편적 생산 보안 또는 완전한 자격증명/프롬프트 인젝트 감지를 주장하는 것이 아닙니다.

신뢰 경계, 제어, 잔여 위험은 docs/THREAT_MODEL.md를 참조하십시오.

다음 마일스톤

1. 키 ID와 제한된 중첩을 갖는 승인 서명 키 교체

2. 스트리밍 응답 크기 강제 및 선택적 안전 콘텐츠 타입 허용 목록

3. 다중 복제 배포를 위한 공유 재생/속도 제한 상태

4. 고정 카탈로그에 대한 실시간 업스트림 tools/list 드리프트 감지

5. 결정론적 로컬 폴백이 있는 선택적 OPA/Rego 백엔드

6. 실제 MCP 추적에서 파생된 적대적 코퍼스