Installer et configurer la CLI

CodeMender est un agent de sécurité du code IA autonome qui analyse, vérifie et corrige les failles de cybersécurité profondes de votre codebase. Avant d'exécuter CodeMender, téléchargez la CLI et initialisez les options de l'espace de travail.

Architecture et modèle de sécurité

CodeMender utilise un modèle d'exécution local en priorité :

• Moteur de raisonnement hébergé : le raisonnement agentique, la modélisation des menaces et la logique d'orchestration s'exécutent de manière sécurisée dans Cloud de Confiance by S3NS sur Gemini Enterprise Agent Platform.
• CLI d'exécution locale : le code source ne quitte jamais votre poste de travail ni votre conteneur CI/CD de manière groupée. L'outil de CLI cm local exécute des lectures de fichiers, des vérifications de compilation locales et des vérifications d'exploitation de preuve de concept (PoC) dans votre bac à sable local. Il n'envoie que des extraits de code chirurgicaux et des résultats d'exécution d'outils au backend cloud via l'API Interactions sur Gemini Enterprise Agent Platform.

Configuration de l'environnement

Pour commencer à utiliser CodeMender, configurez votre projet Cloud de Confiance , téléchargez et installez la CLI, configurez vos identifiants et votre projet cible, puis initialisez votre espace de travail.

Configuration du projet et autorisations IAM

Avant de télécharger la CLI et de configurer les identifiants, assurez-vous que le projet Cloud de Confiance cible est correctement configuré avec les API et les autorisations requises.

API requises

Assurez-vous que les API Cloud de Confiance by S3NS suivantes sont activées dans votre projet :

1. API Agent Platform (aiplatform.googleapis.com) : gère le streaming et la gestion des sessions actives.
2. API Cloud Resource Manager (cloudresourcemanager.googleapis.com) : valide les états d'authentification des utilisateurs et les métadonnées du projet.

Rôle IAM prédéfini recommandé

Pour exécuter les commandes de la CLI, les utilisateurs doivent disposer du rôle IAM suivant :

• Utilisateur Agent Platform (roles/aiplatform.user) : permet aux utilisateurs de créer, de diffuser et de gérer des sessions actives.

Télécharger et installer CodeMender CLI

Les binaires de la CLI CodeMender sont hébergés dans Artifact Registry. Sélectionnez l'onglet correspondant à votre système d'exploitation pour télécharger et installer la CLI.

Configurer les identifiants et le projet Cloud de Confiance

Comme la CLI CodeMender interagit avec le moteur de raisonnement hébergé dans le cloud via l'API Interactions, vous devez configurer les Cloud de Confiance by S3NS identifiants par défaut de l'application (ADC) et spécifier votre projet cible dans votre environnement.

1. Pour vous authentifier, exécutez la commande suivante et suivez les invites de connexion :

   gcloud auth application-default login
   

2. Pour la variable d'environnement GOOGLE_CLOUD_PROJECT, indiquez l'ID de votre projet Cloud de Confiance  :

   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   

   Vous pouvez également configurer votre projet gcloud CLI actif :

   gcloud config set project PROJECT_ID
   

   Remplacez PROJECT_ID par l'ID du projet Cloud de Confiance .

Initialiser l'espace de travail

Après avoir configuré vos identifiants et votre projet cible, vous devez initialiser CodeMender dans votre environnement local. L'initialisation de CodeMender prépare votre espace de travail local en créant des fichiers de suivi de l'état et en établissant des paramètres de connexion au moteur de raisonnement hébergé dans le cloud.

Exécutez cm init à partir du répertoire racine de votre codebase pour créer des fichiers de suivi de l'état local et établir des configurations de référence :

cm init

Utilisez l'indicateur --verify pour tester la connectivité au moteur de raisonnement hébergé dans le cloud et vérifier les paramètres de l'espace de travail :

cm init --verify

Paramètres de configuration (config.yaml)

