Instala y configura la CLI

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

Modelo de arquitectura y seguridad

CodeMender usa un modelo de ejecución local primero:

  • Motor de razonamiento alojado: El razonamiento agentivo, el modelado de amenazas y la lógica de orquestación se ejecutan de forma segura en Google Cloud 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 cm local ejecuta lecturas de archivos, verificaciones de compilación locales y verificaciones de explotación 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 la plataforma de Gemini Enterprise Agent.

Configuración del entorno

Para comenzar a usar CodeMender, configura tu proyecto de Google Cloud , descarga e instala la CLI, configura tus credenciales 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 Google Cloud de destino esté configurado correctamente con las APIs y los permisos necesarios.

APIs requeridas

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

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

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

  • Usuario de Vertex AI (roles/aiplatform.user): Permite a los usuarios crear, transmitir y administrar sesiones activas.

Descarga e instala la CLI de CodeMender

Los archivos 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.

Linux x86_64

Para descargar e instalar la CLI de CodeMender para Linux (x86_64), haz lo siguiente:

  1. Descarga el paquete con uno de los siguientes métodos:
    • CLI de gcloud: Ejecuta el siguiente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-amd64.zip \
        --destination=./
    • curl: Ejecuta el siguiente comando:
      curl -L -o cm-linux-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-amd64.zip:download?alt=media"
  2. Instala la CLI:
    unzip cm-linux-amd64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

Linux ARM64

Para descargar e instalar la CLI de CodeMender para Linux (ARM64), haz lo siguiente:

  1. Descarga el paquete con uno de los siguientes métodos:
    • CLI de gcloud: Ejecuta el siguiente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-arm64.zip \
        --destination=./
    • curl: Ejecuta el siguiente comando:
      curl -L -o cm-linux-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-arm64.zip:download?alt=media"
  2. Instala la CLI:
    unzip cm-linux-arm64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

macOS Intel

Para descargar e instalar la CLI de CodeMender para macOS (Intel), haz lo siguiente:

  1. Descarga el paquete con uno de los siguientes métodos:
    • CLI de gcloud: Ejecuta el siguiente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-amd64.zip \
        --destination=./
    • curl: Ejecuta el siguiente comando:
      curl -L -o cm-darwin-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-amd64.zip:download?alt=media"
  2. Instala la CLI:
    unzip cm-darwin-amd64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

macOS Apple Silicon

Para descargar e instalar la CLI de CodeMender para macOS (silicon de Apple), haz lo siguiente:

  1. Descarga el paquete con uno de los siguientes métodos:
    • CLI de gcloud: Ejecuta el siguiente comando:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-arm64.zip \
        --destination=./
    • curl: Ejecuta el siguiente comando:
      curl -L -o cm-darwin-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-arm64.zip:download?alt=media"
  2. Instala la CLI:
    unzip cm-darwin-arm64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Windows x86_64

Para descargar e instalar la CLI de CodeMender para Windows (x86_64), haz lo siguiente:

  1. Descarga el paquete con uno de los siguientes métodos:
    • CLI de gcloud: Ejecuta el siguiente comando en PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-amd64.zip `
        --destination=./
    • PowerShell: Ejecuta el siguiente comando:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-amd64.zip:download?alt=media" -OutFile cm-windows-amd64.zip
  2. Instala la CLI:
    Expand-Archive -Path cm-windows-amd64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Windows ARM64

Para descargar e instalar la CLI de CodeMender para Windows (ARM64), haz lo siguiente:

  1. Descarga el paquete con uno de los siguientes métodos:
    • CLI de gcloud: Ejecuta el siguiente comando en PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-arm64.zip `
        --destination=./
    • PowerShell: Ejecuta el siguiente comando:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-arm64.zip:download?alt=media" -OutFile cm-windows-arm64.zip
  2. Instala la CLI:
    Expand-Archive -Path cm-windows-arm64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Configura las credenciales de Google Cloud

Dado que la CLI de CodeMender interactúa con el motor de inferencia alojado en la nube a través de la API de Interactions, debes configurar las Google Cloud credenciales predeterminadas de la aplicación (ADC) en tu entorno.

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

gcloud auth application-default login

Inicializa el espacio de trabajo

