관찰 전용 거버넌스 설정하기 (지켜보되 차단하지 않기)

사용하는 적용 지점: 모든 적용 지점 (SDK, 게이트웨이, 코딩 훅) 지원 모드: Hosted Hybrid Local 플랜: Free Solo Teams

수행할 내용

영어 원문 -- 번역은 기술 검토 대기 중입니다

Stand up Control Zero so it watches and records every governed AI and tool call -- and blocks nothing. Every decision lands in the audit log so you can see exactly what your agents do in production, what a stricter policy would have blocked, and where your real risk is, before you ever turn enforcement on.

거버넌스를 처음 도입하는 팀에 가장 안전한 방법입니다. 첫날부터 누구의 워크플로도 깨지지 않으며, 실제 트래픽에 맞는 정책을 작성하는 데 필요한 근거를 수집할 수 있습니다.

이 방법이 적합한 경우

• 먼저 가시성을 원합니다. "무슨 일이 일어나는지 보여 주세요"가 "차단하고 무엇이 깨졌는지 알아내기"보다 낫습니다.
• 다른 사람의 에이전트나 노트북에 배포하는 중이며 첫날의 오탐 차단을 감당할 수 없습니다.
• 검토, 인시던트 또는 컴플라이언스 논의를 위한 감사 추적이 필요하지만 아직 차단 방식을 확정할 준비가 되지 않았습니다.
• 실제 허용 목록을 작성하고 싶지만 에이전트가 실제로 어떤 도구, 모델, 리소스에 접근하는지 아직 모릅니다.

이는 성숙한 보안 도구의 도입 방식과 같습니다. 탐지 모드가 먼저이고 적용은 그다음입니다. 실제 트래픽을 관찰하고, 그에 맞춰 조정한 다음에야 스위치를 전환합니다.

이 방법을 사용하지 말아야 할 경우

주의

관찰 전용은 설계상 아무것도 차단하지 않습니다. 오늘 반드시 막아야 할 알려진 위험 액션이 이미 있다면(예: "에이전트는 프로덕션에서 DROP TABLE을 절대 실행하면 안 됨") 관찰 전용으로 시작하지 마세요. 그 액션 하나에 대한 deny 규칙을 작성하고 나머지는 모두 허용 상태로 두세요. 혼합 운영 방식은 개발은 경고, 프로덕션은 거부를 참고하세요.

관찰 전용의 작동 방식

영어 원문 -- 번역은 기술 검토 대기 중입니다

Control Zero evaluates every call against your policy and records the decision.

결정이 내려진 이후에 일어나는 일은 번들 수준의 설정 하나인 default_action이 제어하며, 어떤 규칙도 호출과 명시적으로 일치하지 않을 때의 결과를 정합니다.

default_action	운영 방식	어떤 규칙도 허용하지 않는 호출에 대한 효과
allow	관찰	호출이 진행됩니다. 결정은 여전히 기록됩니다. 아무것도 깨지지 않습니다.
warn	소프트	호출은 진행되지만 결정에 플래그가 지정되어 더 엄격한 정책이 무엇을 차단할지 볼 수 있습니다.
deny	Enforce	The call is blocked. This is the secure-by-default posture.

모든 것을 지켜보는 배포를 하려면 default_action: allow로 설정합니다.

영어 원문 -- 번역은 기술 검토 대기 중입니다

Every call is permitted and every decision is written to the audit trail.

이러한 배포 방식을 플랫폼에서는 감사 전용 롤아웃이라고 부릅니다. 강화할 준비가 되면 같은 정책을 warn(차단되었을 항목을 보여 주는 소프트 롤아웃)으로 옮기고 마지막으로 deny로 옮깁니다.

5분 설정

Hosted (대시보드에서 관리)

1. app.controlzero.ai에 가입하고 프로젝트를 만듭니다(빠른 시작 참고).
2. 대시보드에서 Project Settings를 열고 프로젝트의 적용 기본값을 Allow (audit-only) 로 설정합니다. 이는 default_action: allow에 해당하는 프로젝트 수준 설정입니다.
3. 원하는 정책을 연결하고(빈 스타터도 괜찮습니다) 적용 지점(게이트웨이, SDK 또는 코딩 훅)을 통합합니다.
4. 평소 워크로드를 실행합니다. Audit Log가 채워지는 것을 지켜보세요.

기본값이 allow인 동안에는 아무것도 차단되지 않습니다. 이제 실제 정책을 작성하는 데 필요한 데이터를 수집하고 있습니다.

Local / Hybrid (저장소 안의 정책 파일)

이 controlzero.yaml을 프로젝트에 넣으세요. 모든 것을 기록하고 아무것도 차단하지 않습니다:

