Le modèle de sécurité

Le modèle de sécurité de ZeroClaw contrôle ce que l’agent est autorisé à faire à l’exécution. Il comporte six couches. De la plus externe à la plus interne :

Appairage des canaux et contrôle d’accès

Avant qu’un message provenant d’un canal n’atteigne l’agent, l’appairage et la liste d’autorisation du canal sont vérifiés. allowed_users, allowed_chats, les listes d’autorisation d’IP pour les webhooks, tout est appliqué au niveau de l’adaptateur de canal, avant que le runtime ne voie l’événement.

Docs : la page de chaque canal sous Channels.

Niveau d’autonomie

Le bouton à grain grossier. Trois paramètres :

• ReadOnly : l’agent peut observer (lire des fichiers, interroger la mémoire, récupérer les URL qu’il est autorisé à récupérer) mais ne peut ni écrire ni exécuter de commandes.
• Supervisé (par défaut) : les opérations à faible risque s’exécutent ; celles à risque moyen demandent l’avis de l’opérateur ; celles à risque élevé sont bloquées.
• Full : aucun point d’approbation ; workspace_only est implicitement désactivé. forbidden_paths, forbidden_commands et le bac à sable du système d’exploitation restent appliqués.

Docs : Niveaux d’autonomie.

Règles de limite d’espace de travail et de chemins

L’agent fonctionne dans un répertoire de travail configuré. Les commandes file_read, file_write et shell (pour les commandes qui interagissent avec le système de fichiers) refusent les chemins situés en dehors de ce répertoire, sauf si workspace_only = false.

Racines de sandbox par session (ACP et WebSocket de passerelle) : Lorsqu’une session est ouverte via ACP (session/new avec un paramètre cwd) ou via le WebSocket de passerelle (paramètre cwd au moment de la connexion), ce chemin devient la limite d’espace de travail SecurityPolicy pour tous les outils de fichiers et de shell pendant toute la durée de vie de la session. Le workspace_dir global du daemon reste le répertoire de données pour la mémoire, l’identité, cron et autres états persistants. Le modèle est le suivant : session cwd = limite du projet que l’agent peut toucher ; workspace_dir = emplacement où ZeroClaw stocke ses propres fichiers. Remarque : le prompt système de l’agent reflète actuellement le workspace_dir du daemon plutôt que le cwd de la session ; l’application des règles est correcte, mais l’emplacement signalé par le modèle peut différer.

Important : le paramètre cwd modifie le répertoire de l’hôte ZeroClaw dans lequel l’agent est isolé (sandbox), il n’affecte pas la machine sur laquelle les outils s’exécutent. L’utilisation des outils (commandes shell, lectures/écritures de fichiers) s’exécute toujours sur la machine qui fait tourner ZeroClaw. Si vous vous connectez à une instance ZeroClaw distante via le WebSocket de la passerelle, les appels d’outils opèrent sur le système de fichiers de la machine distante, et non sur votre machine locale. Pour les déploiements limités à localhost, cette distinction n’a pas d’importance, mais les configurations distantes doivent en tenir compte.

En dehors de l’espace de travail, les valeurs par défaut de forbidden_paths incluent /etc, /sys, /boot, ~/.ssh et d’autres racines sensibles. Les entrées absolues d’autorisation et d’interdiction utilisent une spécificité basée sur le préfixe de composant : l’entrée correspondante la plus spécifique l’emporte, l’interdiction étant prioritaire en cas d’égalité de profondeur. Cela permet à un sous-arbre interdit imbriqué de bloquer une partie de l’espace de travail ou une racine autorisée, sans que des valeurs par défaut larges telles que /home supplantent une autorisation plus étroite configurée par l’opérateur.

Stratégie des commandes shell

Pour les invocations de shell :

• allowed_commands : si non vide, le shell n’exécute que les commandes dont le nom de base figure dans cette liste
• forbidden_commands : liste de refus explicite (rm -rf /, shutdown, opérations du noyau)
• validate_command_execution : une passe de correspondance de motifs qui recherche les drapeaux dangereux, les pipelines et les formes d’arguments

