Configurar el escaneo de código

Puedes configurar la forma en que GitHub escanea el código en tu proyecto para encontrar vulnerabilidades y errores.

People with write permissions to a repository can configure escaneo de código for the repository.

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

Acerca de la configuración de escaneo de código

Puedes ejecutar el escaneo de código en GitHub si utilizas las GitHub Actions o desde tu sistema de integración continua (IC). Para obtener más información, consulta la sección "Acerca de las GitHub Actions" o "Acerca del escaneo de código de CodeQL en tu sistema de IC".

Este artículo se trata de ejecutar el escaneo de código en GitHub utilizando acciones.

Antes de que puedas configurar el escaneo de código para un repositorio, debes configurar el escaneo de código agregando un flujo de trabajo de GitHub Actions a este. Para obtener más información, consulta la sección "Configurar el escaneo de código en un repositorio".

Habitualmente, no necesitas editar el flujo de trabajo predeterminado para escaneo de código. Sin embargo, si lo requieres, puedes editar el flujo de trabajo para personalizar algunos de los ajustes. Por ejemplo, puedes editar 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 CodeQL del escaneo de código en tu código. También podrías necesitar editar el Flujo de trabajo de análisis de CodeQL si utilizas un conjunto de comandos específicos para compilar tu código.

El análisis de CodeQL es tan solo un tipo de escaneo de código que puedes hacer en GitHub. GitHub Marketplace contiene otros flujos de trabajo de escaneo de código que puedes utilizar. Puedes encontrar una selección de estos en la página "Iniciar con escaneo de código", a la cual puedes acceder desde la pestaña de Seguridad. Los ejemplos específicos que se dan a este artículo se relacionan con el archivo Flujo de trabajo de análisis de CodeQL.

Editing a code scanning workflow

GitHub guarda los archivos de flujo de trabajo en el directorio de .github/workflows de tu repositorio. Puedes encontrar un flujo de trabajo que hayas agregado si buscas su nombre de archivo. For example, the default workflow file for CodeQL code scanning is called codeql-analysis.yml.

  1. En tu repositorio, navega hasta el archivo de flujo de trabajo que deseas editar.
  2. En el ángulo superior derecho de la vista del archivo, para abrir el editor de flujo de trabajo, haz clic en .Botón para editar un archivo de flujo de trabajo
  3. Después de que hayas editado el archivo, da clic en Iniciar confirmación y completa el formato de "Cambios de la confirmación". Puedes elegir confirmar directamente en la rama actual, o crear una rama nueva e iniciar una solicitud de extracción. Confirmar la actualización del flujo de trabajo de codeql.yml

Para obtener más información acerca de cómo editar los archivos de flujo de trabajo, consulta la sección "Aprende sobre GitHub Actions."

Configurar la frecuencia

Puedes escanear código con cierta programación o cuando ocurren 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

Si utilizas el flujo de trabajo predeterminado, el escaneo de código escaneará el código en tu repositorio una vez por semana, adicionalmente a los escaneos activados por los eventos. Para ajustar este programa, edita el valor cron en el flujo de trabajo. Para obtener más información, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

Si escaneas al subir, entonces los resultados aparecen en la pestaña de Seguridad de tu repositorio. Para obtener más información, consulta la sección "Administrar las alertas del escaneo de código para tu repositorio".

Additionally, when an on:push scan returns results that can be mapped to an open pull request, these alerts will automatically appear on the pull request in the same places as other pull request alerts. The alerts are identified by comparing the existing analysis of the head of the branch to the analysis for the target branch. For more information on escaneo de código alerts in pull requests, see "Triaging escaneo de código alerts in pull requests."

Escanear las solicitudes de extracción

El Flujo de trabajo de análisis de CodeQL predeterminado utiliza el evento pull_request para activar un escaneo de código sobre las solilcitudes de cambios que se dirigen a la rama predeterminada. Si una solicitud de cambios es de una bifurcación privada, el evento de pull_request solo se activará si seleccionaste la opción de "Ejecutar flujos de trabajo desde solicitudes de cambios de la bifurcación" en la configuración del repositorio. Para obtener más información, consulta la sección "Administrar los ajustes de las GitHub Actions en un repositorio".

Para obtener más información acerca del evento pull_request, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

Si escaneas las solicitudes de cambios, entonces los resultados aparecerán como alertas en una verificación de solicitud de cambios. Para obtener màs informaciònPara obtener más información, consulta la sección "Clasificar las alertas del escaneo de código en las solicitudes de cambios".

