Acerca de la CLI de CodeQL

Los desarrolladores de software y los investigadores de seguridad pueden proteger su código mediante el análisis de CodeQL. Para más información sobre CodeQL, consulta AUTOTITLE.

La CodeQL CLI es una herramienta de línea de comandos independiente que puedes utilizar para analizar código. Su propósito principal es generar una representación de base de datos de un código base, una base de datos de CodeQL. Una vez que esté lista la base de datos, puede consultarla interactivamente o ejecutar un varias consultas para generar un conjunto de resultados en formato SARIF y cargarlos a GitHub.

Puedes usar la CodeQL CLI para:

• Ejecuten análisis de CodeQL usando consultas proporcionadas por ingenieros de GitHub y la comunidad de código abierto.
• Generar alertas de examen de código que puedes cargar para mostrar en GitHub
• Crear bases de datos de CodeQL para usarlas en la extensión CodeQL para Visual Studio Code.
• Desarrollar y probar consultas personalizadas de CodeQL para usarlas en tus propios análisis.

La CodeQL CLI puede analizar:

• Lenguajes dinámicos, por ejemplo, JavaScript y Python.
• Lenguajes compilados, por ejemplo, C/C++, C#, Go, Java, Kotlin, Rust, y Swift
• Bases de código escritas en varios lenguajes.

Acerca de utilizar el CodeQL CLI para el code scanning

Puedes usar la CodeQL CLI para ejecutar code scanning en el código que estás procesando en un sistema de integración continua (CI) de terceros. Code scanning es una característica que se usa para analizar el código en un repositorio de GitHub para buscar vulnerabilidades de seguridad y errores de código. Los problemas identificados por el análisis se muestran en el repositorio. Para obtener información general sobre el uso del análisis de código con sistemas de CI externos, consulte AUTOTITLE. Para conocer las especificaciones recomendadas (RAM, núcleos de CPU y disco) para ejecutar análisis de CodeQL, consulta AUTOTITLE.

Como alternativa, puede usar GitHub Actions o las canalizaciones de Azure DevOps para examinar el código mediante CodeQL CLI. Para más información, consulta AUTOTITLE o Configuración de GitHub Advanced Security for Azure DevOps en Microsoft Learn.

Para obtener información general de todas las opciones para usar el análisis de CodeQL para el examen de código, consulta AUTOTITLE.

Acerca de generar los resultados del escaneo de código con la CodeQL CLI

Si decides ejecutar la CodeQL CLI directamente, primero tienes que instalar la CodeQL CLI localmente. Si pretendes usar la CodeQL CLI con un sistema de CI externo, debes poner la CodeQL CLI a disposición de los servidores del sistema de CI.

Una vez configurada la CodeQL CLI, puedes usar tres comandos diferentes para generar resultados y cargarlos en GitHub:

1. para crear una base de datos de CodeQL que represente la estructura jerárquica de cada lenguaje de programación admitido en el repositorio. Para más información, consulta AUTOTITLE.
2. para ejecutar consultas para analizar cada base de datos de CodeQL y resumir los resultados en un archivo SARIF. Para más información, consulta AUTOTITLE.
3. para cargar los archivos SARIF resultantes a GitHub, donde los resultados se comparan con una rama o solicitud de incorporación de cambios y se muestran como alertas del code scanning. Para más información, consulta AUTOTITLE.

Configuración de IC de ejemplo para el análisis de CodeQL

Este es un ejemplo de la serie completa de comandos para la CodeQL CLI que puedes utilizar para analizar una base de código con dos lenguajes compatibles y luego cargar los resultados en GitHub.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

Extracción de bases de datos

CodeQL CLI usa programas especiales, denominados extractores, para extraer información del código fuente de un sistema de software a una base de datos que se puede consultar. Puedes personalizar el comportamiento de los extractores estableciendo las opciones de configuración de extractor mediante la CodeQL CLI. Consulta AUTOTITLE.

Cómo empezar

Para obtener la manera más sencilla de empezar, consulte AUTOTITLE.

Hay disponibles opciones de configuración más avanzadas si las necesita. Por ejemplo, si:

• Quiere contribuir a las consultas compartidas de código abierto CodeQL y prefiere trabajar directamente con el código fuente CodeQL. Consulta AUTOTITLE.
• Es necesario instalar varias versiones de CodeQL CLI simultáneamente. Por ejemplo, si un código base requiere una versión específica mientras que otra usa la versión más reciente. Puede descargar cada versión y desempaquetar ambos archivos de la CLI en el mismo directorio primario.
• Está investigando o desarrollando consultas y desea descargar bases de datos de GitHub.com. Consulta AUTOTITLE.