Policy 개념

Policy 개념 (Policy concepts)

Docker 샌드박스 거버넌스의 핵심 개념인 리소스 모델, 규칙 문법, 우선순위를 꼼꼼히 정리해 드릴게요.

출처: 문서

본문

여기서 설명하는 거버넌스는 로컬 샌드박스에 적용돼요. 클라우드 샌드박스는 별도의 네트워크 정책 구성을 사용해요. 클라우드 제어는 클라우드 네트워크 정책을 참고하세요.

리소스 모델 (Resource model)

Docker 샌드박스 거버넌스는 **정책(policy)**과 **규칙(rule)**이라는 두 가지 리소스 타입을 중심으로 구성돼요.

정책은 샌드박스 접근을 제어하는 규칙의 이름 붙은 모음이에요. 정책은 두 수준으로 존재해요:

Local: sbx policy CLI로 머신별로 구성돼요. 그 머신의 샌드박스에만 적용돼요.
Organization: Docker Home에서 구성돼요. 네트워크와 파일시스템 정책은 Governance API로도 관리할 수 있어요. 조직 전체의 샌드박스에 적용돼요. 조직은 여러 정책을 가질 수 있으며, 각 정책은 조직 전체 또는 특정 팀에 적용돼요. Policy 범위를 참고하세요.

Organization 거버넌스가 활성화되면 organization의 allow 규칙만 접근을 허용할 수 있어요. Local 및 kit 정의 deny 규칙은 여전히 위에 적용돼요. Precedence(우선순위)를 참고하세요.

규칙은 정책 내에서의 접근 제어 단위예요. 각 규칙에는 다음이 있어요:

Name: 사람이 읽을 수 있는 라벨
Actions: 규칙이 제어하는 접근 유형
Resources: 규칙이 매칭하는 대상
Decision: allow 또는 deny

규칙은 도메인별로 그룹화돼요. 정책의 네트워크 규칙과 파일시스템 규칙은 network 또는 filesystem이라는 동일한 도메인을 공유해야 해요. MCP 정책은 네트워크·파일시스템 규칙 형식 대신 MCP 네임스페이스로 작성된 Cedar 문을 사용해요.

한도 (Limits)

Organization 정책에는 공정 사용과 조직 간 리소스 가용성을 보장하는 다음 한도가 있어요:

한도	값
조직당 정책 수	100
정책당 규칙 수	250
정책 크기	400 KB 총합, 정책의 모든 규칙이 공유

일반적인 정책은 정책 크기 한도의 아주 일부만 사용해요. 도메인과 파일 경로 값에는 유효한 형식 외에 별도의 길이 한도는 없어요.

이 한도가 조직의 요구에 맞지 않으면 Docker 영업팀에 문의하여 옵션을 논의하세요.

Policy 범위 (Policy scope)

각 organization 정책은 조직 전체 또는 특정 팀에만 적용돼요:

조직 전체(Org-wide): 팀이 지정되지 않으면 정책이 조직의 모든 멤버에게 적용돼요.
팀 범위(Team-scoped): 팀이 하나 이상 지정되면 정책이 그 팀의 멤버에게만 적용돼요.

팀은 조직을 위해 관리하는 팀과 동일해요. Docker는 정책의 팀을 각 사용자의 팀 멤버십과 매칭해요. 조직이 조직 전체와 팀 범위 정책을 섞을 수 있으므로, 한 사용자가 여러 정책의 대상이 되는 경우가 흔해요. 특정 사용자에게 적용되는 정책이 그들의 _유효 정책(effective policies)_이에요: 모든 조직 전체 정책에 더해, 사용자가 속한 팀에 대한 모든 팀 범위 정책을 합친 것이에요. 사용자의 유효 정책이 어떻게 결합되는지는 규칙 평가를 참고하세요.

규칙 문법 (Rule syntax)

네트워크 규칙

네트워크 규칙은 TCP에 connect:tcp, UDP에 connect:udp를 사용해요. 리소스는 호스트네임, CIDR 범위, 또는 포트예요. UDP에는 실험적 아웃바운드 UDP가 필요해요. ICMP는 차단돼요.

호스트네임 패턴

패턴	예시	매칭
정확한 호스트네임	`example.com`	모든 포트의 `example.com`. 서브도메인은 아님
단일 수준 와일드카드	`*.example.com`	한 서브도메인 수준, 모든 포트: `api.example.com`
다중 수준 와일드카드	`**.example.com`	모든 깊이, 모든 포트: `api.example.com`, `v2.api.example.com`
포트가 있는 호스트네임	`example.com:443`	포트 443의 `example.com`만

example.com과 *.example.com은 서로를 포함하지 않아요. 루트 도메인과 서브도메인을 모두 매칭해야 한다면 둘 다 지정하세요.

CIDR 범위

IPv4와 IPv6 표기 모두 지원해요: 10.0.0.0/8, 192.168.1.0/24, 2001:db8::/32.

