Local 정책

Local 정책 (Local policy)

sbx policy 명령으로 여러분 머신의 로컬 정책을 관리하는 방법을 차근차근 살펴볼게요. 로컬 정책에는 네트워크 접근 규칙이 들어 있어요.

출처: 문서

본문

sbx policy 명령은 여러분 머신의 로컬 정책을 관리해요. 로컬 정책에는 네트워크 접근 규칙이 들어 있어요. 전역 스코프를 사용하면 규칙이 머신의 모든 샌드박스에 적용되고, 이름으로 스코프를 지정하면 단일 샌드박스에만 적용돼요.

로컬 정책은 organization 거버넌스와 다음과 같이 상호작용해요:

• 조직 거버넌스 없음: 로컬 정책이 샌드박스가 접근할 수 있는 대상을 제어해요.
• 조직 거버넌스 활성화: organization의 allow 규칙만 접근을 허용하므로, 로컬 allow 규칙은 비활성화되어 조직이 허용하는 범위를 넓힐 수 없어요. 로컬 deny 규칙은 여전히 평가되므로 조직 정책보다 더 제한적으로 만들 수 있어요. 비활성 규칙을 보려면 sbx policy ls --include-inactive를 실행하세요. Monitoring(모니터링)을 참고하세요.

organization 거버넌스가 어떻게 동작하는지는 Organization 정책을 참고하세요.

도메인 패턴, 와일드카드, CIDR 범위, 파일시스템 경로 문법은 Policy 개념을 참고하세요.

기본 프리셋 (Default preset)

아웃바운드 TCP 트래픽은 호스트의 프록시를 통과하며, 이 프록시가 모든 연결에 접근 규칙을 적용해요. SSH를 포함한 비-HTTP TCP 트래픽은 호스트네임 규칙(예: sbx policy allow network "myhost:22")이나 주소 기반 규칙으로 허용할 수 있어요. UDP는 실험적 기능과 아웃바운드 UDP 허용에서 설명하는 정책 규칙이 필요해요. ICMP는 차단돼요.

기본 프리셋을 선택하지 않았다면, CLI가 샌드박스를 실행하기 전에 선택하라고 물어봐요. sbx policy reset을 실행하면 프리셋을 지우고 다시 선택하라는 안내가 나와요:

Initialize the global network policy for your sandboxes:

  Applies to all sandboxes, current and future — change it later with
  "sbx policy allow/deny/rm". Kits, including built-in agent kits, may
  also add per-sandbox rules.

     1. Open         — All network traffic allowed, no restrictions.
  ❯  2. Balanced     — Default deny, with common dev sites allowed.
     3. Locked Down  — All network traffic blocked unless you allow it.

  Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel.

프리셋	설명
Open	모든 아웃바운드 TCP 트래픽을 허용해요. sbx policy allow network "**"로 와일드카드 allow 규칙을 추가한 것과 동일해요.
Balanced	기본적으로 차단(deny)하되, AI 제공자 API, 패키지 매니저, 코드 호스트, 컨테이너 레지스트리, 일반적인 클라우드 서비스를 포함한 기본 allowlist를 제공해요.
Locked Down	기본 allow 규칙이 없어요. 대상은 사용자나 kit의 allow 규칙이 있어야 해요.

프리셋은 전역 정책을 초기화해요. 내장 에이전트 kit와 다른 kit는 Locked Down(deny-all)에서도 샌드박스별 allow 규칙을 추가할 수 있어요. 프리셋은 그 허용들을 덮어쓰는 명시적 deny 규칙이 아니에요. kit가 샌드박스에 추가한 규칙을 확인하려면 다음을 실행하세요:

$ sbx policy ls my-sandbox --source kit --type network --wide

kit가 허용한 대상을 차단하려면 명시적 deny 규칙을 추가하세요:

$ sbx policy deny network --sandbox my-sandbox openrouter.ai

