Personalización de la configuración avanzada para el examen de código

Puede personalizar cómo examina su configuración avanzada el código del proyecto en busca de vulnerabilidades y errores.

¿Quién puede utilizar esta característica?

Usuarios con acceso de escritura if advanced setup is already enabled

En este artículo

Acerca de la configuración de code scanning

Puedes ejecutar el code scanning en GitHub si utilizas las GitHub Actions o desde tu sistema de integración continua (IC). Para más información, consulta Escritura de flujos de trabajo o Utilizar el análisis de código de CodeQL con tu sistema de IC existente.

La configuración avanzada del code scanning es útil cuando necesitas un control más pormenorizado de la configuración del code scanning. Para más información, consulta Establecimiento de la configuración avanzada para el examen del código.

El análisis de CodeQL es tan solo un tipo de code scanning que puedes hacer en GitHub. GitHub Marketplace contiene otros flujos de trabajo del code scanning que puedes utilizar. Puedes encontrar una selección en la página "Get started with code scanning", a la que puedes acceder desde la pestaña Security. Los ejemplos específicos que se mencionan en este artículo se relacionan con el archivo Flujo de trabajo de análisis de CodeQL.

Editar un flujo de trabjo de code scanning

GitHub guarda los archivos de flujo de trabajo en el directorio de .github/workflows de su repositorio. Para encontrar un flujo de trabajo que haya agregado, busque su nombre de archivo. Por ejemplo, de manera predeterminada, el archivo de flujo de trabajo del code scanning de CodeQL se llama codeql-analysis.yml.

  1. En tu repositorio, navega hasta el archivo de flujo de trabajo que deseas editar.
  2. En la esquina superior derecha de la vista del archivo, haga clic en para abrir el editor de flujos de trabajo.
  3. Una vez editado el archivo, haga clic en Start commit (Iniciar confirmación) y complete el formulario "Commit changes" (Confirmar cambios). Puede elegir entre confirmar directamente en la rama actual o crear una rama e iniciar una solicitud de incorporación de cambios.

Para obtener más información sobre la edición de archivos de flujo de trabajo, consulta Escritura de flujos de trabajo.

Configurar la frecuencia

Puedes configurar el Flujo de trabajo de análisis de CodeQL para que escanee código en horarios programados o cuando ocurran eventos específicos en un repositorio.

Escanear el código en cada carga al repositorio, y cada vez que se crea una solicitud de extracción, previene que los desarrolladores introduzcan vulnerabilidades y errores nuevos en dicho código. Escanear el código con una programación definida te informará de las últimas vulnerabilidades y errores que GitHub, los investigadores de seguridad, y la comunidad descubren, aún cuando los desarrolladores no estén manteniendo el repositorio activamente.

Escanear cuando se carga información

De manera predeterminada, el Flujo de trabajo de análisis de CodeQL utiliza el evento on:push para activar un análisis de código en cada subida a la rama predeterminada del repositorio y de cualquier rama protegida. Para que el code scanning se active en una rama específica, el flujo de trabajo debe existir en ella. Para más información, consulta Sintaxis del flujo de trabajo para Acciones de GitHub.

Si el examen se realiza al enviar cambios, los resultados aparecen en la pestaña Security del repositorio. Para más información, consulta Evaluación de alertas de análisis de código para el repositorio.

Además, cuando un examen on:push devuelve resultados que se pueden asignar a una solicitud de incorporación de cambios abierta, estas alertas aparecerán automáticamente en la solicitud de incorporación de cambios en el mismo lugar que otras alertas de solicitud de incorporación de cambios. Las alertas se identifican comparando el análisis existente del encabezado de la rama con el análisis de la rama de destino. Para obtener más información sobre code scanning alertas en solicitudes de incorporación de cambios, consulta Clasificar las alertas del escaneo de código en las solicitudes de cambios.

Escanear las solicitudes de extracción

El Flujo de trabajo de análisis de CodeQL predeterminado utiliza el evento pull_request para activar un análisis de código en las solicitudes de incorporación de cambios relativas a la rama predeterminada. Si una solicitud de incorporación de cambios es de una bifurcación privada, el evento de pull_request solo se activará si seleccionó la opción "Run workflows from fork pull requests" en la configuración del repositorio. Para más información, consulta Administrar los ajustes de las GitHub Actions de un repositorio.

Para obtener más información sobre el evento pull_request, consulta Eventos que desencadenan flujos de trabajo.

Si examina las solicitudes de incorporación de cambios, los resultados aparecen como alertas en una comprobación de solicitudes de incorporación de cambios. Para más información, consulta Clasificar las alertas del escaneo de código en las solicitudes de cambios.

