Configurar el CLI de CodeQL en tu sistema de IC

Puedes configurar tu sistema de integración continua para que ejecute el CodeQL CLI, realice un análisis de CodeQL y cargue los resultados en GitHub para mostrarlos como alertas del escaneo de código.

El Escaneo de código se encuentra disponible para todos los repositorios públicos y para los privados que pertenecen a organizaciones en donde se habilitó la GitHub Advanced Security. Para obtener más información, consulta la sección "Acerca de GitHub Advanced Security".

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

Una vez que hayas puesto el CodeQL CLI disponible en los servidores de tu sistema de IC y de que te hayas asegurado que se pueden autenticar con GitHub, estarás listo para generar datos.

Utilizarás tres comandos diferentes para generar los resultados y cargarlos a GitHub:

  1. database create para crear una base de datos de CodeQL para representar la estructura jerárquica de cada lenguage de programación compatible en el repositorio.
  2. database analyze para ejecutar consultas para analizar cada base de datos de CodeQL y resumir los resultados en un archivo SARIF.
  3. github upload-results para cargar los archivos sarif resultantes a GitHub en donde los resultados se empatan con una rama o solicitud de cambios y se muestran como alertas del escaneo de código.

Puedes mostrar la ayuda en la línea de comandos para apoyarte sobre cualquier comando utilizando la opción --help .

Nota: El cargar datos de SARIF para mostrarlos como resultados del escaneo de código eb 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, consulta la sección "Administrar la configuración de seguridad y análisis para tu repositorio".

Crear bases de datos de CodeQL para analizar

  1. Verifica que el código que quieres analizar:

    • Para una rama, verifica el encabezado de la rama que quieras analizar.
    • Para una solicitud de cambios, verifica ya sea la confirmación de encabezado de la solicitud o una confirmación de fusión generada por GitHub de dicha solicitud.
  2. Configura el ambiente de la base de código, asegurándote de que todas las dependencias estén disponibles. Para obtener más información, consulta las secciones Crear bases de datos para lenguajes no compilados y Crear bases de datos para lenguajes compilados en la documentación del CodeQL CLI.

  3. Encuentra el comando de compilación, en caso de que exista, para la base de código. Habitualmente, esta es una variable en un archivo de configración en el sistema de IC.

  4. Ejecuta codeql database create desde la raíz de verificación de tu repositorio y recompila la base de código.

    # Single supported language - create one CodeQL databsae
    codeql database create <database> --command<build> --language=<language-identifier> 
    
    # Multiple supported languages - create one CodeQL database per langauge
    codeql database create <database> --command<build> \
          --db-cluster --language=<language-identifier>,<language-identifier> 

    Nota: Si utilizas una compilación que usa contenedores, necesitas ejecutar el CodeQL CLI dentro del contenedor en donde toma lugar tu tarea de compilación.

Opción Requerido Uso
<database> Especifica el nombre y ubicación de un directorio a crear para la base de datos de CodeQL. El comando fallará si intentas sobrescribir un directorio existente. Si también especificas el --db-cluster, este es el directorio padre y se crea un subdirectorio para cada lenguaje analizado.
`--language` Especifica el identificador del lenguaje para el cual se creará la base de datos, debe ser uno de entre: `cpp`, `csharp`, `go`, `java`, `javascript`, y `python` (utiliza javascript para analizar el código en TypeScript).
cuando se utiliza con `--db-cluster`, la opción acepta una lista separada por comas o puede especificarse más de una vez.
`--command` Recomendado. Utilízalo para especificar el comando o script de compilación que invoca el proceso de compilación para la base de código. Los comandos se ejecutan desde la carpeta actual o, cuando se define, desde `--source-root`. No se necesita para analizar Python y JavaScript/TypeScript.
`--db-cluster` Opcional. Utiliza las bases de código multi-lenguaje para generar una base de datos para cada lenguaje que especifica `--language`.
`--no-run-unnecessary-builds` Recomendado. Utilízalo para suprimir el comando de compilación para los lenguajes en donde el CodeQL CLI no necesite monitorear la compilación (por ejemplo, Python y JavaScript/TypeScript).
`--source-root` Opcional. Utilízalo si ejecutas el CLI fuera de la raíz de verificación del repositorio. Predeterminadamente, el comando de database create asume que el directorio actual es el directorio raíz de los archivos fuente, utiliza esta opción para especificar una ubicación diferente.

