Opciones de configuración de flujo de trabajo para el examen de código

Prerrequisitos

Debe usar la configuración avanzada para code scanning y poder editar el archivo de flujo de trabajo donde se define la configuración.

Los ejemplos proporcionados en este artículo se relacionan con el Flujo de trabajo de análisis de CodeQL archivo. De forma predeterminada, este archivo se define en .github/workflows/codeql-analysis.yml.

Frecuencia de examen

Puede configurar el Flujo de trabajo de análisis de CodeQL para escanear el código según una programación o cuando se produzcan 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. El análisis de código según una programación le informa sobre las vulnerabilidades y errores más recientes que GitHub, los investigadores de seguridad y la comunidad detectan, incluso cuando los desarrolladores no mantienen activamente el repositorio.

Escanear cuando se carga información

De forma predeterminada, Flujo de trabajo de análisis de CodeQL usa el evento on:push para desencadenar un examen de código en cada envío a la rama predeterminada del repositorio y en las ramas protegidas. Para que code scanning se desencadene en una rama especificada, el flujo de trabajo debe existir en dicha rama. Para más información, consulta Sintaxis del flujo de trabajo para GitHub Actions.

Si escanea en la acción de inserción, los resultados aparecen en la Security and quality pestaña de su 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 las alertas code scanning en las solicitudes de extracción, consulte Clasificar las alertas del escaneo de código en las solicitudes de cambios.

Escanear las solicitudes de extracción

El valor predeterminado Flujo de trabajo de análisis de CodeQL usa el pull_request evento para desencadenar un examen de código en las solicitudes de incorporación de cambios destinadas a la rama predeterminada. Si una solicitud de incorporación de cambios procede de una bifurcación privada, el pull_request evento solo se desencadenará si ha seleccionado la opción "Ejecutar flujos de trabajo desde solicitudes de incorporación de cambios" en la configuración del repositorio. Para obtener más información, consulte Administración de la configuración de GitHub Actions para un repositorio.

Para obtener más información sobre el evento pull_request, consulte 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 activarse con las solicitudes de incorporación de cambios, puede seguir utilizando el on:push disparador, y code scanning asignará los resultados a las solicitudes de incorporación de cambios abiertas en la rama, añadiendo las alertas como anotaciones en la solicitud de incorporación de cambios. Para obtener más información, consulte Examinar al insertar.

Nota:

Si el repositorio está configurado con una cola de fusión, debe incluir el evento merge_group como un desencadenador adicional para 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.

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 code scanning flujo de trabajo. 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'

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