Cuando se usa el desencadenador pull_request, configurado para examinar la confirmación de combinación de la solicitud de incorporación de cambios en lugar de la confirmación del encabezado, se generarán resultados más eficaces y precisos que el examen del encabezado de la rama en cada envío de cambios de cambios. Sin embargo, si usa un sistema de CI/CD que no se puede configurar para que se desencadene en las solicitudes de incorporación de cambios, puede usar el desencadenador on:push, y code scanning asignará los resultados a las solicitudes de incorporación de cambios abiertas en la rama y agregará las alertas como anotaciones en la solicitud de incorporación de cambios. Para obtener más información, consulta Examinar al insertar.

Note

Si el repositorio está configurado con una cola de fusión mediante combinación, debes incluir el evento merge_group como desencadenador adicional de code scanning. Esto garantizará que las solicitudes de incorporación de cambios también se examinen cuando se agreguen a una cola de fusión. Para más información, consulta Administración de una cola de fusión mediante combinación.

Evitar escaneos innecesarios en las solicitudes de cambios

Es posible que quiera evitar que se desencadene un examen de código en solicitudes de incorporación de cambios específicas destinadas a la rama predeterminada, independientemente de los archivos que se hayan cambiado. Puede configurarlo especificando on:pull_request:paths-ignore o on:pull_request:paths en el flujo de trabajo de code scanning. Por ejemplo, si los únicos cambios en una solicitud de incorporación de cambios se realizan en archivos con las extensiones .md o .txt, puede usar la matriz paths-ignore siguiente.

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

Note

on:pull_request:paths-ignore y on:pull_request:paths establecen condiciones que determinan si las acciones del flujo de trabajo se ejecutarán en una solicitud de incorporación de cambios. No determinan qué archivos se analizarán cuando se ejecuten las acciones. Cuando una solicitud de incorporación de cambios contiene archivos que no coinciden con on:pull_request:paths-ignore o on:pull_request:paths, el flujo de trabajo ejecuta las acciones y analiza todos los archivos modificados en la solicitud de incorporación de cambios, incluidos los que coinciden con on:pull_request:paths-ignore o on:pull_request:paths, a menos que se hayan excluido. Para obtener información sobre cómo excluir archivos del análisis, consulta Especificar directorios para escanear.

Para obtener más información sobre el uso de on:pull_request:paths-ignore y on:pull_request:paths para determinar cuándo se ejecutará un flujo de trabajo para una solicitud de incorporación de cambios, consulta Sintaxis del flujo de trabajo para Acciones de GitHub.

Escanear de forma pre-programada

Si utilizas el Flujo de trabajo de análisis de CodeQL predeterminado, este escaneará el código en tu repositorio una vez a la semana adicionalmente a los escaneos que se activen con los eventos. Para ajustar esta programación, edite el valor cron en el flujo de trabajo. Para más información, consulta Sintaxis del flujo de trabajo para Acciones de GitHub.

Note

GitHub solo ejecuta trabajos programados que están en los flujos de trabajo de la rama predeterminada. Cambiar la programación en un flujo de trabajo en cualquier otra rama no tendrá efecto hasta que fusiones esta rama con la predeterminada.

Ejemplo

En el siguiente ejemplo se muestra un Flujo de trabajo de análisis de CodeQL para un repositorio en particular que tiene una rama predeterminada que se llama main y una protegida que se llama protected.

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

Este flujo de trabajo examina lo siguiente:

  • Cada envío de cambios a la rama predeterminada y a la rama protegida
  • Cada solicitud de incorporación de cambios a la rama predeterminada
  • La rama predeterminada todos los lunes a las 14:20 UTC

Especificar un sistema operativo

Note

  • El examen de código de Swift usa ejecutores de macOS de forma predeterminada. Los ejecutores de macOS hospedados por GitHub son más caros que los ejecutores de Linux y Windows, por lo que solo deberías considerar examinar el paso de compilación. Para más información sobre cómo configurar el examen de código para Swift, consulta Análisis de código de CodeQL para lenguajes compilados. Para más información sobre los precios de los ejecutores hospedados por GitHub, consulta Acerca de la facturación para las Acciones de GitHub.

  • Code scanning del código Swift no se admite para los ejecutores que forman parte de un Actions Runner Controller (ARC), ya que los ejecutores de ARC solo usan Linux y Swift requiere ejecutores de macOS. Sin embargo, puedes tener una combinación de ejecutores de ARC y ejecutores de macOS autohospedados. Para obtener más información, vea «Acerca de Actions Runner Controller».

