AgentGuard

Sandbox Zero Trust pour agents IA autonomes.

AgentGuard enveloppe tout agent IA (LangChain, CrewAI, AutoGen, scripts personnalisés) avec des rails de sécurité. Un simple changement de commande :

# Avant (dangereux — l'agent a un accès complet au système)
python my_agent.py

# Après (en bac à sable)
agentguard run -- python my_agent.py

AgentGuard intercepte chaque commande shell, modification de fichier et requête réseau effectuée par l'agent. Les actions sûres sont automatiquement autorisées, les actions dangereuses sont automatiquement bloquées, et tout le reste invite l'humain à approuver.

Comment ça marche

AgentGuard dispose de quatre couches de défense qui fonctionnent ensemble :

┌─────────────────────────────────────────────────────────────┐
│ Couche 0 : Prison de fichiers (sandbox-exec sur macOS)      │
│   Application au niveau du noyau. Restreint les écritures   │
│   de fichiers et le réseau au niveau des appels système.    │
│   L'agent ne peut pas contourner depuis l'espace utilisateur.│
│   Bloque open() de Python, requests.post(), etc.            │
├─────────────────────────────────────────────────────────────┤
│ Couche 1 : Proxy réseau                                     │
│   Proxy HTTP/HTTPS transparent. Chaque appel réseau de      │
│   l'agent est vérifié par rapport à la politique.           │
│   Autorisation/refus par destination avec visibilité totale │
│   dans la TUI.                                              │
├─────────────────────────────────────────────────────────────┤
│ Couche 2 : Shims de PATH                                    │
│   Scripts shell shim qui interceptent des commandes comme   │
│   git, pip, curl, rm. Chaque shim demande la permission au  │
│   démon avant d'exécuter le vrai binaire.                   │
├─────────────────────────────────────────────────────────────┤
│ Couche 3 : Moteur de politique + Démon d'approbation        │
│   Règles basées sur YAML évaluant chaque action interceptée.│
│   Autorise automatiquement les commandes sûres, bloque      │
│   automatiquement les dangereuses, invite l'humain pour     │
│   tout le reste.                                            │
└─────────────────────────────────────────────────────────────┘

Aucune couche unique ne constitue la limite de sécurité. Elles travaillent ensemble — défense en profondeur.

Démarrage rapide

Compilation

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

Les deux binaires doivent être dans le même répertoire.

Créer une politique

agentguard init

Ceci crée .agentguard/policy.yaml dans le répertoire courant. Modifiez-le selon vos besoins.

Lancer un agent (TUI interactif)

agentguard run -- python my_agent.py

La TUI prend le contrôle du terminal et affiche :

• Flux d'activité en direct (chaque action interceptée)
• Invites d'approbation pour les commandes ambiguës (appuyez sur Y/N/A/B)
• Événements d'autorisation/refus réseau du proxy
• Événements de violation de bac à sable
• stdout/stderr de l'agent (basculer avec Tab)

Lancer un agent (sans interface)

Pour les outils interactifs comme Claude Code qui ont besoin du terminal :

agentguard run --headless -- claude

L'agent obtient le terminal directement. AgentGuard s'exécute silencieusement en arrière-plan. Tous les événements sont enregistrés dans ~/.agentguard/logs/headless.log. Surveillez dans un autre terminal :

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

Référence CLI

agentguard run [flags] -- <command> [args...]
    --policy <path>     Utiliser un fichier de politique spécifique
    --headless          Pas de TUI — l'agent obtient le terminal
    --default-allow     Autoriser automatiquement les décisions PROMPT en mode headless (défaut : auto-deny)
    --no-sandbox        Désactiver sandbox-exec (shims et proxy toujours actifs)

agentguard init         Créer un fichier de politique par défaut
agentguard version      Afficher la version

Fichier de politique

Les politiques sont des fichiers YAML qui définissent ce que l'agent peut et ne peut pas faire. AgentGuard vérifie trois emplacements (dans l'ordre) :

1. ./.agentguard/policy.yaml (local au projet)
2. ~/.agentguard/policy.yaml (global utilisateur)
3. Valeurs par défaut intégrées

Exemple de politique

version: 1

deny:
  # Bloquer les commandes dangereuses
  - command: "rm"
    args: "-rf *"
    reason: "La suppression forcée récursive est trop dangereuse"
  - command: "sudo"
    args: "*"
    reason: "L'escalade de privilèges n'est pas autorisée"
  - command: "chmod"
    args: "777 *"
    reason: "Les permissions en écriture mondiale sont dangereuses"

  # Bloquer la lecture de fichiers sensibles (appliqué par sandbox-exec)
  - file:
      path: "*.env"
      action: "read"
      reason: "Ne pas laisser l'agent lire les fichiers .env"
  - file:
      path: "*.pem"
      action: "read"
      reason: "Ne pas laisser l'agent lire les clés privées"

allow:
  # Commandes en lecture seule sûres
  - command: "ls"
  - command: "cat"
  - command: "pwd"
  - command: "echo"
  - command: "grep"
  - command: "head"
  - command: "tail"
  - command: "wc"

  # Git en lecture seule
  - command: "git"
    args: "status"
  - command: "git"
    args: "log *"
  - command: "git"
    args: "diff *"

  # Autoriser les écritures dans l'espace de travail
  - file:
      path: "/tmp/workspace/**"
      action: "write"

  # Autoriser des endpoints API spécifiques
  - network:
      destination: "api.anthropic.com:443"
  - network:
      destination: "api.github.com:443"

Ordre d'évaluation des règles

1. Règles de refus spécifiques — vérifiées en premier. Si correspondance, l'action est immédiatement bloquée.
2. Règles d'autorisation — vérifiées en second. Si correspondance, l'action est permise.
3. Règles de refus génériques (ex. deny network *) — vérifiées en troisième. Agit comme un refus par défaut.
4. Aucune correspondance — l'humain est invité (TUI) ou automatiquement refusé (headless).

Types de règles

Règles de commande — correspondent aux commandes shell par nom et motif d'argument :

- command: "git"
  args: "push *"
  reason: "Le push nécessite une approbation"

Règles de fichier — correspondent aux opérations sur les fichiers (appliquées par sandbox-exec) :

- file:
    path: "*.env"
    action: "read"     # "read" ou "write"
    reason: "Protéger les secrets"

Règles réseau — correspondent aux destinations réseau (appliquées par proxy + sandbox-exec) :

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

Utilisez * comme caractère générique dans les arguments de commande, les chemins de fichiers et les destinations réseau.

Contrôles TUI

Touche	Action	Quand
Y	Autoriser la requête en attente	Invite d'approbation visible
N	Refuser la requête en attente	Invite d'approbation visible
A	Autoriser + mémoriser pour cette session ("Toujours autoriser")	Invite d'approbation visible
B	Refuser + mémoriser pour cette session ("Bloquer pour toujours")	Invite d'approbation visible
Tab	Basculer le panneau stdout/stderr de l'agent	Toujours
Haut/Bas	Faire défiler le flux d'activité	Toujours
Q	Quitter (tue l'agent)	Toujours

Ce que chaque couche intercepte

Action de l'agent	Shims	Proxy	sandbox-exec
subprocess.run(["rm", "-rf", "/"])	Oui	-	-
subprocess.run(["git", "push"])	Oui	-	-
requests.post("https://evil.com")	-	Oui	Oui
urllib.request.urlopen("https://api.com")	-	Oui	Oui
open(".env", "r")	-	-	Oui
open("/etc/shadow", "w")	-	-	Oui
/usr/bin/curl https://evil.com (chemin absolu)	-	Oui	Oui

Architecture