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, y equilibra la velocidad, el alcance y la profundidad.

Cómo comparar los modos de búsqueda

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

Modo Comando Alcance del 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 y archivos dependientes (como los que llaman y los que son llamados) Tiempo de ejecución rápido Canalizaciones de CI/CD de solicitudes de extracción (GitHub Actions, Cloud Build), ganchos de pre-commit
Análisis profundo cm find PATH --deep Todo el repositorio Mayor tiempo de ejecución Auditorías programadas, preparación para el lanzamiento, 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 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 objetivo:

# 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 parámetros ni marcas adicionales. Equilibra la velocidad y la cobertura con un tiempo de ejecución moderado, y usa una cantidad mínima de tokens y procesamiento, lo que lo hace rentable para el desarrollo diario.

Compromisos 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 solo contexto de sesión. También se enfoca principalmente en los 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 clonado recientemente o un proyecto pequeño para realizar 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 inspeccionando los 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 los archivos intactos del 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 errores en el análisis 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 confirmados 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 la configuración de canalizaciones de extremo a extremo, consulta Integración con CI/CD.

Ventajas

Un análisis de diferencias es rápido y determinístico, y suele completarse 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 entre el llamador y el llamado para detectar regresiones de seguridad y violaciones de contrato entre archivos. 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 del 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 las 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 pre-commit o pre-push antes de enviar el código al repositorio remoto.
  • Validar que las combinaciones entre las ramas de versiones no introduzcan regresiones

Análisis profundo

El 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 posibles hallazgos, 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 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 recuperación alta y un descubrimiento integral de vulnerabilidades en grandes bases de código empresariales, supera a los análisis de una sola sesión y usa la verificación automatizada para mantener una alta precisión. Es compatible con varios idiomas y es independiente de la plataforma, ya que funciona en todos los idiomas admitidos por Gemini sin necesidad de compiladores, configuraciones de compilación o archivos de gramática específicos del idioma. También 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.

Compromisos 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 una mayor inversión 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 todas las noches o semanas 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 se incorpora 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 escaneo 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 organizados antes de la transferencia Análisis de diferencias cm find . --diff --staged
Canalización de CI/CD Control automatizado de solicitud de extracción en el código y los llamadores modificados 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 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 "" Es el contexto adicional para guiar al agente de análisis, como las notas de arquitectura.
--model MODEL_NAME gemini-3.8-flash 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 Desactiva el espacio aislado 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 comparación con 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 comparación a la diferencia del índice en etapa de pruebas (git diff --cached). Requiere --diff.
--diff-depth DEPTH 1 Profundidad de la exploración 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 Es la cantidad máxima de archivos de la persona que llama o la persona llamada dependientes que se pueden 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 en la salida estándar.

Marcadores de análisis profundo

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

Marca Valor predeterminado Descripción
--deep false Habilita el análisis detallado 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).