Personalización del examen de código

Acerca de la configuración de code scanning

Puedes ejecutar el code scanning en GitHub Enterprise Server 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".

Este artículo trata sobre la ejecución de code scanning en GitHub Enterprise Server mediante acciones.

Antes de que puedas personalizar el code scanning para un repositorio, debes configurar code scanning agregando un flujo de trabajo de GitHub Actions al repositorio. Para más información, consulta "Configuración del análisis de código para un repositorio".

Habitualmente, no necesitas editar el archivo de flujo de trabajo generado para code scanning. 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 code scanning 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 code scanning que puedes hacer en GitHub. GitHub Marketplace en GitHub.com contiene otros flujos de trabajo del code scanning que puedes utilizar. 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. El evento pull_request no se activará si la solicitud de incorporación de cambios se abrió desde una bifurcación privada.

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 tu instancia de GitHub Enterprise Server, navega a la página principal del repositorio. 1. Debajo del nombre del repositorio, haz clic en Configuración.
2. En la barra lateral de la izquierda, haga clic en Security & analysis.
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. Para especificar el sistema operativo, use 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».

Debes asegurarte de que Git esté en la variable PATH en los ejecutores autohospedados. 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, 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@v1
  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
• 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@v1
  with:
    languages: cpp, csharp, python

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@v1
      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 Enterprise Server 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.

Las consultas adicionales que quiera ejecutar deben pertenecer a un paquete de QL en un repositorio. Para obtener más información, vea «Acerca del examen de código con CodeQL».

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

Para agregar una o varias consultas, agregue una entrada with: queries: dentro de la sección uses: github/codeql-action/init@v1 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@v1
  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.

Si también usas un archivo de configuración para los ajustes personalizados, se usará cualquier consulta 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 consultas adicionales, antepón el valor de 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 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@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

Uso de un archivo de configuración personalizado

Un archivo de configuración personalizado es una forma alternativa de especificar consultas adicionales para su ejecución. También puedes usar el archivo para deshabilitar las consultas predeterminadas 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@v1
  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@v1
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

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.

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'

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#, 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, 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».