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.

  1. Vérifier si trust.json contient une décision enregistrée (en remontant depuis le répertoire courant)
  2. Si oui, utiliser la décision enregistrée
  3. Sinon, suivre le comportement du paramètre defaultProjectTrust (par défaut : ask)
  4. 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.

ValeurComportement en mode interactifComportement en mode non interactif
"ask" (par défaut)Afficher une invite de confirmation de confianceNe pas charger les ressources du projet (comportement identique à "never")
"always"Confiance automatiqueConfiance automatique
"never"Rejet automatiqueRejet 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 :

Pi Agent 安全分层:进程权限、项目信任、容器隔离与 Gondolin 微 VM

  • 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énarioRecommandation
Examen du code tiersExé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'équipeUtiliser le .pi/settings.json du projet, mais n'y mettez pas d'informations sensibles
Installation de paquets d'extension tiersVérifiez le code source avant d'installer ; les extensions peuvent exécuter du code arbitraire
Installation de Skills tiercesVérifiez le contenu de SKILL.md ; les Skills peuvent demander au modèle d'effectuer des actions arbitraires
Autres extensions