Para obtener más información, consulta la sección Crear bases de datos de CodeQL en la documentación del CodeQL CLI.

Ejemplo con un solo lenguaje

Este ejemplo crea una base de datos de CodeQL para el repositorio que se verificón en /checkouts/example-repo. Utiliza el extractor de JavaScript para crear una representación jerárquica del código de JavaScript y TypeScript en el repositorio. La base de datos resultante se almacena en /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
... 
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Ejemplo de lenguaje múltiple

Este ejemplo crea dos bases de datos de CodeQL para el repositorio que se verificó en /checkouts/example-repo-multi. Esta utiliza:

  • --db-cluster para solicitar el análisis de más de un lenguaje.
  • --language para especificar para qué lenguajes creará bases de datos.
  • --command para decirle a la herramienta el comando de compilación para la base de código, aquí es make.
  • --no-run-unnecessary-builds para decirle a la herramienta que se salte el comando de compilación para los lenguajes en donde no se necesita (como Pyhon).

La base de datos resultante se almacena en los subdirectorios python y cpp de /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Analizar una base de datos de CodeQL

  1. Crea una base de datos de CodeQL (mira el ejemplo anterior).
  2. Opcionalmente, ejecuta codeql pack download para descargar cualquier paquete de CodeQL (beta) que quieras ejecutar durante el análisis. Para obtener más información, consulta la sección "Descargar y usar los paquetes de consultas de CodeQL" a continuación.
    codeql pack download <packs> 
  3. Ejecuta codeql database analyze en la base de datos y especifica qué paquetes o consultas utilizar.
    codeql database analyze <database> --format=<format> \
        --output=<output>  <packs,queries> 

Nota: Si analizaste más de una base de datos de CodeQL para una confirmación simple, debes especificar una categoría SARIF para cada conjunto de resultados que se generaron con este comando. Cuando cargas los resultados en GitHub, el escaneo de código utiliza esta categoría para almacenar los resultados para cada lenguaje por separado. Si te olvidas de hacerlo, cada carga sobreescribe los resultados anteriores.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>
Opción Requerido Uso
<database> Especifica la ruta del directorio que contiene la base de datos de CodeQL a analizar.
<packs,queries> Specify CodeQL packs or queries to run. To run the standard queries used for escaneo de código, omit this parameter. Para ver el resto de las suites de consultas que se incluyen en el paquete del CodeQL CLI, revisa /<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites. Para obtener más información sobre cómo crear tu suite de consultas, dirígete a la sección "Crear suites de consultas de CodeQL en la documentación para el CodeQL CLI.
`--format` Especifica el formato del archivo de resultados que generó el comando. Para cargar a GitHub, este debe ser: sarif-latest. Para obtener más información, consulta la sección "Soporte de SARIF para escaneo de código".
`--output` Especifica dónde guardar el archivo de resultados SARIF.
--sarif-category Opcional para el análisis de bases de datos simples. Requerido para definir el idioma cuando analizas bases de datos múltiples para una confirmación simple en un repositorio. Especifica una categoría para incluir en el archivo de resultados SARIF para su análisis. Se utiliza una categoría para distinguir entre análisis múltiples para la misma herramienta y confirmación, pero se realiza en lenguajes diferentes o en partes diferentes del código.
<packs> Opcional. Utilízalo si descargaste paquetes de consultas de CodeQL y quieres ejecutar las consultas predeterminadas o suites de consultas especificadas en estos. Para obtener más información, consulta la sección "Descargar y utilizar paquetes de CodeQL".
`--threads` Opcional. Utilízala si quieres usar más de un subproceso para ejecutar consultas. El valor predeterminado es 1. Puedes especificar más subprcesos para agilizar la ejecución de la consulta. Para configurar la cantidad de subprocesos en la cantidad de procesadores lógicos, especifica 0.
`--verbose` Opcional. Utilízalo para obtener información más detallada sobre el proceso de análisis y datos de diagnóstico del proceso de creación de bases de datos.