L'objectif principal de config.yaml est d'aligner les comportements de l'agent CodeMender sur la sécurité, les contraintes d'environnement et les besoins en performances de votre système local.

Étant donné que l'agent IA hébergé exécute des commandes locales (comme la compilation de code, l'exécution de tests ou la modification de fichiers) à l'aide de votre client daemon local, ce fichier de configuration sert de limite définissant ce que l'agent est autorisé à faire ou non.

Utilisation

• Emplacement : par défaut, la CLI lit ce fichier à partir de ~/.codemender/config.yaml. Vous pouvez remplacer l'espace de travail et le répertoire de configuration en définissant la variable d'environnement CM_HOME (par exemple, CM_HOME=/path/to/custom/dir, qui lit /path/to/custom/dir/config.yaml).
• Exécution : lorsque vous exécutez des commandes telles que cm find, cm verify ou cm fix, le client local lit ce fichier pour configurer les paramètres de sécurité, appliquer les contournements du système et spécifier les fichiers ou répertoires à ignorer.

Paramètres par défaut de base

Voici la signification des principaux paramètres par défaut :

• human_confirmation: true (ou require_confirmation: true)

  • Ce que cela signifie : par défaut, CodeMender ne peut pas modifier de fichier sur votre disque ni exécuter de commandes shell sans vous demander explicitement une confirmation [Y/n] dans le terminal.
  • Pourquoi ce paramètre est-il défini par défaut ? CodeMender peut générer des correctifs spéculatifs ou tenter d'exécuter des scripts d'exploitation pour vérifier une faille. Forcer la confirmation humaine permet d'éviter les modifications accidentelles du système ou l'exécution de code non autorisée dans votre environnement local.
  • Contournement : pour les pipelines CI/CD non interactifs, cette valeur peut être définie sur false.

• confirm_writes: false

  • Signification : désactive les invites interactives pour les modifications de fichiers, ce qui permet à l'agent CodeMender d'écrire des correctifs de sécurité et de modifier les fichiers sources directement sur votre disque local sans attendre l'approbation d'un humain.
  • Pourquoi cette valeur par défaut ? Par défaut, CodeMender définit ce garde-fou sur true pour appliquer un workflow "Human-in-the-Loop". Étant donné que CodeMender agit sur votre codebase local, une confirmation manuelle (par exemple, Write? [Y/n]) empêche l'agent d'apporter des modifications spéculatives, incorrectes ou destructrices à vos fichiers sources. Vous ne devez définir cette option sur false que lorsque vous exécutez des pipelines CI/CD automatisés et sans interface graphique, ou des bacs à sable isolés et jetables.

• include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hpp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php"]

  • Signification : définit la liste explicite des extensions de fichier que vous autorisez CodeMender à ingérer et à analyser lors de l'analyse de votre espace de travail. CodeMender ignore automatiquement tous les fichiers de votre dépôt dont l'extension n'est pas spécifiée dans cette liste.
  • Pourquoi cette valeur est-elle définie par défaut ? Cette liste inclut par défaut les principaux langages de programmation afin de maximiser l'efficacité de l'analyse et d'éviter que l'agent ne perde du temps et des jetons sur des fichiers texte, des artefacts de compilation ou des fichiers binaires non pertinents. Toutefois, comme les applications modernes intègrent souvent des failles dans les configurations de déploiement ou les outils d'automatisation, vous pouvez étendre manuellement cette liste par défaut dans config.yaml pour inclure les fichiers de configuration, les formats de script et les fichiers IaC (par exemple, les scripts shell, XML, YAML, les propriétés et les fichiers JSON) afin que CodeMender ne les ignore pas silencieusement.

