AgentGuard

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.

Como Funciona

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.

Início Rápido

Compilar

go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/

Ambos os binários devem estar no mesmo diretório.

Criar uma Política

agentguard init

Isso cria .agentguard/policy.yaml no diretório atual. Edite-o para atender suas necessidades.

Executar um Agente (TUI Interativa)

agentguard run -- python my_agent.py

A TUI assume o terminal e mostra:

• Fluxo de atividade ao vivo (cada ação interceptada)
• Solicitações de aprovação para comandos ambíguos (pressione Y/N/A/B)
• Eventos de permitir/negar rede do proxy
• Eventos de violação da sandbox
• stdout/stderr do agente (alternar com Tab)

Executar um Agente (Headless)

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

Referência da CLI

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

Arquivo de Política

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):

1. ./.agentguard/policy.yaml (local ao projeto)
2. ~/.agentguard/policy.yaml (global do usuário)
3. Padrões embutidos

Exemplo de Política

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"

Ordem de Avaliação das Regras

1. Regras de negação específicas — verificadas primeiro. Se corresponderem, a ação é bloqueada imediatamente.
2. Regras de permissão — verificadas em segundo lugar. Se corresponderem, a ação é permitida.
3. Regras de negação abrangentes (ex.: deny network *) — verificadas em terceiro lugar. Atuam como negação padrão.
4. Nenhuma correspondência — o humano é solicitado (TUI) ou negado automaticamente (headless).

Tipos de Regra

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.

Controles da TUI

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

O Que Cada Camada Captura

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

Arquitetura