본문으로 건너뛰기
이 페이지는 기계 번역이며 충분한 검토를 거치지 않았습니다. 영어 원문이 기준입니다. 보안, 개인정보 보호, 데이터 처리, 규정 준수 및 라이선스에 관한 설명은 기술 검토가 끝날 때까지 영어로 유지됩니다. 영어 원문 보기

Control Zero 개요

Control Zero는 AI 에이전트를 위한 거버넌스 계층입니다. 에이전트가 할 수 있는 일을 정의하면 Control Zero가 런타임에 이를 적용합니다. Claude Code, Gemini CLI, Cursor IDE, Kiro CLI에서는 거부(deny) 결정이 내려지면 도구 호출이 실행되기 전에 중단됩니다.

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

Coverage is declared per event, so the audit trail never implies protection for a call path that was not covered.

Kiro IDE는 적용 지점이 아닙니다.

Hello World​

실제로 실행할 수 있는 Python "hello world"입니다. 가입도, API 키도, 네트워크도 필요 없습니다.

pip install controlzero
# hello_controlzero.py
from controlzero import Client

# Define what your agent is allowed to do.
# Read operations: allowed. Write operations: blocked.
# Note: `database:query` and `database:execute` are legacy action names
# that remain supported. The canonical names are `database:read` and
# `database:write`; both forms match the same calls.
cz = Client(policy={
    "rules": [
        {"allow": "database:query",   "reason": "Reads are fine"},
        {"deny":  "database:execute", "reason": "No writes from this agent"},
    ]
})

# Your agent tries to read; allowed.
result = cz.guard("database", method="query", args={"sql": "SELECT id FROM orders"})
print(result.decision)   # "allow"

# Your agent tries to write; blocked before it ever runs.
result = cz.guard("database", method="execute", args={"sql": "DROP TABLE orders"})
print(result.decision)   # "deny"
print(result.reason)     # "No writes from this agent"

실행해 보세요:

$ python hello_controlzero.py
allow
deny
No writes from this agent

이것이 전체 흐름입니다. 정책을 작성하고, 각 도구 호출 전에 guard()를 호출하면, SDK가 허용 또는 거부를 결정합니다. 거부된 호출은 실행되지 않습니다. 적용 코드도, 인증 검사도, 허용 목록 로직도 작성할 필요가 없습니다.

레거시 및 표준 액션 이름 모두 사용 가능

레거시 이름(database:query, database:execute, database:delete)과 표준 이름(database:read, database:write, database:admin) 모두 동일한 호출과 일치합니다. 새 정책에는 표준 이름을 사용하세요. 레거시 이름을 사용하는 기존 규칙은 변경 없이 계속 동작합니다. 전체 매핑은 정책을 참고하세요.

다음 단계는 정책을 코드에서 Control Zero 대시보드로 옮기는 것입니다. 그러면 다시 배포하지 않고도 정책을 변경할 수 있습니다. 대시보드를 사용하는 5분 버전은 빠른 시작을 참고하세요.

해결하는 문제: AI 에이전트는 도구를 호출하고, 코드를 실행하고, API에 접근하고, MCP를 통해 서비스를 사용합니다. 에이전트가 점점 더 자율적으로 동작할수록 명확하고 검증 가능한 적용 계약을 갖춘 가드레일이 필요합니다. Control Zero는 이러한 가드레일을 정의하는 단일 위치를 제공하고, 적용을 수행하는 지점에서 거부된 호출을 결정론적으로 차단하며, 각 이벤트의 적용 범위를 기록합니다. 기능 매트릭스는 SDK 자체의 기능 선언에서 도출됩니다. 설치된 SDK가 실제로 선언하는 내용을 내보내려면 controlzero coverage --json을 실행하세요(옵션 없는 controlzero coverage는 호스트별 요약만 짧게 출력합니다).

