실행할 때 일어나는 일
실행할 때마다 잠깐이면 끝나고, 그 뒤에 백그라운드에 남는 것은 없습니다.
규칙을 읽습니다
ai-jail은 내 ~/.ai-jail 파일을 신뢰합니다. 프로젝트 안의 .ai-jail 파일은 신뢰하지 않습니다. 이 파일은 샌드박스를 더 조일 수만 있고 열 수는 없습니다. 명령줄 플래그는 두 파일보다 우선합니다.
샌드박스를 구성합니다
ai-jail은 에이전트가 생기기 전에 아래 계층을 모두 준비합니다. 설정 파일을 읽을 수 없거나 내용이 잘못되었으면 더 약한 규칙으로 시작하지 않고 그대로 멈춥니다.
그 안에서 에이전트를 시작합니다
에이전트와 에이전트가 띄우는 스크립트, 패키지, MCP 서버는 모두 같은 벽을 물려받습니다. 에이전트가 종료되면 ai-jail도 종료됩니다.
바깥에서 안쪽으로, 계층별 설명
ai-jail은 벽 하나가 혼자 버텨 주리라고 믿지 않습니다. Linux에서 에이전트는 커널이 강제하는 벽 다섯 겹 안에 있고, 여기에 들어가는 것과 나오는 것을 거르는 필터 두 개가 더해집니다.
네임스페이스
bubblewrap- 무엇인가
- 네임스페이스는 커널이 프로세스에 시스템을 바라보는 전용 뷰를 주는 기능입니다. ai-jail은 bubblewrap에 네임스페이스 생성을 맡깁니다. bubblewrap은 Flatpak이 데스크톱 앱을 샌드박싱할 때 쓰는 작은 도구이고 root가 필요 없습니다.
- 무엇을 막는가
- 에이전트는 자기만의 프로세스 목록과 호스트 이름(
ai-sandbox)을 받습니다. 호스트 프로그램과 통하는 프로세스 간 채널이 없고,--network를 넘기지 않으면 네트워크도 없습니다. ai-jail이 죽으면 안에 있는 것도 전부 함께 죽습니다.
파일시스템
마운트- 무엇인가
- 네임스페이스 안에는 ai-jail이 마운트한 것만 존재합니다. 프로젝트는 실제 경로에 읽기·쓰기로,
/usr같은 시스템 디렉터리는 읽기 전용으로 마운트됩니다. 홈 디렉터리와/tmp는 새로 만들어 메모리에 둡니다. - 무엇을 막는가
~/.ssh,~/.aws,~/.gnupg,~/.docker, 브라우저 프로필은 절대 마운트하지 않는 내장 목록에 들어 있습니다. 프로젝트 바깥에 쓴 것은 세션이 끝나면 사라집니다.
Landlock
커널 5.13+- 무엇인가
- Landlock은 프로세스가 파일 접근 권한을 되돌릴 수 없게 스스로 포기하도록 해 주는 Linux 커널 기능입니다. ai-jail은 Landlock으로 파일시스템 규칙을 커널 안의 두 번째 허용 목록으로 한 번 더 적용합니다.
- 무엇을 막는가
- 마운트 계층에 실수나 속임수가 있어도 그것만으로는 목록 밖 경로에 닿을 수 없고, 읽기 전용은 읽기 전용으로 남습니다. 커널이 오래되어 Landlock을 쓸 수 없으면 ai-jail은 그 사실을 알리고 나머지 계층으로 계속 진행합니다.
seccomp
시스템 콜- 무엇인가
- 프로그램은 시스템 콜로 커널에 요청을 보냅니다. seccomp는 이 호출을 거르는 필터이고, ai-jail은 코딩 에이전트에 필요할 일이 없는 호출을 seccomp로 거부합니다.
- 무엇을 막는가
- 필터가 막는 것은
ptrace,mount,bpf, 커널 모듈,io_uring, 커널 키링, raw 소켓, 그리고 터미널에 키 입력을 밀어 넣는 호출인TIOCSTI입니다. 컴파일러와 런타임이 계속 동작하도록 일부러 차단 목록 방식을 택했습니다.
리소스 제한
rlimits- 무엇인가
- 프로세스 트리가 쓸 수 있는 양에 커널이 강제하는 상한입니다. 프로세스 4,096개, 열린 파일 65,536개이고 코어 덤프는 꺼져 있습니다. 락다운 모드에서는 각각 1,024와 4,096으로 낮아집니다.
- 무엇을 막는가
- 포크 폭탄이나 폭주하는 스크립트는 내 컴퓨터를 멈추기 전에 감옥 안에서 상한에 걸립니다. 에이전트는 이 제한을 다시 올릴 수 없습니다.
환경 변수 허용 목록
들어가는 것- 무엇인가
- 셸에는 변수가 가득하고 그중 일부는 API 키입니다. ai-jail은 환경을 비운 뒤 짧은 목록만 전달합니다.
PATH,HOME,TERM, 로케일, 프록시, 인증서 설정입니다. - 무엇을 막는가
- 셸에 export해 둔 토큰과 클라우드 자격 증명은 에이전트에 전달되지 않습니다. 작업에 필요한 변수는
--env에 이름을 지정해서 통과시킵니다.
터미널 프록시
나오는 것- 무엇인가
- 에이전트는 전용 의사 터미널(PTY) 뒤에서 실행되고, 에이전트가 출력한 내용은 터미널 파서를 거친 다음 화면에 나옵니다. 맨 아래 줄의 ai-jail 상태 표시줄도 이 프록시가 그립니다.
- 무엇을 막는가
- 프록시는 클립보드를 건드리거나 터미널에 질의하는 이스케이프 시퀀스를 걸러 냅니다. tmux나 zellij 안에서는 스스로 꺼집니다. 중첩된 터미널끼리 크기 조정을 두고 충돌하기 때문입니다.
macOS에서는 벽이 더 얇습니다
macOS에는 네임스페이스도 Landlock도 seccomp도 없습니다. ai-jail은 같은 정책을 Apple의 내장 샌드박스인 sandbox-exec용 프로파일로 바꿉니다. ai-jail 문서는 이것이 Linux의 격리와 동등하지 않다고 분명히 밝힙니다.
| Linux | macOS | |
|---|---|---|
| 백엔드 | bubblewrap, 그 위에 Landlock, seccomp, 리소스 제한 | 실행할 때마다 생성한 프로파일을 쓰는 sandbox-exec. Apple이 deprecated로 지정했지만 커널 확장 없이 쓸 수 있는 더 나은 대안이 없습니다. |
| 홈 디렉터리 | 메모리에 새로 만든 홈. 실제 홈은 마운트되지 않습니다. | 프로파일은 전역 읽기 권한이 전혀 없는 상태에서 시작해 에이전트에 필요한 경로만 허용하므로 실제 홈은 닫혀 있습니다. |
/tmp | 전용이며 종료 시 폐기 | 마운트 네임스페이스가 없어서 호스트의 /tmp를 씁니다. TMPDIR은 실행할 때 만든 전용 폴더를 가리키고, 허용되는 임시 경로는 이것뿐입니다. |
| Copy-on-write 매핑 | --overlay-map으로 에이전트가 사본에 쓰게 합니다 | 읽기 전용 매핑으로 처리 |
| 네트워크 | 기본으로 꺼짐, 전용 네트워크 네임스페이스 사용 | 기본으로 꺼짐. 락다운에서는 --network를 줘도 항상 차단됩니다. |
| 다른 프로그램 | 보이지 않음. 전용 프로세스 목록, 호스트 IPC 없음 | --macos-host-ipc를 넘기지 않으면 Mach, IOKit, 호스트 IPC를 거부 |
이 구성 요소를 고른 이유
ai-jail은 보안 코드를 되도록 직접 작성하지 않습니다. 크기가 작고 주요 배포판이 모두 패키징하며 Flatpak이 매일 쓰고 있는 bubblewrap을 구동하고, 그 위에 커널 기능을 더합니다.
| 선택지 | 택하지 않은 이유 |
|---|---|
| Firejail | 기능은 충분하지만 setuid root 바이너리이고, 이 설계 때문에 나온 CVE가 여러 건입니다. bubblewrap은 root 없이 동작합니다. |
| bubblewrap을 Rust로 재작성 | 업스트림에서 수정을 받는 50 KB 정도의 의존성 하나를 없애려고 보안에 민감한 코드 500줄 이상을 혼자 유지보수하고 패치해야 합니다. |
| nsjail | 기능은 충분하지만 서버용으로 만들어졌고 protobuf 설정 파일로 구동하며, 패키징된 배포판이 적습니다. |
| systemd-nspawn | systemd가 필요해서 컨테이너 안이나 systemd가 없는 시스템에서는 동작하지 않습니다. |
직접 읽어 볼 수 있는 크기
도구 전체가 동기식 Rust 프로그램 하나입니다. async 런타임도, 데몬도, 컨테이너 이미지도 없습니다.
- 1
- 설치할 바이너리
- 8
- 직접 의존성
- 720
- 소스에 포함된 단위 테스트
- 19
- 실제 샌드박스 탈출을 시도하는 테스트
ai-jail 저장소 버전 1.22.0 기준으로 센 숫자입니다.
에이전트를 철창 안에 넣으세요
ai-jail은 바이너리 하나입니다. 데몬도 root 권한도 필요 없습니다. 평소 실행하던 명령 앞에 단어 하나만 붙이면 됩니다.
brew tap akitaonrails/tap && brew install ai-jailai-jail claude