Using the pull_request trigger, configured to scan the pull request's merge commit rather than the head commit, will produce more efficient and accurate results than scanning the head of the branch on each push. However, if you use a CI/CD system that cannot be configured to trigger on pull requests, you can still use the on:push trigger and escaneo de código will map the results to open pull requests on the branch and add the alerts as annotations on the pull request. For more information, see "Scanning on push."

Definir las gravedades que causan el fallo en la verificación de las solicitudes de cambio

Predeterminadamente, solo las alertas con un nivel de gravedad de Error o nivel de gravedad de seguridad de Crítica o Alta ocasionarán que falle la verificación de una solicitud de cambios y la verificación aún tendrá éxito con aquellas alertas de gravedades menores. Puedes cambiar los niveles de gravedad de las alertas y de las gravedades de seguridad que ocasionarán el fallo de una verificación de solicitud de cambios en los ajustes de tu repositorio. Para obtener más información sobre los niveles de gravedad, consulta la sección "Administrar las alertas del escaneo de código para tu repositorio".

  1. En GitHub, visita la página principal del repositorio.
  2. Debajo de tu nombre de repositorio, da clic en Configuración. Botón de configuración del repositorio
  3. En la barra lateral izquierda, da clic en Seguridad & análisis. pestaña de "Seguridad & análisis" en la configuración de repositorio
  4. 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.

Configuración de fallo de verificación

Evitar escaneos innecesarios en las solicitudes de cambios

Puede que quieras evitar que se active un escaneo de código en solicitudes de cambio específicas que se dirijan a la rama predeterminada, independientemente de los archivos que se hayan cambiado. Puedes configurar esto si especificas on:pull_request:paths-ignore o on:pull_request:paths en el flujo de trabajo de escaneo de código. Por ejemplo, si los únicos cambios en una solicitud de cambios se hacen en archivos con las extensiones .md o .txt, puedes utilizar el siguiente arreglo de paths-ignore.

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

Notas

  • on:pull_request:paths-ignore y on:pull_request:paths configuran condiciones que determinan si una acción en el flujo de trabajo se ejecutará en una solicitud de cambios. No determinan qué archivos se analizarán cuando las acciones se ejecuten. Cuando una solicitud de cambios contiene cualquier archivo que no coincida con on:pull_request:paths-ignore o con on:pull_request:paths, el flujo de trabajo ejecuta las acciones y escanea todos los archivos que cambiaron en la solicitud de cambios, incluyendo aquellos que coincidieron con on:pull_request:paths-ignore o con on:pull_request:paths, a menos de que éstos se hayan excluido. Para obtener más información sobre cómo excluir archivos del análisis, consulta la sección "Especificar directorios para escanear".
  • Para los archivos de flujo de trabajo del escaneo de código de CodeQL, no utilices las palabras clave paths-ignore o paths con el evento on:push, ya que es probable que cause que falten análisis. Para obtener resultados precisos, el escaneo de código de CodeQL necesita poder comparar los cambios nuevos con el análisis de la confirmación previa.

Para obtener más información acerca de utilizar on:pull_request:paths-ignore y on:pull_request:paths para determinar cuando se ejecutará un flujo de trabajo para una solicitud de cambios, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

Escanear de forma pre-programada

El flujo de trabajo del escaneo de código utiliza el evento pull_request para activar un escaneo de código en la confirmación HEAD de una solicitud de extracción. Para ajustar este programa, edita el valor cron en el flujo de trabajo. Para obtener más información, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

Nota: GitHub solo ejecuta jobs pre-programados que se encuentren en 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

El siguiente ejemplo muestra un Flujo de trabajo de análisis de CodeQL para un repositorio 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 escanea:

  • Cada subida a la rama predeterminada y a la rama protegida
  • Cada solicitud de cambios a la rama predeterminada
  • La rama predeterminada cada 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. Edita el valor de jobs.analyze.runs-on para especificar el sistema operativo para la máquina que ejecuta tus acciones de escaneo de código.

Si eliges utilizar une ejecutor auto-hospedado para el escaneo de código, puedes especificar un sistema operativo si utilizas una etiqueta adecuada como el segundo elemento en un arreglo de dos elementos, después de self-hosted.

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

Para obtener más información, consulta la sección "Acerca de los ejecutores auto-hospedados" and "Agregar ejecutores auto-hospedados."

Escaneo de código es compatible con las últimas versiones de macOs, Ubuntu, y Windows. Los valores habituales para esta configuración son por lo tanto: ubuntu-latest, windows-latest, y macos-latest. For more information, see "Workflow syntax for GitHub Actions."

If you use a self-hosted runner, you must ensure that Git is in the PATH variable.

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ás 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 bajo la acción init.

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

