AI 코딩 에이전트를 위한 커널 강제 샌드박스

AI 코딩 에이전트를 위한 커널 강제 샌드박스입니다. cplt는 GitHub Copilot CLI, OpenCode, Gemini CLI, Antigravity CLI, Pi, Claude Code, goose, DeepSeek Harness 또는 모든 셸을 감싸서(wraps) 에이전트가 코드를 작성할 수는 있지만, 자격 증명(credentials)을 훔치거나, main 브랜치에 푸시하거나, PR을 병합하거나, 비밀 정보를 유출하는 것은 불가능하게 만듭니다.

macOS: Apple Seatbelt/SBPL을 sandbox-exec를 통해 사용합니다.

Linux: Landlock LSM + seccomp-BPF + 선택적 Bubblewrap 네임스페이스 격리(커널 5.13 이상, 6.7+에서는 전체 네트워크 필터링)를 사용합니다.Windows: 기본 지원되지 않습니다. Windows용 샌드박스 백엔드가 없습니다. cplt는 WSL2 내부에서 실행해야 하며, 이 경우 일반적인 Linux 설치 환경이며 Microsoft 커널이 Landlock을 제공합니다. Windows (WSL2) 설정 섹션을 참조하세요.

AI 에이전트는 임의 코드를 실행합니다. 프롬프트 주입(prompt injection), 공급망 공격(supply chain attack), 또는 악성 MCP 서버를 통해 손상된 에이전트는 OS 자체가 막지 않는 한, ~/.ssh을 읽거나, main 브랜치에 푸시하거나, PR을 병합하거나, 코드를 유출할 수 있습니다.

cplt는 팀 구성 가능한 정책과 함께 커널 수준의 강제 적용 기능을 제공합니다:

• .cplt.toml 파일 내 리포지토리별 정책: 버전 관리에 커밋되어 위변조가 불가능하고 감사(auditable)가 가능하며, 자격 증명, 비밀 정보 및 민감한 파일에 대해 기본적으로 거부(Deny by default)됩니다.

• 명령어 수준의 git 및 gh 가로채기(interception): 기본 브랜치에 푸시하는 것, 강제 푸시(force pushes), 병합(merges), 릴리스는 차단되며, 기능 브랜치는 열린 상태를 유지합니다.

• 감사 로그가 포함된 아웃바운드 네트워크 필터링

• Docker도 없고, VM도 없습니다. 잠금 장치가 된 노트북에서 실행되는 단일 바이너리입니다.

• 개발자를 위한 제로 설정 시작(Zero-config start)을 제공하며, 빌드가 정말 필요로 하는 경우를 위한 탈출구(escape hatches)가 있습니다.

• 빠른 시작 (Quick start)

• 차단하는 것 (What it blocks)

• cplt 비교 방법 (How cplt compares)

• 설치 (Install)

• 사용법 (Usage)

• 구성 (Configuration)

• 아키텍처 (Architecture)

• 보안 (Security)

• 네트워크 및 프록시 (Network and proxy)

• 명령어 가드 (Command guards)

• 알려진 영향 (Known impacts)

• 제한 사항 (Limitations)

• 기여하기 (Contributing)

• 참고 자료 (References)

상세 문서:
구성 · 프록시 및 도메인 필터링 · gh 명령어 가드 · git 명령어 가드 · 알려진 영향 · 보안 세부 정보 · 보안 모델

Other agents and sandbox commands:

cplt --agent opencode # OpenCode (Copilot subscription)
cplt --agent opencode --pass-env ANTHROPIC_API_KEY # third-party provider
cplt --agent shell # interactive sandboxed shell (no AI)
...

# 1. Generate per-repo policy
cplt init --write
# 2. Developers approve on first run
...

The sandbox는 커널 수준에서 자격 증명(credentials) 및 비밀 정보(secrets)에 대한 접근을 차단합니다. 명령어 가드(Command guards)는 파괴적인 작업(destructive operations)을 막습니다. 모든 제한 사항은 에이전트와 그 에이전트가 생성하는 모든 프로세스에 적용됩니다.