deny 규칙은 allow 규칙보다 우선해요. Policy 우선순위를 참고하세요.

Balanced 프리셋의 기본 allowlist는 대부분의 워크플로우에 좋은 출발점이에요. sbx policy ls를 실행하면 정확히 어떤 규칙이 포함되는지 볼 수 있어요. v0.35.0부터 Balanced 프리셋은 VS Code 도메인, Azure Blob Storage(*.blob.core.windows.net), dhi.io(HTTP)도 허용해요.

[!NOTE] 조직이 샌드박스 정책을 중앙에서 관리한다면, 여기서 선택한 프리셋보다 organization 규칙이 우선해요. Organization 정책을 참고하세요.

비대화형 환경 (Non-interactive environments)

CI 파이프라인이나 헤드리스 서버 같은 비대화형 환경에서는 대화형 프롬프트를 표시할 수 없어요. 다른 sbx 명령을 실행하기 전에 sbx policy init으로 프리셋을 설정하세요:

$ sbx policy init balanced

사용 가능한 값은 allow-all, balanced, deny-all이에요.

규칙 관리 (Managing rules)

규칙은 대상 호스트를 다뤄요. 호스트의 일부로 매칭 범위를 좁히기 위해 HTTP 메서드와 경로를 지정할 수도 있어요.

네트워크 규칙

활성 프리셋 위에 접근을 추가하거나 제한하려면 sbx policy allow와 sbx policy deny를 사용하세요. 변경 사항은 즉시 적용돼요. 규칙은 기본적으로 모든 샌드박스에 적용돼요:

$ sbx policy allow network api.anthropic.com
$ sbx policy deny network ads.example.com

규칙을 한 샌드박스로 한정하려면 --sandbox <name>을 전달하세요:

$ sbx policy allow network --sandbox my-sandbox api.example.com
$ sbx policy deny network --sandbox my-sandbox ads.example.com

v0.38.0부터는 sbx create나 sbx run에서 --deny-network를 사용해 생성 시점에 샌드박스별 deny 규칙을 설정할 수도 있어요 (이후에 추가하는 대신):

$ sbx create --deny-network ads.example.com claude .
$ sbx run --deny-network ads.example.com claude

이 방식으로 호스트를 여러 개 차단하려면 플래그를 여러 번 전달하세요. 이렇게 추가된 규칙은 sbx policy ls <name>에 나타나며, sbx policy rm network --sandbox <name> --resource <host>로 제거할 수 있어요.

여러 호스트를 한 명령에서 지정하려면 쉼표로 구분된 목록을 쓰세요:

$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org"

리소스 또는 규칙 ID로 규칙을 제거하세요:

$ sbx policy rm network --resource ads.example.com
$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67

샌드박스 스코프 규칙을 제거하려면 --sandbox <name>을 전달하세요:

$ sbx policy rm network --sandbox my-sandbox --resource api.example.com

HTTP 메서드 및 경로 규칙

allow 또는 deny 규칙에 --method를 추가하면 호스트의 특정 HTTP 메서드를 매칭하고, --path로 호스트의 URL 공간 일부로 제한할 수 있어요:

$ sbx policy allow network api.github.com --method GET --path '/repos/org/project/**'

셸이 와일드카드를 펼치지 않도록 경로를 따옴표로 감싸세요. 여러 메서드는 쉼표로 구분된 목록으로 전달할 수 있어요:

$ sbx policy allow network api.github.com --method GET,HEAD