• exclude_dirs: ["node_modules", "vendor", "dist", "bin", "target", "obj", "build", ".gradle"]

  • Ce que cela signifie : CodeMender ignorera complètement ces répertoires lors de l'analyse de l'espace de travail et du code.
  • Pourquoi ce paramètre est-il défini par défaut ? Les dossiers de dépendances ou de compilation volumineux entraînent une latence importante et une pénalité de jeton. Le fait de les exclure par défaut garantit des performances élevées et des temps de réponse rapides. Vous pouvez personnaliser cette liste dans config.yaml pour inclure ou exclure des répertoires spécifiques en fonction de la structure de votre projet.

• project_paths: []

  • Signification : liste des chemins d'accès aux répertoires auxquels CodeMender peut accéder (lecture/écriture) lors de l'exécution de l'outil.
  • Pourquoi ce paramètre est-il défini par défaut ? Par défaut, il est vide, ce qui limite l'agent au répertoire cible de l'analyse. Si votre processus de compilation ou de test nécessite d'accéder à des fichiers en dehors du répertoire cible de l'analyse, vous devez ajouter ces chemins d'accès ici.
  • Répertoire d'artefacts : l'agent peut également écrire dans un répertoire d'artefacts par session (~/.codemender/artifacts/<session_id>/ ou l'équivalent sous $CM_HOME).
  • Fichiers temporaires : lorsque le bac à sable est activé, le répertoire hôte /tmp est toujours bloqué, même si vous ajoutez /tmp à project_paths. Les outils qui respectent TMPDIR utilisent plutôt un répertoire temporaire dans le répertoire des artefacts.

• sandbox :

  • Signification : bloc de configuration pour l'environnement de bac à sable au niveau du processus.
  • Sous-paramètres :
    • enabled: true : (booléen) active ou désactive le bac à sable. Si vous définissez cette option sur true (par défaut), l'agent exécute les outils dans le bac à sable local. Si vous le définissez sur false, l'agent exécute les outils directement sur le système hôte sans isolation.
    • mounts : (Objet)
      • target_dir: "." : (chaîne) répertoire à installer en tant qu'espace de travail actif dans le bac à sable. La CLI résout les chemins relatifs par rapport à la racine de l'espace de travail.
    • network : (objet)
      • profile: "permissive-closed" : (String) Profil d'accès au réseau sortant dans le bac à sable. L'ajout à la liste d'autorisation de domaines ou de formats d'URL spécifiques n'est pas encore possible. Profils compatibles :
        • permissive-closed (par défaut) : isolement complet du réseau. Le bac à sable bloque toutes les connexions sortantes.
        • permissive-open : autorise un accès réseau sortant complet.

• security :

  • Signification : bloc de configuration pour les stratégies de sécurité.
  • Sous-paramètres :
    • protected_files: [] : (liste de chaînes) fichiers ou répertoires du système hôte que vous souhaitez installer en lecture seule dans le bac à sable pour les protéger contre toute modification (par exemple, ["~/.ssh/*"]). Accepte l'expansion de chemin (~) et les caractères génériques (*).

• model: "gemini-3.8-flash"

  • Signification : moteur d'intelligence par défaut qui alimente les boucles de raisonnement du backend.
  • Pourquoi cette option est-elle sélectionnée par défaut ? gemini-3.8-flash offre l'équilibre optimal entre vitesse, coût et raisonnement analytique requis pour suggérer des correctifs. (Les utilisateurs peuvent remplacer ce modèle par gemini-4-argon (Gemini 4 Argon) pour un raisonnement plus approfondi et plus complexe si nécessaire).

• vcs: { type: "git" }

  • Signification : définit le type de système de contrôle des versions utilisé par votre projet via la clé vcs. Si vous ne configurez pas cette option, l'outil tente d'identifier automatiquement les dépôts Git ou Mercurial. Si vous définissez vcs sur none, la CLI affiche un avertissement, mais poursuit l'exécution sans la fonctionnalité VCS. CodeMender s'appuie sur ce paramètre pour gérer les correctifs de sécurité spéculatifs, suivre les modifications de la codebase et s'intégrer à votre dépôt local.
  • Pourquoi est-ce l'option par défaut ? CodeMender est compatible avec les configurations Git, Mercurial ou VCS personnalisées. Git est le système par défaut, car il s'agit de la norme du secteur pour le suivi du contrôle des versions. Il garantit une intégration fluide des différences et la sécurité des annulations.