Control Zero를 쓰는 이유​

  • 게이트웨이 프록시: 코드 변경 없이 LLM 트래픽을 통제하는 투명한 드롭인 프록시입니다. 기본 URL만 바꾸면 끝입니다.

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

  • Local enforcement: Every action is evaluated against your policies without a per-call network round-trip.
  • 도구 호출 가로채기: 모든 tool_use(Anthropic)와 function_call(OpenAI)이 정책에 따라 평가됩니다. 거부된 호출은 에이전트에 도달하기 전에 인라인으로 대체됩니다.

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

  • DLP detection, masking, and blocking: Detect or block sensitive data in prompts. On Claude Code and Gemini CLI, Python SDK hooks can redact matches in place and let the call proceed. On the coding-agent surfaces that cannot accept rewritten tool input -- Cursor, Kiro, Codex CLI, Antigravity -- a mask rule becomes a deny, so the secret never reaches the tool either way. The Gateway can mask, on both the request and the response path, but does neither by default: it detects. See Gateway for the two switches and which one a policy bundle can set.
  • 모델 차단: 게이트웨이 수준에서 허가되지 않은 모델에 대한 요청을 거부합니다.
  • 비용 한도: 예상 토큰 비용이 예산을 초과하면 요청을 거부합니다.

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

  • Secret injection: Store LLM provider keys in an encrypted vault. The SDK and gateway inject them at runtime.

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

  • Tamper detection: Policy bundles are encrypted at rest and cryptographically signed. A bundle that fails verification is never loaded, and the event is logged and reported. The SDK re-fetches its signing keys once in case they rotated; if verification still fails, the bundle is refused rather than trusted. During a background refresh the agent keeps enforcing the last known good policy; at startup there is nothing to fall back to, so calls are denied. See tamper detection.

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

  • Fail closed by default: When Control Zero cannot establish coverage, it denies rather than guesses. An unavailable policy bundle blocks traffic instead of silently allowing it.
  • 다중 공급자 지원: Anthropic, OpenAI, Ollama, DeepSeek, MoonshotAI, HuggingFace TGI, LangChain, CrewAI 등을 지원합니다.
  • 공식 SDK: Python과 Node.js. 두 줄의 코드로 AI 클라이언트를 설치하고 감쌀 수 있습니다.
  • MCP 서버: Claude Code, Cursor, Windsurf 같은 AI 코딩 클라이언트에서 직접 거버넌스를 관리합니다.
  • MCP 네이티브: MCP를 지원하는 모든 클라이언트에서 MCP 도구 호출에 대한 일급 거버넌스를 제공합니다.

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

  • Complete audit trails: Every decision is logged with action, resource, result, timestamp, agent identity, and per-event coverage. “Did not run” is distinguishable from “ran and found nothing.”
  • 코드에서 도출되는 기능 매트릭스: 적용 지점 매트릭스는 SDK 자체의 기능 선언에서 도출됩니다. controlzero coverage --json은 사용 중인 설치 환경의 선언을 내보내며, 이 문서와 내용이 다를 경우 기준이 되는 것은 이 출력입니다. 옵션 없는 controlzero coverage는 호스트별 요약만 짧게 출력합니다.
  • Free 플랜: 월 5,000건의 통제된 액션을 무료로 제공합니다. 신용카드가 필요 없습니다.

핵심 아이디어: 정책은 코드가 아닌 대시보드에 있습니다​

이것이 핵심 설계 원칙입니다.

  • 정책은 Control Zero 대시보드(또는 API)에서 정의합니다. 어떤 액션을 허용하거나 거부할지 기술합니다.
  • 코드는 SDK 클라이언트를 통해 도구를 호출합니다. 특정 정책에 대한 참조도, 애플리케이션에 하드코딩된 액션 이름도 없습니다.
  • SDK가 적용을 자동으로 처리합니다. 모든 guard() 호출은 로컬에 캐시된 정책 번들에 따라 평가됩니다.

코드를 건드리지 않고 언제든 대시보드에서 정책을 변경할 수 있습니다. 오래 실행되는 SDK 프로세스는 다음 갱신 때 변경 사항을 반영합니다. Python SDK는 기본적으로 60초마다, Node SDK는 300초마다 폴링합니다. 수동으로 갱신하면 즉시 적용됩니다.

적용되는 대상​

guard()를 통한 모든 호출은 활성 정책에 따라 검사됩니다. 정책 액션은 전달한 도구 이름과 메서드에서 도출됩니다.

guard() 인자검사되는 정책 액션
guard("github", method="list_issues", ...)github:list_issues
guard("database", method="query", ...)database:query (canonical class: database:read)
guard("filesystem", method="write_file", ...)filesystem:write_file
guard("slack", method="post_message", ...)slack:post_message

대시보드에서 이러한 tool:method 액션 문자열로 정책을 정의합니다.

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

The SDK evaluates them locally from a cached policy bundle, so each guard() call doesn't make a network request.

아키텍처​