Una vez que te hayas autenticado, 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 del estado local 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 busca este archivo en tu espacio de trabajo inicializado (por lo general, .codemender/config.yaml o un directorio de configuración global como ~/.config/codemender/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 anulaciones del sistema y especificar qué archivos o directorios ignorar.

Configuración predeterminada principal

Estos son 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 configuració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 archivos fuente 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 de "humano en el circuito". 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 este parámetro a false cuando se ejecute en zonas de pruebas aisladas y desechables, o en canalizaciones de CI/CD automatizadas y sin encabezado.
  • include: [".py", ".java", ".go", ".js", ".ts", ".c", ".cc", ".cpp", ".h", ".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 con una extensión que no se especifique en esta lista.
    • Por qué esta es la configuració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, te recomendamos que expandas manualmente esta lista predeterminada 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_paths: ["node_modules", "vendor", "dist", "bin"]

    • 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é esta es la configuración predeterminada: Las carpetas de compilación o dependencia grandes generan una latencia masiva y una penalización de tokens. Mantenerlos excluidos de forma predeterminada garantiza un alto rendimiento y tiempos de respuesta rápidos.
  • project_paths: []

    • Qué significa: Es una lista de rutas de acceso a directorios a los 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 el agente al directorio de destino del análisis, al directorio del espacio de trabajo .codemender y a /tmp. Si tu proceso de compilación o prueba requiere acceder a archivos fuera de estos directorios, debes agregar esas rutas aquí.
  • 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 como 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) Perfil de acceso a la red saliente dentro de la zona de pruebas. Aún no se admite la inclusión en la lista de entidades permitidas detallada 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 un bloque de configuración para las políticas de seguridad.
    • Parámetros secundarios:
      • protected_files: []: (Lista de cadenas) Son los archivos o directorios del sistema host que deseas montar como de solo lectura dentro de la zona de pruebas para protegerlos de modificaciones (p.ej., ["~/.ssh/*"]). Admite la expansión de rutas de acceso (~) y comodines (*).
  • model: "gemini-3.5-flash"

    • Qué significa: Es el motor de inteligencia predeterminado que impulsa los bucles de razonamiento del backend.
    • Por qué esta es la opción predeterminada: gemini-3.5-flash ofrece el equilibrio óptimo de velocidad, costo y razonamiento analítico necesarios para sugerir parches. (Los usuarios pueden anular este valor y establecerlo en gemini-3.1-pro 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 no configuras este parámetro, la herramienta intentará identificar automáticamente los repositorios de Git o Mercurial. Si configuras vcs como none, la CLI genera una advertencia, pero continúa la ejecución sin la funcionalidad del VCS. CodeMender depende de 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é esta 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 sin problemas y seguridad de reversión.
  • build: { command: "make build && make test" }

    • Qué significa: Define el comando de shell exacto que ejecuta CodeMender para compilar y crear tu proyecto, así como para ejecutar tus pruebas de unidades y de regresión.
    • Por qué esta es la opción predeterminada: 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 aislado de zona de pruebas para demostrar que el parche de seguridad generado mitiga correctamente la vulnerabilidad sin interrumpir 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 herramientas, la CLI de CodeMender se ejecuta de forma predeterminada dentro de un sandbox a nivel del SO. Puedes inhabilitar el aislamiento de forma persistente en la configuración o evitarlo por comando con marcas de la CLI.

Si bien este aislamiento ofrece una capa inicial de defensa en tu estación de trabajo, ofrece una protección de seguridad más débil que la ejecución del agente en una máquina virtual (VM) completamente aislada:

  • Linux: Usa espacios de nombres del kernel (CLONE_NEWNS, CLONE_NEWUSER, etc.) y filtros seccomp para aislar los puntos de montaje 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). El aislamiento de zona de pruebas en Windows es experimental y puede requerir privilegios de administrador o ser incompatible con algunos parámetros de configuración del sistema.

Comportamiento de la zona de pruebas

Cuando la zona de pruebas está activa, sucede 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 en la memoria temporal (tmpfs) sin afectar tu sistema host.
  2. Aislamiento de red: De forma predeterminada, la zona de pruebas bloquea el acceso a la red saliente. 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 introduce 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 a la red para las compilaciones o las 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"
    
  • Cómo omitir el sandbox: Ejecuta el comando con la marca --unrestricted para inhabilitar por completo el sandbox 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 explícitamente 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 de tu host) y, por completo, el aislamiento del contenedor a nivel del SO (incluido el aislamiento de la red).

Cómo elegir 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.

Método Descripción Ventajas Desventajas
Zona de pruebas integrada (a nivel del SO) Está habilitado de forma predeterminada. Puedes inhabilitarlo en el archivo config.yaml o evitarlo con marcas de la CLI. Usa funciones integradas del SO (espacios de nombres/seccomp, sandbox-exec, AppContainer [experimental]) para aislar la ejecución. Ligero, sin sobrecarga de inicio, acceso directo a herramientas del espacio de trabajo local con control detallado. Se recomienda para el desarrollo local diario. La seguridad depende de las funciones del kernel del SO, está menos aislado que una VM completa, la compatibilidad con Windows es experimental y puede requerir privilegios de administrador o ser incompatible con algunas configuraciones.
Contenedores Ejecutar el agente en un contenedor (p. ej., Docker) Buen aislamiento y entorno estandarizado. Requiere un tiempo de ejecución del contenedor, puede ser pesado y no permite la interacción directa con las herramientas en la máquina local.
VMs completas Ejecutar el agente en una VM dedicada Seguridad máxima y aislamiento completo. Sobrecarga de recursos alta, inicio lento y no permite la interacción directa con herramientas en la máquina local.

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.

Comprobaciones de actualizaciones automáticas

De forma predeterminada, la CLI de CodeMender verifica automáticamente si hay actualizaciones 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 realices cuando se ejecuta en una terminal interactiva. En los entornos no interactivos (como las canalizaciones o los 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 versión nueva 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 continúa ejecutando tu comando.
  • Omisión: Puedes omitir la verificación automática de actualizaciones pasando la marca --yes o -y a cualquier comando.

Actualizaciones manuales (cm update)

Puedes forzar a CodeMender a buscar y aplicar 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 solicitarlo (no interactiva).
  • No requiere una terminal interactiva (seguro para secuencias de comandos y administración de la configuración).

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

sudo cm update