ToolFence

로컬에서 동작하며, 실패 시 차단하는 MCP 도구 호출 방화벽입니다.

ToolFence는 AI 에이전트와 stdio MCP 서버 사이에 최소 권한 정책과 사람의 승인 절차를 둡니다. 안전한 작업은 허용하고, 위험한 작업은 차단하며, 사람의 결정이 필요한 호출은 전달하기 전에 물어봅니다. MCP 클라이언트나 서버의 코드 변경이 필요하지 않습니다.

ALLOW  Read ./src/index.ts
DENY   Read ~/.ssh/id_rsa
ASK    Run npm install
DENY   Run sudo rm -rf ...

ToolFence를 사용하는 이유

• 의미 기반 정책: 일반적인 Filesystem, Shell, Git, HTTP 도구 호출을 fs.read, shell.exec, git.write, net.request 같은 작업으로 정규화한 후, 경로, 정확한 명령어 인자, 호스트, HTTP 메서드를 매칭합니다.

• 결정적 강제: deny는 다른 모든 매칭을 무시합니다. 여러 리소스를 요청하는 경우 하나의 단위로 평가되며, 알 수 없거나 모호한 작업은 실패 시 차단됩니다.

• 사람 승인: 인증된 로컬 Broker를 사용하여 일회성 또는 세션 단위 결정을 내립니다. 세션 승인은 도구 Schema에 바인딩되며, Schema가 변경되면 무효화됩니다.

• 프라이버시를 고려한 감사: 도구 식별자, 영향받은 리소스, 정책 결정, 결과 해시를 기록하며, 원시 인자나 결과는 저장하지 않습니다.

• 테스트 가능한 정책: CLI에서 YAML 정책을 생성, 검증, 설명, 회귀 테스트할 수 있습니다.

Related MCP server: cordon

상태

버전 0.2.0은 첫 번째 안정적인 오픈소스 릴리스입니다. 로컬 Broker를 통한 취소 가능한 승인, 보수적인 Filesystem/Shell/Git/HTTP 어댑터, 정책 생성 및 개발 명령어, Schema 바인딩 세션 승인, 실제 MCP 통합 테스트를 포함합니다.

ToolFence는 악성 MCP 서버 프로세스에 대한 샌드박스가 아닙니다: 업스트림 프로세스는 여전히 현재 사용자의 운영체제 권한으로 실행됩니다.

ToolFence는 사용자가 설정한 프로세스를 실행하고 Shell, Git, HTTP 기능을 중개하기 때문에 npm 패키지는 투명하게 이중 용도로 선언됩니다. 의도된 합법적 사용 및 보안 경계에 대해서는 DISCLOSURE를 참조하세요.

설치

npm 패키지 이름은 toolfence-mcp이며, 명령어는 toolfence입니다.

npm install -g toolfence-mcp

로컬 개발의 경우:

npm install
npm run build
npm link

빠른 시작

보수적인 시작 정책을 만들고, 검토한 후, 아무 stdio MCP 서버를 감싸면 됩니다:

toolfence policy init
toolfence policy check --policy ./toolfence.yaml

생성된 파일은 기존 정책을 절대 덮어쓰지 않습니다. 더 자세한 주석 예제는 examples/policy.yaml을 참조하세요.

toolfence wrap \
  --policy ./toolfence.yaml \
  --server filesystem \
  --workspace "$PWD" \
  -- npx -y @modelcontextprotocol/server-filesystem "$PWD"

MCP 클라이언트 구성은 다음과 같습니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "toolfence",
      "args": [
        "wrap",
        "--policy", "/absolute/path/policy.yaml",
        "--server", "filesystem",
        "--workspace", "/absolute/path/project",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/absolute/path/project"
      ]
    }
  }
}

ToolFence는 stdout을 MCP JSON-RPC 메시지용으로 예약합니다. 진단 및 업스트림 stderr는 stderr로 유지됩니다. 사용자별 Broker 및 승인 터미널을 별도의 터미널에서 시작하세요:

toolfence broker
toolfence approvals

wrap은 기본적으로 Broker를 사용합니다. Broker가 없거나, 호환되지 않거나, 인증되지 않았거나, 연결이 끊어졌거나, 타임아웃되면 ask 결정은 실패 시 차단됩니다. 직접 /dev/tty 승인이 필요한 경우에만 --approval tty를 사용하세요. toolfence status는 Broker 연결, 프로토콜 버전, 소켓 권한을 확인합니다.

정책

version: 1
default: ask

