anthropic-experimental/sandbox-runtime

컨테이너를 필요로 하지 않고, OS 레벨에서 임의의 프로세스에 대해 파일 시스템 및 네트워크 제한을 강제하기 위한 경량 샌드박싱 (sandboxing) 도구입니다.

srt

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

Beta Research Preview: Sandbox Runtime은 더 안전한 AI 에이전트를 구현하기 위해 Claude Code를 위해 개발된 연구 프리뷰 (research preview)입니다. 더 넓은 생태계가 더욱 안전한 에이전트 시스템 (agentic systems)을 구축할 수 있도록 초기 오픈 소스 프리뷰로 제공됩니다. 이는 초기 연구 프리뷰이므로, API 및 구성 형식 (configuration formats)은 변경될 수 있습니다. AI 에이전트를 기본적으로 더 안전하게 만들기 위한 피드백과 기여를 환영합니다!

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

# 네트워크 제한 (Network restrictions)
$ srt "curl anthropic.com"
Running: curl anthropic.com
...

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

주요 기능:

네트워크 제한 (Network restrictions): HTTP/HTTPS 및 기타 프로토콜을 통해 액세스할 수 있는 호스트/도메인을 제어합니다.
파일 시스템 제한 (Filesystem restrictions): 읽기/쓰기가 가능한 파일/디렉토리를 제어합니다.
Unix 소켓 제한 (Unix socket restrictions): 로컬 IPC 소켓에 대한 액세스를 제어합니다.
위반 모니터링 (Violation monitoring): macOS에서 시스템의 샌드박스 위반 로그 저장소에 접속하여 실시간 알림을 제공합니다.

주요 사용 사례는 Model Context Protocol (MCP) 서버를 샌드박싱하여 그 기능을 제한하는 것입니다. 예를 들어, 파일 시스템 MCP 서버를 샌드박싱하려면:

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

