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 como parte de la GitHub Advanced Security, la cual es gratuita durante el lanzamiento beta. Para obtener más información, consulta la sección "Acerca de GitHub Advanced Security".

Nota: Escaneo de código se encuentra acutalmente en beta y está sujeto a cambios.

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

Puedes ejecutar el escaneo de código en GitHub AE 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 "Ejecutar el Ejecutor de CodeQL en tu sistema de IC."

Este artículo se trata de ejecutar el escaneo de código en GitHub AE 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. 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".

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

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]

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.

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

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

Si también utilizas un archivo de configuración para los ajustes personalizados, cualquier 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 consultas adicionales, coloca un prefijo en el valor de 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 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

Utilizar una herramienta de escaneo de código de terceros

Un archivo de configuración personalizado es una forma alterna de especificar 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 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.