Nota:

          `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, consulte [Especificar directorios para escanear](#specifying-directories-to-scan).

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, consulte Sintaxis del flujo de trabajo para GitHub Actions.

Escanear de forma pre-programada

Si usa el valor predeterminado Flujo de trabajo de análisis de CodeQL, el flujo de trabajo examinará el código del repositorio una vez a la semana, además de los exámenes desencadenados por eventos. Para ajustar esta programación, edita el valor cron del evento on.schedule en el flujo de trabajo. Para más información, consulta Sintaxis del flujo de trabajo para GitHub Actions.

Nota:

Este evento solo desencadenará una ejecución de flujo de trabajo si el archivo de flujo de trabajo existe en la rama predeterminada.

Ejemplo

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

YAML

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

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

Sistema operativo

Nota:

El examen de código de Swift usa ejecutores de macOS de forma predeterminada.

          GitHubLos ejecutores de macOS hospedados son más caros que los ejecutores de Linux y Windows, por lo que debe considerar la posibilidad de examinar solo el paso de compilación. Para obtener más información sobre cómo configurar el examen de código para Swift, consulte [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#considerations-for-building-swift). Para obtener más información sobre los precios de GitHublos ejecutores hospedados, consulte [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions).

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 más información, consulta Controlador del ejecutor de acciones.

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

YAML

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

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

Si decide usar un runner autohospedado para el escaneo de código, puede especificar un sistema operativo mediante una etiqueta adecuada como segundo elemento de una matriz de dos elementos, después de self-hosted.

YAML

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

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

          CodeQL
          code scanning admite 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 [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job) y [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners).

          Si usa un ejecutor autohospedado, debe asegurarse de que Git está en la variable PATH. Para más información, consulta [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) y [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners).

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

          CodeQL ubicación de la base de datos

En general, no es necesario preocuparse por dónde se Flujo de trabajo de análisis de CodeQL colocan las CodeQL bases de datos, ya que los pasos posteriores encontrarán automáticamente las bases de datos creadas por los pasos anteriores. Sin embargo, si va a escribir un paso de flujo de trabajo personalizado que requiere que la CodeQL base de datos esté en una ubicación de disco específica, por ejemplo, para cargar la base de datos como un artefacto de flujo de trabajo, puede especificar esa ubicación mediante el db-location parámetro en la init acción.

YAML

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

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

          Flujo de trabajo de análisis de CodeQL espera que la ruta de acceso proporcionada en `db-location` sea grabable y 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 GitHubejecutores hospedados, que obtienen una instancia nueva y un sistema de archivos limpio cada vez que se ejecutan. Para más información, consulta [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners).

Si no se usa 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.

Idiomas que se van a analizar

          CodeQL
          code scanning admite el código escrito en los siguientes idiomas:

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

Nota:

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

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

          CodeQL usa los siguientes identificadores de idioma:

Lenguaje	Identificador	Identificadores alternativos opcionales (si los hay)
C/C++	`c-cpp`

          `c` o `cpp` |

Nota:

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. En su lugar, puedes usar un archivo de configuración personalizado para excluir archivos del análisis mediante la configuración paths-ignore. Para obtener más información, consulta Usar un archivo de configuración personalizado y Especificar directorios para examinar.

Estos identificadores de lenguaje se pueden usar como argumentos para la entrada languages de la acción init. Se recomienda que solo se proporcione un lenguaje como argumento:

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

El archivo predeterminado Flujo de trabajo de análisis de CodeQL creado después de configurar la configuración avanzada para el análisis de código con CodeQL define una matriz que contiene una propiedad denominada language que enumera los idiomas del repositorio que se analizarán. Esta matriz se ha rellenado previamente automáticamente con los lenguajes admitidos detectados en el repositorio. El uso de la language matriz permite CodeQL ejecutar cada análisis de lenguaje en paralelo y personalizar el análisis de cada idioma. En un análisis individual, el nombre del lenguaje de la matriz se proporciona a la acción init como argumento de la entrada languages. Se recomienda que todos los flujos de trabajo adopten esta configuración. Para obtener más información sobre las matrices, consulta Ejecución de variaciones de trabajos en un flujo de trabajo.

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

Si el flujo de trabajo usa la language matriz, CodeQL solo analizará los idiomas de la matriz. Para cambiar los lenguajes que deseas analizar, edita la configuración de la matriz. Puedes quitar un lenguaje para evitar que se analice. 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. También puede agregar un idioma que no estaba presente en el repositorio cuando code scanning se configuró. Por ejemplo, si el repositorio solo contenía JavaScript inicialmente cuando code scanning se configuró y más adelante agregó código de Python, deberá agregarlo python a la matriz.

YAML

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

En el caso de los lenguajes compilados, la matriz también se puede usar para configurar qué modo de compilación se debe usar para el análisis cambiando el valor de la propiedad build-mode. Para obtener más información sobre los modos de compilación, consulta Análisis de código de CodeQL para lenguajes compilados.

Si el flujo de trabajo no proporciona un argumento a la languages entrada de la init acción, CodeQL se configura para ejecutar análisis secuencialmente. En este caso, CodeQL detecta e intenta analizar automáticamente los idiomas admitidos en el repositorio. Según el tamaño del repositorio y el número de lenguajes, esto puede tardar mucho tiempo. Si se produce un error en el análisis de un lenguaje en este modo, se produce un error en el análisis de todos los lenguajes. Por lo tanto, no se recomienda esta configuración.

Nota:

Al analizar lenguajes secuencialmente, se usará el modo de compilación predeterminado para cada lenguaje. Como alternativa, si proporciona un paso explícito autobuild, cada lenguaje que admita el modo autobuild lo usará mientras que otros lenguajes usan su modo predeterminado. Si se requiere una configuración de modo de compilación más compleja de la necesaria, deberás configurar una matriz.

Niveles de gravedad de alerta para fallos de verificación

Puede usar conjuntos de reglas para evitar que las solicitudes de incorporación de cambios se combinen cuando se cumple una de las condiciones siguientes:

Una herramienta necesaria encuentra una alerta code scanning con una gravedad definida en el conjunto de reglas.
El análisis de una herramienta necesaria todavía está en curso.
No se ha configurado una herramienta necesaria para el repositorio.

Para más información, consulta Establecimiento de la protección contra la fusión de análisis de códigos. Para obtener información más general sobre los conjuntos de reglas, consulta Acerca de los conjuntos de reglas.

Categoría de 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 trabaja en monorepositorios y tiene varios archivos SARIF para diferentes componentes del monorepositorio.

YAML

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      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"

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      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 un category parámetro en el flujo de trabajo, GitHub generará un nombre de categoría automáticamente, en función del nombre del archivo de flujo de trabajo que desencadene la acción, el nombre de la acción y las variables de 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 category aparecerá como la propiedad <run>.automationDetails.id 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.

          CodeQL paquetes de modelos

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

Nota:

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

El editor de modelos de CodeQL de la extensión CodeQL para Visual Studio Code admite el modelado de dependencias para C#, Java/Kotlin, Python y Ruby.

Uso de CodeQL paquetes de modelos

Para agregar uno o varios paquetes de modelos publicados CodeQL , especifíquelos dentro de la with: packs: entrada dentro de la uses: github/codeql-action/init@v4 sección 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 Uso de GITHUB_TOKEN para la autenticación en flujos de trabajo y Uso de secretos en Acciones de GitHub.

YAML

- uses: github/codeql-action/init@v4
  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

- uses: github/codeql-action/init@v4
  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 menos de 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.

Consultas no predeterminadas

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 análisis de CodeQL utiliza un conjunto predeterminado de consultas, pero puedes especificar más consultas para ejecutar, además de las predeterminadas.

Sugerencia

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, consulte Archivos de configuración personalizados y Exclusión de consultas específicas del análisis siguiente.

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 más información, consulta 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 obtener más información sobre las definiciones de conjuntos de consultas, consulte [Creación de conjuntos de consultas de CodeQL](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/).

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 CodeQL paquetes de consultas, agregue una with: packs: entrada dentro de la uses: github/codeql-action/init@v4 sección 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 Uso de GITHUB_TOKEN para la autenticación en flujos de trabajo y Uso de secretos en Acciones de GitHub.

Nota:

En el caso de los flujos de trabajo que generan CodeQL bases de datos para varios lenguajes, debe especificar en su lugar los CodeQL paquetes de consulta en un archivo de configuración. Para obtener más información, consulte Especificación CodeQL de paquetes de consulta 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 CodeQL paquetes de consulta se descargan de GitHub y se ejecutan las consultas predeterminadas o el conjunto de consultas predeterminado 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@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

Nota:

Si especifica una versión determinada de un paquete de consultas para utilizar, tenga en cuenta que la versión que especifique puede llegar a ser demasiado antigua para que el motor predeterminado CodeQL sea usado de manera eficiente por la acción 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, consulte Referencia de paquetes de consulta de CodeQL.

Descarga de CodeQL paquetes desde GitHub Enterprise Server

Si el flujo de trabajo usa paquetes publicados en una GitHub Enterprise Server instalación, debe indicar al flujo de trabajo dónde encontrarlos. Puede hacerlo con la entrada registries de la acción github/codeql-action/init@v4. Esta entrada acepta una lista de propiedades url, packages y token, como se muestra a continuación.

YAML

- uses: github/codeql-action/init@v4
  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 }}

- uses: github/codeql-action/init@v4
  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. Los valores de token deben ser un personal access token (classic) generado por la instancia de GitHub desde la que estás descargando, con permiso de read:packages.

Fíjate en | después del nombre de la propiedad registries. Esto es importante, ya que GitHub Actions las entradas solo pueden aceptar cadenas. El uso de | convierte el texto subsiguiente en una cadena de texto, que la acción github/codeql-action/init@v4 analiza más adelante.

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@v4 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@v4
  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 }}

- uses: github/codeql-action/init@v4
  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 consultas	Descripción
`security-extended`	Consultas del conjunto predeterminado, además de consultas de gravedad y precisión más bajas
`security-and-quality`	Consultas de `security-extended`, además de consultas de mantenimiento y confiabilidad.

Para obtener 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 packs como prefijo del valor queries o + en el flujo de trabajo. Para obtener más información, consulte Archivos de configuración personalizados.

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@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

Archivos de configuración personalizados

Un archivo de configuración personalizado es una manera alternativa de especificar paquetes y consultas adicionales para ejecutar. También puede usar el archivo para deshabilitar las consultas predeterminadas, excluir o incluir consultas concretas, o 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@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml

- uses: github/codeql-action/init@v4
  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@v4
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

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

Especificación de CodeQL paquetes de consultas

Se especifican los paquetes de consulta CodeQL en una matriz. 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/[email protected]
  # 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

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/[email protected]
  # 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]. Ambos 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 tiene un flujo de trabajo que genera más de una CodeQL base de datos, puede especificar los CodeQL paquetes de consulta que se ejecuten en un archivo de configuración personalizado mediante un mapa anidado de paquetes.

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/[email protected]

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/[email protected]

Ampliando la cobertura de CodeQL con modelos de amenazas

Nota:

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 CodeQL modelo de amenazas para incluir orígenes locales de datos que no son de confianza (por ejemplo: argumentos de 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

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, consulte Consultas no predeterminadas anteriores.

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

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

Para buscar el identificador de una consulta, puede hacer clic en la alerta en la lista de alertas de la Security and quality pestaña . 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, consulte Acerca de las alertas de análisis de código.

Sugerencia

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.

Puede 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 su archivo de configuración personalizado, consulte Creación de conjuntos de consultas de CodeQL. Para obtener información sobre los metadatos de consulta en los que puede filtrar, consulte Metadatos para consultas CodeQL.

Especificar directorios para escanear

Cuando se analizan los códigos base sin compilar el código, puede restringir code scanning los archivos de directorios específicos agregando una paths matriz 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 CodeQL acciones en un lenguaje interpretado (Python, Ruby y JavaScript/TypeScript) o al analizar un lenguaje compilado sin necesidad de compilar el código (actualmente compatible para C/C++, C#, Java y Rust).

YAML

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

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

Nota:

Las paths palabras clave y paths-ignore , que se usan en el contexto del code scanning archivo de configuración, 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 GitHub Actions.
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 analizar dónde se compila el código, si desea limitar code scanning a directorios específicos del proyecto, debe 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 los 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 incorpora la suite de consultas security-and-quality a la lista de consultas ejecutadas por CodeQL al analizar tu código. Para obtener más información sobre los conjuntos de consultas disponibles para su uso, consulte Consultas no predeterminadas.

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

Detalles de configuración

Si prefiere especificar detalles de configuración adicionales en el archivo de flujo de trabajo, puede usar la entrada config del comando init de la acción CodeQL. El valor de esta entrada debe ser una cadena YAML que siga el formato de archivo de configuración documentado en Archivos de configuración personalizados anteriores.

Configuración de ejemplo

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

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      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.

Sugerencia

Puede compartir una configuración entre varios repositorios mediante GitHub Actions variables. 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 GitHub Actions variable. 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@v4
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

Lenguajes compilados

En el caso de los lenguajes compilados, puede decidir cómo la CodeQL acción crea una CodeQL base de datos 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

          GitHub puede mostrar datos de análisis de código generados externamente por 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 [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github).

Opciones de configuración de flujo de trabajo para el examen de código

¿Quién puede utilizar esta característica?

En este artículo

Prerrequisitos

Frecuencia de examen

Escanear cuando se carga información

Escanear las solicitudes de extracción

Evitar escaneos innecesarios en las solicitudes de cambios

Escanear de forma pre-programada

Ejemplo

Sistema operativo

Idiomas que se van a analizar

Niveles de gravedad de alerta para fallos de verificación

Categoría de análisis

Uso de CodeQL paquetes de modelos

Consultas no predeterminadas

Usar los paquetes de la consulta

Descarga de CodeQL paquetes desde GitHub Enterprise Server

Utilizar las consultas en los paquetes de QL

Trabajar con archivos de configuración personalizados

Archivos de configuración personalizados

Especificación de CodeQL paquetes de consultas

Ampliando la cobertura de CodeQL con modelos de amenazas

Especificar consultas adicionales

Inhabilitar las consultas predeterminadas

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

Especificar directorios para escanear

Archivos de configuración de ejemplo

Detalles de configuración

Configuración de ejemplo

Lenguajes compilados

Carga de datos