Si tu código requiere un sistema operativo específico para compilar, puedes configurarlo en tu Flujo de trabajo de análisis de CodeQL. Edite el valor de jobs.analyze.runs-on para especificar el sistema operativo de la máquina que ejecuta las acciones de code scanning.

YAML
jobs:
  analyze:
    name: Analyze
    runs-on: [ubuntu-latest]

Si decide utilizar un ejecutor autohospedado para el análisis de código, puede especificar un sistema operativo mediante la etiqueta adecuada como el segundo elemento en una matriz de dos elementos, después de self-hosted.

YAML
jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

El code scanning de CodeQL es compatible con las versiones más recientes de Ubuntu, Windows y macOS. Por lo tanto, los valores típicos de esta configuración son: ubuntu-latest, windows-latest y macos-latest. Para más información, consulta Elegir un ejecutor para un job y Uso de etiquetas con ejecutores autohospedados.

Si usas un ejecutor autohospedado, debes asegurarte de que Git esté en la variable PATH. Para obtener más información, consulta Acerca de los ejecutores autohospedados y Agrega ejecutores auto-hospedados.

Para conocer las especificaciones recomendadas (RAM, núcleos de CPU y disco) para ejecutar CodeQL análisis en máquinas autohospedadas, consulta Recursos de hardware recomendados para ejecutar CodeQL.

Especificar la ubicación de las bases de datos de CodeQL

En general, no necesitas preocuparte por dónde Flujo de trabajo de análisis de CodeQL coloca las bases de dato de CodeQL, ya que los pasos subsecuentes encontrarán automáticamente las bases de datos que crearon los pasos previos. Sin embargo, si está escribiendo un paso de un flujo de trabajo personalizado que requiera que la base de datos de CodeQL esté en una ubicación de disco específica, por ejemplo, para cargar la base de datos como un artefacto de flujo de trabajo, puedes especificar esa ubicación utilizando el parámetro db-location de la acción init.

YAML
- uses: github/codeql-action/init@v3
  with:
    db-location: '${{ github.runner_temp }}/my_location'

El Flujo de trabajo de análisis de CodeQL esperará a que la ruta proporcionada por db-location sea grabable y que no exista o sea un directorio vacío. Cuando utilizamos este parámetro en un job que se ejecuta en un ejecutor auto-hospedado o utilizando un contenedor de Docker, es responsabilidad del usuario garantizar que el directorio elegido se limpie entre ejecuciones o que las bases de datos se eliminen una vez que ya no se necesiten. Esto no es necesario para los trabajos que se ejecutan en los ejecutores hospedados en GitHub, los cuales obtienen una instancia nueva y un sistema de archivos limpio cada vez que se ejecutan. Para más información, consulta Utilizar los ejecutores hospedados en GitHub.

Si no se utiliza este parámetro, el Flujo de trabajo de análisis de CodeQL creará bases de datos en una ubicación temporal de su propia elección. Actualmente, el valor predeterminado es ${{ github.runner_temp }}/codeql_databases.

Cambiar los lenguajes que se analizan

El CodeQL del code scanning detecta automáticamente el código que se escribe en los lenguajes compatibles.

  • C/C++
  • C#
  • Go
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby
  • Swift

Note

  • Use java-kotlin para analizar el código escrito en Java, Kotlin o ambos.
  • Use javascript-typescript para analizar el código escrito en JavaScript, TypeScript o ambos.

Para más información, vea la documentación en el sitio web de CodeQL: "Lenguajes y marcos admitidos".

CodeQL utiliza los siguientes identificadores de idioma:

LenguajeIdentificadorIdentificadores alternativos opcionales (si los hay)
C/C++c-cppc o cpp
C#csharp
Gogo
Java/Kotlinjava-kotlinjava o kotlin
JavaScript/TypeScriptjavascript-typescriptjavascript o typescript
Pythonpython
Rubyruby
Swiftswift

Note

Si especificas uno de los identificadores alternativos, esto equivale a usar el identificador de idioma estándar. Por ejemplo, especificar javascript en lugar de javascript-typescript no excluirá el análisis del código TypeScript. Puede hacerlo en un flujo de trabajo de configuración avanzada con la opción --paths-ignore. Para obtener más información, vea «Personalización de la configuración avanzada para el examen de código».

El archivo predeterminado Flujo de trabajo de análisis de CodeQL contiene una matriz de compilación denominada language que muestra los lenguajes del repositorio que se han analizado. El CodeQL llena automáticamente esta matriz cuando agregas el code scanning a un repositorio. Cuando se utiliza la matriz de language, se optimiza CodeQL para ejecutar cada análisis en paralelo. Se recomienda que todos los flujos de trabajo adopten esta configuración debido a las ventajas de rendimiento de paralelizar las compilaciones. Para obtener más información sobre las matrices, consulta Ejecución de variaciones de trabajos en un flujo de trabajo.

