정책 레시피
사용자가 가장 자주 마주치는 시나리오를 위한 복사해서 붙여넣는 정책입니다. 이 페이지의 모든 레시피는 다음을 따릅니다:
- 쉬운 말로 쓴 한 문단짜리 문제 설명으로 시작합니다.
- 대시보드나 로컬
controlzero.yaml에 바로 넣을 수 있는, 주석이 달린 완전한policy.yaml을 제공합니다. - 무엇이 차단되고 무엇이 허용되는지를 각 경우의 추출된 액션과
reason_code와 함께 정확히 나열합니다. - 픽스처 기반 적용 레시피에는 CI에서 실행되는 기계 판독용
scenarios.json파일이 포함되며, 단계별 안내만 있는 레시피에는 없을 수 있습니다.
Claude Code, Gemini CLI, Cursor IDE, Kiro CLI에서 적용 이벤트의 거부는 도구 호출이 실행되기 전에 중지시킵니다.
영어 원문 -- 번역은 기술 검토 대기 중입니다
Coverage is declared per event, not per host, so an enforcing event never implies protection for another event the vendor does not expose.
기능 매트릭스는 코드에 있는 어댑터의 기능 선언에서 도출됩니다. 설치 환경의 선언을 내보내려면
controlzero coverage --json을 실행하세요(옵션 없는 controlzero coverage는 호스트별
짧은 요약만 출력합니다).
영어 원문 -- 번역은 기술 검토 대기 중입니다
The enforcement path fails closed by default when it cannot establish coverage. Signed policy bundles make policy tampering detectable, and the audit trail distinguishes a control that did not run from one that ran and found nothing. For modify-and-proceed DLP, the Python SDK masks matching secrets in place on Claude Code and Gemini CLI and returns the redacted arguments for forwarding.
처음이신가요? 읽기 전용 데이터베이스부터 시작하세요 -- 대표적인 예시이며 대부분의 고객이 가장 먼저 연결하는 레시피입니다.
제공되는 레시피
| # | 레시피 | 해결하는 문제 |
|---|---|---|
| 1 | Read-only database | Agent can SELECT but never DROP. Piggyback-proof. |
| 2 | Block secrets and PII egress | LLM calls allowed, but API keys / SSNs / cards never leave. |
| 3 | 개발은 경고, 프로덕션은 거부 | 하나의 정책, 두 가지 운영 방식: 개발에서는 소프트, 프로덕션에서는 하드. |
| 4 | LLM model allow-list | Only the models you have vetted can be called. |
| 5 | 범위가 제한된 파일 접근 | 저장소와 /tmp는 읽기/쓰기를 허용하고 SSH 키, AWS 자격 증명, /etc는 거부합니다. |
| 6 | Block outbound network | Stop curl / wget / ssh / nc from exfiltrating data. |
| 7 | Multi-tenant isolation | Team A agents never touch Team B resources. |
| 8 | Tamper response | Four postures when the bundle is altered: warn, deny, deny-all, quarantine. |
| 9 | Deny-list: block the dangerous few | Let the agent work freely; hard-block only rm, DROP, disk wipes, and SSH-key writes. |
| 10 | Approval (HITL) for destructive actions | Green-light rm / DROP / TRUNCATE / DELETE / GRANT / REVOKE before they run; fail closed otherwise. |
| 15 | 프롬프트 수준 PII 가림 처리 | Python SDK 전용이며, 지원되는 코딩 호스트는 Claude Code와 Gemini CLI입니다. |
COMING SOON
레시피 네 개는 개발 중이거나 문서화가 필요한 기능에 의존하고 있어 보류 중입니다. 우선
처리를 원하시면 TODO-RECIPE-NN 태그와 함께 지원팀에 문의하세요.
| # | 레시피 | 보류 사유 | 추적 |
|---|---|---|---|
| 11 | 시간대별 접근 | 시간 및 주체 일치를 위한 조건 DSL | TODO-RECIPE-11 |
| 12 | 반복 거부 시 알림 | 알림 규칙 빌더 (신규 기능) | TODO-RECIPE-12 |
| 13 | Git 브랜치 범위 작업 | 셸 추출기 (T4 -- 사양 반영 완료, SDK 사본 개발 중) | TODO-RECIPE-13 |
| 14 | 조직별 속도 제한 | 기능은 있으나 문서화와 조건 DSL 필요 | TODO-RECIPE-14 |
레시피 형식
모든 레시피 페이지는 빠르게 훑어볼 수 있도록 같은 템플릿을 따릅니다:
- 문제 -- 사용자의 말투로 쓴 한 문단.
- 정책 -- 복사해서 붙여넣을 수 있는 전체 YAML.
- 작동 원리 -- 어떤 추출기가 실행되고, 어떤 규칙이 일치하며, 어떤 결정이 내려지는지.
- 차단되는 항목 -- 추출된 액션, 결정,
reason_code가 있는 표. - 허용되는 항목 -- 추출된 액션, 결정,
reason_code가 있는 표. - 직접 테스트하기 -- 문서화된 시나리오에 대한
controlzero test실행 예와, 가능한 경우 위 표를 뒷받침하는 픽스처. - 주의 사항 -- 레시피가 다루지 않는 범위. 빈틈을 솔직히 밝히므로 두 번째 레시피나 도구 계층 통제와 함께 사용할 수 있습니다.
- 관련 레시피 -- 다음으로 필요할 가능성이 높은 두세 개.
테스트 픽스처의 작동 방식
docs-site/docs/recipes/ 아래의 픽스처 기반 적용 레시피는 메인 저장소의
tests/fixtures/enforcement-spec/recipes/{recipe-name}/에 대응하는 디렉터리를
가집니다:
policy.yaml-- 레시피에 표시된 YAML과 바이트 단위로 동일합니다.scenarios.json-- 레시피마다 최소 하나의 허용, 하나의 거부, 하나의 우회 시도, 하나의 "기본값으로 넘어가는" 경우를 다루는{input, expected}케이스 배열입니다.
tests/fixtures/enforcement-spec/recipes/test_recipes.py의 드라이버가 CI를 실행할
때마다 모든 레시피 디렉터리를 순회하며 결정 + reason_code + 추출된 메서드가
기대값과 일치하는지 검증합니다. 레시피 페이지가 코드의 실제 동작과 모순되면 CI가
실패합니다.
레시피 추가하기
레시피는 단순한 문서 페이지가 아니라 제품에 대한 진술입니다. 작성하기 전에 다음을 확인하세요:
- 최소 세 곳의 고객이 문의한 문제인가?
- 제품이 오늘 실제로 이를 적용할 수 있는가?
- 80%의 경우에 맞는 하나의 정책이 있고, 나머지 20%에 대한 주의 사항이 명시되어 있는가?
세 질문 모두 "예"라면 위 형식을 따라 같은 PR에 마크다운 파일과 픽스처 디렉터리를 모두 추가하세요. 나머지는 CI 드라이버가 처리합니다.
질문 2의 답이 "아직 아니오"라면 지원팀에 문의하여 로드맵 팀이 격차를 등록하도록 하고,
위의 "COMING SOON" 표에 새 TODO-RECIPE-NN 태그와 함께 레시피를 추가한 뒤 멈추세요.
반쯤 작동하는 레시피는 없는 것보다 나쁩니다.