codexpi/docs/security.md

# Modèle de sécurité

CodexPi est un outil d'administration puissant. Il doit rester sur un réseau local de confiance ou derrière Tailscale Serve et ne doit jamais être directement exposé à Internet.

## Protections mises en œuvre

- seul nginx est publié sur le LAN au port `8765` ; FastAPI `8000` et Django `8001` restent internes à Docker ;
- aucun UPnP, DMZ, Funnel ou transfert de port de box ;
- sessions et authentification Django, mot de passe Argon2, cookies `Secure`, `HttpOnly`, `SameSite=Strict` ;
- CSRF sur les mutations et contrôle d'origine des WebSockets ;
- limite par IP, délai progressif et verrouillage temporaire après les échecs de connexion ;
- journal JSONL en mode 0600 sans mot de passe, cookie, jeton Codex ou credential OpenAI ;
- CSP, anti-framing, nosniff, politique de référent et permissions navigateur restrictives ;
- conteneurs non-root, capacités Linux supprimées, système de fichiers racine en lecture seule et `no-new-privileges` ;
- projets sous racines autorisées, résolution canonique, rejet des traversées et symlinks sortants ;
- propagation unidirectionnelle des sous-montages de la racine de projets (`rslave`), sans propagation des montages du conteneur vers l'hôte ;
- concurrence Codex bornée et sérialisation par projet pour éviter les écritures simultanées dans un même espace de travail ;
- groupes limités à des projets locaux explicitement sélectionnés et appartenant au même propriétaire ; un projet peut rejoindre plusieurs groupes et les chemins des autres membres ne sont exposés qu’à Codex SAFE comme références de lecture, sans ajouter de racine d’écriture ;
- groupes compatibles avec SAFE et `FULL ACCESS` : Codex SAFE reçoit les chemins voisins en lecture seule par sandbox ; en `FULL ACCESS`, les chemins sont transmis avec une consigne de consultation, sans prétendre fournir une frontière d’écriture ; Claude et OpenCode en SAFE ne reçoivent que les noms et comptes rendus inter-projets ;
- processus lancés avec tableaux d'arguments, sans interpolation shell de saisie utilisateur ;
- actions Git et Docker destructrices confirmées, aucune fonction prune globale ;
- `FULL ACCESS` désactivé par défaut et confirmé explicitement ; dans ou hors d’un groupe, ce mode contourne le sandbox et le dossier courant ne constitue donc plus une frontière d’écriture ;
- Git facultatif : le mode SAFE combine l'exécution hors dépôt avec un sandbox `workspace-write` limité au projet ;
- debug Django/FastAPI et rechargement automatique désactivés ; secrets exclus de Git.
- connecteur distant limité à un dossier, aux fichiers texte de 2 Mo et aux opérations liste/lecture/écriture ; jeton révocable et aucun terminal distant.
- bridge IA limité aux adresses privées, associé par code temporaire et protégé
  par un jeton aléatoire chiffré au repos ; le proxy PC n’accepte que les routes
  Ollama nécessaires à la découverte et à l’inférence, avec une taille de requête
  bornée, et Ollama reste lié à localhost ; la configuration OpenCode générée et
  son jeton restent sous `data/local-ai/` en mode privé ;
- règles communes versionnées et consignes projet injectées comme contexte, sans jamais remplacer les contrôles d’autorisation du backend ;
- agent maître isolé derrière un socket Unix et un jeton local `0600`, réservé aux administrateurs avec confirmation explicite des demandes privilégiées, désactivé tant que le propriétaire ne l’installe pas sur l’hôte ;
- approbations d’orchestration attachées à une empreinte ou un commit précis, invalidées par toute modification ultérieure.
- chantier autonome réservé au propriétaire et démarré par une mutation CSRF explicite ; projets cibles résolus côté serveur dans son périmètre, un seul chantier actif, verdict du maître structuré et relances de correction bornées ; un blocage peut créer au maximum trois missions `CodexPi (Self)` dans un fil persistant, mais seule une réponse structurée `fixed` et testée permet une reprise automatique, tandis que `needs_user`, une autorité absente, un secret ou une opération irréversible maintiennent le blocage ; l’agent Self ne peut ni écrire directement dans SQLite, ni forcer un statut, ni modifier l’ordre, la cible ou le risque ; une reprise peut préciser les prompts mais ne peut changer ni l’ordre, ni la cible, ni le risque ; les interdictions de suppression, de migration irréversible et de contournement de sécurité des étapes restent applicables à chaque transmission.
- exécution hôte des conversations limitée au projet global Pi Doctor/Agent Raspberry Pi déjà confirmé en `FULL ACCESS` et au propriétaire initial ; socket Unix et jeton `0600`, historique et file d’attente persistés, autres projets maintenus dans le worker conteneurisé.
- centre de coordination réservé au propriétaire initial et mutations protégées par CSRF ; une réponse à une décision reprend le fil mais n’élargit jamais ses permissions et ne vaut ni confirmation destructive implicite, ni fourniture d’un secret absent ;
- incidents techniques enregistrés sans le prompt complet dans la notification ; la mission de réparation reçoit le contexte nécessaire dans un fil privé de `CodexPi (Self)`, refuse le rejeu aveugle et exige une décision humaine pour les secrets, changements d’autorité et opérations irréversibles ;
- agents spécialisés créés en SAFE dans des ateliers séparés, projets sources fournis en lecture, appel par compétence explicite et profondeur de délégation limitée à deux ; un spécialiste ne peut ni s’accorder `FULL ACCESS`, ni déployer, ni devenir l’intégrateur du projet appelant ;
- budgets de ressources non destructifs : les seuils et priorités ne concernent que l’admission des nouvelles tâches, tandis qu’un dépassement de durée produit une alerte sans tuer, suspendre ou préempter le processus actif ;
- catégories Web Push filtrées par préférence utilisateur avant mise en file, abonnements privés au compte et liens de notification limités aux routes internes de l’application.
- réconciliation de stockage en dry-run par défaut : bases ouvertes en lecture seule et absence, illisibilité ou schéma incomplet traités en mode fermé ; un `data/` symbolique n'est jamais parcouru ; symlinks et tous leurs parents sont refusés ; références de conversation (y compris parentes) et sessions actives sont exclues ; état vivant relu sous verrou avant déplacement et admissions SQLite bloquées par `BEGIN IMMEDIATE` pendant toute la fenêtre critique ; worktrees sales ou verrouillés protégés ; quarantaine et restauration exigent chacune une confirmation liée à leur plan ou reçu, sont sérialisées par `flock` et journalisées dans un fichier privé `0600` ; aucune purge automatique ni ouverture implicite des profils Chromium.

## Limite importante

Le conteneur API accède au socket Docker pour fournir les actions demandées. Ce socket est une capacité très privilégiée : seuls des utilisateurs CodexPi de confiance doivent pouvoir se connecter. En particulier, `FULL ACCESS` peut écrire hors du projet courant dans les chemins visibles du conteneur et avoir des conséquences sur l'hôte ; l'avertissement n'est pas cosmétique. Sauvegardez les projets et limitez les membres/ACL du tailnet.

L’auto-réparation de cet accès ne relâche pas l’isolation du conteneur : l’API reste non-root, sans capacités Linux et avec `no-new-privileges`. L’installateur génère les unités avec les UID/GID numériques du propriétaire du projet, sans dépendre de son nom. Un service hôte sous ce compte compare seulement le GID du socket au groupe supplémentaire du conteneur et recrée l’API en cas d’écart, après la fin des tâches actives.

L'audit et les procédures de révocation figurent dans [SECURITY_AUDIT.md](SECURITY_AUDIT.md).