Instala y configura la CLI

CodeMender es un agente de seguridad de código de IA autónomo que analiza, verifica y aplica parches a vulnerabilidades profundas de ciberseguridad en tu base de código. Antes de ejecutar CodeMender, descarga la CLI y, luego, inicializa las opciones del espacio de trabajo.

Arquitectura y modelo de seguridad

CodeMender usa un modelo de ejecución local primero:

• Motor de razonamiento alojado: El razonamiento de agentes, la creación de modelos de amenazas y la lógica de organización se ejecutan de forma segura en Cloud de Confiance by S3NS en Gemini Enterprise Agent Platform.
• CLI de ejecución local: El código fuente nunca sale de tu estación de trabajo ni del contenedor de CI/CD de forma masiva. La herramienta de CLI local de cm ejecuta lecturas de archivos, verificaciones de compilaciones locales y verificaciones de exploits de prueba de concepto (PoC) en tu zona de pruebas local, y envía solo fragmentos de código quirúrgicos y resultados de ejecución de herramientas al backend de la nube a través de la API de Interactions en Gemini Enterprise Agent Platform.

Configuración del entorno

Para comenzar a usar CodeMender, configura tu proyecto de Cloud de Confiance , descarga e instala la CLI, configura tus credenciales y el proyecto de destino, y, luego, inicializa tu espacio de trabajo.

Configuración del proyecto y permisos de IAM

Antes de descargar la CLI y configurar las credenciales, asegúrate de que el proyecto de Cloud de Confiance de destino esté configurado correctamente con las APIs y los permisos necesarios.

APIs requeridas

Asegúrate de que las siguientes APIs de Cloud de Confiance by S3NS estén habilitadas en tu proyecto:

1. API de Agent Platform (aiplatform.googleapis.com): Potencia la transmisión y la administración de las sesiones activas.
2. API de Cloud Resource Manager (cloudresourcemanager.googleapis.com): Valida los estados de autenticación de los usuarios y los metadatos del proyecto.

Rol de IAM predefinido recomendado

Para ejecutar los comandos de la CLI, se debe asignar a los usuarios el siguiente rol de IAM:

• Usuario de Agent Platform (roles/aiplatform.user): Permite que los usuarios creen, transmitan y administren sesiones activas.

Descarga e instala la CLI de CodeMender

Los objetos binarios de la CLI de CodeMender se alojan en Artifact Registry. Elige la pestaña de tu sistema operativo para descargar e instalar la CLI.

Configura las credenciales y el proyecto de Cloud de Confiance

Debido a que la CLI de CodeMender interactúa con el motor de razonamiento alojado en la nube a través de la API de Interactions, debes configurar Cloud de Confiance by S3NS las credenciales predeterminadas de la aplicación (ADC) y especificar el proyecto de destino en tu entorno.

1. Para autenticarte, ejecuta el siguiente comando y sigue las instrucciones de acceso:

   gcloud auth application-default login
   

2. Establece la variable de entorno GOOGLE_CLOUD_PROJECT en tu ID del proyecto Cloud de Confiance :

   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   

   Como alternativa, configura tu proyecto activo de gcloud CLI:

   gcloud config set project PROJECT_ID
   

   Reemplaza PROJECT_ID por el ID del proyecto de Cloud de Confiance .

Inicializa el espacio de trabajo

Después de configurar tus credenciales y el proyecto de destino, el siguiente paso es inicializar CodeMender en tu entorno local. La inicialización de CodeMender prepara tu espacio de trabajo local creando archivos de seguimiento de estado y estableciendo la configuración de conexión con el motor de razonamiento alojado en la nube.

Ejecuta cm init desde el directorio raíz de tu base de código para crear archivos de seguimiento de estado locales y establecer configuraciones de referencia:

cm init

Usa la marca --verify para probar la conectividad con el motor de razonamiento alojado en la nube y verificar la configuración del espacio de trabajo:

cm init --verify

Parámetros de configuración (config.yaml)

El objetivo principal de config.yaml es alinear los comportamientos del agente de CodeMender con la seguridad, las restricciones del entorno y las necesidades de rendimiento de tu sistema local.

Dado que el agente de IA alojado ejecuta comandos locales (como compilar código, ejecutar pruebas o editar archivos) con tu cliente de daemon local, este archivo de configuración actúa como el límite que define lo que el agente puede y no puede hacer.

Uso

• Ubicación: De forma predeterminada, la CLI lee este archivo desde ~/.codemender/config.yaml. Puedes anular el directorio de configuración y el espacio de trabajo configurando la variable de entorno CM_HOME (por ejemplo, CM_HOME=/path/to/custom/dir, que lee /path/to/custom/dir/config.yaml).
• Ejecución: Cuando ejecutas comandos como cm find, cm verify o cm fix, el cliente local lee este archivo para configurar parámetros de seguridad, aplicar omisiones del sistema y especificar qué archivos o directorios ignorar.