El Flujo de trabajo de análisis de CodeQL esperará que se pueda escribir la ruta que se proporcionó en db-location y que ya sea 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. 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 obtener más información, consulta la sección "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 escaneo de código detecta automáticamente el código que se escribe en los lenguajes compatibles.

  • C/C++
  • C#
  • Go
  • Java
  • JavaScript/TypeScript
  • Python

El archivo predeterminado del Flujo de trabajo de análisis de CodeQL contiene una matriz de compilación que se llama language, la cual lista los lenguajes en tu repositorio que se han analizado. El CodeQL llena automáticamente esta matriz cuando agregas el escaneo de código a un repositorio. Cuando se utiliza la matriz de language se optimiza a CodeQL para ejecutar cada análisis en paralelo. Te recomendamos que todos los flujos de trabajo adopten esta configuración debido a los beneficios de rendimiento que implica el paralelizar las compilaciones. Para obtener más información acerca de las matrices de compilación, consulta la sección "Administrar flujos de trabajo complejos".

Si tu repositorio contiene código en más de uno de los lenguajes compatibles, puedes elegir qué lenguajes quieres analizar. Hay varias razones que por las cuales querrías prevenir que un lenguaje se analice. Por ejemplo, el proyecto puede tener dependencias en un lenguaje distinto al del cuerpo principal de tu código, y tal vez prefieras no ver las alertas para esas dependencias.

Si tu flujo de trabajo utiliza la matriz language, entonces CodeQL se codifica fijamente para analizar únicamente los lenguajes en dicha matriz. Para cambiar los lenguajes que quieres analizar, edita el valor de la variable de la matriz. Puedes eliminar un lenguaje para que no se analice, o puedes agregar alguno que no estuviera presente en el repositorio cuando se configuró el escaneo de código. Por ejemplo, si el repositorio inicialmente contenía solo JavaScript cuando se configuró el escaneo de código, y luego quieres agregar código de Python, entonces necesitarás agregar python a la matriz.

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

Si tu flujo de trabajo no contiene una matriz que se llame language, entonces CodeQL se configurará para ejecutar un análisis secuencialmente. Si no especificas los lenguajes en los flujos de trabajo, CodeQL detectará e intentará analizar cualquier lenguaje compatible que haya en el repositorio. Si quieres elegir qué lenguajes analizar sin utilizar una matriz, puedes utilizar el parámetro languages en la acción de init.

- uses: github/codeql-action/init@v1
  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. Puedes controlar este comportamiento si especificas el paràmetro setup-python-dependencies para la acciòn que el paso "Initialize CodeQL" llama. Predeterminadamente, este paràmetro se configura como 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 la instalaciòn automàtica es exitosa, la acciòn tambièn configura la variable de ambiente 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. Necesitaràs agregar a setup-python-dependencies y configurarlo como false, asì como configurar CODEQL_PYTHON para el ejecutable de Python que incluye las dependencias, tal 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@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        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@v1
        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

Utiliza category para distinguir entre análisis múltiples de la misma herramienta y confirmación, pero que se lleven a cabo en lenguajes o partes diferentes 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
      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"

If you don't specify a category parameter in your workflow, GitHub will generate a category name for you, based on the name of the workflow file triggering the action, the action name, and any matrix variables. Por ejemplo:

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

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

La categoría que especificaste no sobrescribirá los detalles del objeto runAutomationDetails en el archivo SARIF, si es que 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 de CodeQL (beta) publicado en el Registro de contenedores de GitHub o de un paquete de QL en un repositorio. Para obtener más información, consulta la sección "Acerca del escaneo de código con CodeQL".

Las opciones disponibles para especificar las consultas adicionales que quieres ejecutar son:

  • packs para instalar uno o más paquetes de consulta de CodeQL (beta) y ejecutar la suite de consultas predeterminada para estos paquetes.
  • queries para especificar un archivo sencilo de .ql, un directorio que contenga varios archivos de .ql, un archivo de definición de suite de consultas .qls o cualquier combinación de estos. Para obtener más información acerca de las definiciones de la suite de consultas, diríjete a la sección "Crear suites de consultas de CodeQL".

Puedes utilizar tanto packs como queries en el mismo flujo de trabajo.

No te recomendamos referenciar las suites de consultas directamente desde el repositorio de github/codeql, como por ejemplo github/codeql/cpp/ql/src@main. Puede que dichas consultas no se compilen con la misma versión de CodeQL que se utiliza para tus otras consultas, lo cual puede llevar a que se cometan errores durante el análisis.

Utilizar los paquetes de consultas de CodeQL

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

