Eclipse Enclave 1.0 오픈소스 아키텍처 해부: AI 코딩 에이전트 격리 샌드박스·dnsmasq/ipset 게이트웨이 플레이스홀더 비밀 주입과 Docker·Podman·QEMU 경계 점검하기
2026년 11월 19일 Eclipse 재단이 발표한 AI 코딩 에이전트 전용 오픈소스(MIT, Go) 샌드박스 런타임 Eclipse Enclave 1.0(v1.0.1)의 내부 아키텍처와 보안 경계를 분석한다. 루트·민감 마운트 가드, Git 워크트리 격리, dnsmasq·iptables/ipset·enclave-gateway-proxy 기반 ENCLAVE_SECRET_* 플레이스홀더 인플라이트 비밀 치환, Rootful Docker·Rootless Podman·실험적 QEMU 백엔드 차이 및 로컬 Python 사전 검증 스크립트를 정리한다.
Eclipse Enclave 1.0 추상 표지 아트워크: 프로젝트 워크트리·에이전트 격리 샌드박스·이그레스 게이트웨이 필터링 계층을 상징하는 개념 그래픽
Eclipse 재단이 2026년 11월 19일 공식 발표한 Eclipse Enclave 1.0은 Claude Code·Codex CLI·GitHub Copilot CLI·OpenCode·Pi·Eclipse Theia 같은 자율형 AI 코딩 에이전트를 개발자 호스트 환경에서 분리된 컨테이너 안에서 안전하게 실행하는 오픈소스(MIT 라이선스, Go 1.24 / toolchain Go 1.26.10 기반, GitHub 최신 릴리스 v1.0.1) 샌드박스 런타임이다. 에이전트가 매번 사용자 승인 프롬프트 없이 셸 명령과 패키지 설치를 자율 실행하는 이른바 'YOLO 모드'를 허용하면서도, 호스트 파일시스템 노출과 시크릿 유출을 구조적으로 차단하는 데 초점을 맞춘다.
핵심 아키텍처 판단 기준을 먼저 요약하면, Eclipse Enclave 1.0은 자체 LLM 에이전트가 아니라 '신뢰할 수 없는 에이전트 워크로드를 감싸는 중립 실행 런타임 및 네트워크 경계 계층'이다. 각 세션은 프로젝트 디렉터리(또는 git worktree)만 바인드 마운트한 일회성 컨테이너에서 실행되며, 호스트의 홈 디렉터리(~)·숨김 설정(~/.ssh, ~/.aws)·XDG 경로·Enclave 자체 루트·SSH_AUTH_SOCK 마운트와 루트(UID 0) 실행을 기동 단계에서 거부한다. 아웃바운드 트래픽은 공유 네트워크 네임스페이스(netns)에 붙는 사이드카 게이트웨이(dnsmasq + iptables/ipset + enclave-gateway-proxy)를 거치며, 제한 모드(restricted)에서 API 키는 컨테이너 안에 랜덤 플레이스홀더(ENCLAVE_SECRET_*)로만 전달되고 지정된 HTTPS 호스트·헤더 규칙이 일치할 때만 게이트웨이가 전송 중(in-flight) 실제 키로 치환한다. 다만 Enclave는 '컨테이너 탈출 방어 하이퍼바이저'가 아니며, Rootless Docker 미지원(Rootful Docker·Rootless Podman만 지원), 실험적 QEMU 백엔드의 게이트웨이·이그레스 차단 부재, 허용 IP 대상 비-80/443 포트(SSH 22 등)의 프록시 우회, 그리고 기존 .git config 외 Git 훅 쓰기 가능 경계를 도입 전 반드시 점검해야 한다. 이 글은 2026년 11월 20일 기준 Eclipse Enclave GitHub 저장소의 README.md, go.mod, LICENSE 및 공식 아키텍처·네트워킹·인증·마운트·백엔드·보안 문서를 교차 검증해 정리한 내용이며, 대규모 컨테이너 런타임 부하 벤치마크 대신 공식 명세의 정량 경계와 로컬 Python 검증 스크립트를 기준으로 설명한다.
1. 격리 샌드박스·민감 경로 가드 및 게이트웨이 비밀 주입 아키텍처
Enclave 세션은 호스트 오케스트레이션(internal/runtime)이 마운트·영속 스토어·인증·네트워크를 준비한 뒤, 게이트웨이 사이드카와 에이전트 CLI 컨테이너를 netns로 결합해 기동한다.
Eclipse Enclave 1.0 호스트 마운트 가드·일회성 에이전트 컨테이너·dnsmasq/iptables/enclave-gateway-proxy 비밀 치환 및 4대 백엔드 지원 경계 도식
1.1 호스트 파일시스템 경계: 루트 가드·민감 마운트 가드·Git 워크트리
- 루트(UID 0) 실행 거부(
root_guard.go): Rootful Docker 환경에서 컨테이너 UID 0은 바인드 마운트 경로에 대해 호스트 root 권한과 동일하게 작동하므로 Enclave는 root 실행을 기본 차단한다. 설정 파일로는 풀 수 없으며--allow-root플래그나ENCLAVE_ALLOW_ROOT=1환경변수로만 예외를 둔다.
- 민감 마운트 차단과 예외 계층(
mount_guard.go,sensitive.go): 읽기 전용 마운트라도 자격증명 유출이 가능하므로run·shell·continue·resume기동 전 모든 프로젝트·추가 마운트(--add-dir,--add-readonly-dir)를 검사한다. 홈 디렉터리(~)와 상위 경로(/,/home), 홈 하위 숨김 항목(~/.ssh,~/.aws,~/.config등 심볼릭 링크 대상 포함), 리눅스 XDG 데이터 경로, Enclave 자체 루트(~/.config/enclave,~/.local/state/enclave,~/.cache/enclave),SSH_AUTH_SOCK소켓 경로가 차단 대상이다.~/.m2같은 하위 경로는--add-sensitive-dir또는sensitive_dir_exceptions로 예외를 둘 수 있지만, 홈·Enclave 루트·SSH 소켓 경로는 설정 예외가 불가능하고--allow-sensitive-mounts로만 우회할 수 있다.
- 호스트 영속 스토어와 Git 메타데이터 경계: 로그인·명령 이력·캐시·에이전트 메모리는 호스트의
~/.local/state/enclave/아래 프로젝트 해시별(또는--auth-scope=shared공유) 디렉터리에 유지된다. 단,env스토어(projects/<hash>/<tool>/env)는 컨테이너 안에 마운트되지 않으며 호스트 측에서 읽고 쓴다. 또한 기존 Git config 파일만 읽기 전용으로 보호되고 나머지.git메타데이터는 쓰기 가능하므로, 신뢰할 수 없는 저장소는--project-mount readonly또는--worktree-metadata readonly|none으로 훅 설치를 막아야 한다.
1.2 게이트웨이 사이드카(127.0.0.1:15080/15443)와 플레이스홀더 비밀 치환
제한 모드(restricted, 기본값)에서는 호스트가 dnsmasq.conf, domains.txt, meta.json 번들과 시크릿 매핑 JSON, 로컬 CA(ca.crt/ca.key)를 게이트웨이 사이드카에 전달해 실패 시 차단(Fail-closed: INPUT DROP, OUTPUT DROP) 방화벽을 구성한다.
- DNS → ipset → 프록시 2단계 검증: 에이전트가 허용 도메인을 질의하면
dnsmasq가 해석된 IP를enclave_allowedipset에 추가하고, 미허용 도메인은NXDOMAIN을 반환해enclave-gateway-proxy -dns-audit가network.log에dns deny를 기록한다. 이후 TCP 80/443 연결은iptablesNAT를 통해 게이트웨이 루프백(127.0.0.1:15080/15443) 프록시로 넘어가며, 프록시가 HTTPHost헤더 또는 TLS ClientHelloSNI를 한 번 더 대조한다.
- 인플라이트(In-flight) 플레이스홀더 치환: 확장이 선언한 API 키나 OAuth 토큰(예:
OPENAI_API_KEY,CLAUDE_CODE_OAUTH_TOKEN)은 컨테이너 내부에서ENCLAVE_SECRET_*형태의 세션별 랜덤 플레이스홀더로만 노출된다. 프록시가network.serviceAuth릴리스 규칙과 일치하는 HTTPS 호스트 요청을 받으면 로컬 CA 리프 인증서로 TLS를 종료한 뒤rewriteHeaders()에서 지정된 헤더만 실제 비밀 값으로 바꿔 업스트림에 전달한다.
- 위반 요청 즉시 거부: 플레이스홀더를 평문 HTTP로 보내거나 릴리스 목록 외 호스트(예: 외부 공격자 서버)로 전송하면 게이트웨이가
HTTP 403 (secret-injection)으로 차단한다. 플레이스홀더 생성에 실패하더라도 실제 값으로 폴백하지 않고 세션 기동 자체를 중단한다.
2. 혼동하기 쉬운 6가지 보안·운영 경계와 백엔드 비교표
공식 문서(docs/networking.md, docs/backends.md, docs/security/README.md)에서 실무 도입 시 가장 자주 오해하는 경계는 다음 6가지다.
- 1) Rootless Docker 미지원과 Docker 방화벽 무력화 함정: Enclave는 Rootful Docker(기본,
buildx필요)와 Rootless Podman(--backend podman)만 지원하며 Rootless Docker는 공식 미지원이다. 또한 Docker 데몬에"iptables": false나"ip6tables": false가 설정되어 있으면 브리지 격리와 루프백 포트 게시 보호가 깨지므로, 운영 호스트에서는userns-remap과 기본 iptables 통합을 유지해야 한다.
- 2) 허용 IP에 대한 비-80/443 포트 우회 표면:
dnsmasq가 허용 도메인의 IP를enclave_allowedipset에 넣고 나면, 포트 80과 443 외의 TCP/UDP(SSH 22번, QUIC/HTTP3 등)는 프록시 검사와network.log기록 없이ipsetIP로 직접 통과한다. 따라서 넓은 CDN 도메인을 allowlist에 넣으면 터널링 표면이 넓어지며, 호스트 SSH 키가 마운트된 상태에서port 22푸시는 감사 로그에 남지 않는다.
- 3) 비제한 모드(
--allow-all-network)에서도 특권 게이트웨이는 실행된다:--allow-all-network를 주더라도 Enclave는 기본적으로 TCP 80/443 관측과network.log기록을 위해NET_ADMIN·NET_RAW권한을 가진 게이트웨이를 함께 띄우며 실제 시크릿을 컨테이너에 직접 주입한다. 게이트웨이를 완전히 끄려면 반드시--disable-gateway를 함께 써야 하며, 반대로restricted모드에서--disable-gateway를 주면 오류가 발생한다.
- 4) 루프백 포트
15080·15443점유 충돌: 에이전트 컨테이너가 게이트웨이와 네트워크 네임스페이스를 공유하고 프록시가 루프백15080(HTTP)·15443(HTTPS)을 점유하므로, 세션 내부 앱 서버나-p포트 매핑으로 해당 포트를 쓰면 시작이 거부된다.
- 5) 실험적 QEMU 백엔드의 무방비 경계:
--backend qemu(x86-64 Alpine microVM)는 현재 게이트웨이와 제한적 이그레스 정책을 구현하지 않아 항상--allow-all-network --disable-gateway로 동작한다. 즉network.log가 남지 않고 게이트웨이 기반 시크릿 플레이스홀더 치환도 작동하지 않으며,--allow-domain지정 시 즉시 거부된다.
- 6)
--network-log=full풀 캡처의 마스킹 범위 한계: 풀 캡처 모드는 요청·응답 본문과 WebSocket 메시지까지 저장하면서 '게이트웨이가 릴리스 규칙으로 관리하는 시크릿'은 플레이스홀더로 치환해 기록한다. 그러나 프롬프트 내용, 소스 파일 본문, 릴리스 규칙 없이 직접 전달된 자격증명은 평문 그대로 캡처 파일에 저장되므로 로그 저장소 접근 통제가 필요하다.
| 비교 항목 | Rootful Docker (기본) | Rootless Podman ( --backend podman) | QEMU microVM ( --backend qemu) |
| 지원 상태 및 전제 | 기본·정식 지원 ( buildx 및 iptables 활성 필수; Rootless Docker는 미지원) | 정식 지원 ( --userns=keep-id • container:<gateway> 네임스페이스 공유) | Experimental (x86-64 Alpine microVM 포그라운드 세션 전용) |
| 세션 네트워크 격리 | 세션별 Docker 브리지 자동 격리 | netavark isolate=strict (구형/미지원 시 isolate=true 경고, firewalld 드라이버는 미격리) | 게이트웨이 미사용 (브리지 격리 대신 VM 단위 분리) |
| 아웃바운드 이그레스 제어 | 지원 ( restricted 기본: dnsmasq • ipset • Host/SNI 프록시) | 지원 (Docker 호환 CLI 경로로 동일 게이트웨이 사이드카 구동) | 미지원 (항상 --allow-all-network --disable-gateway 강제) |
| 플레이스홀더 비밀 주입 | 지원 (HTTPS 일치 호스트·헤더에만 ENCLAVE_SECRET_* 인플라이트 치환) | 지원 (동일 게이트웨이 프록시 경유 치환 및 HTTP 403 차단) | 미지원 (게이트웨이 부재로 플레이스홀더 치환 불가) |
| 네트워크 감사 로그 | network.log (JSONL: dns·tcp·http·session, full 캡처 지원) | 동일 network.log 및 enclave network log 지원 | 미지원 (게이트웨이 부재로 로그 미생성) |
| 운용 특이사항 | userns-remap 호스트 하드닝 권장; 15080/15443 포트 예약 | idmapped-mount 없으면 첫 기동/재빌드 시 keep-id 레이어 복사로 수 분 지연 가능 | --allow-domain 플래그 사용 시 거부됨; 백그라운드 분리 세션 제약 |
3. 실전 운영 커맨드와 로컬 Python 사전 검증 스크립트
3.1 신뢰 경계별 Enclave 실행 및 네트워크 감사 흐름
개발 환경이나 CI에서 에이전트를 기동할 때는 저장소 신뢰 수준에 따라 마운트·네트워크·인증 옵션을 조합해 실행한다.
3.2 Python 표준 라이브러리 기반 Enclave 1.0 정책·마운트·게이트웨이 사전 검증기
실제 컨테이너를 띄우기 전에 마운트 경로가 민감 경로 규칙(홈·~/.ssh·XDG·Enclave 루트·SSH_AUTH_SOCK)에 걸리는지, 선택한 백엔드(Docker/Podman/QEMU)·포트(15080/15443)·도메인 allowlist·플레이스홀더 릴리스 경로가 Enclave 1.0 보안 경계를 위반하지 않는지 로컬에서 사전 점검하는 Python 스크립트(verify_eclipse_enclave.py)다.
로컬 Python 3 실행 결과, 홈 디렉터리·Enclave 루트·SSH 에이전트 소켓의 hard_blocked 판정, ~/.m2의 --add-sensitive-dir 예외 전환, Rootless Docker·iptables: false·예약 포트(15443)·와일드카드 도메인·평문 HTTP/미등록 호스트 시크릿 유출 등 11가지 위반 탐지, restricted 모드와 --disable-gateway 충돌 및 QEMU 백엔드 제약 탐지, 그리고 하드닝된 Rootless Podman 세션의 무오류 통과(ALL CHECKS PASSED)를 모두 확인했다.
4. 실무 도입 및 보안 점검 체크리스트
지원 컨테이너 엔진 확인: Rootful Docker(buildx·iptables: true) 또는 Rootless Podman(--backend podman)을 준비한다. Rootless Docker는 지원되지 않으며, 실험적 qemu 백엔드는 게이트웨이·이그레스 차단·시크릿 치환이 없으므로 격리 목적 프로덕션 작업에 쓰지 않는다.
실행 계정 및 프로젝트 마운트 범위 제한: 일반 사용자 계정으로 프로젝트 디렉터리 안에서만 enclave를 실행하고, 신뢰하지 않는 외부 저장소는 --project-mount readonly 또는 --worktree-metadata readonly를 지정해 .git 훅 변조와 devcontainer.json/.env 임의 실행 위험을 낮춘다.
게이트웨이 제한 모드 및 최소 도메인 allowlist 유지: 기본 restricted 모드를 유지하고 --allow-domain에는 순수 DNS 호스트명만 최소한으로 추가한다. 넓은 CDN 도메인과 비-80/443 포트(특히 SSH 22번) 우회 가능성을 인지하고, 컨테이너 내 서비스 포트 바인딩 시 15080·15443을 피한다.
플레이스홀더 기반 시크릿 릴리스 및 감사 로그 점검: API 키와 Bearer 토큰은 게이트웨이 serviceAuth 릴리스 규칙을 통해 ENCLAVE_SECRET_* 플레이스홀더로만 컨테이너에 노출하고, 세션 종료 후 enclave network log로 dns deny·secret-injection 403 차단 이력을 주기적으로 감사한다.
확장 도구(enclave-extensions) 및 --network-log=full 로그 보호: 기본 내장 6종 도구 외에 Amp·Antigravity 등을 확장으로 추가하거나 --network-log=full 풀 캡처를 켤 경우, 릴리스 규칙 밖의 자격증명과 프롬프트 본문이 호스트 로그에 남지 않도록 접근 권한을 통제한다.
5. 참고 자료 및 공식 출처 (2026-11-20 확인)
- GitHub — Eclipse Enclave 네트워킹 및 요청 흐름 문서 (docs/networking.md · docs/runtime/network-request-flow.md)
확인 기준일: November 20, 2026