Solución de problemas de configuración avanzada para CodeQL

Nota: En el caso de los repositorios internos y privados, el code scanning estará disponible cuando se habiliten las características de la GitHub Advanced Security para el repositorio. Si ves el error Advanced Security must be enabled for this repository to use code scanning, comprueba que GitHub Advanced Security esté habilitado. Para obtener más información, vea «Administración de la configuración de seguridad y análisis para el repositorio».

Producir bitácoras detalladas para la depuración

Para producir una salida más detallada de bitácoras, puedes habilitar el registro de depuración de pasos. Para obtener más información, vea «Habilitación del registro de depuración».

Crear artefactos de depuración de CodeQL

Puedes obtener artefactos para que te ayuden a depurar CodeQL. Los artefactos de depuración se cargarán en la ejecución de flujo de trabajo como un artefacto denominado debug-artifacts. Los datos contienen las bitácoras de CodeQL. la(s) base(s) de datos de CodeQL y cualquier archivo SARIF que produzca el flujo de trabajo.

Estos artefactos te ayudarán a depurar los problemas con CodeQL code scanning. Si contactas al soporte de GitHub, podrían pedirte estos datos.

Creación de artefactos de depuración de CodeQL mediante la reejecución de trabajos con el registro de depuración habilitado

Puedes habilitar el registro de depuración y volver a ejecutar los trabajos para crear artefactos de depuración de CodeQL. Para obtener más información sobre cómo volver a ejecutar los flujos de trabajo y los trabajos de GitHub Actions, consulta "Volver a ejecutar flujos de trabajo y jobs".

Asegúrate de seleccionar Habilitar registro de depuración. Esta opción habilita el registro de diagnóstico del ejecutor y el registro de depuración de pasos para la ejecución. A continuación, podrás descargar debug-artifacts para investigar más a fondo. No necesitas volver a ejecutar trabajos para modificar el archivo de flujo de trabajo al crear artefactos de depuración de CodeQL.

Creación de artefactos de depuración de CodeQL mediante una marca de flujo de trabajo

Puedes crear artefactos de depuración de CodeQL mediante el uso de una marca en el flujo de trabajo. Para ello, tienes que modificar el paso init del archivo de Flujo de trabajo de análisis de CodeQL y establecer debug: true.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Los resultados son diferentes de los esperados

Si los resultados de code scanning son diferentes de los esperados, es posible que el repositorio tenga configuraciones predeterminadas y avanzadas de code scanning. Cuando habilitas la configuración predeterminada, esto deshabilita el archivo de flujo de trabajo de CodeQL existente e impide que cualquier análisis de API de CodeQL cargue resultados.

Para comprobar si la configuración predeterminada está habilitada, navega a la página principal del repositorio y, después, haz clic en Configuración. En la sección "Seguridad" de la barra lateral, haz clic en Análisis y seguridad del código. En la sección "Code scanning" de la página, junto a "análisis de CodeQL", haz clic en . Si hay una opción Cambiar a la opción avanzada, significa que actualmente se usa la configuración predeterminada.

Si quieres volver a usar la configuración avanzada y obtener resultados de code scanning del archivo de flujo de trabajo personalizado, haz clic en Deshabilitar CodeQL para deshabilitar la instalación predeterminada. Después, debes volver a habilitar los flujos de trabajo preexistentes para empezar a desencadenar y cargar los resultados de la configuración avanzada. Para más información, consulta: "Deshabilitación y habilitación de un flujo de trabajo" y "Configuración del análisis de código para un repositorio".

En algunos casos, el repositorio puede usar varias configuraciones de code scanning. Estas configuraciones pueden generar alertas duplicadas. Además, las configuraciones obsoletas que ya no se ejecutan mostrarán estados de alerta obsoletos y las alertas obsoletas permanecerán abiertas indefinidamente. Para evitar alertas obsoletas, debes quitar las configuraciones obsoletas de code scanning de una rama. Para obtener más información sobre varias configuraciones y eliminar configuraciones obsoletas, consulta "Acerca de las alertas de análisis de código" y "Administración de alertas de examen de código para el repositorio".

Compilación automática para los fallos de un lenguaje compilado

Si una compilación automática de código para un lenguaje compilado dentro de tu proyecto falla, intenta los siguientes pasos de solución de problemas.