Le validateur s’exécute avant que la commande n’atteigne le shell. Une commande bloquée se manifeste sous forme d’une erreur d’outil que le modèle peut voir et à laquelle il peut réagir.

Bac à sable au niveau du système d’exploitation

Lorsqu’un backend de sandbox est disponible, les invocations d’outils s’exécutent à l’intérieur de celui-ci :

Le bac à sable limite l’accès au système de fichiers à l’espace de travail, supprime la connectivité réseau sauf pour ce dont l’outil a explicitement besoin, et retire l’accès aux secrets du processus parent.

Docs : Isolation des processus.

Reçus d’outils

Les reçus d’outils fournissent une preuve HMAC qu’un appel d’outil réussi et son résultat sont passés par le runtime. Lorsque les reçus sont activés, les sorties d’outils réussies reçoivent un reçu HMAC-SHA256 sur l’appel et le résultat, et le reçu est réinjecté dans la conversation avec le résultat de l’outil.

Les reçus aident à détecter les affirmations d’outils fabriquées. Ils ne constituent pas un journal d’audit chaîné ou durable aujourd’hui : les clés de reçus sont éphémères, les reçus ne sont pas contresignés avec le hachage de la conversation, et le stockage persistant des reçus est encore un travail futur.

Docs : Reçus d’outils.

Portes supplémentaires

Au-delà des six couches :

• Contrôle par OTP : [security.otp] gated_actions = ["shell", "browser", "file_write"] exige un code à usage unique avant chaque action listée. Utile pour les scénarios d’accès à distance.
• Arrêt d’urgence : zeroclaw estop interrompt tous les appels d’outils en cours. Avec [security.estop] enabled = true, la reprise nécessite un OTP.
• Protection contre l’injection de prompts : analyse la sortie du modèle à la recherche de schémas d’injection connus avant la validation des appels d’outils.
• Détecteur de fuites : analyse les réponses des canaux sortants à la recherche d’identifiants et supprime les correspondances avant la transmission. Il prend en charge les schémas déterministes d’identifiants et peut également exécuter une heuristique autonome sur les jetons à haute entropie.
• Garde d’appairage : appairage des appareils pour l’authentification de canal ; empêche les identifiants volés de fonctionner sur un nouvel appareil.

Configuration du détecteur de fuites

Configurer la détection des fuites sortantes dans sa propre section TOML :

[security.leak_detection]
enabled = true
sensitivity = 0.7
high_entropy_tokens = true

enabled = false désactive entièrement le détecteur de fuites sortantes. high_entropy_tokens = false désactive uniquement l’heuristique d’entropie autonome ; les motifs d’identifiants déterministes s’exécutent toujours. sensitivity accepte de 0.0 à 1.0 ; des valeurs plus élevées sont plus agressives.

La table complète des champs et les valeurs par défaut se trouvent dans la référence de configuration.

Lorsque les choses tournent mal

Un appel d’outil bloqué ne se termine pas silencieusement en échec :

1. Le validateur de sécurité renvoie une erreur
2. Le runtime l’emballe dans un ToolResult::Err et le renvoie au modèle.
3. Le modèle voit « Erreur : commande shell bloquée par la politique : motif interdit rm -rf / » et peut réessayer, s’excuser ou demander à l’utilisateur

Si un outil est exclu du canal via [autonomy].non_cli_excluded_tools (qui contrôle les canaux non-CLI en tant que groupe), il n’est tout simplement pas présenté au modèle sur ces canaux. Le modèle ne voit jamais un outil qu’il ne peut pas utiliser.

Posture par défaut

Prêt à l’emploi :

• Autonomie : Supervisé
• Espace de travail uniquement : true
• Sandbox : détection automatique (utilise ce que le système d’exploitation fournit)
• Journalisation des audits : false (activer explicitement)
• OTP : false
• Arrêt d’urgence : false

C’est un juste milieu raisonnable, suffisamment sûr pour un ordinateur portable, suffisamment permissif pour ne pas frustrer. Renforcez-le pour la production (OTP, audit, outils restreints) ou assouplissez-le jusqu’à YOLO pour une machine de développement.