HTTP 메서드 및 경로

네트워크 규칙은 그 자체로 대상 호스트를 매칭해요. HTTP 규칙은 HTTP 메서드와 URL 경로도 함께 이름을 붙이는 네트워크 규칙이라, 정책이 API에 쓰기를 허용하지 않으면서 읽기를 허용할 수 있어요.

HTTP 규칙은 하나 이상의 메서드, 대상, 경로 패턴을 이름 붙여요:

부분	허용
Method	하나 이상의 HTTP 메서드, 또는 모든 메서드
Destination	선택적 포트가 있는 호스트
Path	`/api/**` 같은 절대 경로 패턴

CIDR 범위는 유효한 HTTP 대상이 아니에요. 그런 대상은 네트워크 규칙으로 다루세요.

메서드를 이름 붙이지 않은 규칙은 모든 메서드를 매칭해요. 개별적으로 선택할 수 있는 메서드는 HTTP 메서드 및 경로 규칙을 참고하세요.

경로 패턴은 파일시스템 경로와 같은 와일드카드 규칙을 따르는데, *는 한 경로 세그먼트 안에서 매칭하고 **는 모든 깊이를 매칭해요. 와일드카드 없는 패턴은 그 경로를 정확히 매칭하므로 /repos는 /repos와 그 아래는 매칭하지 않아요. 패턴은 /로 시작해야 하고 정규화되어야 해서, 쿼리 문자열, 프래그먼트, 퍼센트 인코딩, 제어 문자, 반복되거나 끝에 붙는 슬래시, .이나 .. 같은 점 세그먼트를 포함할 수 없어요.

HTTP 요청은 두 계층 모두에 대해 평가돼요. 네트워크 규칙이 호스트의 기준선을 정하고, HTTP 규칙이 그 안에서 개별 메서드와 경로를 조정해요:

호스트를 다루는 규칙	HTTP 요청의 결과
네트워크 allow만	어떤 메서드·경로에서도 허용
HTTP allow만	규칙이 메서드·경로와 매칭되는 곳에서만 허용. 나머지는 거부
네트워크 allow + HTTP deny	거부된 메서드·경로는 차단. 나머지는 계속 허용
네트워크 deny	차단. HTTP allow가 거부된 호스트를 다시 열 수 없음

따라서 네트워크 deny는 HTTP 규칙이 올릴 수 없는 바닥이고, 네트워크 allow는 HTTP 규칙이 파고들 수 있는 천장이에요.

규칙이 메서드와 경로 결정을 요구하면, 샌드박스 HTTP 프록시는 연결마다 한 번 결정하는 대신 각 요청을 개별적으로 평가해요.

그 요청들은 프록시를 통과해야 해요. 프록시가 검사할 수 없는 연결(예: 투명하게 처리하는 연결)은 평가 대신 차단돼요. SSH 같은 HTTP가 아닌 트래픽은 메서드나 경로가 없으므로 HTTP 규칙이 절대 매칭하지 않아요. 그 대상은 네트워크 규칙으로 제어하세요.

Local 및 organization 정책 구성은 네트워크 접근 정책을 참고하세요.

파일시스템 규칙

파일시스템 규칙은 read와 write 액션을 사용해요. 리소스는 샌드박스가 워크스페이스로 마운트할 수 있는 호스트 경로예요.

쓰기 접근으로 마운트된 워크스페이스는 read 규칙과 write 규칙 모두로 허용되어야 하고, 읽기 전용 워크스페이스는 read만 필요해요. 기본 차단(deny)이 마운트를 막으면, 거부 이유가 읽기 또는 쓰기 접근 중 무엇이 없었는지 이름을 붙여요.

