AI 코딩 에이전트를 위한 서브-밀리초 Linux 커널 샌드박스

Sub-Millisecond Linux Kernel Sandbox for AI Coding Agents

Vetto는 Claude Code, OpenAI Codex, Cursor, OpenCode, Aider와 같은 AI 코딩 CLI 에이전트를 위한 비특권(unprivileged) 샌드박스입니다. 이는 리눅스와 macOS의 네이티브 커널 기능을 사용하여 fork()와 execve() 사이에서 파일 시스템 접근, 네트워크 소켓 및 자식 프로세스를 격리하며, 백그라운드 데몬을 실행하거나 루트 권한을 요구하지 않습니다.

AI 코딩 에이전트는 생성된 셸 명령어와 빌드 스크립트를 실행합니다. 만약 에이전트가 개인 인증 정보(private credentials)를 읽으려 하거나, 원시 네트워크 소켓(raw network sockets)을 열려고 시도하거나, 추적되지 않은 백그라운드 프로세스를 생성하려고 하면, Vetto는 커널 계층에서 해당 작업을 차단합니다:

> Reading ~/.ssh/id_rsa... BLOCKED (secret mask, EACCES)
> Opening raw socket... BLOCKED (net namespace, EAFNOSUPPORT)
> Spawning detached daemon... TERMINATED (process tree extinction, exit 125)

에이전트가 정책을 위반하거나 호스트 커널이 필요한 격리 메커니즘을 갖추지 못한 경우, Vetto는 즉시 코드 125로 종료됩니다. 자손 프로세스(Descendant processes)와 백그라운드 워커는 cgroups v2 cgroup.kill를 통해 동기적으로 종료됩니다. 만약 호스트 운영체제가 구성된 규칙을 강제할 수 없다면, Vetto는 보안이 낮은 상태로 실행하는 대신 누락된 기능을 보고하고 중단합니다.

표준 패키지 관리자를 통해:

# npm (크로스 플랫폼 전역 바이너리)
npm install -g @shledery/vetto
# Homebrew (macOS & Linux)
...

또는 독립형 curl 설치 프로그램으로:

curl -fsSL https://raw.githubusercontent.com/shleder/vetto/main/install.sh | sh

셸 구성이나 별칭을 수정하지 않고 설치된 AI 코딩 에이전트를 래핑합니다:

vetto enable --all

Vetto는 $PATH에서 지원되는 에이전트 바이너리(claude, codex, cursor, opencode, aider, antigravity)를 검색합니다.

, 그리고 기타) 및 ~/.vetto/shims에 인터셉터 shim을 배치합니다.

활성화 후, 에이전트를 평소처럼 실행하세요:

claude # 커널 LSM 정책 하에서 샌드박싱되어 실행됨
cursor # 보호된 자격 증명 및 제한된 네트워크 이그레스로 실행됨

개별 에이전트 관리 방법:

vetto enable claude # claude만 감싸기
vetto disable claude # 샌드박싱 없이 직접 실행으로 복원

AI 코딩 에이전트는 로컬 컴파일러, 기존 패키지 캐시, 그리고 인터랙티브 터미널 처리가 필요합니다. 이들을 Docker 내부에서 실행하려면 무거운 컨테이너 설정이 필요한 반면, Vetto는 커널 샌드박싱을 호스트 프로세스에 직접 적용합니다:

실증적 성능 측정을 위해 SWE-bench vs Docker Benchmark를 참조하세요.

샌드박스 내부에서 임의의 명령어 또는 스크립트를 실행합니다:

vetto run -- python script.py
vetto -- npm test

Vetto는 에이전트가 작업을 시작하기 전에 프로젝트 디렉터리의 Copy-on-write 스냅샷을 생성합니다:

vetto diff # 에이전트에 의해 수정, 추가 또는 제거된 파일 표시
vetto undo # 작업 공간을 실행 전 상태로 되돌림