Elimine el paso autobuild del flujo de trabajo de code scanning y agregue los pasos de compilación específicos. Para obtener información sobre la edición de archivos de flujo de trabajo, consulta "Personalización del examen de código". Para obtener más información sobre cómo reemplazar el paso autobuild, consulta "Configuración del flujo de trabajo de CodeQL para lenguajes compilados".
Si tu flujo de trabajo no especifica explícitamente los lenguajes a analizar, CodeQL detectará implícitamente los lenguajes compatibles en tu código base. En esta configuración, fuera de los lenguajes compilados C/C++, C#, Go y Java, CodeQL solo analizará el lenguaje presente en la mayoría de los archivos de origen. Edita el flujo de trabajo y agrega una matriz que especifique los lenguajes que quieres analizar. El flujo de trabajo de análisis de CodeQL predeterminado usa esta matriz.

Los siguientes extractos de un flujo de trabajo te muestran cómo puedes utilizar una matriz dentro de la estrategia del job para especificar lenguajes, y luego hace referencia a cada uno de ellos con el paso de "Inicializar CodeQL":
```
jobs:
  analyze:
    permissions:
      security-events: write
      actions: read
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['csharp', 'cpp', 'javascript']

    steps:
    ...
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: ${{ matrix.language }}
```
Para obtener información sobre la edición del flujo de trabajo, consulta "Personalización del examen de código".

No se encontró código durante la compilación

Si se produce un error No source code was seen during the build o The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32 en el flujo de trabajo, esto indica que CodeQL no ha podido supervisar el código. Hay muchas razones que podrían explicar esta falla:

Es posible que el repositorio no contenga código fuente escrito en lenguajes admitidos por CodeQL. Comprueba la lista de lenguajes admitidos y, si este es el caso, quita el flujo de trabajo de CodeQL. Para más información, consulta "Acerca del examen de código con CodeQL".
La detección automática del lenguaje identificó un lenguaje compatible, pero no hay código analizable en dicho lenguaje dentro del repositorio. Un ejemplo típico es cuando nuestro servicio de detección de lenguaje encuentra un archivo asociado a un lenguaje de programación específico, como un archivo .h o .gyp, pero en el repositorio no existe el código ejecutable correspondiente. Para resolver el problema, puede definir manualmente los lenguajes que quiere analizar si actualiza la lista de lenguajes en la matriz language. Por ejemplo, la siguiente configuración analizará únicamente a Go y a Javascript.
```
strategy:
  fail-fast: false
  matrix:
    # Override automatic language detection by changing the list below.
    # Supported options are listed in a comment in the default workflow.
    language: ['go', 'javascript']
```
Para más información, vea el extracto de flujo de trabajo en "Error de compilación automático para un lenguaje compilado" más arriba.
Tu flujo de trabajo de code scanning está analizando un lenguaje compilado (C, C++, C#, Go o Java), pero el código no se compiló. De manera predeterminada, el flujo de trabajo de análisis de CodeQL contiene un paso autobuild, pero este paso representa un proceso de mejor esfuerzo y podría no compilar el código de forma correcta, en función del entorno de compilación específico. También se podría producir un error en la compilación si ha eliminado el paso autobuild y no ha incluido manualmente los pasos de compilación. Para obtener más información sobre cómo especificar los pasos de compilación, consulta "Configuración del flujo de trabajo de CodeQL para lenguajes compilados".
Tu flujo de trabajo está analizando un lenguaje compilado (C, C++, C#, Go o Java), pero algunas partes de tu compilación se almacenan en caché para mejorar el rendimiento (esto muy probablemente ocurra con los sistemas de compilación como Gradle o Bazel). Ya que CodeQL observa la actividad del compilador para entender los flujos de datos en un repositorio, CodeQL requiere que suceda una compilación completa para poder llevar a cabo este análisis.
El flujo de trabajo analiza un lenguaje compilado (C, C++, C#, Go o Java),pero no se produce ninguna compilación entre los pasos init y analyze del flujo de trabajo. CodeQL requiere que tu compilación tome lugar entre estos dos pasos para poder observar la actividad del compilador y llevar a cabo el análisis.
Tu código compilado (en C, C++, C#, Go o Java) se compiló con éxito, pero CodeQL no pudo detectar las invocaciones del compilador. Las causas más comunes son:
- Ejecutar tu proceso de compilación en un contenedor separado a CodeQL. Para obtener más información, vea «Ejecutarel escaneo de código de CodeQL en un contenedor».
- Compilar utilizando un sistema de compilación distribuida externo a GitHub Actions, utilizando un proceso de daemon.
- CodeQL no está consciente del compilador específico que estás utilizando.
Para proyectos de .NET Framework y para los proyectos de C# que usen dotnet build o msbuild, tendrá que especificar /p:UseSharedCompilation=false en el paso run del flujo de trabajo, al compilar el código.

Por ejemplo, la siguiente configuración para C# pasará el marcador durante el primer paso de compilación.
```
- run: |
    dotnet build /p:UseSharedCompilation=false
```
Si encuentras otro problema con tu compilador específico o con tu configuración, contacta a Soporte técnico de GitHub.

Para obtener más información sobre cómo especificar los pasos de compilación, consulta "Configuración del flujo de trabajo de CodeQL para lenguajes compilados".

Las líneas de código escaneado son menores de lo esperado

Para los lenguajes compilados como C/C++, C#, Go y Java, CodeQL solo escanea los archivos que se compilen durante el análisis. Por lo tanto, la cantidad de líneas de código escaneado será menor de lo esperado si parte del código fuente no se compila correctamente. Esto puede ocurrir por varios motivos:

La característica autobuild de CodeQL utiliza la heurística para compilar el código de un repositorio. Sin embargo, algunas veces, este enfoque da como resultado un análisis incompleto del repositorio. Por ejemplo, cuando existen varios comandos build.sh en un mismo repositorio, es posible que no se complete el análisis, ya que el paso autobuild solo ejecutará uno de los comandos y, por tanto, algunos archivos de código fuente podrían no compilarse.
Algunos compiladores no funcionan con CodeQL y pueden causar problemas cuando analizan el código. Por ejemplo, Project Lombok utiliza unas API de compilación no públicas para modificar el comportamiento del compilador. Las asunciones que se utilizan en las modificaciones de este compilador no son válidas para el extractor de Java de CodeQL, así que el código no se puede analizar.

Si tu análisis de CodeQL escanea menos líneas de código de lo esperado, hay varios enfoques que puedes intentar para asegurarte de que todos los archivos de código fuente necesarios se compilen.

Reemplazo del paso `autobuild`

Reemplace el paso autobuild con los mismos comandos de compilación que usaría en producción. Esto garantiza que CodeQL sepa exactamente cómo compilar todos los archivos de código fuente que quieras escanear. Para obtener más información, vea «Configuración del flujo de trabajo de CodeQL para lenguajes compilados».

Inspecciona la copia de los archivos de código fuente en la base de datos de CodeQL

Podrías entender por qué algunos archivos de código fuente no se ha analizado si inspeccionas la copia del código fuente que se incluye utilizando la base de datos de CodeQL. Para obtener la base de datos del flujo de trabajo de Acciones, modifique el paso init del archivo de flujo de trabajo de CodeQL y establezca debug: true.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Esto carga la base de datos como un artefacto de acciones que puedes descargar en tu máquina local. Para obtener más información, vea «Almacenar los datos de los flujos de trabajo como artefactos».

El artefacto contendrá una copia archivada de los archivos de código fuente examinados por CodeQL denominada src.zip. Si compara los archivos de código fuente del repositorio con los de src.zip, verá qué tipos de archivo faltan. Una vez que sepas qué tipos de archivo son los que no se analizan es más fácil entender cómo podrías cambiar el flujo de trabajo para el análisis de CodeQL.

Alertas encontradas en el código generado

Para los lenguajes compilados como Java, Kotlin, Go, C, C++, y C#, CodeQL analiza todo el código que se haya compilado durante la ejecución del flujo de trabajo. Para limitar la cantidad de código que se analiza, compile únicamente el código que quiera analizar; para ello, especifique pasos de compilación propios en un bloque run. Puede combinar la especificación de los pasos de compilación propios con el uso de los filtros paths o paths-ignore en los eventos pull_request y push para asegurarse de que el flujo de trabajo solo se ejecuta cuando se cambia código específico. Para obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».

En el caso de los lenguajes como JavaScript, Python y TypeScript, que analiza CodeQL sin compilar el código fuente, puedes especificar opciones adicionales de configuración para limitar la cantidad de código que se va a analizar. Para obtener más información, vea «Personalización del examen de código».

Extracción de errores en la base de datos

El equipo de CodeQL trabaja constantemente en los errores de extracción críticos para asegurarse de que todos los archivos de código fuente pueden escanearse. Sin embargo, los extractores de CodeQL sí generan errores durante la creación de bases de datos ocasionalmente. CodeQL proporciona información acerca de los errores de extracción y las advertencias que se generan durante la creación de bases de datos en un archivo de bitácora. La información de diagnóstico de extracción proporciona una indicación de la salud general de la base de datos. La mayoría de los errores del extractor no impactan el análisis significativamente. Una pequeña parte de los errores del extractor es saludable y, a menudo, indica un buen estado del análisis.

Sin embargo, si ves errores del extractor en la vasta mayoría de archivos que se compilan durante la creación de la base de datos, deberías revisarlos a detalle para intentar entender por qué algunos archivos de código fuente no se extrajeron adecuadamente.

La compilación tarda demasiado

Si tu compilación con análisis de CodeQL toma demasiado para ejecutarse, hay varios acercamientos que puedes intentar para reducir el tiempo de compilación.

Incrementar la memoria o los núcleos

Si utilizas ejecutores auto-hospedados para ejecutar el análisis de CodeQL, puedes incrementar la memoria o la cantidad de núcleos en estos ejecutores.

Utilizar matrices de compilación para paralelizar el análisis

El Flujo de trabajo de análisis de CodeQL predeterminado utiliza una matriz de lenguajes, que hace que el análisis de cada uno de ellos se ejecute en paralelo. Si especificaste los lenguajes que quieres analizar directamente en el paso de "Inicializar CodeQL", el análisis de cada lenguaje ocurrirá de forma secuencial. Para agilizar el análisis de lenguajes múltiples, modifica tu flujo de trabajo para utilizar una matriz. Para más información, vea el extracto de flujo de trabajo en "Error de compilación automático para un lenguaje compilado" más arriba.

Reducir la cantidad de código que se está analizando en un solo flujo de trabajo

El tiempo de análisis suele ser proporcional a la cantidad de código que se analiza. Puedes reducir el tiempo de análisis si reduces la cantidad de código que se analice en cada vez, por ejemplo, si excluyes el código de prueba o si divides el análisis en varios flujos de trabajo que analizan únicamente un subconjunto de tu código a la vez.

Para los lenguajes compilados como Java, Kotlin, Go, C, C++, y C#, CodeQL analiza todo el código que se haya compilado durante la ejecución del flujo de trabajo. Para limitar la cantidad de código que se analiza, compile únicamente el código que quiera analizar; para ello, especifique pasos de compilación propios en un bloque run. Puede combinar la especificación de los pasos de compilación propios con el uso de los filtros paths o paths-ignore en los eventos pull_request y push para asegurarse de que el flujo de trabajo solo se ejecuta cuando se cambia código específico. Para obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».

En el caso de los lenguajes como JavaScript, Python y TypeScript, que analiza CodeQL sin compilar el código fuente, puedes especificar opciones adicionales de configuración para limitar la cantidad de código que se va a analizar. Para obtener más información, vea «Personalización del examen de código».

Si divide el análisis en varios flujos de trabajo como se ha descrito antes, le recomendamos que al menos tenga uno que se ejecute en una schedule que analice todo el código del repositorio. Ya que CodeQL analiza los flujos de datos entre componentes, algunos comportamientos de seguridad complejos podrían detectarse únicamente en una compilación completa.

Ejecución durante un evento `schedule`

Si el análisis es demasiado lento para ejecutarse durante los eventos push o pull_request, es posible que solo quiera desencadenarlo cuando se produzca el evento schedule. Para obtener más información, vea «Entender las GitHub Actions».

Verificar qué suites de consultas ejecuta el flujo de trabajo

Predeterminadamente, existen tres suites de consultas principales disponibles para cada lenguaje. Si has optimizado la compilación de la base de datos de CodeQL y el proceso sigue siendo demasiado largo, podrías reducir la cantidad de consultas que ejecutas. La suite de consultas predeterminada se ejecuta automáticamente; esta contiene las consultas de seguridad más rápidas con las tasas más bajas de resultados falsos positivos.

Podrías estar ejecutando consultas o suites de consultas adicionales además de aquellas predeterminadas. Compruebe si el flujo de trabajo define una consulta adicional o un conjunto de consultas para ejecutarse con el elemento queries. Puedes probar el inhabilitar la consulta o suite de consultas adicionales. Para obtener más información, vea «Personalización del examen de código».

Nota: Si ejecuta el conjunto de consultas security-extended o security-and-quality para JavaScript, algunas consultas usan tecnología experimental. Para obtener más información, vea «Acerca de las alertas de análisis de código».

Los resultados difieren de acuerdo con la plataforma de análisis

Si estás analizando código escrito en Python, podrías ver resultados diferentes dependiendo de si ejecutas el Flujo de trabajo de análisis de CodeQL en Linux, macOS o Windows.

En los ejecutores hospedados en GitHub que utilizan Linux, el Flujo de trabajo de análisis de CodeQL intenta instalar y analizar las dependencias de Python, lo cual podría llevar a más resultados. Para deshabilitar la instalación automática, agregue setup-python-dependencies: false al paso "Inicializar CodeQL" del flujo de trabajo. Para más información sobre cómo configurar el análisis de dependencias de Python, consulta "Personalización del examen de código".

Error: "Error del servidor"

Si la ejecución de un flujo de trabajo para code scanning falla debido a un error de servidor, trata de ejecutar el flujo de trabajo nuevamente. Si el problema persiste, contaca a Soporte técnico de GitHub.

Error: "Espacio en disco insuficiente" o "Memoria insuficiente"

En proyectos muy grandes, CodeQL podría quedarse sin memoria o espacio de disco en el ejecutor. Si se produce esta incidencia en un ejecutor hospedado en GitHub Actions, póngase en contacto con Soporte técnico de GitHub para que podamos investigar el problema.

Error:403 "No se puede acceder al recurso por integración" al utilizar Dependabot

El Dependabot se considera no confiable cuando activa una ejecución de flujo de trabajo y este se ejecutará con un alcance de solo lectura. Para cargar resultados de code scanning en una rama normalmente se necesita el ámbito security_events: write. Pero code scanning siempre permite que se carguen los resultados cuando el evento pull_request desencadena la ejecución de la acción. Por este motivo, para las ramas de Dependabot, se recomienda usar el evento pull_request en lugar del evento push.

Un enfoque simple es ejecutar las subidas a la rama predeterminada y cualquier otra rama que se ejecute a la larga, así como las solicitudes de cambio que se abren contra este conjunto de ramas:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

Un enfoque alternativo es ejecutar todas las subidas con excepción de las ramas del Dependabot:

on:
  push:
    branches-ignore:
      - 'dependabot/**'
  pull_request:

Error persistente de análisis en la rama predeterminada

Si el Flujo de trabajo de análisis de CodeQL aún falla en una confirmación que se hizo en una rama predeterminada, debes verificar:

si el Dependabot fue el autor de la confirmación
si la solicitud de incorporación de cambios que incluye la confirmación se ha combinado mediante @dependabot squash and merge

Este tipo de confirmación por fusión tiene como autor al Dependabot y, por lo tanto, cualquier flujo de trabajo que se ejecute en la confirmación tendrá permisos de solo lectura. Si ha habilitado las actualizaciones de seguridad o de versión de code scanning y Dependabot en el repositorio, se recomienda evitar el uso del comando @dependabot squash and merge de Dependabot. En su lugar, puede habilitar la combinación automática para el repositorio. Esto significa que las solicitudes de incorporación de cambios se combinarán automáticamente cuando se cumplan todas las revisiones necesarias y se hayan superado las comprobaciones de estado. Para más información sobre cómo habilitar la combinación automática, consulta "Fusionar una solicitud de cambios automáticamente".

Error: "no es un archivo .ql, un archivo .qls, un directorio o una especificación del paquete de consultas"

Verás este error si CodeQL no encuentra la consulta con nombre, el conjunto de consultas o el paquete de consultas en la ubicación solicitada en el flujo de trabajo. Hay dos motivos habituales por los que se puede producir este error.

Hay un error tipográfico en el flujo de trabajo.
Un recurso al que hace referencia el flujo de trabajo por la ruta de acceso se cambió de nombre, eliminó o movió a una nueva ubicación.

Después de comprobar la ubicación del recurso, puedes actualizar el flujo de trabajo para especificar la ubicación correcta.

Advertencia: "git checkout HEAD^2 ya no es necesario"

Si estás utilizando un flujo de trabajo de CodeQL antiguo, podrías obtener el siguiente mensaje de advertencia en la salida "inicializar CodeQL" de la acción:

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer
necessary. Please remove this step as Code Scanning recommends analyzing the merge
commit for best results.

Puedes arreglar esto si eliminas las siguientes líneas del flujo de trabajo de CodeQL. Estas líneas se han incluido en la sección steps del trabajo Analyze en las versiones iniciales del flujo de trabajo de CodeQL.

        with:
          # We must fetch at least the immediate parents so that if this is
          # a pull request then we can checkout the head.
          fetch-depth: 2

      # If this run was triggered by a pull request event, then checkout
      # the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

La sección revisada steps del flujo de trabajo tendrá el siguiente aspecto:

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2

      ...

Para más información sobre la edición del archivo de flujo de trabajo CodeQL, consulta "Personalización del examen de código".

Solución de problemas de configuración avanzada para CodeQL

En este artículo