Si el repositorio contiene código en más de uno de los lenguajes admitidos, puede elegir qué lenguajes desea analizar. Hay varias razones por las que es posible que quiera evitar que se analice un lenguaje. Por ejemplo, el proyecto podría tener dependencias en un lenguaje diferente al cuerpo principal del código y es posible que prefiera no ver alertas para esas dependencias.

Si su flujo de trabajo utiliza la matriz language, CodeQL se codifica para analizar únicamente los lenguajes de esa matriz. Para cambiar los lenguajes que desea analizar, edite el valor de la variable de matriz. Puedes eliminar un lenguaje para que no se analice o puedes agregar alguno que no estuviera presente en el repositorio cuando code scanning se configuró. Por ejemplo, si inicialmente el repositorio solo contenía JavaScript cuando se configuró code scanning y posteriormente se agregó el código de Python, deberás agregar python a la matriz.

YAML
jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript', 'python']

Si su flujo de trabajo no contiene una matriz que se llame language, CodeQL se configurará para ejecutar un análisis es secuencias. Si no especificas los lenguajes en los flujos de trabajo, CodeQL detectará e intentará analizar cualquier lenguaje compatible que haya en el repositorio. Si desea elegir qué lenguajes se deben analizar sin usar una matriz, puede usar el parámetro languages en la acción init.

YAML
- uses: github/codeql-action/init@v3
  with:
    languages: c-cpp, csharp, python

Definición de las gravedades de alerta que provocan un error de comprobación de una solicitud de incorporación de cambios

Al habilitar code scanning en las solicitudes de incorporación de cambios, la comprobación solo produce un error si se detectan una o varias alertas de gravedad error, o gravedad critical de seguridad o high. La comprobación se realizará correctamente si se detectan alertas con gravedades inferiores o gravedades de seguridad. En el caso de los códigos base importantes, es posible que desees que code scanning compruebe si se producen errores cuando se detecten alertas, de modo que la alerta deba corregirse o descartarse antes de que se combine el cambio de código. Para obtener más información sobre los niveles de gravedad, consulta «Acerca de la gravedad de alerta y los niveles de gravedad de seguridad».

Puedes editar qué niveles de alerta de gravedad y gravedad de seguridad provocan un error de comprobación. Para más información, consulta Editar la configuración predeterminada.

Configurar una cateogría para el análisis

Use category para distinguir varios análisis de la misma herramienta y confirmación que se ejecutan en distintos lenguajes o partes del código. La categoría que especificas en tu flujo de trabajo se incluirá en el archivo de resultados de SARIF.

Este parámetro es particularmente útil si trabajas en monorepositorios y tienes vrios archivos SARIF para diferentes componentes de este.

YAML
    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v3
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

Si no especifica ningún parámetro de category en su flujo de trabajo, GitHub generará un nombre de categoría en función del nombre del archivo de flujo de trabajo que activa la acción, el nombre de la acción y cualquier variable de la matriz. Por ejemplo:

  • El flujo de trabajo .github/workflows/codeql-analysis.yml y la acción analyze generarán la categoría .github/workflows/codeql.yml:analyze.
  • El flujo de trabajo .github/workflows/codeql-analysis.yml, la acción analyze y las variables de matriz {language: javascript-typescript, os: linux} generarán la categoría .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux.

El valor <run>.automationDetails.id aparecerá como la propiedad category en SARIF v2.1.0. Para más información, consulta Soporte de SARIF para escaneo de código.

La categoría especificada no sobrescribirá los detalles del objeto runAutomationDetails en el archivo SARIF, si se incluye.

Extensión de la cobertura de CodeQL con paquetes de modelos de CodeQL

Si el código base depende de una biblioteca o marco que no reconozcan las consultas estándar en CodeQL, puede ampliar la cobertura de datos CodeQL en el flujo de trabajo de code scanning especificando los paquetes de modelos publicados CodeQL. Para más información sobre cómo crear sus propios paquetes de modelos, consulta Creación y uso de paquetes de CodeQL.

Note

Los paquetes de modelos de CodeQL y el editor de modelos de CodeQL se encuentran actualmente en versión preliminar pública y están sujetos a cambios. Los paquetes de modelos son compatibles con el análisis de C#, Java/Kotlin, Python, and Ruby.

Utilizar los paquetes de modelos de CodeQL