현재 머신에서 사용 가능한 커널 격리 기능을 확인하세요:

vetto doctor --preflight # Landlock ABI, 네임스페이스 및 cgroups v2 검사
vetto doctor --preflight --json # 진단 보고서를 JSON으로 출력

AI 코딩 에이전트를 Docker나 root 권한 없이 CI 파이프라인 내부에서 안전하게 실행하는 방법은 공식 shleder/vetto를 사용합니다.

action:

- name: Run Sandboxed Agent
uses: shleder/[email protected]
with:
...

전체 구성 옵션, 다단계 워크플로우, SARIF 보안 보고서에 대한 내용은 CI/CD 통합 가이드를 참조하세요.

Claude Code나 Codex와 같은 대화형 에이전트는 자체 터미널 상태(PTY)를 관리합니다. Vetto는 샌드박스 상태를 표시하는 동시에 직접적인 터미널 입력과 출력을 보존합니다:

상태줄 오버레이 (Statusline overlay): 기본값으로, 비대화형 명령에 사용됩니다. 터미널의 하단 줄에서 활성 파일 시스템 및 네트워크 정책을 보여줍니다. (--tui=statusline)
헤드리스 모드 (Headless mode): 터미널 UI 렌더링을 비활성화합니다. CI 환경, 셸 스크립트 또는 표준 스트림 파이프를 사용할 때 이 플래그를 사용하세요. (--tui=none)
/--ci

Vetto는 각 운영 체제가 제공하는 권한 없는 격리 기능들을 활용합니다:

macOS는 비특권(unprivileged) 네트워크 네임스페이스를 제공하지 않습니다. Vetto는 파일 시스템 쓰기 접근을 제한하고 사용자 자격 증명을 보호하기 위해 Apple의 기본 Seatbelt 프레임워크(libsandbox.1.dylib)를 사용합니다. --net=off로 설정하면 네트워크 트래픽과 mDNSResponder로의 IPC가 차단됩니다. --net=allowlist로 설정하면 Vetto는 127.0.0.1에서 임시 루프백 프록시를 실행하고 나가는 TCP 트래픽을 해당 포트로 제한합니다. macOS에서의 읽기 제한은 시스템 dyld 캐시 동작을 고려하여 광범위하게 적용됩니다.

Vetto는 25개 이상의 AI 코딩 도구를 위한 사전 구성된 프로파일을 포함합니다. 각 프로파일은 알려진 제공업체 엔드포인트로 네트워크 이그레스(egress)를 제한하고 패키지 캐시를 유지하면서 호스트 자격 증명을 보호합니다:

지원되는 에이전트, 네트워크 범위 및 경로 규칙의 전체 목록은 Agent compatibility registry를 참조하십시오.

릴리스는 공개 암호화 검증을 갖춘 자동화된 GitHub Actions 워크플로우를 통해 빌드됩니다:

SLSA Level 3 Provenance: 릴리스 바이너리를 위해 생성된 In-toto 빌드 증명서(attestations). Minisign 서명: 각 릴리스 아카이브에 공개 키 75ECEC9B5080C590 아래 게시됩니다. SHA-256 체크섬: 설치 스크립트에 의해 자동으로 검증됩니다.

• 플랫폼 백엔드 및 격리 사양
• 에이전트 프리셋 및 구성
• SWE-bench 대 Docker 런타임 벤치마크
• 위협 모델 및 보안 경계
• CI/CD 통합 및 GitHub Actions
• 종료 코드 및 실패 모드
• 보안 정책 및 취약점 보고

기여는 환영합니다. main 브랜치에 풀 리퀘스트를 열어주세요. 모든 경계 단언(boundary assertions)에는 해당 검증 테스트가 포함되어야 합니다. 풀 리퀘스트는 GitHub Actions CI에서 Linux, macOS, 그리고 Windows 러너를 통해 실행됩니다.

Apache License, Version 2.0 (LICENSE)에 따라 라이선스가 부여됩니다.