흐름:

  1. 대시보드에서 정책을 정의합니다.

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

  1. The server compiles them into an encrypted, signed bundle.
  1. SDK는 시작 시 번들을 한 번 다운로드하여 로컬에 캐시합니다.

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

  1. Every wrapped API call is checked against the locally cached policy. No network round-trip per call.

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

  1. Every decision (allow or deny) is logged for audit.

적용 흐름​

에이전트가 guard()를 호출하면 Control Zero는 호출을 정책에 따라 검사하여 허용(도구가 실행됨)하거나 거부(도구가 실행되지 않고 PolicyDeniedError가 발생함)합니다.

주요 기능​

  • 게이트웨이 프록시: LLM 트래픽을 위한 투명한 드롭인 프록시입니다. 코드 변경이 필요 없습니다. Anthropic, OpenAI, Google AI, Ollama, DeepSeek, MoonshotAI, HuggingFace TGI, Mistral, Cohere를 지원합니다.

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

  • Local policy evaluation: Policies are evaluated locally with no per-call network round-trip.
  • 도구 호출 가로채기: 모든 tool_use와 function_call이 평가되며, 거부된 호출은 스트리밍 응답과 비스트리밍 응답 모두에서 인라인으로 대체됩니다.
  • 사전 요청 가드: 요청이 공급자에 도달하기 전에 모델 차단, 비용 한도, PII 탐지 및 차단을 수행합니다. Python SDK 마스킹은 Claude Code와 Gemini CLI에서만 지원됩니다.

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

  • Fail closed by default: When coverage cannot be established, the decision is deny. An unavailable policy bundle blocks traffic instead of silently allowing it.

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

  • Signed policy bundles: Policy bundles are encrypted at rest and cryptographically signed. The SDK verifies every bundle before use and refuses to load one that fails verification. On a background refresh it keeps enforcing the last known good policy; at startup, with nothing verified to fall back to, it denies rather than running unguarded.

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

  • Offline enforcement: After the initial bundle download, SDK enforcement runs locally with no further network calls per request.

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

  • Secrets vault: Store LLM provider keys in an encrypted vault. Injected at runtime by the SDK and gateway.

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

  • Audit trail: Every decision is logged with action, resource, result, timestamp, token usage, agent identity, and per-event coverage. The record distinguishes “did not run” from “ran and found nothing.”
  • 기능 주장은 코드에서 나옵니다: 모든 기능 주장은 어댑터 자체의 CoverageDecl 선언까지 추적됩니다. 기능 매트릭스의 생성된 사본은 SDK 저장소에 있으며, 해당 페이지와 구현이 일치하지 않으면 CI 드리프트 게이트가 빌드를 실패시킵니다. 이 게이트는 생성된 페이지에만 적용됩니다 -- 이 문서 페이지들은 손으로 작성됩니다. 설치 환경의 선언을 내보내려면 controlzero coverage --json을 실행하세요. 여기 페이지와 내용이 다를 경우 기준이 되는 것은 이 출력입니다.
  • 다중 공급자: Anthropic, OpenAI, Ollama, DeepSeek, MoonshotAI, HuggingFace TGI, LangChain, CrewAI 등.
  • 다중 언어 SDK: Python과 Node.js용 공식 SDK.
  • MCP 서버: Claude Code, Cursor, Windsurf 같은 AI 코딩 클라이언트에서 직접 거버넌스를 관리합니다.
  • MCP 도구 제어: 에이전트가 호출할 수 있는 MCP 서버와 도구를 제한합니다.
  • 알림 채널: Telegram, Slack, 이메일, Discord 또는 웹훅으로 알림을 받습니다.

다음 단계​

Free 플랜에는 월 5,000건의 통제된 액션이 포함됩니다. 신용카드가 필요 없습니다.

  • 빠른 시작: 5분 만에 시작합니다(게이트웨이 또는 SDK).
  • 게이트웨이 프록시: 코드 변경 없는 거버넌스를 위한 투명 프록시를 배포합니다.
  • 정책: 대시보드에서 정책을 구성하는 방법을 알아봅니다.
  • 가격: Free, Solo, Teams 플랜.
  • MCP 서버: AI 코딩 클라이언트에서 거버넌스를 관리합니다.
  • 통합: OpenAI, Anthropic, Ollama, DeepSeek, LangChain 등.
  • 블루프린트 라이브러리: 엔터프라이즈 SRE, HR, 재무를 위한 구현 패턴.
  • 가이드: 정책이 자동으로 적용되는 실제 애플리케이션을 구축합니다.