Configurar el escaneo de código

Nota: El Escaneo de código se encuentra en beta dentro de GitHub Enterprise Server 2.22. Para encontrar un lanzamiento de disponibilidad general del escaneo de código, mejora al último lanzamiento de GitHub Enterprise Server.

Nota: Tu administrador de sitio debe habilitar el escaneo de código para tu instancia de GitHub Enterprise Server antes de que puedas utilizar esta característica. Si quieres utilizar GitHub Actions para escanear tu código, el administrador de sitio también puede habilitar las GitHub Actions y configurar la infraestructura que se requiera. Para obtener más información, consulta "Configurar el escaneo de código en tu aplicativo."

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

Puedes ejecutar el escaneo de código en GitHub Enterprise Server, utilizando las GitHub Actions, o desde tu sistema de integración contínua (IC), si utilizas el Ejecutor de CodeQL. Para obtener más información acerca de GitHub Actions, consulta la sección "Acerca de GitHub Actions". Para obtener más información acerca del Ejecutor de CodeQL, consulta la sección Ejecutar el escaneo de código en tu sistema de IC".

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

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 en GitHub.com contiene otros flujos de trabajo del escaneo de código que puedes utilizar. Los ejemplos específicos que se muestran en este artículo se relacionan con el archivo de 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.

En tu repositorio, navega hasta el archivo de flujo de trabajo que deseas editar.
En el ángulo superior derecho de la vista del archivo, para abrir el editor de flujo de trabajo, haz clic en .
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.

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

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. El evento pull_request no se activa si se abrió la solicitud de cambios desde una bifurcación privada.

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

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: '40 7 * * 2'

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 martes a las 7:40 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. Se especifica el sistema operativo usando una 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]

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. Para obtener más información, consulta las secciones "Sintaxis de flujos de trabajo para GitHub Actions" y "Utilizar etiquetas con ejecutores auto-hospedados".

Debes asegurarte de que Git esté en la variable PATH en tus ejecutores auto-hospedados.

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

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.

Cualquier consulta adicional que quieras ejecutar debe pertenecer a un paquete de QL en un repositorio. Para obtener más información, consulta la sección "Acerca del escaneo de código".

Puedes especificar un solo archivo .ql, un directorio que contenga varios archivos .ql, un archivo de definición de suite de consulta .qls, o cualquier combinación de éstos. 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".

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 tenga acceso a este.

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access 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 consultas	Descripción
`security-extended`	Las consultas de severidad y precisión más baja que aquellas predeterminadas
`security-and-quality`	Las 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.

Puedes ejecutar consultas adicionales si las especificas en un archivo de configuración. So quieres ejecutar el conjunto combinado de consultas adicionales que se especifica aquí y en el archivo de configuración, agrega como prefijo el valor 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 + se asegura de que las consultas adicionales especificadas se utilicen en conjunto con cualquier otra consulta que se especifique 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
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Utilizar una herramienta de escaneo de código de terceros

Como alternativa para especificar qué consultas se ejecutarán en un archivo de flujo de trabajo, puedes hacer esto en un archivo de configuración diferente. También puedes utilizar un archivo de configuración 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 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: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.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 acerca de cómo configurar el CodeQL del escaneo de código 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".

Explorar por producto

En este artículo