Para agregar uno o varios paquetes de modelos publicados de CodeQL, especifíquelos en la entrada with: packs: dentro de la sección uses: github/codeql-action/init@v3 del flujo de trabajo. Dentro de packs, especifique uno o varios paquetes para usar y, opcionalmente, la versión que desea descargar. Cuando no se especifica una versión, se descarga la más reciente. Si quiere usar paquetes que no están disponibles públicamente, debe establecer la variable de entorno GITHUB_TOKEN en un secreto que tenga acceso a los paquetes. Para más información, consulta Autenticación automática de tokens y Uso de secretos en Acciones de GitHub.

YAML
- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

En este ejemplo, las consultas predeterminadas se ejecutarán para Java, así como las consultas de una versión mayor o igual que 7.8.9 y menor que 7.9.0 del paquete de consultas my-company/my-java-queries. Las dependencias modeladas en la última versión del paquete de modelos my-repo/my-java-model-pack estarán disponibles para las consultas predeterminadas y las de my-company/my-java-queries.

Ejecutar consultas adicionales

Cuando utilizas CodeQL para escanear código, el motor de análisis de CodeQL genera una base de datos desde el código y ejecuta consultas en éste. El CodeQL utiliza un conjunto predeterminado de consultas, pero puedes especificar más consultas para que se ejecuten, adicionalmente a las predeterminadas.

Tip

También puedes especificar las consultas que deseas excluir del análisis o incluirlas en el análisis. Esto requiere el uso de un archivo de configuración personalizado. Para obtener más información, consulta "Uso de un archivo de configuración personalizado" y "Exclusión de consultas específicas del análisis " a continuación.

Puede ejecutar consultas adicionales si son parte de un paquete CodeQL publicado en el GitHub Container registry o de un paquete CodeQL almacenado en un repositorio. Para obtener más información, vea «Acerca del examen de código con CodeQL».

Las opciones disponibles para especificar las consultas adicionales que se quieren ejecutar son las siguientes:

  • packs para instalar uno o más paquetes de consulta de CodeQL y ejecutar el conjunto de consultas predeterminado o las consultas para estos paquetes.
  • queries para especificar un único archivo .ql, un directorio con varios archivos .ql, un archivo de definición de conjunto de consultas .qls o cualquier combinación. Para más información sobre las definiciones de conjunto de consultas, vea "Creación de conjuntos de consultas de CodeQL".

Puede usar packs y queries en el mismo flujo de trabajo.

No se recomienda hacer referencia a conjuntos de consultas directamente desde el repositorio github/codeql, como github/codeql/cpp/ql/src@main. Estas consultas tendrían que volver a compilarse y es posible que no sean compatibles con la versión de CodeQL actualmente activa en GitHub Actions, lo que podría provocar errores durante el análisis.

Usar los paquetes de la consulta

Para agregar uno o varios paquetes de consulta de CodeQL, agregue una entrada with: packs: dentro de la sección uses: github/codeql-action/init@v3 del flujo de trabajo. Dentro de packs, especifique uno o varios paquetes para usar y, opcionalmente, la versión que desea descargar. Cuando no se especifica una versión, se descarga la más reciente. Si quiere usar paquetes que no están disponibles públicamente, debe establecer la variable de entorno GITHUB_TOKEN en un secreto que tenga acceso a los paquetes. Para más información, consulta Autenticación automática de tokens y Uso de secretos en Acciones de GitHub.

Note

En el caso de los flujos de trabajo que generan bases de datos de CodeQL para varios lenguajes, debes especificar los paquetes de consultas de CodeQL en un archivo de configuración. Para obtener más información, consulta Especificar paquetes de consultas de CodeQL a continuación.

En el ejemplo siguiente, scope es la cuenta personal o de la organización que ha publicado el paquete. Cuando se ejecuta el flujo de trabajo, los cuatro paquetes de consulta de CodeQL se descargan de GitHub y se ejecutan las consultas predeterminadas o conjunto de consultas para cada paquete:

  • Se descarga la versión más reciente de pack1 y se ejecutan todas las consultas predeterminadas.
  • Se descarga la versión 1.2.3 de pack2 y se ejecutan todas las consultas predeterminadas.
  • Se descarga la versión más reciente de pack3 que es compatible con la versión 3.2.1 y se ejecutan todas las consultas.
  • Se descarga la versión 4.5.6 de pack4 y solo se ejecutan las consultas que se encuentran en path/to/queries.
YAML
- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Note