version: '1'
settings:
  # Observation-only: anything no rule matches is allowed and logged.
  default_action: allow
  default_on_missing: allow
  default_on_tamper: warn
rules:
  # A single permissive rule keeps the bundle non-empty and makes the
  # observe-everything intent explicit. Every call is still audited.
  - id: observe-all
    allow: '*'
    reason: 'Observation-only: allow and audit every action.'

에이전트에 다른 변경 없이 SDK에 연결합니다:

from controlzero import Client

# Local mode: policy on disk, audit to a local file. No blocking while
# default_action is "allow"; every guard() decision is still recorded.
cz = Client(policy_file="./controlzero.yaml")

# Your agent calls guard() before each tool call, exactly as it would
# under enforcement. In observation-only the decision is "allow" and the
# call proceeds -- but it lands in the audit log either way.
result = cz.guard("database", method="SELECT", args={"sql": "SELECT id FROM orders"})
print(result.decision)  # "allow"

cz.close()

AI 코딩 어시스턴트를 관찰 전용으로 통제하려면 훅을 설치하고 같은 허용 정책을 사용하세요. 훅은 명령 하나로 연결됩니다:

controlzero install claude-code

설치 프로그램이 스타터 정책을 작성하며, 관찰 전용 단계에서는 이를 default_action: allow로 완화합니다.

영어 원문 -- 번역은 기술 검토 대기 중입니다

The assistant keeps working exactly as before; every tool call it makes is recorded.

작동 확인

1. Hosted: 프로젝트의 Audit Log를 엽니다. 통제 대상 호출마다 decision이 allow이고 도구, 메서드, 타임스탬프가 있는 행이 표시되어야 합니다.

2. Local: SDK는 순환 감사 파일(기본값 ./controlzero.log)을 기록합니다. 실시간으로 확인하세요:

   controlzero tail --log ./controlzero.log

3. 더 엄격한 정책이 차단할 것으로 예상하는 호출(쓰기, 삭제, 미승인 모델)이 여전히 허용되고 기록되는지 확인합니다. 이것이 핵심입니다. 아무것도 막지 않고도 이제 그 호출을 볼 수 있습니다.

적용으로 전환하기

관찰 전용은 출발선이지 종착지가 아닙니다. 탐지 모드 보안 도구와 같은 권장 경로는 세 단계입니다:

1. 관찰. 1~2주 동안 default_action: allow로 실행합니다. 에이전트가 실제로 무엇을 하는지 감사 로그로 확인합니다.

2. 소프트 롤아웃. 막으려는 액션에 대한 deny 규칙을 작성하되 default_action: warn을 유지합니다. 이제 감사 로그는 새 규칙이 차단했을 모든 호출에 플래그를 표시하지만 실제로 차단하지는 않습니다. 경고를 검토하고 allow 규칙을 넓혀 오탐을 수정합니다.

   version: '1'
   settings:
     # Soft rollout: would-be blocks are flagged, not enforced yet.
     default_action: warn
     default_on_missing: deny
     default_on_tamper: warn
   rules:
     - id: allow-reads
       allow: 'database:read'
       reason: 'Reads are fine.'
     - id: block-writes
       deny: 'database:write'
       reason: 'No writes from this agent (soft: surfaced as a warning for now).'

3. 적용. 경고가 올바르게 보이고 오탐률이 허용 가능한 수준이면 default_action을 deny로 전환합니다. allow 규칙이 허용된 작업의 전체 목록이 되고, 나머지는 모두 차단됩니다.

   version: '1'
   settings:
     # Enforce: only explicitly allowed actions proceed.
     default_action: deny
     default_on_missing: deny
     default_on_tamper: quarantine
   rules:
     - id: allow-reads
       allow: 'database:read'
       reason: 'Reads are the only permitted database operation.'
     - id: block-writes
       deny: 'database:write'
       reason: 'Writes are blocked.'

세 단계 모두 정책 파일이 같고 default_action만 바뀌므로, 규칙을 하나도 다시 작성하지 않고 개발, 스테이징, 프로덕션으로 승격할 수 있습니다.

자주 이어지는 질문

• "개발에서는 소프트, 프로덕션에서는 하드인 정책 하나를 원해요" -> 개발은 경고, 프로덕션은 거부
• "이제 첫 번째 실제 허용 목록을 작성하고 싶어요" -> 읽기 전용 데이터베이스
• "우리 조직에서 AI가 어디에 쓰이는지 알고 싶어요" -> 섀도 AI 찾기
• "내 역할에 맞는 설정은 무엇인가요?" -> 역할별 설정

참고 자료

• 개념: 적용 동작 (default_action / default_on_missing / default_on_tamper 설정)
• 개념: 정책
• 가이드: 완전한 오프라인 실행 (Local 모드)
• API: API 레퍼런스