Para obtener más información, consulta la sección Analizar las bases de datos con el CodeQL CLI en la documentación del CodeQL CLI.

Ejemplo básico

Este ejemplo analiza una base de datos de CodeQL que se almacena en /codeql-dbs/example-repo y guarda los resultados como un archivo SARIF: /temp/example-repo-js.sarif. Este utiliza --sarif-category para incluir información adicional en el archivo SARIF que identifica los resultados como JavaScript. Esto es escencial cuando tienes más de una base de datos de CodeQL que analizar para una sola confirmación en un repositorio.

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=javascript
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
    codeql-javascript/AngularJS/DisablingSce.ql.
... 
> Shutting down query evaluator.
> Interpreting results.

Cargar resultados en GitHub

Notas:

  • SARIF upload supports a maximum of 5000 results per upload. Cualquier resultado que sobrepase este límite se ignorará. Si una herramienta genera demasiados resultados, debes actualizar la configuración para enfocarte en los resultados de las reglas o consultas más importantes.

  • For each upload, SARIF upload supports a maximum size of 10 MB for the gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.

Antes de que puedas cargar los resultados a GitHub, debes determinar la mejor forma de pasar el token de acceso personal o de la GitHub App que creaste anteriormente al CodeQL CLI (consulta la sección Instalar el CodeQL CLI en tu sistema de IC). Te recomendamos que revises las instrucciones de tu sistema de IC sobre el uso seguro para un almacenamiento de secretos. El CodeQL CLI es compatible con:

  • Pasar el token al CLI a través de una entrada estándar utilizando la opción --github-auth-stdin (recomendado).
  • Guardar el secreto en la variable de ambiente GITHUB_TOKEN y ejecutando el CLI sin incluir la opción --github-auth-stdin.

Cuando decidas cuál será el método más seguro y confiable para tu servidor de IC, ejecuta codeql github upload-results en cada archivo de resultados SARIF e incluye --github-auth-stdin, a menos de que el token esté disponible en la variable de ambiente GITHUB_TOKEN.

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin
Opción Requerido Uso
`--repository` Especifica el OWNER/NAME del repositorio al cual quieres cargar los datos. El propietario debe ser una organización dentro de una empresa que tenga una licencia de GitHub Advanced Security y la GitHub Advanced Security debe estar habilitada para el repositorio, a menos de que este sea público. Para obtener más información, consulta la sección "Administrar la configuración de seguridad y análisis para tu repositorio".
`--ref` Especifica el nombre de la ref que verificaste y analizaste para que los resultados puedan empatarse con el código correcto. Para una rama, utiliza: refs/heads/BRANCH-NAME, para la confirmación de encabezado de una solicitud de cambios utiliza refs/pulls/NUMBER/head o, para la confirmación de fusión que genera GitHub para una solicitud de cambios, utiliza refs/pulls/NUMBER/merge.
`--commit` Especifica el SHA completo de la confirmación que analizaste.
`--sarif` Especifica el archivo SARIF a cargar.
`--github-auth-stdin` Opcional. Utilízala para pasar al CLI la GitHub App o token de acceso personal que creaste para autenticarse con la API de REST de GitHub a través de una entrada estándar. Esto no se necesita si el comando tiene acceso a una variable de ambiente de GITHUB_TOKEN que se configuró con este token.

Para obtener más información, consulta la sección resultados de carga de github en la documentación del CodeQL CLI.

Ejemplo básico

Este ejemplo carga los resultados del archivo SARIF temp/example-repo-js.sarif al repositorio my-org/example-repo. Le dice a la API del escaneo de código que los resultados son para la confirmación deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 en la rama main.

$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

No hay salida para este comando a menos de que la carga no sea exitosa. El símbolo de sistema regresa cuando la carga se completa e inicia el procesamiento de datos. En bases de código más pequeñas, debes poder explorar las alertas del escaneo de código en GitHub poco tiempo después. Puedes ver las alertas directamente en la solicitud de cambios en la pestaña de Seguridad de las ramas, dependiendo del código que verificaste. Para obtener más información, consulta las secciones "Clasificar las alertas del escaneo de código en las solicitudes de cambio" y "Administrar las alertas del escaneo de código de tu repositorio".

Descargar y utilizar paquetes de consultas de CodeQL