• build: { command: "make build && make test" }

  • Signification : définit la commande shell exacte que CodeMender exécute pour compiler et créer votre projet, ainsi que pour exécuter vos tests unitaires et de régression.
  • Pourquoi cette option est-elle définie par défaut ? Définir une commande de compilation et de test est essentiel pour le workflow de validation. Il permet à CodeMender de compiler votre projet et d'exécuter votre suite de tests existante dans l'environnement de bac à sable isolé pour prouver que le correctif de sécurité généré atténue bien la faille sans perturber la logique d'application existante.

Exécution en bac à sable

Pour protéger votre poste de travail contre les modifications involontaires de fichiers ou les effets secondaires inattendus des outils, la CLI CodeMender s'exécute par défaut dans un bac à sable au niveau de l'OS. Vous pouvez désactiver le bac à sable de manière persistante dans la configuration ou le contourner par commande à l'aide des indicateurs de la CLI.

Bien que ce bac à sable offre une première couche de protection sur votre poste de travail, il offre une protection de sécurité plus faible que l'exécution de l'agent dans une machine virtuelle (VM) entièrement isolée :

• Linux : utilise des espaces de noms de noyau (CLONE_NEWNS, CLONE_NEWUSER, etc.) et des filtres seccomp pour isoler les points d'installation et limiter les appels système.
• macOS : utilise le mécanisme sandbox-exec (Seatbelt) intégré.
• Windows (expérimental) : utilise l'isolation AppContainer et les listes de contrôle d'accès (LCA). Le bac à sable sous Windows est expérimental et peut nécessiter des droits d'administrateur ou être incompatible avec certaines configurations système.

Comportement du bac à sable

Lorsque le bac à sable est actif :

