Acerca de la CLI de CodeQL

Acerca de CodeQL CLI

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 "Acerca del examen de código con CodeQL".

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 una base de código, una base de datos de CodeQL. Una vez que esté lista la base de datos, puedes consultarla interactivamente o ejecutar un varias consultas para generar un conjunto de resultados en formato SARIF y cargarlos a GitHub.com.

Puedes usar la CodeQL CLI para:

Ejecutar análisis de CodeQL usando consultas proporcionadas por ingenieros de GitHub y por 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 eje mplo, JavaScript y Python.
Lenguajes compilados, por ejemplo, C/C++, C#, Go, y Java.
Bases de código escritas en varios lenguajes.

Para más información sobre la configuración de la CodeQL CLI, consulta "Configuración de la CLI de CodeQL."

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. Cualquier problema que se identifique con el análisis se muestra en GitHub. Para información general sobre el uso del análisis de código con sistemas de CI externos, consulta «Utilizar el análisis de código de CodeQL con tu sistema de IC existente». Para conocer las especificaciones recomendadas (RAM, núcleos de CPU y disco) para ejecutar análisis de CodeQL, consulta "Recursos de hardware recomendados para ejecutar CodeQL".

Como alternativa, puedes usar GitHub Actions o canalizaciones de Azure DevOps para examinar el código mediante la CodeQL CLI. Para obtener más información, consulta "Establecimiento de la configuración predeterminada para el examen del código" o Configurar 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 "Acerca del examen de código con CodeQL".

Notas:

La CodeQL CLI puede usarse libremente en repositorios públicos. CodeQL CLI también está disponible en los repositorios privados que pertenecen a las organizaciones que usan GitHub Enterprise Cloud y que tienen una licencia de GitHub Advanced Security. Para obtener información, vea "Términos y condiciones de GitHub CodeQL" y "CLI de CodeQL".
La CodeQL CLI no es compatible actualmente con distribuciones de Linux que no sean glibc, como Alpine Linux (basado en musl).

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. Para obtener más información, vea «Configuración de la CLI de CodeQL».

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

database create 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 obtener más información, vea «Preparación del código para el análisis de CodeQL».
database analyze para ejecutar consultas para analizar cada base de datos de CodeQL y resumir los resultados en un archivo SARIF. Para obtener más información, vea «Análisis del código con consultas de CodeQL».
github upload-results 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 obtener más información, vea «Carga de los resultados del análisis de CodeQL en GitHub».

Nota: Cargar datos de SARIF para mostrarlos como resultados de code scanning en GitHub es compatible para los repositorios que pertenezcan a organizaciones con la GitHub Advanced Security habilitada y para los repositorios públicos en GitHub.com. Para obtener más información, vea «Administración de la configuración de seguridad y análisis para el repositorio».

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

Acerca de la licencia de GitHub CodeQL

Aviso sobre la licencia: Si no tienes una licencia de GitHub Enterprise, al instalar este producto aceptas los términos y condiciones de GitHub CodeQL.

Las licencias de GitHub CodeQL se otorgan por usuario. De conformidad con las restricciones de las licencias, puedes usar CodeQL para realizar las siguientes tareas:

Realizar investigaciones académicas.
Hacer demostraciones del software.
Probar las consultas de CodeQL publicadas bajo una licencia aprobada por la OSI para confirmar que las nuevas versiones de esas consultas siguen detectando las vulnerabilidades adecuadas.

"Licencia aprobada por la OSI" hace referencia a una licencia de software de código abierto aprobada por la Iniciativa para el Código Abierto (OSI, por sus siglas en inglés).

Si trabajas con un código base de código abierto (es decir, un código base que se publica bajo una licencia aprobada por la OSI), también puedes usar CodeQL para las siguientes tareas:

Realizar análisis del código base de código abierto.
Generar bases de datos de CodeQL para o durante el análisis automatizado, la integración continua o la entrega continua, solo si el código base de código abierto se hospeda y mantiene en GitHub.com.

Salvo en los casos específicos definidos en este documento, no se puede usar CodeQL para el análisis automatizado, la integración continua o la entrega continua, ya sea como parte de procesos normales de ingeniería de software o de otro modo. Para estos usos, ponte en contacto con el equipo de ventas.