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 de ciberseguridad profundas 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, el modelado de amenazas y la lógica de organizació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 local de cm ejecuta lecturas de archivos, verificaciones de compilaciones locales y verificaciones de exploits de prueba de concepto (PoC) en tu entorno 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 Google Cloud , 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 Google Cloud de destino esté configurado correctamente con las APIs y los permisos necesarios.

APIs requeridas

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

  1. API de Agent Platform (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 de los usuarios y los metadatos del proyecto.

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.

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:
    • gcloud CLI: 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:
    • gcloud CLI: 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:
    • gcloud CLI: 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

Apple Silicon para macOS

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

  1. Descarga el paquete con uno de los siguientes métodos:
    • gcloud CLI: 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:
    • gcloud CLI: 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:
    • gcloud CLI: 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 y el proyecto de Google Cloud

Como 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 las Google Cloud 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 para el ID del proyecto de Google Cloud :

    export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
    

    Como alternativa, configura tu proyecto activo de la CLI de gcloud:

    gcloud config set project PROJECT_ID
    

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

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

Verifica la conectividad y los permisos del servicio

Para verificar tus credenciales, configuración, accesibilidad de la red y permisos de IAM sin iniciar un análisis ni modificar tu espacio de trabajo, ejecuta cm health:

cm health

El comando cm health ejecuta cuatro verificaciones secuenciales y se detiene en la primera capa que falla. Puedes ejecutar cm health desde cualquier directorio, incluso antes de ejecutar cm init. No escribe en el disco ni consume cuota de modelo.

Para las verificaciones previas de CI/CD automatizadas o la supervisión sintética programada, usa --strict para que se produzca un error cuando se omitan las verificaciones de IAM a nivel del proyecto y --json para generar un informe JSON legible por máquinas:

cm health --strict --json

En la siguiente tabla, se describen los códigos de salida de cm health:

Código de salida Capa Descripción
0 — Se aprobaron todas las verificaciones de estado.
10 credentials La CLI no pudo adquirir un token de OAuth o de credenciales predeterminadas de la aplicación válido, o el servidor rechazó el token (401 Unauthorized).
20 config El archivo config.yaml local, la marca --team-id o la variable de entorno CM_TEAM_ID no son válidos.
30 reachability La CLI no pudo acceder al extremo de API de Agent Platform (por ejemplo, debido a restricciones de DNS, TLS, proxy o Controles del servicio de VPC).
40 authorization Se estableció conexión con el servidor, pero el emisor o el proyecto no tienen autorización para ejecutar análisis de CodeMender (por ejemplo, faltan permisos de roles/aiplatform.user).
50 — La verificación de estado superó la duración de --timeout (el valor predeterminado es 30s).

cm health admite las siguientes marcas:

Marca Valor predeterminado Descripción
--json false Genera un solo objeto JSON en la salida estándar, incluidos status, exit_code, backend, endpoint, location, project_id, agent_id, duration_ms, layers y (cuando están presentes) warnings y error.
--strict false Trata las advertencias de las verificación de estado (como las verificaciones de permisos de IAM a nivel de proyecto no verificadas o omitidas) como fallas del código de salida 40.
--timeout 30s Establece el tiempo de espera general para el sondeo de verificación de estado.

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.

Como el agente de IA alojado ejecuta comandos locales (como compilar código, ejecutar pruebas o editar archivos) con tu cliente 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 si configuras 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 se deben ignorar.

Configuración predeterminada principal

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

  • tools.confirm_commands: true

    • Qué significa: De forma predeterminada, CodeMender te solicita una confirmación [Y/n] en la terminal antes de ejecutar comandos de shell (run_command). Cuando cm find se ejecuta con la zona de pruebas a nivel del SO habilitada (sandbox.enabled: true) y el aislamiento de red predeterminado (permissive-closed), el espacio de trabajo se activa como de solo lectura y las solicitudes de confirmación de comandos se omiten automáticamente.
    • Por qué este es el valor predeterminado: CodeMender puede ejecutar comandos de compilación, paquetes de pruebas o secuencias de comandos de explotación durante la verificación y la aplicación de parches. Exigir confirmación cuando el espacio de trabajo es de escritura o no está en una zona de pruebas ayuda a evitar la ejecución de comandos no deseados en tu entorno local.
    • Omisión: Pasa -y (o --yes) para una sola ejecución o establece tools.confirm_commands: false en config.yaml para canalizaciones de CI/CD no interactivas.
  • tools.confirm_writes: true

    • Qué significa: Te solicita una confirmación de [Y/n] en la terminal antes de que el agente de CodeMender escriba o modifique archivos en el disco (write_to_file y search_and_replace).
    • Por qué este es el valor predeterminado: El requisito de confirmación manual evita que el agente realice modificaciones especulativas o no deseadas en tus archivos de origen durante cm fix o cm verify. Establece este valor en false (o pasa -y o --yes) solo cuando se ejecute en entornos aislados y desechables, o en canalizaciones de CI/CD automatizadas.
  • execution.interactive_mode: true

    • Qué significa: Habilita los mensajes interactivos de la terminal durante la ejecución de la herramienta. Establece este valor en false (o pasa -y o --yes) en entornos de CI/CD sin interfaz gráfica en los que no haya una terminal conectada.
  • execution.duration: ""

    • Qué significa: Establece una duración máxima predeterminada del tiempo real por invocación de comando (por ejemplo, "15m" o "1h") en cm find, cm verify, cm fix y cm session resume. Deja este campo vacío o establécelo en "0" para que no haya un límite de tiempo. Puedes anular este parámetro de configuración con la variable de entorno CM_DURATION o la marca --duration (o --timeout). Cuando un comando se detiene en su límite de duración, guarda los resultados completados y sale con el estado 1 si un análisis de cm find --diff coincide con --fail-on, o con el estado 50 de lo contrario.
  • execution.stall_detection: false

    • Qué significa: Cuando se establece en true (o cuando es CM_STALL_DETECTION=on), detiene una sesión de agente que no avanza en los turnos de herramientas consecutivos. Los comandos de sesión única (cm find --quick, cm verify, cm fix y cm session resume de un solo paso) se cierran con el estado 50. En los análisis de varias sesiones --deep, --diff y --parallel, una sesión detenida se registra como fallida y el análisis continúa.
  • scan.extensions.include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx", ".inl", ".ipp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php", ".sol", ".tf", ".hcl"]

    • Qué significa: Define la lista explícita de extensiones de archivo que autorizas a CodeMender a transferir y analizar cuando analiza 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 incluye de forma predeterminada 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.
  • scan.exclude_dirs: ["node_modules", "vendor", "dist", "/target", "/obj", "/build", ".gradle"]

    • Qué significa: CodeMender omite estos directorios durante el análisis del espacio de trabajo y del código. Las entradas con un / inicial (como /target, /obj y /build) solo coinciden en la raíz del análisis, por lo que no se omiten los paquetes de origen anidados con esos nombres.
    • Por qué este es el valor predeterminado: Las carpetas de dependencias o compilaciones 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 acceso a directorios a las que CodeMender puede acceder (leer/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 a la raíz del proyecto que lo contiene (o al directorio de destino del análisis). Si tu proceso de compilación o prueba requiere acceder a archivos fuera de la raíz del proyecto, agrega esas rutas de acceso aquí o pasa --allow-all-paths para una sola ejecución. Las operaciones de escritura en .git, .hg y .codemender siempre están bloqueadas.
    • 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. En cambio, las herramientas que respetan TMPDIR usan un directorio temporal dentro del directorio de artefactos.
  • sandbox:

    • Qué significa: Es el bloque de configuración para el entorno de zona de pruebas a nivel del proceso.
    • Subparámetros:
      • enabled: true: (booleano) Habilita o inhabilita la zona de pruebas. Si estableces este parámetro en true (predeterminado), el agente ejecuta las herramientas dentro de la zona de pruebas local. Si lo configuras como false (o pasas --sandbox=false), el agente ejecuta herramientas directamente en el sistema host sin aislamiento a nivel del SO.
      • 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.
    • Subparámetros:
      • protected_files: []: (lista de cadenas) Archivos o directorios adicionales en el sistema host que deseas activar como solo lectura dentro de la zona de pruebas para protegerlos de modificaciones. Admite la expansión de rutas de acceso (~) y comodines (*). Incluso cuando protected_files está vacío, la zona de pruebas siempre protege .git/hooks, .git/config, .hg/hgrc y .codemender como de solo lectura y excluye los directorios de credenciales comunes (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker).
  • Modelo: config.yaml no establece el modelo. Para elegir un modelo, pasa --model a cm find, cm verify o cm fix. Para conocer los modelos compatibles y el predeterminado, consulta Especifica el modelo.

  • 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 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 la opción predeterminada, 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 CodeMender ejecuta para compilar y crear tu proyecto, así como para 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 verificar que el parche de seguridad generado mitigue correctamente la vulnerabilidad sin dañar la lógica de la aplicación existente.

Mensajes de confirmación

CodeMender pide confirmación antes de ejecutar un comando de shell (tools.confirm_commands) y antes de escribir un archivo (tools.confirm_writes). Los dos parámetros de configuración son independientes y ambos se establecen de forma predeterminada en true. Los siguientes parámetros de configuración desactivan estos mensajes, en orden de prioridad:

  1. -y o --yes: Aprueba todos los mensajes de comando y escritura de archivos para una ejecución, independientemente de lo que diga config.yaml.
  2. execution.interactive_mode: false en config.yaml: Desactiva las solicitudes de comando y de escritura de archivos para cada ejecución.
  3. tools.confirm_commands: false o tools.confirm_writes: false en config.yaml: Desactiva los símbolos del sistema o las solicitudes de escritura de archivos para cada ejecución, de forma independiente entre sí.

Si no se aplica ninguno de estos parámetros de configuración y nadie puede responder el mensaje, por ejemplo, en un trabajo de CI/CD sin una terminal, CodeMender no ejecuta el comando ni escribe el archivo.

Independientemente de estos mensajes, la CLI te advierte que el agente puede modificar archivos y ejecutar comandos en tu sistema, y te pide que confirmes la advertencia. -y no omite esta advertencia. Para omitirlo, pasa --bypass-warning. En un entorno no interactivo sin --bypass-warning, cm falla con warning not acknowledged. cm find omite la advertencia cuando la zona de pruebas está habilitada con el perfil de red permissive-closed predeterminado.

Política de comandos (command_policy.yaml)

Además de la zona de pruebas a nivel del SO, puedes definir una lista de bloqueo de comandos en ~/.codemender/command_policy.yaml (global) y <project>/.codemender/command_policy.yaml (específica del proyecto). Cuando ambos archivos están presentes, CodeMender combina sus reglas.

En la primera ejecución, CodeMender crea una plantilla marcada como comentario en ~/.codemender/command_policy.yaml. Puedes quitar el comentario o agregar reglas en dos claves:

  • block: Es una lista de nombres de objetos binarios que se bloquearán en todas las canalizaciones de shell, subshells y sustituciones de comandos (por ejemplo, curl, wget, ssh, sudo, rm).
  • block_patterns: Es una lista de expresiones regulares que coinciden con cada segmento de comando (por ejemplo, '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b').

Para omitir la aplicación forzosa de command_policy.yaml en una sola invocación de comando, pasa la marca --allow-all-commands.

  • output: { plain: false }
    • Qué significa: Controla si la CLI de CodeMender reemplaza los emojis, los símbolos Unicode y los colores de la terminal por texto ASCII en el resultado de la CLI y los informes con formato.
    • Por qué este es el valor predeterminado: El estilo de terminal enriquecido y los íconos de estado facilitan el análisis de los análisis interactivos y los informes exportados. Establece plain en true para los registros de CI/CD, los lectores de pantalla o las terminales mínimas. Para conocer las reglas de precedencia y las anulaciones de marcas, consulta Configura el resultado de texto sin formato.

Zona de pruebas de ejecución

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

Google proporciona la zona de pruebas de CodeMender como una función de seguridad recomendada. La ejecución de CodeMender fuera de un entorno de zona de pruebas se realiza bajo el propio riesgo del Cliente, de conformidad con el Artículo 20(j) de las Condiciones Específicas del Servicio.

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.) 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 el aislamiento de AppContainer y las 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 acceder a los archivos dentro de los directorios permitidos. Durante cm find, el espacio de trabajo y las raíces permitidas se activan como solo lectura, por lo que los comandos solo pueden escribir en el directorio de artefactos por sesión. En todos los comandos (incluidos cm verify y cm fix), .git/hooks, .git/config, .hg/hgrc y .codemender se activan como de solo lectura para que los comandos de la zona de pruebas no puedan instalar hooks de Git o Mercurial ni modificar la configuración de CodeMender.
  2. Aislamiento de red: La zona de pruebas bloquea el acceso a la red saliente de forma predeterminada (sandbox.network.profile: "permissive-closed"). 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.
  3. Aislamiento de credenciales y secretos: La zona de pruebas excluye los directorios de credenciales de host comunes (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker y otros) y quita las variables de entorno que coinciden con patrones de secretos (*_TOKEN, *_SECRET, *_KEY, *_PASSWORD, *_CREDENTIALS y sufijos similares) antes de ejecutar comandos.

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

Debido a que la zona de pruebas habilita el aislamiento de red de forma predeterminada (sandbox.network.profile se establece de forma predeterminada en permissive-closed), 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"
    
  • Inhabilitar la zona de pruebas para una ejecución: Ejecuta el comando con la marca --sandbox=false para inhabilitar la zona de pruebas a nivel del SO (incluido el aislamiento de red) para esa ejecución.

Configuración de la zona de pruebas

Puedes configurar y controlar la zona de pruebas y los límites de seguridad con las siguientes opciones:

  • Configuración persistente (config.yaml y command_policy.yaml): Personaliza el comportamiento de la zona de pruebas, las activaciones del sistema de archivos, el acceso a la red y las listas de denegación de comandos en config.yaml y command_policy.yaml. Consulta Parámetros de configuración y Política de comandos para obtener más detalles.
  • Controla el entorno aislado a nivel del sistema operativo (--sandbox): Habilita o deshabilita explícitamente el entorno aislado a nivel del sistema operativo para una sola ejecución pasando --sandbox=true o --sandbox=false a cm find, cm verify, cm fix o cm session resume.
  • Omitir los límites de la ruta de acceso (--allow-all-paths): Inhabilita la verificación de los límites de la ruta de acceso del espacio de trabajo para una sola ejecución, de modo que las herramientas del agente puedan acceder a las rutas de acceso fuera de la raíz del proyecto y al project_paths configurado (combínalo con --sandbox=false para acceder a las rutas de acceso del host que no están activadas dentro de la zona de pruebas).
  • Omitir la política de comandos (--allow-all-commands): Inhabilita la aplicación de la lista de entidades bloqueadas de command_policy.yaml para una sola ejecución.

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.

Método Descripción Ventajas Desventajas
Zona de pruebas integrada (a nivel del SO) Está habilitada de forma predeterminada. Puedes inhabilitarla en el archivo config.yaml o omitirla con las marcas de la CLI. Usa funciones integradas del SO (espacios de nombres/seccomp, sandbox-exec, AppContainer (experimental)) para aislar la ejecución. Liviano; sin sobrecarga de inicio; acceso directo a las 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 (por ejemplo, Docker) Buen aislamiento; entorno estandarizado. Requiere un entorno de ejecución de contenedores, puede ser pesado y no permite la interacción directa con las herramientas de la máquina local.
VMs completas Ejecuta el agente en una VM dedicada. Máxima seguridad y aislamiento completo. Sobrecarga de recursos alta, inicio lento, no permite la interacción directa con las herramientas en la máquina local.

Configura la salida de texto sin formato

De forma predeterminada, la CLI de CodeMender usa emojis, símbolos Unicode y colores de terminal en los resultados interactivos y los informes con formato. Para usar solo resultados ASCII en los registros de CI/CD, los lectores de pantalla o las terminales mínimas, habilita el modo de texto sin formato. La CLI de CodeMender verifica estos parámetros de configuración de mayor a menor precedencia:

  1. Pasa la marca --plain a cualquier comando cm para una sola ejecución o pasa --plain=false para anular la configuración del entorno y de la configuración:

    cm --plain find .
    
  2. Establece la variable de entorno CM_PLAIN como true o 1 para habilitar la salida de texto sin formato en los comandos, o como false o 0 para desactivarla:

    export CM_PLAIN=true
    
  3. Establece output.plain como true en tu archivo ~/.codemender/config.yaml:

    output:
      plain: true
    
  4. Ejecuta una sesión interactiva en una terminal en la que TERM=dumb, lo que habilita la salida de texto sin formato automáticamente.

El modo de texto sin formato reemplaza los emojis de estado por etiquetas ASCII, como [OK], [INFO], [WARN], [ERROR], [PASS] y [FAIL]. CodeMender también desactiva los íconos giratorios animados y las reescrituras de líneas in situ, y renderiza los bordes de las tablas ASCII. En cm report, el modo de texto sin formato quita los emojis de la IU de los formatos table, md y html sin cambiar el resultado de json o sarif ni las diferencias de código.

Los archivos redireccionados y los flujos de CI/CD no interactivos mantienen plain establecido en false de forma predeterminada para que los informes de Markdown y HTML exportados conserven los íconos de estado. Para quitar los emojis y los símbolos Unicode de los registros de CI/CD, establece CM_PLAIN=true, pasa --plain o establece output.plain: true. Los escapes de color de la terminal se omiten automáticamente en las transmisiones no interactivas y cuando configuras la variable de entorno NO_COLOR.

Telemetría

Para ayudarnos a supervisar y mejorar el estado del producto, la CLI envía telemetría de uso a Google: un evento cuando se inicia un comando, un evento cuando se cierra y un evento para cada error que informa. Cuando la CLI puede determinarlos, los eventos identifican la Cuenta de Google o la cuenta de servicio que ejecuta la CLI y el proyecto de Google Cloud que usa.

Los eventos de telemetría pueden contener lo siguiente:

  • El ID de tu Cuenta de Google o de tu cuenta de servicio, el ID del proyecto de Google Cloud y el ID del equipo, si configuraste uno.
  • Un ID aleatorio para cada comando, el nombre del comando, el ID de sesión del servidor, el modelo seleccionado y la versión de la CLI.
  • La familia, la plataforma y la versión del sistema operativo.
  • Si la zona de pruebas está activada y si -y (--yes) está configurado para omitir los mensajes de confirmación.
  • Al salir: la duración, el código de salida y el resultado; los recuentos de tokens; la cantidad de líneas, archivos y bytes analizados, y los lenguajes detectados; y la cantidad de hallazgos por gravedad o el resultado de una verificación o corrección.
  • En caso de error: la categoría y el motivo del error, y un seguimiento de pila del código propio de la CLI.

La telemetría no contiene código fuente, contenido de archivos, rutas de acceso de archivos, instrucciones, hallazgos, parches ni texto de mensajes de error. La CLI envía telemetría a un extremo global de Google. La telemetría son Datos del Servicio, como se describe en el Aviso de Privacidad deGoogle Cloud .

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 ayudarte a mantener tu CLI actualizada con la versión más reciente.

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 envía mensajes cuando se ejecuta en una terminal interactiva. En entornos no interactivos (como canalizaciones de CI/CD o secuencias de comandos), se omite la verificación y se registra una advertencia en stderr como máximo una vez al día.
  • Indicaciones: Si hay una versión nueva disponible, se te indicará en stderr: none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): Si eliges que sí (y o yes), CodeMender descarga la actualización, reemplaza el objeto binario y sale. Debes volver a ejecutar el comando para que se ejecute con la versión nueva. Si eliges que 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 (segura 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