Configuración predeterminada principal

Esto es lo que significan los parámetros predeterminados principales:

• human_confirmation: true (o require_confirmation: true)

  • Qué significa: De forma predeterminada, CodeMender no puede modificar ningún archivo en tu disco ni ejecutar comandos de shell sin solicitarte explícitamente una confirmación de [Y/n] en la terminal.
  • Por qué esta es la opción predeterminada: CodeMender puede generar parches especulativos o intentar ejecutar secuencias de comandos de explotación para verificar una vulnerabilidad. Forzar la confirmación humana ayuda a evitar cambios accidentales en el sistema o la ejecución de código no autorizado en tu entorno local.
  • Omisión: Para las canalizaciones de CI/CD no interactivas, se puede establecer en false.

• confirm_writes: false

  • Qué significa: Inhabilita las indicaciones interactivas para las modificaciones de archivos, lo que permite que el agente de CodeMender escriba parches de seguridad y modifique los archivos de origen directamente en tu disco local sin esperar la aprobación humana.
  • Por qué este es el valor predeterminado: De forma predeterminada, CodeMender establece este límite de seguridad en true para aplicar un flujo de trabajo con intervención humana. Dado que CodeMender actúa sobre tu base de código local, requerir confirmación manual (por ejemplo, Write? [Y/n]) evita que el agente realice modificaciones especulativas, incorrectas o destructivas en tus archivos fuente. Solo debes cambiar esto a false cuando ejecutes en entornos de pruebas aislados y desechables o en canalizaciones de CI/CD automatizadas y sin interfaz gráfica.

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

  • Qué significa: Define la lista explícita de extensiones de archivos que autorizas a CodeMender a ingerir y analizar cuando explora tu espacio de trabajo. CodeMender omite automáticamente cualquier archivo de tu repositorio que tenga una extensión que no se especifique en esta lista.
  • Por qué esta es la opción predeterminada: Esta lista se establece de forma predeterminada en los principales lenguajes de programación para maximizar la eficiencia del análisis y evitar que el agente pierda tiempo y tokens en archivos de texto, artefactos de compilación o archivos binarios irrelevantes. Sin embargo, debido a que las aplicaciones modernas suelen incorporar vulnerabilidades en las configuraciones de implementación o las herramientas de automatización, puedes expandir manualmente esta lista predeterminada en config.yaml para incluir archivos de configuración, formatos de secuencias de comandos y archivos de IaC (por ejemplo, secuencias de comandos de shell, XML, YAML, propiedades y archivos JSON) para que CodeMender no los ignore de forma silenciosa.

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

  • Qué significa: CodeMender omitirá por completo estos directorios durante el análisis del espacio de trabajo y el análisis de código.
  • Por qué este es el valor predeterminado: Las carpetas de compilación o dependencia grandes activan una penalización masiva de latencia y tokens. Mantenerlos excluidos de forma predeterminada garantiza un alto rendimiento y tiempos de respuesta rápidos. Puedes personalizar esta lista en config.yaml para incluir o excluir directorios específicos según la estructura de tu proyecto.

• project_paths: []

  • Qué significa: Es una lista de rutas de directorio a las que CodeMender puede acceder (leer o escribir) durante la ejecución de la herramienta.
  • Por qué este es el valor predeterminado: De forma predeterminada, está vacío, lo que restringe al agente al directorio de destino del análisis. Si tu proceso de compilación o prueba requiere acceder a archivos fuera del directorio de destino del análisis, debes agregar esas rutas de acceso aquí.
  • Directorio de artefactos: El agente también puede escribir en un directorio de artefactos por sesión (~/.codemender/artifacts/<session_id>/ o el equivalente en $CM_HOME).
  • Archivos temporales: Cuando la zona de pruebas está habilitada, el directorio /tmp del host siempre está bloqueado, incluso si agregas /tmp a project_paths. Las herramientas que respetan TMPDIR usan un directorio temporal dentro del directorio de artefactos.

• sandbox:

  • Qué significa: Es un bloque de configuración para el entorno de zona de pruebas a nivel del proceso.
  • Parámetros secundarios:
    • enabled: true: (booleano) Habilita o inhabilita la zona de pruebas. Si configuras este parámetro como true (predeterminado), el agente ejecutará herramientas dentro de la zona de pruebas local. Si lo configuras en false, el agente ejecuta herramientas directamente en el sistema host sin aislamiento.
    • mounts: (objeto)
      • target_dir: ".": (cadena) Es el directorio que se activará como el espacio de trabajo activo dentro de la zona de pruebas. La CLI resuelve las rutas de acceso relativas en relación con la raíz del espacio de trabajo.
    • network: (objeto)
      • profile: "permissive-closed": (cadena) Es el perfil de acceso a la red saliente dentro de la zona de pruebas. Aún no se admite la inclusión detallada en la lista de entidades permitidas de dominios o patrones de URL específicos. Perfiles compatibles:
        • permissive-closed (predeterminado): Aislamiento completo de la red; la zona de pruebas bloquea todas las conexiones salientes.
        • permissive-open: Permite el acceso completo a la red saliente.