Si especificas que se debe usar una versión determinada de un paquete de consultas, ten en cuenta que la versión que especifiques puede volverse demasiado antigua para que la use de forma eficaz el motor predeterminado de CodeQL que se emplea con la acción de CodeQL. Para garantizar un rendimiento óptimo, si necesitas especificar una versión concreta de un paquete de consultas, deberías revisar periódicamente si es necesario actualizar la versión anclada del paquete de consultas.

Para obtener más información sobre la compatibilidad de los paquetes, consulta Publicación y uso de paquetes de CodeQL.

Descarga de paquetes de CodeQL desde el GitHub Enterprise Server

Si en el flujo de trabajo se usan paquetes publicados en un GitHub Enterprise Server, debes indicar al flujo de trabajo dónde encontrarlos. Para ello, usa la entrada registries de la acción github/codeql-action/init@v3. Esta entrada acepta una lista de propiedades url, packages y token, como se muestra a continuación.

YAML
- uses: github/codeql-action/init@v3
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

Los patrones de paquete de la lista de registros se examinan en orden, por lo que generalmente debes colocar primero los patrones de paquete más específicos. El valor de token debe ser un personal access token (classic) generado por la instancia de GitHub desde la que estés realizando la descarga con el permiso read:packages.

Fíjate en | después del nombre de la propiedad registries. Es importante, ya que GitHub Actions solo acepta cadenas. El uso de | convierte el texto subsiguiente en una cadena, que se analiza más adelante mediante la acción github/codeql-action/init@v3.

Utilizar las consultas en los paquetes de QL

Para agregar una o varias consultas, agregue una entrada with: queries: dentro de la sección uses: github/codeql-action/init@v3 del flujo de trabajo. Si las consultas están en un repositorio privado, use el parámetro external-repository-token para especificar un token que tenga acceso para extraer del repositorio privado.

También puede especificar conjuntos de consultas en el valor de queries. Los conjuntos de consultas son colecciones de consultas, normalmente agrupadas por propósito o lenguaje.

YAML
- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Las siguientes suites de consultas se compilan en el CodeQL del code scanning y están disponibles para utilizarse.

Conjunto de consultasDescripción
security-extendedConsultas del conjunto predeterminado, además de consultas de gravedad y precisión más bajas
security-and-qualityConsultas de security-extended, además de consultas de mantenimiento y confiabilidad.

Para más información, consulta "Conjuntos de consultas codeQL".

Cada uno de estos conjuntos de consultas contiene otro subconjunto de las consultas incluidas en el paquete de consultas de CodeQL integrado para ese lenguaje. Los conjuntos de consultas se generan automáticamente con los metadatos de cada consulta. Para más información, consulta "Metadatos para consultas de CodeQL".

Al especificar un conjunto de consultas, el motor de análisis de CodeQL ejecutará el conjunto de consultas predeterminado y todas las demás definidas en el conjunto de consultas adicional.

Trabajar con archivos de configuración personalizados

Si también usa un archivo de configuración para la configuración personalizada, se usan los paquetes o consultas adicionales especificados en el flujo de trabajo en lugar de los especificados en el archivo de configuración. Si quiere ejecutar el conjunto combinado de paquetes o consultas adicionales, use el símbolo + como prefijo del valor packs o queries en el flujo de trabajo. Para obtener más información, consulta Uso de un archivo de configuración personalizado.

En el ejemplo siguiente, el símbolo + garantiza que los paquetes y consultas adicionales especificados se usan junto con los especificados en el archivo de configuración al que se hace referencia.

YAML
- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

Uso de un archivo de configuración personalizado

Un archivo de configuración personalizado es una manera alternativa de especificar paquetes y consultas adicionales para ejecutar. También puedes usar el archivo para deshabilitar las consultas predeterminadas, excluir o incluir consultas específicas y especificar los directorios que se examinarán durante el análisis.

En el archivo de flujo de trabajo, use el parámetro config-file de la acción init para especificar la ruta de acceso al archivo de configuración que desea usar. En este ejemplo se carga el archivo de configuración ./.github/codeql/codeql-config.yml.

YAML
- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

El archivo de configuración se puede encontrar en el repositorio que va a analizar o en un repositorio externo. El uso de un repositorio externo permite especificar opciones de configuración para varios repositorios en un solo lugar. Al hacer referencia a un archivo de configuración ubicado en un repositorio externo, puede usar la sintaxis OWNER/REPOSITORY/FILENAME@BRANCH . Por ejemplo, octo-org/shared/codeql-config.yml@main.

Si el archivo de configuración se encuentra en un repositorio privado externo, use el parámetro external-repository-token de la acción init para especificar un token que tenga acceso al repositorio privado.

