Modos de búsqueda de CodeMender

CodeMender proporciona tres modos de análisis distintos a través del comando cm find. Cada modo está diseñado para una etapa específica del ciclo de vida del desarrollo de software, lo que equilibra la velocidad, el alcance y la profundidad.

Compara los modos de búsqueda

En la siguiente tabla, se comparan los tres modos de análisis de cm find:

Modo Comando Permiso de destino Tiempo de ejecución típico Ideal para
Análisis profundo (predeterminado) cm find PATH Directorio o repositorio especificado Mayor tiempo de ejecución Auditorías de seguridad integrales, preparación para el lanzamiento y certificaciones de cumplimiento (SOC 2, ISO)
Análisis de diferencias cm find PATH --diff[=REF] Archivos modificados y archivos dependientes (como emisores y receptores de llamadas) Entorno de ejecución rápido Canalizaciones de CI/CD de solicitudes de extracción (GitHub Actions, Cloud Build), hooks de confirmación previa
Análisis rápido cm find PATH --quick Directorio especificado Entorno de ejecución moderado Descubrimiento de desarrolladores locales, verificaciones rápidas y revisiones exploratorias

Análisis profundo (predeterminado)

Un análisis profundo es el modo predeterminado cuando ejecutas cm find sin proporcionar marcas de análisis adicionales (la marca --deep también es compatible con la retrocompatibilidad). Es un modo de análisis exhaustivo diseñado para auditorías de seguridad completas. Audita los archivos de origen en el directorio o repositorio de destino de forma simultánea con trabajadores paralelos (configurados con --deep-workers, que se establece de forma predeterminada en 8 y admite un rango de 1 a 16). A medida que descubre hallazgos candidatos, los valida y corrobora con el contexto del código circundante para filtrar los falsos positivos antes de informar los resultados.

En los siguientes ejemplos, se muestra cómo ejecutar un análisis profundo en un repositorio:

# Run an exhaustive deep scan across the repository (default mode)
cm find .

# Tune concurrency and use the cyber-specialized security model
cm find . --deep-workers=8 --model=gemini-3.8-flash-cyber

Ventajas

Un análisis profundo se ejecuta sin configuración y ofrece una alta recuperación y un descubrimiento integral de vulnerabilidades en grandes bases de código empresariales. Supera los análisis de una sola sesión y usa la verificación automatizada para mantener una alta precisión. También es independiente de la plataforma y funciona en todos los idiomas admitidos por Gemini sin necesidad de compiladores específicos de cada idioma, configuraciones de compilación ni archivos de gramática. Por último, optimiza el uso de recursos, ya que enfoca el análisis en el código de producción y minimiza el consumo de procesamiento y tokens en los archivos que no son de producción.

Compensaciones y limitaciones

No uses un análisis profundo como una verificación síncrona que bloquee las solicitudes de extracción. Los análisis profundos realizan un análisis exhaustivo, archivo por archivo. Como resultado, requieren un tiempo de ejecución más largo y un mayor gasto de tokens que los análisis rápidos o de diferencias.

Cuándo usar

Usa un análisis profundo en las siguientes situaciones:

  • Ejecuta auditorías de seguridad programadas de forma nocturna o semanal en todos los repositorios de producción.
  • Realiza una auditoría de seguridad completa previo al lanzamiento de versiones principales o implementaciones de producción.
  • Genera evidencia de auditoría para las revisiones de certificación y cumplimiento de SOC 2, ISO 27001, FedRAMP o PCI-DSS.
  • Establecer un modelo de referencia de seguridad inicial cuando se incorpore una base de código nueva a CodeMender

Análisis de diferencias

Un análisis de diferencias realiza un análisis de diferencias de Git para los flujos de trabajo de solicitud de extracción y las canalizaciones de CI/CD, ya que inspecciona los archivos modificados y agregados, y se enfoca en los rangos de líneas exactos (bloques de diferencias) que cambiaron. Además de inspeccionar las líneas modificadas, realiza un análisis de impacto para descubrir archivos intactos en el repositorio que llaman, importan o dependen de las funciones y los símbolos modificados. Esto ayuda a garantizar que los cambios que alteran los contratos o las firmas de funciones en un archivo no introduzcan vulnerabilidades en los archivos dependientes.

Durante el análisis, CodeMender aísla automáticamente las vulnerabilidades preexistentes en el código sin modificar para que los problemas heredados no hagan que el análisis falle ni bloqueen la solicitud de extracción. Luego, evalúa los hallazgos en función de tu política de --fail-on y genera los resultados en formato de tabla, JSON o SARIF v2.1.0.

En los siguientes ejemplos, se muestra cómo ejecutar un análisis de diferencias en los cambios de la copia de trabajo, los cambios en etapa de pruebas o una rama de destino:

# Scan working copy changes versus HEAD
cm find . --diff

# Scan staged changes only (pre-commit)
cm find . --diff --staged

# Scan a pull request branch against the main branch in CI/CD
cm find . --diff=origin/main --format=sarif --output=results.sarif \
    --fail-on=CRITICAL,HIGH

Para obtener información sobre las configuraciones de canalizaciones de extremo a extremo, consulta Integra con CI/CD.

Ventajas

Un análisis de diferencias es rápido y determinístico, y suele finalizar en menos de 2 minutos para mantener cortos los tiempos de ejecución de la canalización de CI/CD. A diferencia de los escáneres de diferencias que solo inspeccionan las líneas modificadas, --diff inspecciona las relaciones entre el emisor y el receptor para detectar regresiones de seguridad entre archivos y violaciones de contratos. Debido a que suprime los hallazgos en el código sin modificar, el análisis solo bloquea las solicitudes de extracción en los problemas introducidos o afectados por los cambios, lo que evita informes ruidosos y fallas de compilación innecesarias. Un análisis de diferencias también emite SARIF v2.1.0 para la integración directa en las anotaciones de análisis de código de GitHub y los paneles de Cloud Build.

Compensaciones y limitaciones

Un análisis de diferencias solo analiza el código dentro del área afectada de la solicitud de extracción y no encuentra vulnerabilidades preexistentes en partes no modificadas del repositorio. También requiere un repositorio de Git con acceso a la referencia base de destino.

Cuándo usar

Usa un análisis de diferencias en las siguientes situaciones:

  • Ejecuta verificaciones automatizadas en cada solicitud de extracción en las canalizaciones de CI/CD, como GitHub Actions, Cloud Build, GitLab CI o Jenkins.
  • Verifica que los cambios locales estén limpios en los hooks de confirmación previa o envío previo antes de enviar el código al repositorio remoto.
  • Valida que las combinaciones entre las ramas de lanzamiento no introduzcan regresiones.

Análisis rápido

Un análisis rápido (cm find --quick) ejecuta un análisis autónomo de una sola sesión del directorio de destino especificado en lugar del análisis profundo simultáneo predeterminado por archivo. Durante el análisis, CodeMender descubre archivos de origen, los prioriza según los patrones de vulnerabilidad, realiza un análisis de seguridad inicial y, luego, informa las vulnerabilidades potenciales con agrupación por gravedad y tipo.

En los siguientes ejemplos, se muestra cómo ejecutar un análisis rápido en un directorio de destino:

# Run a single-session quick scan on a directory using the default model
cm find ./src --quick

# Run a quick scan with a specific Gemini model
cm find ./src --quick --model gemini-3.8-flash

Ventajas

Un análisis rápido equilibra la velocidad y la cobertura con un tiempo de ejecución moderado, y usa menos tokens y menos procesamiento que un análisis profundo completo, lo que lo hace rentable para realizar verificaciones exploratorias rápidas durante el desarrollo diario.

Compensaciones y limitaciones