Para agregar uno o más paquetes de consulta de CodeQL (beta), agrega una entrada de with: packs: dentro de la sección de uses: github/codeql-action/init@v1 del flujo de trabajo. Dentro de packs especificas uno o más paquetes a utilizar y, opcionalmente, la versión a descargar. Donde no especifiques una versión, se descargará la más reciente. Si quieres utilizar paquetes que no están disponibles al público, necesitarás configurar la variable de ambiente GITHUB_TOKEN como un secreto que tenga acceso a los paquetes. Para obtener más información, consulta las secciones "Autenticación en un flujo de trabajo" y "Secretos cifrados".

Nota: Para el caso de los flujos de trabajo que generan bases de dato de CodeQL para lenguajes múltiples, en su lugar, debes especificar los paquetes de consultas de CodeQL en un archivo de configuración. Para obtener más información, consulta la sección "Especificar los paquetes de consultas de CodeQL" a continuación.

En el siguiente ejemplo, scope es la organización o cuenta personal que publicó el paquete. Cuando se ejecuta el flujo de trabajo, los tres paquetes de consulta de CodeQL se descargan de GitHub y se ejecutan las consultas predeterminadas o suite de consultas para cada paquete. La última versión de pack1 se descarga, ya que no se especificó ninguna versión. Se descarga la versión 1.2.3 del pack2, así como la última versión del pack3 que es compatible con la versión 1.2.3.

- uses: github/codeql-action/init@v1
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~1.2.3

Utilizar las consultas en los paquetes de QL

Para agregar uno o más conjuntos de consultas, agrega una sección de queries a tu archivo de configuración. Si las consultas están en un repositorio privado, utiliza el parámetro external-repository-token para especificar un token que tiene acceso para verificar el repositorio privado.

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

También puedes ejecutar conjuntos de consultas adicionales si los especificas en un archivo de configuración. Los conjuntos de consultas son colecciones de consultas que a menudo se agrupan por propósito o lenguaje.

Las siguientes suites de consultas se compilan en el CodeQL del escaneo de código y están disponibles para utilizarse.

Conjunto de consultasDescripción
security-extendedLas consultas de severidad y precisión más baja que aquellas predeterminadas
security-and-qualityLas consultas de security-extended, mas aquellas de mantenibilidad y confiabilidad

Cuando especificas una suite de consultas, el motor de análisis de CodeQL ejecutará las consultas dentro de la suite para ti, adicionalmente a el conjunto de consultas adicional.

Trabajar con archivos de configuración personalizados

Si también utilizas un archivo de configuración para los ajustes personalizados, cualquier paquete o consulta adicional especificados en tu flujo de trabajo se utilizarán en vez de aquellos especificados en el archivo de configuración. Si quieres ejecutar el juego combinado de paquetes o consultas adicionales, coloca un prefijo en el valor de packs o queries en el flujo de trabajo con el símbolo +. Para encontrar ejemplos de archivos de configuración, consulta la sección "Ejemplos de archivos de configuración".

En el siguiente ejemplo, el símbolo + garantiza que los paquetes y consultas adicionales especificados se utilicen juntos con cualquiera que se haya especificado en el archivo de configuración referenciado.

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

Utilizar una herramienta de escaneo de código de terceros

Un archivo de configuración personalizado es una forma alterna de especificar paquetes y consultas adicionales a ejecutar. También puedes utilizar el archivo para inhabilitar las consultas predeterminadas y para especificar qué directorios escanear durante el análisis.

En el archivo de flujo de trabajo, utiliza el parámetro config-file de la acción init para especificar la ruta al archivo de configuración que quieres utilizar. Este ejemplo carga el archivo de configuración ./.github/codeql/codeql-config.yml.

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

El archivo de configuración puede ubicarse dentro del repositorio que estás analizando o en un repositorio externo. El utilizar un repositorio externo te permite especificar las opciones de configuración para repositorios múltiples en un solo lugar. Cuando referencias un archivo de configuración que se ubica en un repositorio externo, puedes utilizar la sintaxis OWNER/REPOSITORY/FILENAME@BRANCH. Por ejemplo, octo-org/shared/codeql-config.yml@main.

El archivo de configuración se ubica en un repositorio privado externo, utiliza 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@v1
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Los ajustes en el archivo de configuración se escriben en formato YAML.

Especificar paquetes de consultas de CodeQL

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

Especificas paquetes de consultas de CodeQL en un arreglo. Nota que el formato es deferente a aquél que utiliza el archivo de flujo de trabajo.

packs: 
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1 
  # Use version 1.23 of 'pack2' 
  - scope/pack2@v1.2.3
  # Use the latest version of 'pack3' compatible with 1.23
  - scope/pack3@~1.2.3

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 analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Especificar consultas adicionales