• security:

  • Qué significa: Es el bloque de configuración para las políticas de seguridad.
  • Parámetros secundarios:
    • protected_files: []: (lista de cadenas) Archivos o directorios del sistema host que deseas activar como solo lectura dentro de la zona de pruebas para protegerlos de modificaciones (por ejemplo, ["~/.ssh/*"]). Admite la expansión de rutas (~) y comodines (*).

• model: "gemini-3.8-flash"

  • Qué significa: Es el motor de inteligencia predeterminado que impulsa los bucles de razonamiento del backend.
  • Por qué es el valor predeterminado: gemini-3.8-flash ofrece el equilibrio óptimo entre velocidad, costo y razonamiento analítico necesario para sugerir parches. (Los usuarios pueden anular esta opción y usar gemini-4-argon [Gemini 4 Argon] para un razonamiento más profundo y complejo cuando sea necesario).

• vcs: { type: "git" }

  • Qué significa: Define el tipo de sistema de control de versión que usa tu proyecto a través de la clave vcs. Si dejas este campo sin configurar, la herramienta intentará identificar automáticamente los repositorios de Git o Mercurial. Si estableces vcs en none, la CLI genera una advertencia, pero continúa la ejecución sin la funcionalidad de VCS. CodeMender se basa en este parámetro de configuración para administrar las correcciones de seguridad especulativas, hacer un seguimiento de las modificaciones de la base de código y realizar la integración con tu repositorio local.
  • Por qué es la opción predeterminada: CodeMender admite Git, Mercurial o configuraciones de VCS personalizadas. Git es el valor predeterminado, ya que es el estándar de la industria para el seguimiento del control de versión, lo que garantiza una integración de diferencias y una seguridad de reversión sin problemas.

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

  • Qué significa: Define el comando de shell exacto que ejecuta CodeMender para compilar tu proyecto, así como ejecutar tus pruebas de unidades y de regresión.
  • Por qué este es el valor predeterminado: Establecer un comando de compilación y prueba es fundamental para el flujo de trabajo de verificación. Permite que CodeMender compile tu proyecto y ejecute tu paquete de pruebas existente en el entorno de zona de pruebas aislado para demostrar que el parche de seguridad generado mitiga correctamente la vulnerabilidad sin alterar la lógica de la aplicación existente.

Zona de pruebas de ejecución

Para proteger tu estación de trabajo contra modificaciones no deseadas de archivos o efectos secundarios inesperados de las herramientas, la CLI de CodeMender se ejecuta de forma predeterminada dentro de un sandbox a nivel del SO. Puedes inhabilitar la zona de pruebas de forma persistente en la configuración o omitirla por comando con las marcas de la CLI.

Aunque esta zona de pruebas ofrece una capa inicial de defensa en tu estación de trabajo, ofrece una protección de seguridad más débil que ejecutar el agente en una máquina virtual (VM) completamente aislada:

• Linux: Usa espacios de nombres del kernel (CLONE_NEWNS, CLONE_NEWUSER, etcétera) y filtros seccomp para aislar los puntos de activación y restringir las llamadas al sistema.
• macOS: Usa el mecanismo integrado sandbox-exec (Seatbelt).
• Windows (experimental): Usa aislamiento de AppContainer y listas de control de acceso (LCA). La zona de pruebas en Windows es experimental y puede requerir privilegios de administrador o ser incompatible con algunas configuraciones del sistema.

Comportamiento de la zona de pruebas

Cuando la zona de pruebas está activa, ocurre lo siguiente:

1. Aislamiento del sistema de archivos: El agente solo puede leer y escribir archivos dentro de los directorios permitidos. La zona de pruebas redirecciona cualquier escritura fuera de estos directorios a un sistema de archivos temporal en la memoria (tmpfs) sin afectar tu sistema host.
2. Aislamiento de red: La zona de pruebas bloquea el acceso a la red saliente de forma predeterminada. Esto evita que el agente (o las herramientas de compilación que invoca) realice conexiones externas inesperadas o transmita datos fuera del espacio de trabajo.

Acceso a la red durante la compilación y la validación

Dado que el sandbox habilita el aislamiento de red de forma predeterminada (sandbox.network.profile se establece en permissive-closed de forma predeterminada), el agente no puede acceder a Internet durante la ejecución de la herramienta.