YAML
- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Los valores del archivo de configuración se escriben en formato YAML.

Especificar paquetes de consultas de CodeQL

Especificas paquetes de consultas de CodeQL en un arreglo. Tenga en cuenta que el formato es diferente del que utiliza el archivo del flujo de trabajo.

YAML
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

El formato completo para especificar un paquete de consulta es scope/name[@version][:path]. version y path son opcionales. version es el intervalo de versiones de SemVer. Si falta, se usa la versión más reciente. Para obtener más información sobre los intervalos de SemVer, consulta la documentación de SemVer en npm.

Si tienes un flujo de trabajo que genere más de una base de datos de CodeQL, puedes especificar cualquier paquete de consultas de CodeQL para que se ejecute en un archivo de configuración personalizado utilizando un mapa de paquetes anidado.

YAML
packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Extensión de la cobertura de CodeQL con modelos de riesgos

Note

Los modelos de riesgos se encuentran actualmente en versión preliminar pública y están sujetos a cambios. Durante la versión preliminar pública, los modelos de riesgos solo son compatibles con el análisis de Java/Kotlin y C#.

El modelo de riesgos predeterminado incluye orígenes remotos de datos que no son de confianza. Puede ampliar el modelo de riesgos de CodeQL para incluir orígenes locales de datos que no son de confianza (por ejemplo: argumentos de la línea de comandos, variables de entorno, sistemas de archivos y bases de datos) especificando threat-models: local en un archivo de configuración personalizado. Si extiende el modelo de riesgos, también se usará el modelo de riesgos predeterminado.

Especificar consultas adicionales

Especifique las consultas adicionales en una matriz de queries. Cada elemento de la matriz contiene un parámetro uses con un valor que identifica un único archivo de consulta, un directorio que contiene archivos de consulta o un archivo de definición de un conjunto de consultas.

YAML
queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Opcionalmente, puedes otorgar un nombre a cada elemento de la matriz, como se muestra en los siguientes ejemplos de archivos de configuración. Para obtener más información sobre las consultas adicionales, consulta la sección anterior Ejecución de consultas adicionales.

Inhabilitar las consultas predeterminadas

Si solo desea ejecutar consultas personalizadas, puede deshabilitar las consultas de seguridad predeterminadas mediante disable-default-queries: true.

Exclusión de consultas específicas del análisis

Puedes agregar filtros exclude y include al archivo de configuración personalizado para especificar las consultas que deseas excluir o incluir en el análisis.

Esto es útil si deseas excluir, por ejemplo:

  • Consultas específicas de los conjuntos predeterminados (security``security-extended y security-and-quality).
  • Consultas específicas cuyos resultados no te interesan.
  • Todas las consultas que generan advertencias y recomendaciones.

Puedes usar exclude filtros similares a los del archivo de configuración siguiente para excluir las consultas que deseas quitar del análisis predeterminado. En el ejemplo de archivo de configuración siguiente, las consultas js/redundant-assignment y js/useless-assignment-to-local se excluyen del análisis.

YAML
query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Para buscar el identificador de una consulta, puedes hacer clic en la alerta en la lista de alertas de la pestaña Seguridad. Se abrirá la página de detalles de la alerta. El campo Rule ID contiene el identificador de consulta. Para obtener más información sobre la página de detalles de la alerta, consulta Acerca de las alertas de análisis de código.

Tip

  • El orden de los parámetros es importante. La primera instrucción de filtro que aparece después de las instrucciones sobre las consultas y los paquetes de consultas determina si las consultas se incluyen o excluyen de forma predeterminada.
  • Las instrucciones posteriores se ejecutan en orden y las instrucciones que aparecen más adelante en el archivo tienen prioridad sobre las instrucciones anteriores.

Puedes encontrar otro ejemplo que ilustra el uso de estos filtros en la sección Archivos de configuración de ejemplo.

Para obtener más información sobre el uso de los filtros exclude y include en tu archivo de configuración personalizado, consulta Creación de conjuntos de consultas de CodeQL. Para obtener información sobre los metadatos de consulta en los que puedes filtrar, consulta Metadatos para consultas CodeQL.

Especificar directorios para escanear