Nota: La funcionalidad de administración de paquetes de CodeQL, incluyendo los paquetes de CodeQL, se encuentra actualmente en beta y está sujeta a cambios.

El paquete de CodeQL CLI incluye consultas que mantienen los expertos de GitHub, los investigadores de seguridad y los contribuyentes de la comunidad. Si quieres ejecutar consultas que desarrollan otras organizaciones, los paquetes de consultas de CodeQL proporcionan una forma confiable y eficiente de descargarlas y ejecutarlas. Para obtener más información, consulta la sección "Acerca del escaneo de código con CodeQL"".

Antes de que puedas utilizar un paquete de CodeQL para analizar una base de datos, debes descargar cualquier paquete que requieras desde el Registro de contenedores de GitHub ejecutando codeql pack download y especificando los paquetes que quieras descargar. Si un paquete no está disponible públicamente, necesitarás utilizar un token de acceso personal o de GitHub App para autenticarte. Para obtener más información y un ejemplo, consulta la sección anterior de "Cargar los resultados a GitHub".

codeql pack download <scope/name@version>,... 
Opción Requerido Uso
`` Especifica el alcance y nombre de uno o más paquetes de consultas de CodeQL a descargar utilizando una lista separada por comas. Opcionalmente, incluye la versión para descargar y descomprimir. Se descarga la versión más reciente de este paquete predeterminadamente.
`--github-auth-stdin` Opcional. Pasa la GitHub App o el token de acceso personal que se creó para la autenticación con la API de REST de GitHub al CLI a través de una entrada estándar. Esto no se necesita si el comando tiene acceso a una variable de ambiente de GITHUB_TOKEN que se configuró con este token.

Ejemplo básico

Este ejemplo ejecuta dos comandos para descargar la última versión del paquete octo-org/security-queries y luego analiza la base de datos /codeql-dbs/example-repo.

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download octo-org/security-queries

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0

$ codeql database analyze /codeql-dbs/example-repo  octo-org/security-queries \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/1] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> [1/1 eval 394ms] Evaluation done; writing results to docto-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

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

Este es un ejemplo de la serie de comandos que puedes utilizar para analizar una base de código con dos lenguajes compatibles y luego cargar los resultados a 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'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

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

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

Solucionar problemas del CodeQL CLI en tu sistema de IC

Visualizar la información diangóstica y de la bitácora

Cuando analices una base de datos de CodeQL utilizando un conjunto de consultas del escaneo de código adicionalmente a generar información detallada sobre las alertas, el CLI reporta datos de diagnóstico desde el paso de generación de base de datos y las métricas de resumen. En el caso de los repositorios con pocas alertas, puede que esta información te sea útil para determinar si genuinamente hay pocos problemas en el código o si hubieron errores que se generaron en la base datos de CodeQL. Para obtener una salida más detallada de codeql database analyze, utiliza la opción --verbose.

Para obtener información sobre el tipo de información de diagnóstico disponible, consulta la sección "Visualizar las bitácoras del escaneo de código".

El Escaneo de código solo muestra los resultados de análisis de uno de los lenguajes analizados

Predeterminadamente, el escaneo de código espera un archivo de resultado SARIF por cada análisis de un repositorio. Como consecuencia, cuando cargues un segundo archivo de resultados SARIF para una confirmación, este se tratará como un reemplazo para el conjunto de datos original.

Si quieres cargar más de un conjunto de resultados a la API del escaneo de código para una confirmación en un repositorio, debes identificar cada conjunto de resultados como un conjunto único. En el caso de los repositorios en donde creas más de una base de datos de CodeQL para analizar cada confirmación, utiliza la opción --sarif-category para especificar un lenguaje u otra categoría para cada archivo SARIF que generes para ese repositorio.

Alternativa si tu sistema de IC no puede activar el CodeQL CLI

Si tu sistema de IC no puede activar la autocompilación del CodeQL CLI y no puedes especificar una línea de comandos para dicha compilación, puedes utilizar el rastreo de compilación indirecta para crear bases de datos de CodeQL para los lenguajes compilados. Para obtener más información, consulta la sección Utilizar el rastreo indirecto de compilaciones en la documentación del CodeQL CLI.

Leer más

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.