--method ANY는 모든 HTTP 메서드를 매칭하고, --path를 생략하면 기본값은 /**예요:

$ sbx policy allow network api.github.com --method ANY

ANY는 특정 메서드와 함께 쓸 수 없고, 메서드 없는 경로는 거부돼요. 메서드를 전달하거나, 모든 메서드를 뜻할 때는 ANY를 쓰세요.

메서드 이름은 대소문자를 구분하지 않아요. 허용되는 값은 GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, CONNECT, TRACE예요.

경로는 /로 시작해야 하고 정규화(canonical)되어야 해요. 쿼리 문자열, 프래그먼트, 퍼센트 인코딩, 제어 문자, 주변 공백, 반복되거나 끝에 붙는 슬래시, .이나 .. 같은 점 세그먼트를 포함할 수 없어요. 각 규칙은 경로 하나를 받아요.

호스트는 네트워크 규칙과 같은 패턴을 따르며 포트를 포함할 수 있어요. 스킴 없이 호스트만 쓰세요. 그래야 HTTP 규칙이 https://api.example.com이 아니라 api.example.com을 받아요.

Local HTTP 규칙은 호스트네임을 받아요. IP 주소나 CIDR 범위를 매칭하려면 그 대상에 대해 일반 네트워크 규칙을 추가하세요.

deny 규칙도 같은 플래그를 받는데, 보다 넓은 allow에서 메서드나 경로를 잘라내는 일반적인 방법이에요:

$ sbx policy allow network api.example.com
$ sbx policy deny network api.example.com --method POST --path '/admin/**'

두 계층이 어떻게 결합되는지는 HTTP 규칙을 참고하세요.

HTTP 규칙을 제거할 때는 추가할 때 썼던 것과 같은 한정자(qualifier)를 지정하거나 규칙 ID로 제거하세요:

$ sbx policy rm network --resource api.github.com --method GET --path '/repos/org/project/**'
$ sbx policy rm network --id 7f3a1c2e-4a73-4e05-bc9d-f2f9a4b50d67

HTTP 규칙은 --type http로 나열하거나, 넓은 목록에서 네트워크 규칙과 함께 볼 수 있어요. 전체 호스트를 매칭하는 규칙의 METHOD와 PATH 열은 비어 있어요:

$ sbx policy ls --wide
TYPE      METHOD   PATH
network   -        -
http      GET      /repos/org/project/**

[!NOTE] sbx policy check network와 sbx policy log는 HTTP 메서드와 경로를 평가하거나 표시하지 않아요. check는 호스트에 대한 결정을 보고하는데, 이는 해당 호스트의 특정 메서드·경로에 대한 결정과 다를 수 있어요.

규칙 조사 (Inspecting rules)

어떤 정책이 활성 상태이고 어디서 왔는지 확인하려면 sbx policy ls를 사용하세요. --source로 출처(local, org, kit)를, --decision으로 결과(allow, deny)를 필터링하고, --wide로 규칙 ID를 포함한 규칙 수준 상세를 볼 수 있어요. 단일 정책이나 규칙을 전체로 보려면 sbx policy inspect를 사용하세요. Monitoring(모니터링)을 참고하세요.

아웃바운드 UDP 허용 (Allow outbound UDP)

아웃바운드 UDP는 실험적이며 기본적으로 비활성화돼 있어요. UDP allow 규칙을 추가하기 전에 실험적 기능과 UDP 이그레스를 켜세요:

$ sbx settings set platform.allowExperimentalFeatures true
$ sbx settings set feature.udp-egress true
$ sbx policy allow network --protocol udp api.example.com:443

Local allow 규칙은 기본적으로 TCP에 적용돼요. UDP는 --protocol udp, 둘 다는 --protocol tcp,udp를 사용하세요. deny 규칙은 기본적으로 두 프로토콜 모두에 적용돼요. --protocol로 deny 규칙을 한 프로토콜로 제한할 수 있어요.

UDP는 TCP와 동일한 organization 및 local 정책 우선순위를 따르고, 대상이 HTTP, SOCKS5, system, PAC 선택 프록시를 요구할 때는 거부돼요. 이 프록시들은 UDP를 전달할 수 없기 때문이에요. ICMP는 계속 차단돼요.

UDP 규칙을 조사하거나 대상을 확인하려면:

$ sbx policy ls --protocol udp
$ sbx policy check network --protocol udp api.example.com:443

UDP 이그레스가 비활성화된 상태에서 UDP 규칙을 저장하면 CLI가 경고해요.

정책 테스트 (Testing policy)

샌드박스를 실행하기 전에 현재 정책이 네트워크 요청을 허용할지 sbx policy check network로 확인할 수 있어요:

$ sbx policy check network api.anthropic.com
Allowed: api.anthropic.com

$ sbx policy check network blocked.example.com
Denied: blocked.example.com

대상은 호스트네임, host:port 쌍, IP 주소, URL일 수 있어요. 호스트네임과 IP 주소는 포트 443 기준으로 평가돼요. 이는 사용자 정의 규칙을 확인하거나, 에이전트를 시작하기 전에 Locked Down 프리셋이 무엇을 차단하는지 확인하는 데 유용해요.

특정 샌드박스 맥락에서 정책을 확인하려면:

$ sbx policy check network --sandbox my-sandbox api.example.com

리셋 (Resetting)

모든 사용자 정의 규칙을 제거하고 새 프리셋으로 시작하려면 sbx policy reset을 사용하세요:

$ sbx policy reset

이 명령은 로컬 정책 저장소를 삭제하고, 데몬을 재시작하며, 새 프리셋을 선택하라고 안내해요. 데몬이 종료되면 실행 중이던 샌드박스도 멈춰요. 확인 프롬프트를 건너뛰려면 --force를 전달하세요:

$ sbx policy reset --force

문제 해결 (Troubleshooting)

로컬 allow 규칙이 효과가 없음

sbx policy allow로 추가한 규칙이 샌드박스 동작을 바꾸지 않는다면, 조직에 거버넌스가 활성화되어 있을 가능성이 높아요. sbx policy ls로 확인하세요: 출력이 Governance: 상태 줄로 시작하고 Managed by <org>를 보여주면 조직 거버넌스가 활성화된 거예요. 이 경우 로컬 allow 규칙은 비활성화돼요. 로컬 allow 규칙으로 조직 정책이 부과한 제한을 느슨하게 만들 수 없어요.

비활성 allow 규칙은 sbx policy ls에서 기본적으로 숨겨져요. sbx policy ls --include-inactive를 실행하면 STATUS 열에 inactive 상태로 보여요.

조직 거버넌스가 활성화되면 organization의 allow 규칙만 접근을 허용해요. 추가 리소스에 접근해야 한다면 관리자에게 organization 정책 업데이트를 요청하세요. 로컬 deny 규칙은 여전히 활성이므로 sbx policy deny로 더 제한할 수 있어요.

allow 규칙을 추가했는데도 도메인이 여전히 차단됨

로컬 allow 규칙을 추가했는데도 도메인이 차단된 채라면, 조직이 거버넌스를 시행 중일 가능성이 높아요. 이 경우 로컬 allow 규칙이 비활성화돼요. sbx policy ls로 조직 거버넌스가 활성인지 확인하세요. 출력이 Governance: 상태 줄로 시작하고 Managed by <org>를 보여주면 활성인 거예요. --include-inactive를 추가하면 규칙이 inactive 상태를 보이는지 확인할 수 있어요. 그렇다면 Docker Home에서 조직 정책을 업데이트하거나 API를 통해야만 차단을 풀 수 있어요.

허용된 호스트에서 특정 HTTP 메서드나 경로가 차단됨

네트워크 규칙이 허용한 호스트라도 HTTP 규칙이 개별 메서드나 경로를 차단할 수 있어요. sbx policy ls --type http로 어떤 HTTP 규칙이 적용되는지 확인하세요. sbx policy check network는 호스트에 대한 결정만 보고하므로, 특정 요청이 거부되더라도 호스트를 허용됨으로 표시해요. HTTP 메서드 및 경로 규칙을 참고하세요.

더 알아보기 (Learn more)