rules:
  - id: deny-dotenv
    effect: deny
    operations: [fs.read, fs.write]
    resources: ["**/.env", "**/.env.*"]

  - id: allow-workspace-read
    effect: allow
    operations: [fs.read]
    resources: ["${workspace}/**"]

  - id: allow-tests
    effect: allow
    operations: [shell.exec]
    commands:
      - [npm, test]

  - id: allow-git-inspection
    effect: allow
    operations: [git.read]

  - id: allow-read-api
    effect: allow
    operations: [net.request]
    hosts: ["api.example.com", "*.internal.example.com"]
    methods: [GET, HEAD]

규칙은 결정적으로 평가됩니다:

1. 일치하는 모든 deny 규칙은 다른 모든 매칭을 무시합니다. 요청된 리소스 중 하나라도 보호되는 경우, deny 리소스 규칙이 일치합니다.

2. 그렇지 않으면, 첫 번째로 일치하는 규칙이 적용됩니다.

3. 일치하는 것이 없으면 default가 사용됩니다.

allow 및 ask 리소스 규칙은 요청된 모든 리소스가 일치해야 합니다. 따라서 다중 파일 호출이 허용된 경로 하나를 사용하여 허가되지 않은 경로를 가져올 수 없습니다.

파일시스템 경로는 기존 심볼릭 링크를 포함하여 정규화된 후 매칭됩니다. 허용된 명령어에는 정확한 argv 매칭이 사용됩니다. 복합 또는 따옴표로 묶인 셸 문자열은 안전한 argv로 취급되지 않으며 기본 결정으로 대체됩니다.

지원되는 v0.2 작업은 fs.read, fs.write, fs.delete, shell.exec, git.read, git.write, git.remote, net.request, unknown입니다. 모호한 Git 명령어, 유효하지 않은 URL, 인식되지 않은 도구는 shell.exec 또는 unknown을 통해 실패 시 차단됩니다.

정책 개발

toolfence policy init [--policy ./toolfence.yaml]
toolfence policy check --policy ./examples/policy.yaml
toolfence policy explain --policy ./examples/policy.yaml --action ./action.json
toolfence policy test --policy ./examples/policy.yaml --cases ./policy-cases.yaml

init은 기존 파일을 덮어쓰지 않고 보수적인 정책을 생성합니다. check는 YAML, 엄격한 Schema 규칙, 변수, 중복 ID, 유효하지 않은 네트워크 필드 조합을 검증합니다. explain은 일치하는 규칙과 최종 결정을 출력합니다. test는 선언적 테스트 케이스를 실행하고 불일치가 있으면 0이 아닌 종료 코드를 반환합니다.

감사 로그

기본 감사 파일은 워크스페이스 아래의 .toolfence/audit.jsonl입니다. 작업 이름, 영향받은 경로, 도구 식별자, 최종 정책 결정, 업스트림 결과의 SHA-256 해시를 기록합니다. 원시 도구 인자, 명령어 인자, 원시 결과는 의도적으로 생략하여 비밀 유출을 줄입니다.

--audit /path/to/audit.jsonl을 사용하여 다른 경로를 선택할 수 있습니다.

보안 경계

ToolFence v0.2는 이 프록시를 통해 도구 호출이 이루어질 때 우발적이거나 프롬프트 인젝션을 통한 도구 오용을 줄입니다. 업스트림 서버 프로세스가 파일, 환경 변수, 네트워크를 직접 읽는 것을 막지 않습니다. 프로세스 격리, 환경 필터링, 네트워크 제어는 이후 샌드박스 단계에 속합니다.

추가적인 현재 제한 사항:

• stdio 전송만 지원

• 로컬 Broker 지원은 POSIX 전용; Windows는 비대화형이며 실패 시 차단

• JSON-RPC 배치 메시지는 거부됨

• 출력 비밀 편집 기능은 아직 없음; 원시 결과가 그대로 전달됨

• HTTP MCP 어댑터는 리디렉션 대상을 (예: redirectUrl로) 노출해야 ToolFence가 다시 평가할 수 있음

개발

아키텍처, 위협 모델, 보안 불변 조건, v0.2 구현 계획은 개발 가이드에 유지 관리됩니다.

npm run typecheck
npm test
npm run build
npm pack --dry-run
npm audit --omit=dev

전체 검증 전략은 TESTING.md에 있으며, 릴리스/보안 검토 기록은 REVIEW.md에 있습니다. 기여, 취약점 보고, 릴리스 게시 전에 CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, RELEASING.md를 참조하세요.

라이선스

MIT