Esto genera limitaciones para los proyectos que requieren recuperar dependencias externas durante los pasos de compilación o verificación (por ejemplo, ejecutar npm install, pip install o go get como parte de build.command). Si tu proceso de compilación intenta acceder a servicios web externos, fallará.

Cómo controlar las dependencias de red

Si tu proyecto requiere acceso de red para las compilaciones o pruebas, tienes las siguientes opciones:

• Recupera previamente las dependencias: Instala todas las dependencias requeridas en el sistema host antes de ejecutar los comandos de cm, de modo que el comando de compilación no necesite acceso a la red.

• Habilita el acceso a la red en la zona de pruebas: Cambia el perfil de red en tu config.yaml para permitir conexiones salientes:

  sandbox:
    network:
      profile: "permissive-open"
  

• Elude la zona de pruebas: Ejecuta el comando con la marca --unrestricted para inhabilitar por completo la zona de pruebas y los límites del sistema de archivos para esa ejecución.

Configuración de la zona de pruebas

Puedes configurar y controlar la zona de pruebas con las siguientes opciones:

• Configuración persistente (config.yaml): Puedes personalizar el comportamiento del sandbox, los puntos de montaje del sistema de archivos, el acceso a la red y las políticas de seguridad agregando bloques sandbox, execution y security a tu archivo config.yaml. Consulta Parámetros de configuración para obtener más detalles.
• Controla la zona de pruebas con la CLI (--sandbox): Puedes habilitar o inhabilitar de forma explícita la zona de pruebas para una sola ejecución pasando --sandbox=true o --sandbox=false a cm find, cm verify o cm fix.
• Cómo omitir el aislamiento con la CLI (--unrestricted): Puedes omitir temporalmente todas las protecciones de la zona de pruebas para una sola ejecución pasando la marca --unrestricted. Esto inhabilita los límites de la ruta del sistema de archivos (lo que permite que el agente acceda a cualquier ruta en tu host) y, por completo, el aislamiento del contenedor a nivel del SO (incluido el aislamiento de red).

Elige un nivel de aislamiento

Según tus requisitos de seguridad y tu entorno de desarrollo, puedes elegir el nivel de aislamiento adecuado para ejecutar la CLI de CodeMender.

Telemetría

Para ayudarnos a supervisar y mejorar el estado del producto, recopilamos datos de telemetría anónimos a través de la CLI. Anonimizamos por completo todos los datos recopilados, lo que incluye las métricas de uso básicas y los diagnósticos de rendimiento. La telemetría nunca recopila ni transmite código fuente, contenido de archivos, hallazgos, parches ni identidades de usuarios.

De forma predeterminada, la telemetría está habilitada. Si quieres inhabilitar la telemetría, establece la variable de entorno CM_TELEMETRY_OPT_OUT en 1 o true.

Actualiza la CLI

CodeMender tiene un mecanismo de actualización integrado para garantizar que ejecutes la versión más reciente de la CLI.

Verificaciones de actualizaciones automáticas

De forma predeterminada, la CLI de CodeMender busca actualizaciones automáticamente en segundo plano cuando ejecutas comandos:

• Limitación: Para minimizar la sobrecarga, la verificación automática se ejecuta como máximo una vez cada 24 horas.
• Se requiere una terminal interactiva (TTY): La CLI solo busca actualizaciones y te solicita que las instales cuando se ejecuta en una terminal interactiva. En entornos no interactivos (como canalizaciones o secuencias de comandos de CI/CD), se omite la verificación y se registra una advertencia en stderr como máximo una vez al día.
• Mensajes: Si hay una nueva versión disponible, recibirás un mensaje en stderr: none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): Si eliges sí (y o yes), CodeMender descargará la actualización, reemplazará el archivo binario y saldrá. Debes volver a ejecutar el comando para que se ejecute con la versión nueva. Si eliges no, se omitirá la actualización y se ejecutará el comando original.
• Tolerancia sin conexión: Si no tienes conexión o no se puede acceder al repositorio de versiones, la verificación falla de forma silenciosa y CodeMender sigue ejecutando tu comando.
• Omisión: Puedes omitir la verificación de actualización automática pasando la marca --yes o -y a cualquier comando.

Actualizaciones manuales (cm update)

Puedes forzar a CodeMender a que busque y aplique actualizaciones de inmediato ejecutando el comando update:

cm update

Con el comando cm update, se realiza lo siguiente:

• Ignora la limitación de 24 horas.
• Descarga y aplica la actualización de inmediato sin preguntar (no interactivo).
• No requiere una terminal interactiva (es seguro para secuencias de comandos y administración de configuraciones).

Si la CLI está instalada en un directorio del sistema que requiere permisos elevados, ejecuta la actualización con sudo:

sudo cm update