~는 Windows(여기서는 %USERPROFILE%로 해석)를 포함한 모든 플랫폼에서 사용자의 홈 디렉터리로 확장돼요. 따라서 단일 ~/** 규칙이 macOS, Linux, Windows에서 각 사용자의 홈 트리를 매칭해요. 정책 엔진은 ~만 확장하고 환경 변수는 확장하지 않으므로, %USERPROFILE%\**나 $HOME/** 같은 패턴은 아무것도 매칭하지 않아요.

홈 디렉터리 밖의 경로는 사용자 OS가 쓰는 형식으로 작성하세요. 규칙은 작성된 형식만 매칭하므로, 여러 플랫폼이 공유하는 위치는 각각에 대한 규칙이 필요해요:

운영 체제	예시 경로
macOS, Linux	`/data/project/**`
Windows	`C:\data\project\**`
WSL	`\\wsl.localhost\<distro>\data\project\**`

Windows에서 *:는 임의의 드라이브 문자를 매칭하므로 *:\data\**는 모든 드라이브의 경로를 매칭해요.

와일드카드는 모든 경로 형식에서 동일하게 동작해요:

패턴	예시	매칭
정확한 경로	`/data`	`/data`만
세그먼트 와일드카드	`/data/*`	`/data/project`, 한 경로 세그먼트만, 하위 디렉터리는 아님
재귀 와일드카드	`/data/**`	`/data/project`, `/data/project/src`, 모든 깊이

**를 사용해 디렉터리 트리를 재귀적으로 매칭하세요. 단일 *는 한 경로 세그먼트 안에서 매칭하고 경로 구분자를 넘지 않아요. 예를 들어 ~/**는 홈 디렉터리 아래 모든 경로를 매칭하지만 ~/*는 직접 자식만 매칭해요.

Organization 정책 구성과 시행 세부 사항은 파일시스템 접근 정책을 참고하세요.

MCP 정책

MCP 정책은 Docker의 MCP 게이트웨이를 통해 샌드박스에 제공되는 Model Context Protocol 활동을 제어해요. 이들은 네트워크·파일시스템 규칙 형식이 아니라 MCP 네임스페이스를 사용해 Cedar로 작성된 organization 정책이에요.

MCP 정책은 개발자가 서버를 등록할 때와 에이전트가 MCP 게이트웨이를 사용할 때 적용돼요. 등록 규칙은 향후 sbx mcp add 작업을 제어해요. 사용 시점 규칙은 이미 등록되거나 로드된 서버에서의 도구 호출, 게이트웨이 메타 도구, 리소스 읽기, 프롬프트 조회를 제어해요.

통제 대상 MCP 활동은 기본 차단(deny)이에요: 매칭되는 permit이 허용하지 않으면 요청이 차단돼요. 매칭되는 forbid는 승인을 요구하는 permit을 포함해 어떤 permit보다 우선해요. 정책 스코프가 principal을 제공하므로, Cedar에서 사용자, 팀, 테넌트, 역할을 매칭하는 대신 organization이나 team 스코프를 사용하세요.

대표 정책은 MCP 접근 정책을, 정확한 액션·리소스·컨텍스트·승인 동작은 MCP 정책 참조를 참고하세요.

규칙 평가 (Rule evaluation)

Organization 거버넌스가 활성화되면 사용자의 모든 유효 정책의 규칙이 결합되어 각 요청에 대해 함께 평가되며, 다음 두 원칙을 따릅니다:

Deny가 이긴다(Deny wins): 어떤 규칙이 decision: deny로 매칭되면, 매칭되는 allow 규칙과 무관하게 요청이 거부돼요.
기본 차단(Default deny): allow 규칙이 매칭하지 않는 것은 모두 차단돼요. 네트워크 규칙이 대상을 허용하지 않으면 아웃바운드 네트워크 트래픽이 차단되고, 파일시스템 규칙이 허용하지 않으면 호스트 경로를 마운트할 수 없어요. MCP permit이 허용하지 않으면 MCP 활동이 차단돼요.

모든 유효 정책이 같은 평가에 들어가므로, allow는 합산적(어떤 유효 정책이 허용하면 요청이 허용)이고 deny는 절대적(어떤 유효 정책이 차단하면 요청이 차단)이에요. 따라서 조직 전체 정책의 deny 규칙은 모든 사람에게 적용되고 팀 범위 정책이 덮어쓸 수 없으며, 조직 전체 deny 규칙을 가드레일로 쓰기 좋아요.

Local 및 kit 정의 allow 규칙은 이 평가에 참여하지 않아요. 해당 출처의 deny 규칙은 여전히 적용돼요. Precedence(우선순위)를 참고하세요.

Precedence (우선순위)

무엇이 적용되는지는 조직에 거버넌스가 활성화되어 있는지에 달려 있어요:

조직 거버넌스 없음: 로컬 규칙과 kit 정의 네트워크 규칙이 샌드박스가 접근할 수 있는 대상을 결정해요.
Organization 거버넌스 활성: organization 정책이 부여할 수 있는 접근을 결정해요. organization의 allow 규칙만 접근을 허용하므로, local 및 kit 정의 allow 규칙은 비활성화되어 조직이 허용하는 범위를 넓힐 수 없어요. deny 규칙은 모든 출처에서 적용되므로, local이나 kit 정의 deny가 더 제한할 수는 있어요.

kit 정의 규칙은 kit 사양의 네트워크 정책을 참고하세요.

우선순위는 출처가 아니라 규칙의 결정(decision)으로 정해져요:

규칙	organization 거버넌스 하에서 평가됨
Organization allow	예
Organization deny	예
Local allow	아니요
Local deny	예
Kit 정의 allow	아니요
Kit 정의 deny	예

Local 및 kit 정의 규칙은 네트워크 접근만 다루므로, organization 정책 위에 겹치는 deny는 항상 네트워크 deny예요. sbx policy ls는 비활성 규칙을 기본적으로 숨겨요. 나열 방법은 Monitoring(모니터링)을 참고하세요.

Organization 거버넌스가 활성화되면 사용자의 organization 정책은 규칙 평가에서 설명한 대로 함께 평가돼요.