scratch 디렉터리는 TMPDIR을 안전한 위치로 리디렉션하며, 기본적으로 활성화됩니다 |
PATH가 해결된 bin/shim 디렉터리 (~/.bun/bin, ~/.deno/bin, $PNPM_HOME, mise shims/ 및 모든 installs/) | 🔒 커널 차단 (macOS) |
사용자가 다음에 비샌드박스 명령을 통해 PATH가 해결하는 바이너리를 트로이 목마화(trojaning)하는 것을 방지합니다. 이와 같은 이유로 ~/.cargo/bin과 ~/go/bin은 항상 읽기 전용이었습니다. cplt 내부에서 bun install -g, deno install, pnpm add -g, mise install, mise upgrade, mise use -g를 실행하는 것을 의도적으로 막고, 리포지토리가 설치되지 않은 툴체인을 부트스트랩(bootstraps)하지 않게 합니다. 프로젝트 로컬 설치는 영향을 받지 않습니다. Linux: mise의 두 가지 방법은 bwrap 읽기 전용 오버레이를 이용하며, 나머지는 네이티브하게 유지됩니다. Global tool installs 참조 |
~/Library/Caches에서 실행 | 🔒 기본적으로 커널 차단 |
바이너리 드롭 스테이징(binary-drop staging)을 방지합니다. Copilot의 네이티브 모듈은 예외 처리(carve-out)를 통해 면제됩니다. --allow-cache-exec <SUBDIR>와 같이 타겟팅된 예외 처리를 추가할 수 있습니다 (예: ms-playwright) |
.vscode/tasks.json, launch.json 수정 |
IDE 신뢰 경계(trust boundary). 완화 조치(mitigations)는 SECURITY.md를 참조하세요 | |
~/.copilot 읽기/쓰기 (인증, 설정) | ✅ 허용됨 | keytar.node, pty.node, computer.node에 대한 file-map-executable 포함 |
~/.copilot/pkg 쓰기 (네이티브 모듈) | 🔒 커널 차단 |
네이티브 모듈 교체를 통한 지속성(persistence)을 방지합니다 |
| 환경 변수 | 🔒 정제 및 강화됨 (Sanitized + hardened) | 안전한 허용 목록만 통과됩니다. 라이프사이클 스크립트는 차단됩니다. --pass-env VAR를 사용하면 하나를 다시 추가할 수 있습니다 |
~/.config/gh/hosts.yml + config.yml 읽기 | ✅ 허용됨 (읽기 전용) | 이 두 파일만 해당합니다. .config/gh의 나머지는 차단됩니다 |
~/.config/mise 읽기 | ✅ 허용됨 (읽기 전용) | 툴 버전 및 PATH이며, 비밀 정보는 없습니다 |
~/.gitconfig, ~/.config/git/config 읽기 | ✅ 허용됨 (읽기 전용) | dotfiles 심링크(symlink)가 대상까지 따라가므로, 보관된(stowed) ~/.gitconfig도 작동합니다 |
~/.git-credentials 읽기 | 🔒 커널 차단 | credential.helper = store는 평문 토큰을 여기에 유지합니다. --allow-read를 사용해도 재개되지 않습니다 (예: ~/.netrc).

Linux: 조상(자신인 $HOME)에 대한 권한을 부여했기 때문에 여전히 노출됩니다. Landlock은 허용된 트리 내부의 서브 경로를 거부할 수 없기 때문입니다 |
읽기 전역 git 훅 (core.hooksPath ) |
✅ 허용됨 (읽기 전용, 쓰기 금지) | 자동 감지됨. 깊이 ≥3을 가지며 $HOME 아래에 있어야 합니다. 쓰기는 명시적으로 차단됩니다 |
커밋/태그 서명 (commit.gpgsign , tag.gpgsign ) |
🔒 비활성화됨 | ~/.ssh 및 ~/.gnupg의 개인 키는 차단되므로, 환경 변수 오버라이드를 통해 서명이 비활성화됩니다 |
~/Library/Application Support/Microsoft 읽기 |
✅ 허용됨 (읽기 전용) | 텔레메트리 장치 ID | macOS Keychain 접근 | 이 권한은 단일 항목으로 범위를 지정할 수 없으므로, 에이전트가 잠금 해제할 수 있는 모든 키체인 항목에 도달합니다. 키체인 대체품 (sandbox.keychain_substitute )은 다음 방법 중 하나로 해당 항목을 드롭합니다: Copilot의 경우 기본적으로 (내보낸 COPILOT_GITHUB_TOKEN , GH_TOKEN 또는 GITHUB_TOKEN , 그렇지 않으면 gh가 GH_TOKEN으로 전달하는 토큰) 및 Claude Code의 경우 (내보낸 CLAUDE_CODE_OAUTH_TOKEN ), Antigravity는 옵트인(폴백 토큰 파일). 이러한 자격 증명이 없으면 권한은 유지됩니다. SECURITY.md를 참조하세요 |
출력 네트워크 (포트 443) | ✅ 허용됨 | 다른 모든 포트는 차단됩니다. --allow-port로 추가할 수 있습니다 |
로컬호스트 출력 | 🔒 커널 차단 (macOS), | 로컬 서비스 접근을 방지합니다. 인바운드는 프록시를 위해 여전히 작동합니다. Linux: Landlock 규칙은 포트 번호만 처리하며 localhost:443과 remote:443을 구분할 수 없으므로, 허용된 포트의 로컬 서비스는 도달 가능하며 localhost 전용 거부 사항은 없습니다. SSRF 보호를 위해 --with-proxy를 사용하세요. Linux 제한 사항을 참조하세요 |
SSH 에이전트 (유닉스 소켓) | 🔒 커널 차단 (macOS), | git 또는 SSH에 로드된 키를 사용하는 것을 방지합니다. 네트워크 경로는 차단하지 않습니다: ssh.github.com:443과 같은 포트 443의 SSH 서버는 도달 가능하며, 포트 443을 통한 SSH를 참조하세요. Linux: 유닉스 소켓 connect()는 제한되지 않으므로, 보류된 SSH_AUTH_SOCK이 유일한 장벽이며, 이를 자체 설정하는 에이전트는 로드된 키를 사용할 수 있습니다.

