thodoristsampouris/agentguard제로트러스트 샌드박스로, AI 에이전트를 위해 커널 수준 파일시스템 감옥, 투명 네트워크 프록시, YAML 기반 정책 엔진을 통해 쉘 명령어, 파일 작업, 네트워크 요청을 차단 및 제어합니다.
자율 AI 에이전트를 위한 제로 트러스트 샌드박스.
AgentGuard는 모든 AI 에이전트(LangChain, CrewAI, AutoGen, 사용자 정의 스크립트)에 안전 레일을 씌웁니다. 명령어 한 줄만 바꾸면 됩니다:
# 이전 (위험 — 에이전트가 전체 시스템에 접근 가능)
python my_agent.py
# 이후 (샌드박스 내)
agentguard run -- python my_agent.py
AgentGuard는 에이전트가 실행하는 모든 셸 명령, 파일 수정, 네트워크 요청을 가로챕니다. 안전한 동작은 자동 허용, 위험한 동작은 자동 차단, 그 외에는 사람의 승인을 요청합니다.
AgentGuard는 함께 작동하는 네 가지 방어 계층을 갖추고 있습니다:
┌─────────────────────────────────────────────────────────────┐
│ Layer 0: 파일시스템 감옥 (macOS sandbox-exec) │
│ 커널 수준 강제. 시스템 콜 수준에서 파일 쓰기와 네트워크를 │
│ 제한합니다. 에이전트가 사용자 공간에서 우회 불가. │
│ Python의 open(), requests.post() 등을 차단합니다. │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: 네트워크 프록시 │
│ 투명 HTTP/HTTPS 프록시. 에이전트가 만드는 모든 네트워크 호출 │
│ 을 정책에 따라 검사합니다. 대상별 허용/거부를 TUI에서 │
│ 완전히 확인 가능. │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: PATH 대체 명령 │
│ git, pip, curl, rm 등의 명령을 가로채는 셸 스크립트 대체물. │
│ 각 대체 명령은 실제 바이너리를 실행하기 전에 데몬에 허가를 │
│ 요청합니다. │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: 정책 엔진 + 승인 데몬 │
│ YAML 기반 규칙이 가로챈 모든 동작을 평가합니다. │
│ 안전한 명령은 자동 허용, 위험한 명령은 자동 차단, │
│ 나머지는 사람에게 묻습니다. │
└─────────────────────────────────────────────────────────────┘
단일 계층이 보안 경계는 아닙니다. 함께 작동합니다 — 심층 방어.
go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/
두 바이너리는 같은 디렉터리에 있어야 합니다.
agentguard init
이 명령은 현재 디렉터리에 .agentguard/policy.yaml을 생성합니다. 필요에 맞게 편집하세요.
agentguard run -- python my_agent.py
TUI가 터미널을 차지하며 다음을 표시합니다:
Claude Code 같이 터미널이 필요한 대화형 도구의 경우:
agentguard run --headless -- claude
에이전트가 직접 터미널을 사용합니다. AgentGuard는 백그라운드에서 조용히 실행됩니다. 모든 이벤트는 ~/.agentguard/logs/headless.log에 기록됩니다. 다른 터미널에서 모니터링:
tail -f ~/.agentguard/logs/headless.log
agentguard run [flags] -- <command> [args...]
--policy <path> 특정 정책 파일 사용
--headless TUI 없음 — 에이전트가 터미널 사용
--default-allow Headless 모드에서 PROMPT 결정 자동 허용 (기본값: 자동 거부)
--no-sandbox sandbox-exec 비활성화 (대체 명령과 프록시는 여전히 활성)
agentguard init 기본 정책 파일 생성
agentguard version 버전 출력
정책은 에이전트가 할 수 있는 일과 없는 일을 정의하는 YAML 파일입니다. AgentGuard는 다음 세 위치를 순서대로 확인합니다:
./.agentguard/policy.yaml (프로젝트 로컬)~/.agentguard/policy.yaml (사용자 전역)version: 1
deny:
# 위험한 명령 차단
- command: "rm"
args: "-rf *"
reason: "재귀적 강제 삭제는 너무 위험합니다"
- command: "sudo"
args: "*"
reason: "권한 상승은 허용되지 않습니다"
- command: "chmod"
args: "777 *"
reason: "모든 사용자 쓰기 권한은 위험합니다"
# 민감한 파일 읽기 차단 (sandbox-exec로 적용)
- file:
path: "*.env"
action: "read"
reason: "에이전트가 .env 파일을 읽지 못하게 합니다"
- file:
path: "*.pem"
action: "read"
reason: "에이전트가 개인 키를 읽지 못하게 합니다"
allow:
# 안전한 읽기 전용 명령
- command: "ls"
- command: "cat"
- command: "pwd"
- command: "echo"
- command: "grep"
- command: "head"
- command: "tail"
- command: "wc"
# 읽기 전용 git
- command: "git"
args: "status"
- command: "git"
args: "log *"
- command: "git"
args: "diff *"
# 작업 공간에 쓰기 허용
- file:
path: "/tmp/workspace/**"
action: "write"
# 특정 API 엔드포인트 허용
- network:
destination: "api.anthropic.com:443"
- network:
destination: "api.github.com:443"
deny network *) — 세 번째 확인. 기본 거부 역할을 합니다.명령 규칙 — 이름과 인자 패턴으로 셸 명령과 대조:
- command: "git"
args: "push *"
reason: "푸시는 승인이 필요합니다"
파일 규칙 — 파일 작업 대조 (sandbox-exec로 적용):
- file:
path: "*.env"
action: "read" # "read" 또는 "write"
reason: "비밀 보호"
네트워크 규칙 — 네트워크 대상 대조 (프록시 + sandbox-exec로 적용):
- network:
destination: "api.anthropic.com:443"
명령 인자, 파일 경로, 네트워크 대상에 *를 와일드카드로 사용할 수 있습니다.
| 키 | 동작 | 시점 |
|---|---|---|
Y | 보류 중인 요청 허용 | 승인 프롬프트 표시 중 |
N | 보류 중인 요청 거부 | 승인 프롬프트 표시 중 |
A | 허용 + 이 세션 동안 기억 ("항상 허용") | 승인 프롬프트 표시 중 |
B | 거부 + 이 세션 동안 기억 ("영구 차단") | 승인 프롬프트 표시 중 |
Tab | 에이전트 stdout/stderr 패널 전환 | 항상 |
위/아래 | 활동 스트림 스크롤 | 항상 |
Q | 종료 (에이전트 종료) | 항상 |
| 에이전트 동작 | 대체 명령 | 프록시 | sandbox-exec |
|---|---|---|---|
subprocess.run(["rm", "-rf", "/"]) | 예 | - | - |
subprocess.run(["git", "push"]) | 예 | - | - |
requests.post("https://evil.com") | - | 예 | 예 |
urllib.request.urlopen("https://api.com") | - | 예 | 예 |
open(".env", "r") | - | - | 예 |
open("/etc/shadow", "w") | - | - | 예 |
/usr/bin/curl https://evil.com (절대 경로) | - | 예 | 예 |
agentguard/
├── cmd/
│ ├── agentguard/ # 메인 CLI 바이너리
│ └── agentguard-check/ # 대체 명령 헬퍼 바이너리
├── internal/
│ ├── policy/ # 정책 엔진 (YAML 파싱, 규칙 평가)
│ ├── events/ # 이벤트 시스템 (JSONL 감사 로그, pub/sub)
│ ├── daemon/ # 중앙 데몬 (Unix 소켓, 승인 큐)
│ │ └── client/ # 대체 명령용 클라이언트 라이브러리
│ ├── shim/ # 대체 명령 생성기 (PATH 기반 가로채기)
│ ├── proxy/ # 투명 네트워크 프록시
│ ├── spawner/ # 오케스트레이션 + macOS 샌드박스 통합
│ └── ui/tui/ # 터미널 UI (Bubble Tea)
├── configs/
│ └── default_policy.yaml # 참조 정책 파일
├── .gitignore
├── go.mod
├── LICENSE
└── README.md
| 구성 요소 | 패키지 | 목적 |
|---|---|---|
| 정책 엔진 | internal/policy | YAML 규칙 파싱, 요청 평가 → ALLOW / DENY / PROMPT |
| 이벤트 시스템 | internal/events | 추가 전용 JSONL 감사 로그 + TUI용 실시간 pub/sub |
| 데몬 | internal/daemon | Unix 소켓 서버, 타임아웃 있는 승인 큐, 세션 관리 |
| TUI | internal/ui/tui | Bubble Tea 터미널 UI: 활동 스트림 및 승인 모달 |
| 대체 명령 생성기 | internal/shim | 셸 스크립트 대체 명령 생성, 실제 바이너리 경로 확인 |
| 네트워크 프록시 | internal/proxy | 대상별 정책을 적용하는 투명 HTTP/HTTPS 프록시 |
| 스포너 | internal/spawner | 모든 것을 오케스트레이션: 정책 → 데몬 → 대체 명령 → 프록시 → 샌드박스 → 에이전트 → TUI |
| macOS 샌드박스 | internal/spawner/jail_darwin.go | Seatbelt 프로파일로 커널 수준 강제를 위한 sandbox-exec |
가로챈 모든 동작은 ~/.agentguard/logs/YYYY-MM-DD.jsonl에 기록됩니다:
{"id":"a1b2c3","timestamp":"2026-03-22T14:30:00Z","session_id":"abc123","source":"shim","command":"git","args":["push","origin","main"],"decision":"deny","decided_by":"human","response_time_ms":3200}
{"id":"d4e5f6","timestamp":"2026-03-22T14:30:01Z","session_id":"abc123","source":"proxy","network_dst":"api.anthropic.com:443","decision":"allow","decided_by":"policy"}
표준 도구로 질의:
# 오늘 거부된 모든 동작
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decision == "deny")'
# 모든 네트워크 요청
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.source == "proxy")'
# 사람 승인이 필요했던 명령
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decided_by == "human")'
| 플랫폼 | 대체 명령 | 프록시 | sandbox-exec | 파일 읽기 거부 |
|---|---|---|---|---|
| macOS (Apple Silicon) | 예 | 예 | 예 | 예 |
| macOS (Intel) | 예 | 예 | 예 | 예 |
| Linux | 예 | 예 | 아니요 (향후: 네임스페이스 + seccomp) | 아니요 |
| Windows | 예 | 예 | 아니요 (향후: Job Objects) | 아니요 |
위협 모델: 에이전트는 신뢰할 수 없습니다. 다음과 같은 시도를 할 수 있습니다:
rm -rf /, sudo).env, 개인 키)