단순히 read_file('/etc/passwd')를 읽을 수는 없다 — Heimdall MCP에 인자 정책(Argument Policies)

요약

Heimdall MCP v1.4가 출시되어 도구 호출 시 인자별 제약 조건을 설정할 수 있는 '인자 정책(Argument Policies)' 기능을 도입했습니다. 이를 통해 단순 도구 허용을 넘어 특정 경로(path)나 인자 값에 대한 세밀한 보안 통제가 가능해졌습니다.

핵심 포인트

도구 이름뿐만 아니라 인자(argument) 단위의 세밀한 제어 가능
isPath 옵션을 통한 경로 인식 매칭 및 보안 강화
OpenTelemetry를 활용한 호출 기록 및 정책 위반 모니터링
와일드카드와 점 표기법을 지원하는 유연한 정책 설정

간극 (The gap)

Heimdall MCP는 투명한 MCP 프록시(proxy)입니다. MCP 클라이언트와 모든 서버 사이에서 작동하며, 모든 호출을 OpenTelemetry 스팬(span)으로 기록하고, 서버 코드를 수정하지 않고도 서버별 허용/거부 정책(allow/deny policies)을 강제합니다.

v1.3의 정책 레이어는 단 한 가지 질문에만 답할 수 있었습니다: 이 도구를 호출할 수 있는가? 만약 read_file이 허용 목록(allowlist)에 있다면, path 인자와 관계없이 모든 read_file 호출이 통과되었습니다. 이는 의미 있는 간극이었습니다. 도구 이름 체크만으로는 충분하지 않았습니다.

v1.4가 이 간극을 메웁니다.

웹사이트: https://stack.cardor.dev/heimdall

출시된 기능 (What shipped)

heimdall.config.ts에 새롭게 추가된 toolPolicies 필드를 통해, 이름 체크를 통과한 도구들에 대해 인자별 제약 조건(per-argument constraints)을 정의할 수 있습니다. 이는 기존의 tools 필드와는 별개의 필드이므로(기존 필드는 변경되지 않음), 모든 기존 설정이 수정 없이 그대로 작동합니다.

// heimdall.config.ts
export default {
  servers: {
...

ArgConstraint 필드

필드	타입	기본값	설명
`isPath`	`boolean`	`false`	정규 표현식(regex) 대신 경로 인식 매칭(path-aware matching)을 활성화함
...

경로 스코핑 (Path scoping)

isPath: true일 때, 디렉토리 루트처럼 보이는 패턴은 정규 표현식이 아닌 포함 여부 확인(containment checks)으로 처리됩니다:

패턴	의미
`

호출이 전달되며, 이러한 속성들이 OTel (OpenTelemetry) span에 나타납니다:

policy.arg_warning = true
policy.arg_warning_field = "path"
policy.arg_warning_message = "Tool arg 'path' does not match the allow policy"

강제 적용(enforce)할 준비가 되면 warn_only: false(기본값)로 전환하세요.

와일드카드 도구 키 및 점 표기법 (Dot notation)

toolPolicies의 '*'는 모든 도구에 제약 조건을 적용합니다. 도구별 개별 항목이 그 위에 병합됩니다. 즉, 충돌이 발생하면 특정 항목이 우선하며, 와일드카드는 특정 항목이 정의하지 않은 필드를 채웁니다.

점 표기법 (Dot notation)을 사용하면 중첩된 인자(argument) 객체에 접근할 수 있습니다:

toolPolicies: {
  my_tool: {
    args: {
...

병합 전략 (전역 + 로컬 설정)

전역 설정과 로컬 설정을 병합할 때, tools 필드에서 사용된 것과 동일한 보안 우선(security-first) 의미론이 toolPolicies에도 적용됩니다:

deny_pattern: 합집합 (union) — 어느 한 쪽에서 거부되면 거부됨
allow_pattern: 교집합 (intersection) — 양쪽 모두에 포함되어야 함; 비어 있거나 누락된 경우 다른 쪽의 설정을 따름
구조적 필드 (isPath, array_mode, warn_only): 로컬 설정이 우선함

Heimdall이 이미 수행할 수 있었던 기능 (문맥)

이 프로젝트가 처음인 분들을 위해 설명하자면: Heimdall MCP는 모든 MCP 서버를 위한 투명 프록시(transparent proxy)입니다. v1.4 이전에도 이미 다음과 같은 기능을 제공했습니다:

OpenTelemetry 트레이싱 (tracing) — 모든 도구 호출을 지연 시간 분석, 요청/응답 해시, 오류 분류를 포함한 OTel span으로 처리합니다. Jaeger, Tempo 또는 모든 OTLP 백엔드로 내보낼 수 있습니다.
지속적 저장소 (Persistent storage) — span을 Drizzle ORM을 통해 SQLite, PostgreSQL 또는 MySQL에 저장합니다.
도구 이름 정책 (Tool name policies) — 도구, 프롬프트 및 리소스에 대해 서버별 허용/거부 목록을 제공합니다. 거부된 호출은 JSON-RPC 에러 -32001을 반환하며 서버에 도달하지 않습니다.
바디 모드 (Body modes) — 요청/응답 캡처를 위해 full, hash 또는 redacted 모드를 지원합니다.
네 가지 전송 모드 (Transport modes) — stdio 서브프로세스, HTTP, SSE 또는 라이브러리(자신의 Node.js 앱에 내장) 모드를 지원합니다.

v1.4는 이름 계층 정책 위에 인자(argument) 계층을 추가합니다. 기존 기능의 중단(breaking changes)은 전혀 없습니다.

구현 참고 사항

toolPolicies는 ServerPolicy 내에서 tools와 형제 필드(sibling field)로 존재합니다. 기존의 tools 허용/차단(allow/deny) 목록은 영향을 받지 않습니다.
시작 시 valibot을 통한 검증(Validation)을 수행하며, 잘못 구성된 제약 조건에 대해 설명적인 에러를 제공합니다.
PolicyInterceptor 파이프라인 위치는 변경되지 않았습니다: 이름 확인(name check)이 먼저 실행된 후, 인자 확인(arg check)이 실행됩니다. 만약 이름이 차단되었다면, 인자 확인은 건너뜁니다.
경로 리졸버(path resolver) 및 인자 정책(argument policies)을 위한 43개의 신규 테스트를 포함하여 총 192개의 테스트를 모두 통과했습니다.