1. Isolation du système de fichiers : l'agent ne peut lire et écrire des fichiers que dans les répertoires autorisés. Le bac à sable redirige toutes les écritures en dehors de ces répertoires vers un système de fichiers temporaire en mémoire (tmpfs) sans affecter votre système hôte.
2. Isolation du réseau : le bac à sable bloque l'accès au réseau sortant par défaut. Cela empêche l'agent (ou les outils de compilation qu'il appelle) d'établir des connexions externes inattendues ou de transmettre des données en dehors de l'espace de travail.

Accès au réseau pendant la compilation et la validation

Étant donné que le bac à sable permet l'isolation du réseau par défaut (sandbox.network.profile est défini sur permissive-closed par défaut), l'agent ne peut pas accéder à Internet lors de l'exécution de l'outil.

Cela introduit des limites pour les projets qui nécessitent de récupérer des dépendances externes lors des étapes de compilation ou de vérification (par exemple, l'exécution de npm install, pip install ou go get dans le cadre de build.command). Si votre processus de compilation tente d'accéder à des services Web externes, il échouera.

Gérer les dépendances réseau

Si votre projet nécessite un accès réseau pour les builds ou les tests, vous disposez des options suivantes :

• Prérécupérer les dépendances : installez toutes les dépendances requises sur le système hôte avant d'exécuter les commandes cm, afin que la commande de compilation n'ait pas besoin d'un accès réseau.

• Activez l'accès au réseau dans le bac à sable : modifiez le profil réseau dans votre config.yaml pour autoriser les connexions sortantes :

  sandbox:
    network:
      profile: "permissive-open"
  

• Contourner le bac à sable : exécutez la commande avec l'option --unrestricted pour désactiver complètement le bac à sable et les limites du système de fichiers pour cette exécution.

Configuration du bac à sable

Vous pouvez configurer et contrôler le bac à sable à l'aide des options suivantes :

• Configuration persistante (config.yaml) : vous pouvez personnaliser le comportement du bac à sable, les installations du système de fichiers, l'accès au réseau et les règles de sécurité en ajoutant des blocs sandbox, execution et security à votre fichier config.yaml. Pour en savoir plus, consultez Paramètres de configuration.
• Contrôler le bac à sable à l'aide de la CLI (--sandbox) : vous pouvez activer ou désactiver explicitement le bac à sable pour une seule exécution en transmettant --sandbox=true ou --sandbox=false à cm find, cm verify ou cm fix.
• Contourner l'isolation à l'aide de la CLI (--unrestricted) : vous pouvez contourner temporairement toutes les protections du bac à sable pour une seule exécution en transmettant l'indicateur --unrestricted. Cela désactive les limites de chemin d'accès au système de fichiers (permettant à l'agent d'accéder à n'importe quel chemin d'accès sur votre hôte) et désactive complètement l'isolation des conteneurs au niveau de l'OS (y compris l'isolation réseau).

Choisir un niveau d'isolation

En fonction de vos exigences de sécurité et de votre environnement de développement, vous pouvez choisir le niveau d'isolation approprié pour exécuter la CLI CodeMender.

Télémétrie

Pour nous aider à surveiller et à améliorer l'état des produits, nous collectons des données de télémétrie anonymes via lCLI. Nous anonymisons entièrement toutes les données collectées, y compris les métriques d'utilisation de base et les diagnostics de performances. La télémétrie ne collecte ni ne transmet jamais de code source, de contenu de fichier, de résultats, de correctifs ni d'identité d'utilisateur.

Par défaut, la télémétrie est activée. Si vous souhaitez désactiver la télémétrie, définissez la variable d'environnement CM_TELEMETRY_OPT_OUT sur 1 ou true.

Mettre à jour la CLI

CodeMender dispose d'un mécanisme de mise à jour intégré pour vous assurer que vous exécutez la dernière version de la CLI.

Vérifications automatiques des mises à jour

Par défaut, la CLI CodeMender recherche automatiquement les mises à jour en arrière-plan lorsque vous exécutez des commandes :

• Limitation : pour minimiser les frais généraux, la vérification automatique s'exécute au maximum une fois toutes les 24 heures.
• Terminal interactif (TTY) requis : la CLI ne recherche les mises à jour et ne vous y invite que lorsqu'elle s'exécute dans un terminal interactif. Dans les environnements non interactifs (tels que les pipelines ou scripts CI/CD), la vérification est ignorée et un avertissement est consigné dans stderr au maximum une fois par jour.
• Invite : si une nouvelle version est disponible, vous serez invité à l'installer sur stderr : none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): Si vous choisissez "oui" (y ou yes), CodeMender télécharge la mise à jour, remplace le binaire et se ferme. Vous devez exécuter à nouveau votre commande pour l'exécuter avec la nouvelle version. Si vous choisissez "Non", la mise à jour est ignorée et votre commande d'origine est exécutée.
• Tolérance hors connexion : si vous êtes hors connexion ou si le dépôt de la version est inaccessible, la vérification échoue de manière silencieuse et CodeMender continue d'exécuter votre commande.
• Contournement : vous pouvez contourner la vérification automatique des mises à jour en transmettant l'option --yes ou -y à n'importe quelle commande.

Mises à jour manuelles (cm update)

Vous pouvez forcer CodeMender à rechercher et à appliquer les mises à jour immédiatement en exécutant la commande update :

cm update

La commande cm update :

• Ignore la limitation de 24 heures.
• Télécharge et applique la mise à jour immédiatement sans demander confirmation (non interactif).
• Ne nécessite pas de terminal interactif (sans risque pour les scripts et la gestion de configuration).

Si la CLI est installée dans un répertoire système qui nécessite des autorisations élevées, exécutez la mise à jour avec sudo :

sudo cm update