Cuando se analizan los códigos base sin compilar el código, puede restringir code scanning a los archivos de directorios específicos agregando una matriz paths al archivo de configuración. También puede excluir los archivos de directorios específicos del análisis agregando una matriz paths-ignore. Puede usar esta opción al ejecutar las acciones de CodeQL en un lenguaje interpretado (Python, Ruby y JavaScript/TypeScript) o al analizar un lenguaje compilado sin compilar el código (actualmente compatible con C# y Java).

YAML
paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Note

  • Las palabras clave paths y paths-ignore, que se usan en el contexto del archivo de configuración de code scanning, no deben confundirse con las mismas palabras clave cuando se usan para on.<push|pull_request>.paths en un flujo de trabajo. Cuando se usan para modificar on.<push|pull_request> en un flujo de trabajo, determinan si las acciones se ejecutarán cuando alguien modifique el código en los directorios especificados. Para más información, consulta Sintaxis del flujo de trabajo para Acciones de GitHub.
  • Los caracteres de patrón de filtro ?, +, [, ] y ! no se admiten y coincidirán literalmente.
  • Los caracteres ** solo pueden colocarse al principio o al final de una línea, o rodeados por barras diagonales, y no se puede mezclar ** ni otros caracteres. Por ejemplo, foo/**, **/foo y foo/**/bar son una sintaxis permitida, pero **foo no lo es. Sin embargo, puede usar un solo asterisco junto con otros caracteres, como se muestra en el ejemplo. Tendrá que citar todo lo que contenga un carácter *.

Para los análisis en los que se compila código, si quieres limitar el code scanning para directorios específicos en tu proyecto, debes especificar los pasos de compilación adecuados en el flujo de trabajo. Los comandos que debe usar para excluir un directorio de la compilación dependerán del sistema de compilación. Para más información, consulta Análisis de código de CodeQL para lenguajes compilados.

Puede analizar rápidamente pequeñas partes de un repositorio mono al modificar el código en directorios específicos. Deberá excluir directorios en los pasos de compilación y usar las palabras clave paths-ignore y paths para on.<push|pull_request> en el flujo de trabajo.

Archivos de configuración de ejemplo

Este archivo de configuración agrega el conjunto de consultas security-and-quality a la lista de consultas que se ejecutan con CodeQL al examinar el código. Para más información sobre los conjuntos de consultas disponibles, vea "Ejecución de consultas adicionales".

name: "My CodeQL config"

queries:
  - uses: security-and-quality

El siguiente archivo de configuración inhabilita las consultas predeterminadas y especifica un conjunto de consultas personalizadas para ejecutarse en vez de éstas. También configura CodeQL para examinar los archivos en el directorio src (relativo a la raíz), a excepción del directorio src/node_modules y de los archivos cuyo nombre termine en .test.js. Por tanto, los archivos de src/node_modules y los archivos con nombres que terminan en .test.js se excluyen del análisis.

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

El siguiente archivo de configuración solo ejecuta consultas que generan alertas de error de gravedad. La configuración selecciona primero todas las consultas predeterminadas, todas las consultas en ./my-queries, así como el conjunto predeterminado en codeql/java-queriesy, a continuación, excluye todas las consultas que generan advertencias o recomendaciones.

queries:
  - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Especificación de detalles de configuración mediante la entrada config

Si prefieres especificar detalles de configuración adicionales en el archivo de flujo de trabajo, puedes usar la entrada config del comando init de la acción de CodeQL. El valor de esta entrada debe ser una cadena YAML que siga el formato de archivo de configuración documentado en Uso de un archivo de configuración personalizado más arriba.

Ejemplo de configuración

Este paso de un archivo de flujo de trabajo de GitHub Actions usa una entrada config para deshabilitar las consultas predeterminadas, agregar el conjunto de consultas security-extended y excluir las consultas etiquetadas con cwe-020.

- uses: github/codeql-action/init@v3
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

Puedes usar el mismo enfoque para especificar las opciones de configuración válidas en el archivo de flujo de trabajo.

Tip

Puedes compartir una configuración en varios repositorios mediante las variables de GitHub Actions. Una ventaja de este enfoque es que puedes actualizar la configuración en un solo lugar sin editar el archivo de flujo de trabajo.

En el ejemplo siguiente, vars.CODEQL_CONF es una variable de GitHub Actions. Su valor puede ser el contenido de cualquier archivo de configuración válido. Para más información, consulta Almacenamiento de información en variables.

- uses: github/codeql-action/init@v3
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

Configurar code scanning para los lenguajes compilados

En el caso de lenguajes compilados, puede decidir cómo la acción de CodeQL crea una base de datos de CodeQL para su análisis. Para más información sobre las opciones de compilación disponibles, consulta Análisis de código de CodeQL para lenguajes compilados.

Carga de datos de code scanning en GitHub

GitHub puede mostrar los datos de análisis de código que se generan externamente con una herramienta de terceros. Puede cargar datos de análisis de código con la acción upload-sarif. Para más información, consulta Subir un archivo SARIF a GitHub.