Personalización del examen de código

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 "Más información sobre las Acciones de GitHub" o "Acerca del escaneo de código de CodeQL en tu sistema de IC".

Tanto las configuraciones predeterminadas como las avanzadas para code scanning se ejecutan en GitHub Actions. La configuración predeterminada detecta automáticamente la mejor configuración de code scanning para el repositorio, mientras que puedes usar la configuración avanzada para personalizar un flujo de trabajo de code scanning. Para obtener más información, consulta "Configuración del análisis de código para un repositorio". Este artículo trata sobre la configuración avanzada de code scanning.

Con la configuración avanzada, puedes editar flujos de trabajo como el Flujo de trabajo de análisis de CodeQL de GitHub para especificar la frecuencia de los escaneos, los idiomas o los directorios a escanear, y qué debe buscar el code scanning en tu código. También puede que necesites editar el flujo de trabajo si utilizas un conjunto específico de comandos para compilar tu 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. Encontrará una selección en la página "Introducción a code scanning", a la cual puede 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, consulte "Más información sobre las Acciones de GitHub".

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 obtener más información, vea «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 obtener más información, vea «Administración de alertas de examen 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, consulte "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, 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 obtener más información, vea «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, vea «Personalización del examen de código».

Definición de los niveles de gravedad que provoca un error de comprobación de solicitud de incorporación de cambios

De forma predeterminada, solo las alertas con el nivel de gravedad de Error o con el nivel de gravedad de seguridad Critical o High provocarán un error de comprobación de solicitud de incorporación de cambios, y una comprobación se realizará correctamente con alertas de gravedad más baja. Puede cambiar los niveles de gravedad de las alertas y de gravedad de seguridad que provocarán un error de comprobación de solicitud de incorporación de cambios en la configuración del repositorio. Para obtener más información sobre los niveles de gravedad, consulte "Acerca de las alertas de análisis de código".

1. En GitHub.com, navega a la página principal del repositorio. 1. Debajo del nombre del repositorio, haz clic en Configuración.

2. En la sección "Seguridad" de la barra lateral, haz clic en Análisis y seguridad del código.

3. Debajo de "Escaneo de código", a la derecha de "Fallo de verificación", utiliza el menú desplegable para seleccionar el nivel de gravedad que quisieras que ocasionara un fallo de verificación en la solicitud de cambios.

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.

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

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 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 obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».

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.

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

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.

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.

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 obtener más información, vea «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, consulte "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, consulte "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.

- uses: github/codeql-action/init@v2
  with:
    db-location: '${{ github.workspace }}/codeql_dbs'

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 jobs 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 "Acerca de 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.

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

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

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 más información sobre las matrices, consulta "Uso de una matriz para tus trabajos".

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.

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript', '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.

- uses: github/codeql-action/init@v2
  with:
    languages: cpp, csharp, python

Analizar las dependencias de Python

Para los ejecutores hospedados en GitHub que utilicen solo Linux, el Flujo de trabajo de análisis de CodeQL intentará instalar automáticamente las dependencias de Python para dar más resultados para el análisis de CodeQL. Puede controlar este comportamiento especificando el parámetro setup-python-dependencies de la acción a la que se llama en el paso "Initialize CodeQL". De manera predeterminada, este parámetro está establecido en true:

• Si el repositorio contiene còdigo escrito en Python, el paso "Initialize CodeQL" instala las dependencias necesarias en el ejecutor hospedado en GitHub. Si se ejecuta correctamente la instalación automática, la acción también define la variable de entorno CODEQL_PYTHON en el archivo ejecutable de Python que incluye las dependencias.

• Si el repositorio no tiene ninguna dependencia de Python o si las dependencias se especifican en una forma inesperada, obtendràs una advertencia y la acciòn seguirà con los jobs restantes. La acciòn puede ejecutarse exitosamente aùn cuando existan problemas para interpretar las dependencias, pero los resultados podrìan estar incompletos.

Como alternativa, puedes instalar las dependencias de Python manualmente en cualquier sistema operativo. Tendrá que agregar setup-python-dependencies y establecerlo en false, así como establecer CODEQL_PYTHON en el ejecutable de Python que incluya las dependencias, como se muestra en este extracto de flujo de trabajo:

jobs:
  CodeQL-Build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ];
          then pip install -r requirements.txt;
          fi
          # Set the `CODEQL-PYTHON` environment variable to the Python executable
          # that includes the dependencies
          echo "CODEQL_PYTHON=$(which python)" >> $GITHUB_ENV
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: python
          # Override the default behavior so that the action doesn't attempt
          # to auto-install Python dependencies
          setup-python-dependencies: false

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.

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      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, os: linux} generarán la categoría .github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux.

El valor <run>.automationDetails.id aparecerá como la propiedad category en SARIF v2.1.0. Para obtener más información, vea «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.

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.

Puedes ejecutar consultas adicionales si son parte de un paquete CodeQL (beta) publicado en el GitHub Container registry o de un paquete QL 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 (beta) 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.

Utilizar los paquetes de consultas de CodeQL

Para agregar uno o varios paquetes de consulta de CodeQL (beta), agregue una entrada with: packs: dentro de la sección uses: github/codeql-action/init@v2 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 obtener más información, vea «Autenticación automática de tokens» y «Secretos cifrados».

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.

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

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@v2. Esta entrada acepta una lista de propiedades url, packages y token, como se muestra a continuación.

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

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@v2 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.

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

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".

Para identificar en qué conjuntos de consultas se incluye una consulta, examina la documentación de ayuda de las consultas de CodeQL. Para cada consulta, los conjuntos en los que se incluye se muestran en la parte superior de la página con los metadatos de la consulta. Por ejemplo: Escritura de archivo arbitrario durante la extracción del código postal ("Lista postal") y Falsificación de solicitud del lado cliente.

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. Los conjuntos de consultas security-extended y security-and-quality para JavaScript contienen consultas experimentales. Para más información, consulta "Acerca de las alertas de análisis de código".

Trabajar con archivos de configuración personalizados

Si también usas un archivo de configuración para los ajustes personalizados, se usará cualquier paquete oconsulta adicional que se especifique en tu flujo de trabajo, en vez de lo que se especifique en el archivo de configuración. Si quieres ejecutar el conjunto combinado de paquetes o consultas adicionales, antepón el valor de packs o queries en el flujo de trabajo con el símbolo +. Para obtener más información, consulte "Uso de un archivo de configuración personalizado".

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

- uses: github/codeql-action/init@v2
  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 forma alternativa de especificar paquetes y consultas adicionales para su ejecución. También puedes usar el archivo para deshabilitar las consultas predeterminadas, excluir o incluir consultas específicas, y especificar los directorios que se van a examinar 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.

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

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

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.

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

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.

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 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.

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".

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 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 puedes filtrar, consulta "Metadatos para consultas CodeQL".

Especificar directorios para escanear

Para los lenguajes interpretados compatibles con CodeQL (Python, Ruby y JavaScript/TypeScript), puedes restringir el code scanning para los archivos que estén en directorios específicos si agregas una matriz de paths al archivo de configuración. Puede excluir los archivos de directorios específicos del análisis agregando una matriz paths-ignore.

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

Para los lenguajes compilados, 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 obtener más información, vea «Configuración del flujo de trabajo 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 QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/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 QL pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Configurar code scanning para los lenguajes compilados

Para los lenguajes compilados compatibles, puedes utilizar la acción autobuild en Flujo de trabajo de análisis de CodeQL para compilar tu código. Esto evita tener que especificar comandos de compilación explícitos para C/C++, C#, Go, Kotlin y Java. En estos lenguajes, CodeQL analiza los archivos de origen del repositorio que se han compilado. En cualquiera de estos lenguajes, puedes deshabilitar autobuild y, en su lugar, usar comandos de compilación personalizados para analizar solo los archivos compilados con estos comandos personalizados.

Si se produce un error de autobuild o quiere analizar un conjunto diferente de archivos de origen de los compilados por el proceso autobuild, deberá quitar el paso autobuild del flujo de trabajo y agregar manualmente pasos de compilación. Para proyectos de C/C++, C#, Go, Kotlin y Java, CodeQL analizará el código fuente que creen los pasos de compilación especificados. Para obtener más información sobre cómo configurar CodeQL code scanning para lenguajes compilados, consulte "Configuración del flujo de trabajo 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 obtener más información, vea «Subir un archivo SARIF a GitHub».