{
"mcpServers": {
"filesystem": {
...

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

{
"mcpServers": {
"filesystem": {
...

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

{
"filesystem": {
"denyRead": [],
...

이제 MCP 서버는 거부된 경로에 파일을 쓰는 것이 차단됩니다:

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

샌드박스 (Sandbox)는 OS 레벨의 프리미티브 (Primitives)를 사용하여 전체 프로세스 트리 (Process tree)에 적용되는 제한 사항을 강제합니다:

macOS: 동적으로 생성된 Seatbelt 프로필을 사용하는 sandbox-exec를 사용합니다.
Linux: 네트워크 네임스페이스 격리 (Network namespace isolation)를 포함한 컨테이너화 (Containerization)를 위해 bubblewrap을 사용합니다.

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

**파일 시스템 격리 (Filesystem Isolation)**는 읽기 및 쓰기 제한을 강제합니다:

읽기 (Read) (deny-then-allow 패턴): 기본적으로 모든 곳에서 읽기 권한이 허용됩니다. 광범위한 영역(예: /Users)을 거부(deny)한 다음, 그 내부의 특정 경로(예: .)를 다시 허용(allow)할 수 있습니다. allowRead는 denyRead보다 우선순위가 높습니다. 이는 denyWrite가 allowWrite보다 우선순위가 높은 쓰기 (Write) 방식과는 반대입니다.
쓰기 (Write) (allow-only 패턴): 기본적으로 모든 곳에서 쓰기 권한이 거부됩니다. 반드시 경로(예: ., /tmp)를 명시적으로 허용해야 합니다. 허용 목록 (Allow list)이 비어 있으면 쓰기 권한이 없습니다.

네트워크 격리 (Network Isolation) (allow-only 패턴): 기본적으로 모든 네트워크 접근이 거부됩니다. 반드시 도메인 (Domains)을 명시적으로 허용해야 합니다. allowedDomains 목록이 비어 있으면 네트워크 접근이 불가능합니다. 네트워크 트래픽은 호스트에서 실행되는 프록시 서버 (Proxy servers)를 통해 라우팅됩니다:

• Linux: 요청은 Unix 도메인 소켓 (Unix domain socket)을 통해 파일 시스템을 거쳐 라우팅됩니다. 샌드박스 처리된 프로세스의 네트워크 네임스페이스 (Network namespace)가 완전히 제거되므로, 모든 네트워크 트래픽은 호스트에서 실행되는 프록시 (Proxies)를 통해 전달되어야 합니다 (이 프록시들은 샌드박스 내로 바인드 마운트 (Bind-mounted)된 Unix 소켓에서 대기합니다).
• macOS: Seatbelt 프로필을 통해 특정 localhost 포트로의 통신만 허용합니다. 프록시가 이 포트에서 대기하며, 모든 네트워크 접근을 위한 제어된 채널을 생성합니다.

HTTP/HTTPS (HTTP 프록시를 통해) 및 기타 TCP 트래픽 (SOCKS5 프록시를 통해) 모두 이러한 프록시에 의해 중재되며, 프록시는 사용자의 도메인 허용 목록 (Allowlists) 및 차단 목록 (Denylists)을 강제합니다.

Claude Code의 샌드박싱 (Sandboxing)에 대한 자세한 내용은 다음을 참조하세요:

• Claude Code Sandboxing Documentation
• Beyond Permission Prompts: Making Claude Code More Secure and Autonomous

src/
├── index.ts # Library exports
├── cli.ts # CLI entrypoint (srt command)
...

srt 명령어 (Anthropic Sandbox Runtime)는 보안 경계 (Security boundaries)를 설정하여 모든 명령어를 감쌉니다:

# 샌드박스에서 명령어 실행
srt echo "hello world"
# 디버그 로깅과 함께 실행
...

import {
SandboxManager,
type SandboxRuntimeConfig,
...

// 메인 샌드박스 매니저
export { SandboxManager } from '@anthropic-ai/sandbox-runtime'
// 위반 사항 추적
...

기본적으로 샌드박스 런타임은 ~/.srt-settings.json에서 설정을 찾습니다. --settings 플래그를 사용하여 사용자 정의 경로를 지정할 수 있습니다:

srt --settings /path/to/srt-settings.json <command>

{
"network": {
"allowedDomains": [
...

**허용 전용 패턴 (Allow-only pattern)**을 사용합니다. 즉, 모든 네트워크 접근은 기본적으로 차단됩니다.

network.allowedDomains

• 허용된 도메인 배열 (*.example.com과 같은 와일드카드 지원). 빈 배열일 경우 = 네트워크 접근 불가.

network.deniedDomains

• 차단된 도메인 배열 (가장 먼저 확인되며, allowedDomains보다 우선순위가 높음)

network.allowLocalBinding

• 로컬 포트 바인딩 허용 (boolean, 기본값: false)

Unix 소켓 설정 (플랫폼별 동작):

설정	macOS	Linux
allowUnixSockets: string[]
소켓 경로 허용 목록 (Allowlist)	무시됨 (seccomp는 경로별 필터링 불가)
allowAllUnixSockets: boolean
모든 소켓 허용	seccomp 차단 비활성화

Unix 소켓은 두 플랫폼 모두에서 **기본적으로 차단(blocked)**됩니다.

macOS: 특정 경로를 허용하려면 allowUnixSockets를 사용하고 (예: ["/var/run/docker.sock"]), 모든 소켓을 허용하려면 allowAllUnixSockets: true를 사용하세요. Linux: 차단에는 seccomp 필터가 사용됩니다 (x64/arm64 전용). seccomp를 사용할 수 없는 경우 소켓에 제한이 없으며 경고가 표시됩니다. 차단을 명시적으로 비활성화하려면 allowAllUnixSockets: true를 사용하세요.

두 가지 서로 다른 패턴을 사용합니다:

읽기 제한 (Read restrictions) (deny-then-allow 패턴) - 기본적으로 모든 읽기가 허용됩니다:

filesystem.denyRead

• 읽기 액세스를 거부할 경로 배열. 빈 배열 = 전체 읽기 액세스 허용.

filesystem.allowRead

• 거부된 영역 내에서 읽기 액세스를 다시 허용할 경로 배열 (denyRead보다 우선순위가 높음).

참고: 이는 denyWrite가 allowWrite보다 우선순위가 높은 쓰기(write) 설정과는 반대입니다.

쓰기 제한 (Write restrictions) (allow-only 패턴) - 기본적으로 모든 쓰기가 거부됩니다:

filesystem.allowWrite

• 쓰기 액세스를 허용할 경로 배열. 빈 배열 = 쓰기 액세스 불가.

filesystem.denyWrite

• 허용된 경로 내에서 쓰기 액세스를 거부할 경로 배열 (allowWrite보다 우선순위가 높음).

경로 구문 (Path Syntax) (macOS):

macOS의 경로는 .gitignore 구문과 유사한 git 스타일의 glob 패턴을 지원합니다:

*

• /를 제외한 모든 문자와 일치 (예: *.ts는 foo.ts와는 일치하지만 foo/bar.ts와는 일치하지 않음)

**

• /를 포함한 모든 문자와 일치 (예: src/**/*.ts는 src/ 내의 모든 .ts 파일과 일치)

?

• /를 제외한 임의의 단일 문자와 일치 (예: file?.txt는 file1.txt와 일치)

[abc]

• 집합 내의 임의의 문자와 일치 (예: file[0-9].txt는 file3.txt와 일치)

예시:

"allowWrite": ["src/"]

• src/ 디렉토리 전체에 대한 쓰기 허용

"allowWrite": ["src/**/*.ts"]

• src/ 내의 모든 .ts 파일에 대한 쓰기 허용

및 하위 디렉터리
"denyRead": ["~/.ssh"]

• SSH 디렉터리에 대한 읽기 거부
  "denyRead": ["/Users"], "allowRead": [."]

• /Users 전체에 대한 읽기를 거부하되, 현재 디렉터리는 다시 허용
  "denyWrite": [".env"]

• .env 파일에 대한 쓰기 거부 (현재 디렉터리가 허용되어 있더라도 적용)

경로 구문 (Linux):

Linux는 현재 glob 매칭을 지원하지 않습니다. 리터럴 경로(literal paths)만 사용하세요:

"allowWrite": ["src/"]

• src/ 디렉터리에 대한 쓰기 허용
  "denyRead": ["/home/user/.ssh"]

• SSH 디렉터리에 대한 읽기 거부
  "denyRead": ["/home"], "allowRead": [."]

• /home 전체에 대한 읽기를 거부하되, 현재 디렉터리는 다시 허용

모든 플랫폼:

• 경로는 절대 경로(예: /home/user/.ssh) 또는 현재 작업 디렉터리 기준의 상대 경로(예: ./src)를 사용할 수 있습니다. ~는 사용자의 홈 디렉터리로 확장됩니다.

ignoreViolations

• 위반 사항을 무시해야 하는 경로 배열에 명령 패턴을 매핑하는 객체 매핑

enableWeakerNestedSandbox

• Docker 환경을 위한 약한 샌드박스 (weaker sandbox) 모드 활성화 (boolean, 기본값: false)

enableWeakerNetworkIsolation

• macOS 샌드박스에서 com.apple.trustd.agent에 대한 액세스 허용 (boolean, default: false). 이는 MITM 프록시 및 사용자 정의 CA와 함께 httpProxyPort를 사용하는 Go 프로그램 (gh, gcloud, terraform, kubectl 등)이 TLS 인증서를 검증하는 데 필요합니다. 보안 경고: 이를 활성화하면 trustd 서비스를 통한 잠재적인 데이터 유출 (data exfiltration) 경로가 열립니다.

allowAppleEvents

• macOS 샌드박스에서 Apple Events 및 Launch Services open 요청 전송 허용 (boolean, default: false). 이 설정이 없으면 open, osascript 및 AppleScript를 통해 URL이나 다른 앱의 스크립트를 여는 모든 명령이 AppleScript 에러 -600 ("Application isn't running") 또는 LaunchServices 에러 (-10822, -54)와 함께 실패합니다. 보안 경고: 이를 활성화하면 샌드박스가 더 이상 코드 실행 격리 (code-execution isolation)를 제공하지 않음을 의미합니다. 샌드박스화된 명령이 open을 통해 다른 애플리케이션을 실행할 수 있습니다.

사용자 프롬프트 없이 실행되며, 실행되는 모든 것은 샌드박스의 파일 시스템 및 네트워크 제한 외부에서 작동합니다. Apple Events를 통해 이미 실행 중인 앱을 스크립팅하는 기능은 추가적으로 사용자의 앱별 TCC (Transparency, Consent, and Control) 자동화 동의에 의해 제어됩니다. 임베더(Embedders)는 이 옵션을 신뢰할 수 있는 사용자 수준의 설정에서만 가져와야 하며, 체크아웃된 저장소의 프로젝트 로컬 파일로부터 절대 가져와서는 안 됩니다. 만약 로컬 파일에서 가져올 경우, 공격자가 작성한 프로젝트가 자체 샌드박스 권한을 상승시킬 수 있습니다.

GitHub 액세스 허용 (모든 필요한 엔드포인트):

{
"network": {
"allowedDomains": [
...

특정 디렉토리로 제한:

{
"network": {
"allowedDomains": [],
...

워크스페이스 전용 파일 시스템 액세스 (워크스페이스 외부 읽기 거부):

{
"network": {
"allowedDomains": [],
...

이는 /Users (또는 Linux의 경우 /home) 하위의 모든 항목에 대한 읽기를 거부한 다음, 현재 작업 디렉토리를 다시 허용합니다. 시스템 경로 (/usr, /lib 등)는 읽기 가능한 상태로 유지됩니다.

Jest 실행: 샌드박스 위반을 피하기 위해 --no-watchman 플래그를 사용하세요:

srt "jest --no-watchman"

Watchman은 샌드박스 경계 외부의 파일에 접근하므로 권한 오류를 발생시킵니다. 이를 비활성화하면 Jest가 내장된 파일 와처 (file watcher)를 사용하여 실행될 수 있습니다.

macOS: 커스텀 프로필을 사용하는 sandbox-exec 사용 (추가 종속성 없음)
Linux: 컨테이너화 (containerization)를 위해 bubblewrap (bwrap) 사용
Windows: 아직 지원되지 않음

Linux 요구 사항:

bubblewrap

• 컨테이너 런타임 (Container runtime)
• Ubuntu/Debian: apt-get install bubblewrap
• Fedora: dnf install bubblewrap
• Arch: pacman -S bubblewrap

socat

• 프록시 브릿징을 위한 소켓 릴레이 (Socket relay)
• Ubuntu/Debian: apt-get install socat
• Fedora: dnf install socat
• Arch: pacman -S socat

ripgrep

• 거부 경로 탐지를 위한 빠른 검색 도구 (Fast search tool)
• Ubuntu/Debian: apt-get install ripgrep
• Fedora: dnf install ripgrep
• Arch: pacman -S ripgrep

Ubuntu/Debian:

Ubuntu 24.04+ 참고 사항: 이 릴리스 버전들은 kernel.apparmor_restrict_unprivileged_userns를 활성화합니다.

기본적으로 unshare(CLONE_NEWUSER)를 허용하지만, 결과적으로 생성된 네임스페이스(namespace)에서 권한(capabilities)을 제거합니다. Bubblewrap과 seccomp 격리 계층(isolation layer) 모두 권한을 보유한 사용자 네임스페이스(user namespaces)가 필요합니다. 다음 명령어로 제한을 비활성화하십시오:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

또는 관련 바이너리에 userns 권한을 부여하는 AppArmor 프로필을 추가하십시오.

선택적 Linux 의존성 (seccomp 폴백용):

이 패키지에는 x86-64 및 arm 아키텍처를 위한 사전 생성된 seccomp BPF 필터가 포함되어 있습니다. 이러한 의존성은 사전 생성된 필터를 사용할 수 없는 다른 아키텍처를 사용하는 경우에만 필요합니다:

gcc 또는 clang

• C 컴파일러

libseccomp-dev

• Seccomp 라이브러리 개발 파일

• Ubuntu/Debian:
  apt-get install gcc libseccomp-dev

• Fedora:
  dnf install gcc libseccomp-devel

• Arch:
  pacman -S gcc libseccomp

• Ubuntu/Debian:

macOS 요구 사항:

ripgrep

• 거부 경로(deny path) 탐지를 위한 빠른 검색 도구

• Homebrew를 통해 설치:
  brew install ripgrep

• 또는 다음에서 다운로드: https://github.com/BurntSushi/ripgrep/releases

• Homebrew를 통해 설치: