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, 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 cm find:

Modo Comando Alcance objetivo Tiempo de ejecución típico Ideal para
Análisis estándar cm find PATH Directorio especificado Tiempo de ejecución moderado Descubrimiento de desarrolladores locales, verificaciones rápidas y revisiones exploratorias
Análisis de diferencias cm find PATH --diff[=REF] Archivos modificados más archivos dependientes (como llamadores y receptores) Tiempo 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 profundo cm find PATH --deep Repositorio completo Tiempo de ejecución más largo Auditorías programadas, preparación para el lanzamiento y certificaciones de cumplimiento (SOC 2, ISO)

Análisis estándar (predeterminado)

Un análisis estándar es el modo predeterminado cuando ejecutas cm find sin proporcionar marcas de análisis adicionales. Ejecuta un análisis autónomo de una sola sesión del directorio de destino especificado. Durante el análisis, CodeMender descubre archivos fuente, los prioriza según los patrones de vulnerabilidad, realiza un análisis de seguridad inicial y genera informes sobre las posibles vulnerabilidades agrupadas por gravedad y tipo.

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

# Scan a directory using the default model
cm find ./src

# Scan with a specific Gemini model
cm find ./src --model gemini-3.8-flash

Ventajas

Un análisis estándar funciona sin configuración y sin marcas ni parámetros adicionales. Equilibra la velocidad y la cobertura con un tiempo de ejecución moderado, y usa tokens y procesamiento mínimos, lo que lo hace rentable para el desarrollo diario.

Compensaciones y limitaciones

Un análisis estándar 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 con varios paquetes porque opera dentro de un contexto de una sola sesión. También se enfoca principalmente en patrones locales dentro de archivos individuales, lo que limita el análisis entre paquetes y podría omitir vulnerabilidades que abarcan paquetes distantes.

Cuándo usar

Usa un análisis estándar en los siguientes casos:

  • Ejecuta un análisis en tu máquina local antes de confirmar los cambios para obtener comentarios rápidos durante el desarrollo local.
  • Inspecciona un repositorio recién clonado o un proyecto pequeño para una evaluación inicial de su postura de seguridad.
  • Inspecciona un subdirectorio o módulo específico cuando investigues un posible problema.

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 mediante la inspección de archivos modificados y agregados, y se enfoca en los rangos de líneas exactos (fragmentos 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 intacto para que los problemas heredados no provoquen que falle el análisis ni bloqueen la solicitud de extracción. Luego, evalúa los resultados en función de tu política --fail-on y genera 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 almacenados 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 canalización de extremo a extremo, consulta Integración con CI/CD.

Ventajas

Un análisis de diferencias es rápido y determinista, 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 analizadores de diferencias que solo inspeccionan las líneas modificadas, --diff inspecciona las relaciones de llamador y receptor para detectar regresiones de seguridad entre archivos y incumplimientos de contrato. Debido a que suprime los resultados en el código intacto, 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 GitHub Code Scanning 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 intactas 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 los siguientes casos:

  • Ejecuta verificaciones automatizadas en cada solicitud de extracción en 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 de 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 profundo

Un análisis profundo es un modo de análisis exhaustivo diseñado para auditorías de seguridad integrales en todo el repositorio. Audita los archivos fuente en todo el repositorio de forma simultánea con trabajadores paralelos (configurados con --deep-workers, que tiene el valor predeterminado 8 y admite un rango de 1 a 16). A medida que descubre los resultados candidatos, los valida y corrobora con el contexto de código circundante para filtrar los falsos positivos antes de generar informes sobre 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 entire repository
cm find . --deep

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

Ventajas

Un análisis profundo 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. Admite varios lenguajes y es independiente de la plataforma, ya que funciona en todos los lenguajes compatibles con Gemini sin requerir compiladores específicos del lenguaje, configuraciones de compilación ni archivos de gramática. También optimiza el uso de recursos enfocando el análisis en el código de producción y minimizando el consumo de tokens y procesamiento en 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 en todo el repositorio. Como resultado, requieren un tiempo de ejecución más largo y un mayor gasto de tokens que los análisis estándar o de diferencias.

Cuándo usar

Usa un análisis profundo en los siguientes casos:

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

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 estándar cm find ./src
Terminal local Verificación previa a la confirmación de los cambios almacenados antes de enviarlos Análisis de diferencias cm find . --diff --staged
Canalización de CI/CD Puerta de solicitud de extracción automatizada en el código modificado y los llamadores Análisis de diferencias cm find . --diff=origin/main --fail-on=CRITICAL,HIGH
Canalización o auditoría programada Auditorías nocturnas, puertas previas al lanzamiento y cumplimiento de SOC 2 Análisis profundo cm find . --deep --deep-workers=8

Referencia de marcas de comandos por modo

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

Marcas comunes (todos los modos)

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

Marcar 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 Modelo de Gemini para usar (gemini-3.8-flash, gemini-3.8-flash-cyber).
-y, --yes false Omite todos los prompts de confirmación interactivos.
--unrestricted false Desactiva el sandbox del sistema de archivos.

Marcas de análisis de diferencias

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

Marcar Valor predeterminado Descripción
--diff[=REF] Desactivado Habilita el modo de diferencias en la referencia de destino, como origin/main o HEAD~1. Sin REF, se compara con HEAD. No se puede usar con --deep.
--staged Desactivado Limita la diferencia al índice almacenado en etapas únicamente (git diff --cached). Requiere --diff.
--diff-depth DEPTH 1 Profundidad de recorrido para el análisis de impacto (de 1 a 3, valor predeterminado: 1 salto).
--diff-workers COUNT 4 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 Cantidad máxima de archivos de llamador o receptor dependientes para 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 resultado: table, json o sarif.
--output FILE Salida estándar Escribe el informe en un archivo en lugar de la salida estándar.

Marcas de análisis profundo

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

Marcar Valor predeterminado Descripción
--deep false Habilita el análisis profundo exhaustivo en todo el repositorio. No se puede usar con --diff.
--deep-workers COUNT 8 Cantidad de trabajadores simultáneos para el análisis profundo (de 1 a 16).