Un análisis rápido tiene una recuperación más baja en bases de código grandes y es posible que no explore todos los archivos en repositorios empresariales grandes de varios paquetes, ya que opera dentro de un solo contexto de sesión. También se enfoca principalmente en patrones locales dentro de archivos individuales, lo que limita el análisis entre paquetes y puede pasar por alto vulnerabilidades que abarcan paquetes distantes.

Cuándo usar

Usa un análisis rápido en las siguientes situaciones:

  • Ejecuta un análisis rápido en tu máquina local para obtener comentarios rápidos durante el desarrollo local.
  • Inspecciona un repositorio recién clonado o un proyecto pequeño para realizar una evaluación inicial rápida de su postura de seguridad.
  • Inspecciona un subdirectorio o módulo específico cuando realices una verificación exploratoria rápida.

Elige un modo de búsqueda

Usa la siguiente tabla de referencia para seleccionar el modo de análisis adecuado para tu flujo de trabajo:

Flujo de trabajo o entorno Caso de uso y objetivo Modo recomendado Comando de ejemplo
Terminal local Descubrimiento rápido o verificación de confianza en un módulo específico Análisis rápido cm find ./src --quick
Terminal local Verificación previa a la confirmación de los cambios en etapa de pruebas antes de enviarlos Análisis de diferencias cm find . --diff --staged
Canalización de CI/CD Control automatizado de solicitud de extracción en el código modificado y los emisores Análisis de diferencias cm find . --diff=origin/main --fail-on=CRITICAL,HIGH
Canalización o auditoría programada Auditorías nocturnas, puertas de enlace previas al lanzamiento y cumplimiento de SOC 2 Análisis profundo cm find . --deep-workers=8

Referencia de marcas de comandos por modo

En las siguientes tablas, se describen las marcas de línea de comandos que admite cada modo de análisis.

Marcas comunes (todos los modos)

Las siguientes marcas se aplican a todos los modos de análisis de cm find:

Marca Valor predeterminado Descripción
-c, --context TEXT "" Contexto adicional para guiar al agente de análisis, como notas de arquitectura.
--model MODEL_NAME gemini-3.8-flash Es el modelo de Gemini que se usará (gemini-3.8-flash, gemini-3.8-flash-cyber).
-y, --yes false Omitir todos los mensajes de confirmación interactivos.
--unrestricted false Desactivar la zona de pruebas del sistema de archivos

Marcas de análisis de diferencias

Las siguientes marcas configuran los análisis de cm find --diff:

Marca Valor predeterminado Descripción
--diff[=REF] Desactivado Habilita el modo de diferencias con respecto a la referencia de destino, como origin/main o HEAD~1. Sin REF, se compara con HEAD. No se puede usar con --deep ni --quick.
--staged Desactivado Limita el alcance de la diferencia solo al índice de etapa de pruebas (git diff --cached). Requiere --diff.
--diff-depth DEPTH 1 Es la profundidad de recorrido para el análisis de impacto (de 1 a 3, valor predeterminado: 1 salto).
--diff-workers COUNT 4 Es la cantidad de trabajadores simultáneos para los trabajos de auditoría de solicitud de extracción (de 1 a 16).
--diff-max-neighbors COUNT 10 Es la cantidad máxima de archivos dependientes de la persona que llama o que recibe la llamada que se deben inspeccionar.
--fail-on SEVERITIES CRITICAL,HIGH Gravedades separadas por comas que hacen que cm find salga con el código 1.
--fail-on-truncation Desactivado Sal con el código 1 si el descubrimiento de vecinos supera el límite.
--format FORMAT table Formato de salida: table, json o sarif.
--output FILE Salida estándar Escribe el informe en un archivo en lugar de la salida estándar.

Marcas de escaneo rápido

La siguiente marca configura los análisis de cm find --quick:

Marca Valor predeterminado Descripción
--quick false Ejecuta un análisis rápido de una sola sesión en lugar del análisis profundo simultáneo predeterminado por archivo. No se puede usar con --deep ni --diff.