Puedes especificar consultas adicionales en una matriz de queries. Cada elemento de la matriz contiene un parámetro de uses con un valor que identifica un archivo de consulta simple, un directorio que contiene los archivos de consulta, o un archivo de suite de definiciones de una consulta.

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 acerca de las consultas adicionales, puedes ver la siguiente sección "Ejecutar consultas adicionales".

Inhabilitar las consultas predeterminadas

Si solo quieres ejecutar consultas personalizadas, puedes inhabilitar las consultas de seguridad predeterminadas si agregas disable-default-queries: true a tu archivo de configuración.

Especificar directorios para escanear

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

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

Nota:

  • Las palabras clave paths y paths-ignore que se utilizan en el contexto del archivo de configuración del escaneo de código no deben confundirse con las mismas palabras clave cuando se utilizan para on.<push|pull_request>.paths en un flujo de trabajo. Cuando se tulizan para modificar on.<push|pull_request> en un flujo de trabajo, éstas determinan si las acciones se ejecutarán cuando alguien modifique el código en los directorios especificados. Para obtener más información, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".
  • Los caracteres de patrón de filtro como ?, +, [, ], y ! no son compatibles y se empatarán literalmente.
  • ** Note: ** characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix ** and other characters. Por ejemplo, foo/**, **/foo, y foo/**/bar son todas sintaxis permitidas, pero **foo no lo es. Sin embargo, puedes utilizar asteriscos sencillos con otros caracteres, tal como se muestra en el ejemplo. Tendrás que poner entre comillas todo lo que contenga un caracter de *.

Para los lenguajes compilados, si quieres limitar el escaneo de código para directorios específicos en tu proyecto, debes especificar los pasos de compilación adecuados en el flujo de trabajo. Los comandos que necesites utilizar para excluir un directorio de la compilación dependerán en tu sistema de compilación. Para obtener más información, consulta la sección "Configurar el flujo de trabajo de CodeQL para los lenguajes compilados".

Puedes analizar rápidamente partes pequeñas de un monorepo cuando modificas el código en directorios específicos. Necesitarás tanto excluir los directorios en tus pasos de compilación como utilizar las palabras clave paths-ignore y paths para on.<push|pull_request> en tu archivo de flujo de trabajo.

Ejemplos de archivos de configuración

Este archivo de configuración agrega el conjunto de consultas security-and-quality a la lista de consultas que se ejecutan con CodeQL cuando se escanea tu código. Para obtener más información acerca de los conjuntos de consultas que están disponibles para utilizarse, consulta la sección "Ejecutar 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 a CodeQL para escanear archivos en el directorio src (relativo a la raíz), con excepción del directorio src/node_modules y de los archivos cuyo nombre termine en .test.js. Los archivos en src/node_modules y aquellos cuyos nombres terminan en .test.js se excluyen por lo tanto 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'

Configurar escaneo de código para los lenguajes compilados

Para los lenguajes compilados compatibles, puedes utilizar la acción de autobuild en el Flujo de trabajo de análisis de CodeQL para compilar tu código. Esto te evita tener que especificar los comandos de compilación explícitos paraC/C++, C#, y Java. CodeQL también ejecuta una compilación para que los proyectos de Go configuren el proyecto. Sin embargo, en contraste con el resto de los lenguajes compilados, todos los archivos de Go en el repositorio se extraen, y no únicamente aquellos que se compilaron. Puedes utilizar comandos personalizados de compilación para saltarte la extracción de archivos de Go que no haya tocado la compilación.

Si el código de C/C++, C# o de Java en tu repositorio tiene un proceso de compilación diferente al estándar, el autobuild podría fallar. Necesitarás eliminar el paso de autobuild del flujo de trabajo y agregar los pasos de compilación manualmente. Si quieres especificar qué archivos de Go se deben extraer de tu repositorio, necesitarás agregar pasos de compilación. Para obtener más información sobre cómo configurar el escaneo de código de CodeQL para los lenguajes compilados, consulta la sección "Configurar el flujo de trabajo de CodeQL para los lenguajes compilados".

Puedes escribir un archivo de configuración para escaneo de código.

GitHub puede mostrar los datos de análisis de código que se generan externamente con una herramienta de terceros. Puedes mostrar el análisis de código de una herramienta de terceros en GitHub su agregas la acción upload-sarif en tu flujo de trabajo. Para obtener más información, consulta la sección "Cargar un archivo SARIF a GitHub".

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

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

Haz una contribución

O, aprende cómo contribuir.