업데이트로 돌아가기
New releaseSep 12, 2026

sandbox-runtime v0.0.76

컨테이너 없이 OS 수준에서 임의의 프로세스에 대한 파일시스템 및 네트워크 제한을 적용하는 경량 샌드박싱 도구입니다.

공유

Anthropic Sandbox Runtime (srt)

컨테이너 없이 OS 수준에서 임의의 프로세스에 파일 시스템 및 네트워크 제한을 적용하기 위한 경량 샌드박싱 도구입니다.

srt는 네이티브 OS 샌드박싱 프리미티브(macOS에서는 sandbox-exec, Linux에서는 bubblewrap)와 프록시 기반 네트워크 필터링을 사용합니다. 에이전트, 로컬 MCP 서버, bash 명령 및 임의의 프로세스의 동작을 샌드박싱하는 데 사용할 수 있습니다.

베타 리서치 프리뷰

Sandbox Runtime은 더 안전한 AI 에이전트를 구현하기 위해 Claude Code용으로 개발된 리서치 프리뷰입니다. 더 광범위한 생태계가 보다 안전한 에이전틱 시스템을 구축할 수 있도록 돕기 위해 초기 오픈 소스 프리뷰로 공개되었습니다. 초기 리서치 프리뷰인 만큼 API와 구성 형식은 변경될 수 있습니다. AI 에이전트를 기본적으로 더 안전하게 만들기 위한 피드백과 기여를 환영합니다!

설치

npm install -g @anthropic-ai/sandbox-runtime

기본 사용법

# Network restrictions
$ srt "curl anthropic.com"
Running: curl anthropic.com
<html>...</html>  # Request succeeds

$ srt "curl example.com"
Running: curl example.com
Connection blocked by network allowlist  # Request blocked

# Filesystem restrictions
$ srt "cat README.md"
Running: cat README.md
# Anthropic Sandb...  # Current directory access allowed

$ srt "cat ~/.ssh/id_rsa"
Running: cat ~/.ssh/id_rsa
cat: /Users/ollie/.ssh/id_rsa: Operation not permitted  # Specific file blocked

개요

이 패키지는 CLI 도구와 라이브러리로 모두 사용할 수 있는 독립형 샌드박스 구현을 제공합니다. 일반적인 개발자 사용 사례에 맞춘 기본적으로 안전한(secure-by-default) 철학을 바탕으로 설계되었습니다. 프로세스는 최소한의 접근 권한으로 시작하며, 필요한 부분만 명시적으로 열어줍니다.

주요 기능:

  • 네트워크 제한: HTTP/HTTPS 및 기타 프로토콜을 통해 접근할 수 있는 호스트/도메인 제어
  • 파일시스템 제한: 읽기/쓰기가 가능한 파일/디렉터리 제어
  • Unix 소켓 제한: 로컬 IPC 소켓에 대한 접근 제어
  • 위반 모니터링: macOS에서 시스템의 샌드박스 위반 로그 저장소에 연결하여 실시간 알림 제공

사용 사례 예시: MCP 서버 샌드박싱

주요 사용 사례 중 하나는 Model Context Protocol(MCP) 서버를 샌드박싱하여 해당 서버의 기능을 제한하는 것입니다. 예를 들어, 파일시스템 MCP 서버를 샌드박싱하려면 다음과 같이 합니다:

