Sécurité de Pi Agent et confiance du projet
Pi Agent s'exécute avec les permissions de votre utilisateur actuel.
Ce chapitre présente le mécanisme de confiance de projet, les limites de sécurité et les options d'exécution conteneurisée.
Modèle de sécurité de Pi Agent
Pi Agent est unagent de codage local—il s'exécute avec les permissions utilisateur que vous aviez lorsque vous l'avez démarré, et peut lire, écrire, modifier des fichiers et exécuter des commandes shell.
Cela signifie :
- Il peut accéder à tous les fichiers auxquels votre compte utilisateur peut accéder
- La gamme de commandes qu'il peut exécuter est exactement la même que ce que vous exécuteriez manuellement dans un terminal
- ilne dispose d'aucunmécanisme d'isolation par bac à sable intégré
C'est intentionnel — Pi Agent doit invoquer les chaînes d'outils du projet, exécuter des tests et installer des dépendances, ce qui nécessite de véritables autorisations système.
La philosophie de conception de Pi Agent est : ne pas fournir un bac à sable bâclé qui « semble sûr mais est facile à mal interpréter. »
L'isolation réelle doit provenir du niveau du système d'exploitation ou des frontières de virtualisation/conteneurs.
Mécanisme de confiance du projet
La confiance accordée au projet contrôle si Pi Agent charge la configuration et les extensions locales au projet.
Ce n'est pas un bac à sable — il contrôle uniquementce qui est chargé au démarrage, et ne restreint pas ce que le modèle peut faire pendant une conversation.
Quand une vérification de confiance est-elle déclenchée ?
Pi Agent déclenche une vérification de confiance lorsqu'il détecte l'un des éléments suivants dans le répertoire du projet :
- .pi/settings.json (fichier de configuration du projet)
- .pi/extensions, .pi/skills, .pi/prompts, .pi/themes (répertoires de ressources du projet)
- .pi/SYSTEM.md ou .pi/APPEND_SYSTEM.md (prompts système du projet)
- .agents/skills (répertoire Skills du projet)
Un répertoire .pi vide seul ne déclenchera pas de vérification de confiance.
Processus de décision de confiance
Pi Agent décide s'il faut charger les ressources du projet actuel dans un ordre fixe.
- Vérifier si trust.json contient une décision enregistrée (en remontant depuis le répertoire courant)
- Si oui, utiliser la décision enregistrée
- Sinon, suivre le comportement du paramètre defaultProjectTrust (par défaut : ask)
- Après que l'utilisateur a pris une décision, il peut choisir « Remember » pour l'écrire dans trust.json
Les décisions de confiance sont enregistrées par répertoire dans le fichier global ~/.pi/agent/trust.json.
Lors de la recherche, il effectue une correspondance avec ce fichier niveau par niveau en remontant les répertoires parents ; ce n'est que lorsqu'aucune décision enregistrée n'est trouvée qu'il revient à la logique defaultProjectTrust.
Lorsque vous entrez pour la première fois dans un projet non fiable, l'interface utilisateur affiche l'invite suivante :
检测到项目本地配置 .pi/settings.json 是否信任此项目并加载其配置与扩展?(y/n/always/never)
Le texte et les options de l'invite peuvent varier selon la version ; reportez-vous à l'interface utilisateur réelle.
La confiance accordée au projet contrôle uniquement le chargement des ressources protégées telles que les extensions et les compétences.
Les fichiers de contexte tels que AGENTS.md et CLAUDE.md sont chargés indépendamment de l'état de confiance.
Paramètre defaultProjectTrust
Ce paramètre détermine le choix par défaut de Pi Agent lorsque personne ne confirme ; le comportement diffère entre les modes interactif et non interactif.
| Valeur | Comportement en mode interactif | Comportement en mode non interactif |
|---|---|---|
| "ask" (par défaut) | Afficher une invite de confirmation de confiance | Ne pas charger les ressources du projet (comportement identique à "never") |
| "always" | Confiance automatique | Confiance automatique |
| "never" | Rejet automatique | Rejet automatique |
Méthode de configuration :
Exemples
"defaultProjectTrust": "always"
}
Vous pouvez également remplacer le comportement pour chaque invocation avec des arguments de ligne de commande :
# 本次运行信任项目 $ pi --approve $ pi -a # 本次运行不信任项目 $ pi --no-approve $ pi -na
Utilisez la commande /trust pour enregistrer les décisions
En mode interactif, vous pouvez utiliser la commande /trust à tout moment pour enregistrer une décision de confiance pour le projet actuel :
/trust
Cette commande écrit dans~/.pi/agent/trust.json, qui stocke les décisions de confiance enregistrées par répertoire.
/trust enregistre la décision actuelle mais ne recharge pas la session actuelle.
Si vous modifiez une décision de confiance, vous devez redémarrer Pi Agent pour que la modification prenne effet.
Considérations de sécurité pour le mode non interactif
En mode Print (-p), en mode JSON (--mode json) et en mode RPC (--mode rpc), Pi Agent n'affiche pas d'invites de confiance.
Le comportement dans ce cas dépend entièrement du paramètre defaultProjectTrust :
- Défini sur "ask" ou "never" : les ressources du projet sont ignorées
- Défini sur « always » : les ressources du projet sont chargées
Utilisez --approve ou --no-approve pour outrepasser temporairement ce comportement.
Exécution de code non fiable
Lorsque vous devez gérer des dépôts non fiables ou des tâches automatisées, il est recommandé d'exécuter Pi Agent dans un conteneur ou un bac à sable :
- Approche par conteneur: Exécuter l'ensemble du processus pi dans un conteneur Docker ou une VM
- Approche Gondolin: Exécuter pi sur l'hôte et acheminer l'exécution des outils vers une micro VM Gondolin
- Approche OpenShell: Exécuter l'ensemble du processus pi dans un bac à sable contrôlé par des politiques NVIDIA, en créant des bacs à sable via une passerelle
- Contrôle des montages: Monter uniquement les répertoires de travail auxquels l'agent doit accéder
- Gestion des identifiants: Évitez de monter le répertoire ~/.pi/agent/ de l'hôte ; transmettez une clé API temporaire à privilèges minimaux
- Isolation réseau: Si la tâche n'a pas besoin d'accéder au réseau, restreignez le réseau du conteneur
- Vérification des résultats: Examinez les diffs et les modifications avant de recopier la sortie vers un système fiable
Gondolin est un projet distinct de micro VM open source (une micro VM Linux locale nécessitant la prise en charge de QEMU) ; Pi achemine l'exécution des outils intégrés vers celle-ci via une extension d'exemple.
OpenShell viaopenshell sandbox create --from pipour créer des bacs à sable, vous devez d'abord vous inscrire et sélectionner une passerelle.
Le mode passerelle distante n'effectue pas de montage de liaison des répertoires locaux ; vous devez utiliser les commandes upload/download pour transférer des fichiers entre l'intérieur et l'extérieur du bac à sable. Les identifiants du modèle peuvent rester en dehors du bac à sable.
Si vous effectuez un montage de liaison du répertoire de travail de l'hôte dans le conteneur avec un accès en lecture-écriture, les opérations d'écriture à l'intérieur du conteneur affecteront toujours les fichiers de l'hôte.
Si vous avez besoin d'une protection plus stricte, utilisez des montages en lecture seule ou copiez les fichiers dans et hors du bac à sable.
Conseils de sécurité
Les recommandations de sécurité suivantes sont organisées par scénarios d'utilisation courants ; consultez-les avant de commencer.
| Scénario | Recommandation |
|---|---|
| Examen du code tiers | Exécuter dans un conteneur avec des montages en lecture seule |
| CI/CD automatisé | Utiliser des identifiants temporaires et restreindre la liste d'autorisation des outils |
| Configuration partagée par l'équipe | Utiliser le .pi/settings.json du projet, mais n'y mettez pas d'informations sensibles |
| Installation de paquets d'extension tiers | Vérifiez le code source avant d'installer ; les extensions peuvent exécuter du code arbitraire |
| Installation de Skills tierces | Vérifiez le contenu de SKILL.md ; les Skills peuvent demander au modèle d'effectuer des actions arbitraires |