bwrap은 /tmp 아래에 기본 OpenSSH 소켓을 숨기지만, $XDG_RUNTIME_DIR 아래의 gnome-keyring/gcr이나 systemd 에이전트는 그렇지 않습니다. Linux 제한 사항 보기 |
개발 도구 (~/.cargo, ~/.gradle, ~/.m2, ~/.sdkman, ~/.jenv, ~/.pyenv, ~/.konan 등) | ✅ 허용됨 (캐시의 읽기+쓰기) | 디스크에 존재하는 디렉터리만 해당. cplt doctor가 감지하는 내용으로 런타임에 강화됨 |
레지스트리 자격 증명 파일 (~/.m2/settings.xml, ~/.gradle/gradle.properties, ~/.cargo/credentials) | 🔒 macOS에서는 커널 차단. Linux의 경우 부모 도구 디렉터리는 읽기 가능 상태 유지 | --allow-read로 재정의. 프라이빗 레지스트리 보기 |
~/.npmrc 읽기 | 🔒 커널 차단 (두 플랫폼 모두) | --allow-read로 재정의. Linux에서 yarn 1을 손상시킬 수 있음, yarn 1 보기 |
Go 소스 코드 (~/go/src) | 🔒 커널 차단 | ~/go/bin과 ~/go/pkg만 읽기 가능 |
~/.ssh, ~/.gnupg, ~/.aws, ~/.azure 읽기 | 🔒 커널 차단 | |
~/.kube, ~/.docker, ~/.nais 읽기 | 🔒 커널 차단 | |
~/.password-store, ~/.terraform.d 읽기 | 🔒 커널 차단 | |
~/.config/gcloud, ~/.config/op 읽기 | 🔒 커널 차단 | 개별 파일은 --allow-read로 재정의 가능. 클라우드 자격 증명 보기 |
~/.config/cplt, ~/.nav-pilot 읽거나 쓰기 | 🔒 커널 차단 | 다음 실행이 무엇을 할지 결정하는 도구 상태. ~/.config/cplt는 전체 서브트리로 재정의 불가능하며, ~/.nav-pilot 내부에서는 이름이 지정된 경로가 부여 가능하므로 고정된 에이전트패키지(agentpakke) 페이로드를 읽을 수 있음 |
~/.netrc, ~/.pypirc, ~/.vault-token 읽기 | 🔒 커널 차단 | 두 플랫폼 모두에서 재정의 불가능. allow.read에 이름을 지정하는 것은 시작 오류임 |
~/.gem/credentials 읽기 | 🔒 커널 차단 | 두 플랫폼 모두에서 재정의 불가능. allow.read에 이름을 지정하는 것은 시작 오류임 |
gh CLI 파괴적 작업 (merge, delete, release) | 🔒 명령어 게이트(Command-gated) (기본값) | --no-gh-guard로 제외 가능.`}```json
{

gh guard 보기 |
git push를 기본 브랜치로 할 때
🔒 커맨드 게이트(Command-gated) (기본 활성화) | main/master로의 푸시 차단; 기능 브랜치 푸시는 여전히 작동합니다. protect_default_branch_only = false는 모든 푸시를 차단하고, git_guard.mode = "warn"은 경고만 하며, --no-git-guard는 제외합니다. |
| 자식 프로세스 상속 (Child process inheritance) | ✅ 모든 제한 사항이 서브프로세스에 적용됩니다 |

해당 표는 요약입니다. 샌드박스는 시스템 파일(SSL 인증서, /etc/hosts), 임시 디렉터리(읽기 및 쓰기, 실행 불가), 그리고 시스템 도구 경로(/usr/bin, /opt/homebrew)에도 접근을 허용합니다. 전체 SBPL 규칙은 cplt --print-profile로 확인하세요.

전체 보안 모델, 위협 분석 및 테스트 전략에 대해서는 SECURITY.md를 읽어보세요.

cplt가 모든 면에서 더 강력한 것은 아닙니다. Codex CLI는 현재 리눅스 네임스페이스 격리(Linux namespace isolation)를 가지고 있으며, 이미 읽기 전용 및 작업 공간 쓰기 같은 명시적인 샌드박스 모드를 노출합니다. cplt는 아직 그러한 모드 매트릭스를 갖추고 있지 않습니다.

• cplt는 IDE 외부에서 작동합니다.
• 환경 변수는 에이전트가 시작되기 전에 필터링됩니다.
• 민감한 파일은 리포지토리 내부에 존재하더라도 차단될 수 있습니다.
• 동일한 제한 사항이 자식 프로세스에도 적용됩니다.

Anthropic Sandbox Runtime (srt)은 Claude Code에서 사용되는 샌드박싱 레이어입니다. cplt와 같은 높은 수준의 접근 방식을 가지지만, 구현 방식은 다릅니다. macOS Seatbelt에 커널 레벨의 Linux 강제 적용과 HTTP 프록시를 추가한 형태입니다.