샌드박싱 없이 (.mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

샌드박싱 사용 시 (.mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "srt",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

그런 다음 ~/.srt-settings.json에서 제한 사항을 구성합니다:

{
  "filesystem": {
    "denyRead": [],
    "allowWrite": ["."],
    "denyWrite": ["~/sensitive-folder"]
  },
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  }
}

이제 MCP 서버는 거부된 경로에 쓰기가 차단됩니다:

> Write a file to ~/sensitive-folder
✗ Error: EPERM: operation not permitted, open '/Users/ollie/sensitive-folder/test.txt'

작동 방식

샌드박스는 OS 수준의 기본 요소를 사용하여 전체 프로세스 트리에 적용되는 제한을 시행합니다:

  • macOS: 동적으로 생성된 Seatbelt 프로필과 함께 sandbox-exec를 사용합니다
  • Linux: 네트워크 네임스페이스 격리를 갖춘 컨테이너화를 위해 bubblewrap을 사용합니다
  • Windows: 전용 srt-sandbox 로컬 사용자 계정으로 샌드박스된 프로세스를 실행하며, 해당 계정의 SID를 키로 하는 Windows Filtering Platform 이그레스 펜스, 쓰기 제한 토큰, 그리고 작업 트리에 대한 명시적 ACE를 사용합니다

0d1c612947c798aef48e6ab4beb7e8544da9d41a-4096x2305

이중 격리 모델

효과적인 샌드박싱을 위해서는 파일 시스템 격리와 네트워크 격리 모두 필요합니다. 파일 격리가 없으면 침해된 프로세스가 SSH 키나 기타 민감한 파일을 유출할 수 있습니다. 네트워크 격리가 없으면 프로세스가 샌드박스를 탈출하여 무제한 네트워크 액세스를 얻을 수 있습니다.

파일 시스템 격리는 읽기 및 쓰기 제한을 시행합니다:

  • 읽기 (거부 후 허용 패턴): 기본적으로 읽기 액세스는 모든 곳에서 허용됩니다. 넓은 영역(예: /Users)을 거부한 다음 그 안의 특정 경로(예: .)를 다시 허용할 수 있습니다. allowRead는 denyRead보다 우선합니다 — 이는 denyWrite가 allowWrite보다 우선하는 쓰기와는 반대입니다. allowRead 영역 내부에 있으면서 그보다 더 구체적인 denyRead 항목(예: allowRead: ["."]와 함께 denyRead: ["**/.env"] 또는 ["./secrets"])은 여전히 거부된 상태로 유지됩니다.
  • 쓰기 (허용 전용 패턴): 기본적으로 쓰기 액세스는 모든 곳에서 거부됩니다. 경로(예: ., /tmp)를 명시적으로 허용해야 합니다. 빈 허용 목록은 쓰기 액세스가 없음을 의미합니다.

네트워크 격리 (허용 전용 패턴): 기본적으로 모든 네트워크 액세스는 거부됩니다. 도메인을 명시적으로 허용해야 합니다. 빈 allowedDomains 목록은 네트워크 액세스가 없음을 의미합니다. 네트워크 트래픽은 호스트에서 실행되는 프록시 서버를 통해 라우팅됩니다:

  • Linux: 요청은 Unix 도메인 소켓을 통해 파일 시스템을 경유하여 라우팅됩니다. 샌드박스된 프로세스의 네트워크 네임스페이스가 완전히 제거되므로, 모든 네트워크 트래픽은 호스트에서 실행되는 프록시(샌드박스에 바인드 마운트된 Unix 소켓에서 수신)를 통해야 합니다

  • macOS: Seatbelt 프로필은 특정 localhost 포트로의 통신만 허용합니다. 프록시가 이 포트에서 수신하여 모든 네트워크 액세스를 위한 제어된 채널을 만듭니다

  • Windows: 머신 전체 WFP 필터 세트가 srt-sandbox 계정으로 실행되는 프로세스가 만드는 아웃바운드 연결을 차단하며, 프록시 포트 범위로의 루프백은 예외입니다. 프록시는 해당 범위 내에서 수신하여 모든 네트워크 액세스를 위한 제어된 채널을 만듭니다. 이 필터는 소켓을 생성하기 전에 스레드에 다른 토큰을 설정하는 샌드박스된 프로세스를 따르지 않으며, 시스템 서비스가 대신 전달하는 트래픽도 따르지 않습니다. Windows 알려진 제한 사항을 참조하십시오

HTTP/HTTPS(HTTP 프록시 경유)와 기타 TCP 트래픽(SOCKS5 프록시 경유) 모두 이러한 프록시에 의해 중개되며, 프록시는 도메인 허용 목록과 거부 목록을 시행합니다.

Claude Code의 샌드박싱에 대한 자세한 내용은 다음을 참조하십시오:

아키텍처

src/
├── index.ts                  # Library exports
├── cli.ts                    # CLI entrypoint (srt command)
├── utils/                    # Shared utilities
│   ├── debug.ts             # Debug logging
│   ├── settings.ts          # Settings reader (permissions + sandbox config)
│   ├── platform.ts          # Platform detection
│   └── exec.ts              # Command execution utilities
└── sandbox/                  # Sandbox implementation
    ├── sandbox-manager.ts    # Main sandbox manager
    ├── sandbox-schemas.ts    # Zod schemas for validation
    ├── sandbox-violation-store.ts # Violation tracking
    ├── sandbox-utils.ts      # Shared sandbox utilities
    ├── http-proxy.ts         # HTTP/HTTPS proxy for network filtering
    ├── socks-proxy.ts        # SOCKS5 proxy for network filtering
    ├── linux-sandbox-utils.ts # Linux bubblewrap sandboxing
    ├── macos-sandbox-utils.ts # macOS sandbox-exec sandboxing
    └── windows-sandbox-utils.ts # Windows srt-win sandboxing

사용법

CLI 도구로 사용하기

srt 명령(Anthropic Sandbox Runtime)은 모든 명령을 보안 경계로 감쌉니다:

# Run a command in the sandbox
srt echo "hello world"

# With debug logging
srt --debug curl https://example.com

# Specify custom settings file
srt --settings /path/to/srt-settings.json npm install

설정 파일은 선택 사항입니다 — ~/.srt-settings.json에 파일이 없으면 srt는 내장 기본값으로 실행됩니다: 네트워크 접근 없음, 기본 쓰기 경로 외부에 쓰기 없음, 읽기는 제한 없음. 파일이 있지만 비어 있거나, 읽을 수 없거나, 검증을 통과하지 못하면 오류입니다: srt는 그렇게 알리고 기본값으로 폴백하지 않고 종료합니다. 기본값은 더 약한 설정이 아니라 다른 설정이기 때문입니다 — 폴백하면 파일의 denyRead, allowRead 및 자격 증명 규칙을 비롯해 파일이 지정한 모든 것이 사라집니다. --settings로 지정한 파일도 마찬가지이며, 이 파일 역시 존재해야 합니다.

명령 실행 중 설정 업데이트: --control-fd

--control-fd <fd>는 호출자가 이미 열어 둔 디스크립터에서 설정 업데이트를 읽으며, 설정 파일과 같은 형태의 JSON 객체를 한 줄에 하나씩 읽습니다. 각 줄은 전체 설정을 대체하며 동일한 스키마로 검증되므로, 한 줄은 패치가 아니라 완전한 설정입니다: network와 filesystem은 필수이며, 줄에서 생략된 키는 기본값으로 돌아갑니다.

# fd 3 is the read end of a pipe the caller writes lines to
srt --control-fd 3 -- npm test

실행 중인 명령에 대해 허용된 라인이 적용되면 바뀌는 사항:

  • 네트워크 목록 — network.allowedDomains, deniedDomains(deniedDomainReasons 포함) 및 deniedResolvedAddresses — 은 모든 플랫폼에서 다음 연결 시점에 적용됩니다. 프록시는 요청마다 이 목록을 참조하며, 확인된 주소 검사도 같은 라인에서 다시 구성됩니다. 요청마다 읽는 network.mitmProxy와 network.tlsTerminate.excludeDomains도 마찬가지입니다.
  • credentials.sigv4는 srt가 credentials 블록과 함께 시작된 경우 다음 요청 시점에 적용됩니다. 서명 훅은 그때만 설치되며, 정책을 캡처하지 않고 요청마다 읽습니다.
  • 그 외에는 아무것도 바뀌지 않습니다. 파일시스템 규칙은 이미 seatbelt 프로필, bubblewrap argv 또는 Windows ACE에 반영되어 있고, 자격 증명 마스크는 명령이 래핑될 때 만들어졌으며, 실행 중인 프록시 서버는 시작 시점에 network.parentProxy와 TLS 종료 여부를 캡처했습니다.
  • Windows에서 srt는 파일 접근 집합(filesystem.*과 credentials.files를 합친 것)이 시작 시 적용된 집합과 다른 라인을 감지하고, SRT_DEBUG에서만 이를 알립니다. ACL 부여는 세션 전체에 적용되므로 시작 시 적용된 집합이 계속 유효합니다. 라인의 나머지 부분은 위와 같이 적용됩니다.

srt가 채널을 읽는 방식과 거부하는 대상:

더 읽기

카테고리

Defensive ToolsContainer SecurityDynamic Analysis (Sandboxing)Configuration AuditingSecurity VirtualizationNetwork SecurityIncident Response