👋 We've unified all of GitHub's product documentation in one place! Check out the content for REST API, GraphQL API, and Developers. Learn more on the GitHub blog.


Frecuentemente publicamos actualizaciones de nuestra documentación. Es posible que la traducción de esta página esté en curso. Para conocer la información más actual, visita la documentación en inglés. Si existe un problema con las traducciones en esta página, por favor infórmanos.

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.

Las personas con permisos de escritura en un repositorio pueden configurar escaneo de código para el mismo.

En este artículo

¿Pudiste encontrar lo que estabas buscando?

Nota: Escaneo de código se encuentra acutalmente en beta y está sujeto a cambios. Para solicitar acceso al beta,, únete a la lista de espera.

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

Escaneo de código utiliza GitHub Actions. Antes de que puedas configurar escaneo de código para un repositorio, debes habilitar escaneo de código agregando un flujo de trabajo de GitHub Actions a dicho repositorio. Para obtener más información, consulta la sección "Habilitar escaneo de código".

Habitualmente, no necesitas editar el flujo de trabajo predeterminado para escaneo de código. Puedes editar el flujo de trabajo para especificar la frecuencia de los escaneos, los lenguajes o directivas de escaneo, así como lo que debería buscar escaneo de código en tu código. También puede que necesites editar el flujo de trabajo si utilizas un conjunto específico de comandos para compilar tu código.

Para obtener más información acerca de la edición de flujos de trabajo, consulta la sección "Configurar un flujo de trabajo".

Configurar la frecuencia

Puedes escanear código con cierta programación o cuando ocurren eventos específicos en un repositorio.

Por ejemplo, los siguientes escaneos de configuración en subidas, en la creación de una solicitud de extracción, y en una programación de calendario.

on:
  push:
  pull_request:
  schedule:
    - cron: '0 15 * * 0'

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

El flujo de trabajo predeterminado de escaneo de código utiliza el evento on.push para activar el escaneo de código cada vez que alguien carga información a cualquier rama que contenga el archivo de flujo de trabajo. Para obtener más información, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

No te recomendamos utilizar la palabra clave branches para limitar on.push a ramas específicas. Si especificas ramas para on.push, escaneo de código únicamente se ejecutará si subes las rama que especificaste en el flujo de trabajo.

Escanear las solicitudes de extracción

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. Escanear el evento pull_request no funcionará si abres una solicitud de extracción de 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".

Escanear de forma pre-programada

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 "Sintaxis del flujo de trabajo paraGitHub 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.

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.<job_id>.runs-on para especificar el sistema operativo para la máquina que ejecuta tus acciones de escaneo de código. Escaneo de código es compatible con las últimas versiones de macOs, Ubuntu, y Windows. Para obtener más información, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

Invalidar la detección automática de lenguaje

Escaneo de código detecta y escanea automáticamente el código que se escribe en los lenguajes compatibles.

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

Si tu repositorio contiene código en varios lenguajes, puedes especificar aquellos que quieras 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.

Para invalidar la detección automática de lenguajes, agrega with:languages: a la acción de init en tu flujo de trabajo. Las palabras clave para los lenguajes compatibles son cpp, csharp, go, java, javascript, y python.

Por ejemplo, la siguiente configuración limita a escaneo de código para reconocer C/C++, C#, y Python.

- uses: github/codeql-action/init@v1
  with:
    languages: cpp, csharp, python

Agregar pasos de compilación para un lenguaje compilado

Para C/C++, C#, y Java, el paso autobuild en el flujo de trabajo predeterminado intenta compilar el código antes de que la acción realice un análisis de CodeQL. En contraste con los otros lenguajes compilados, CodeQL analiza Go sin compilar el código.

Si el código escrito en C/C++, C#, o Java en tu repositorio tiene un proceso de compilación no estándar, autobuild podría fallar. Si esto sucede, elimina la acción autobuild del flujo de trabajo, y quita el comentario de el paso run.

El paso run ejecuta programas de línea de comandos que utilizan el shell del sistema operativo. Puedes modificar estos comandos y agregar más de ellos para personalizar el proceso de compilación.

- run: |
  make bootstrap
  make release

Para obtener más información acerca de la palabra clave run, consulta la sección "Sintaxis de flujo de trabajo para { site.data.variables.product.prodname_actions }}".

Acceder a repositorios privados

Si tu flujo de trabajo para escaneo de código accede a repositorios privados en GitHub, necesitarás configurar Git para autenticarte con un token de acceso personal. Define el secreto en el ambiente del ejecutor utilizando jobs.<job_id>.steps.env en tu flujo de trabajo antes de cualquier acción de CodeQL. Para obtener más información, consulta la sección "Crear un token de acceso personal para la línea de comandos" y "Crear y almacenar secretos cifrados".

Por ejemplo, la siguiente configuración hace que Git reemplace las URL completas en los repositorios github/foo, github/bar, y github/baz en GitHub.com con las URL que incluyen el token de acceso personal que almacenas en la variable de ambiente ACCESS_TOKEN.

steps:
- name: Configure access to private repository on GitHub.com
  env:
    TOKEN: ${{ secrets.ACCESS_TOKEN }}
  run: |
    git config --global url."https://${TOKEN}@github.com/github/foo".insteadOf "https://github.com/github/foo"
    git config --global url."https://${TOKEN}@github.com/github/bar".insteadOf "https://github.com/github/bar"
    git config --global url."https://${TOKEN}@github.com/github/baz".insteadOf "https://github.com/github/baz"

Utilizar una configuración personalizada

Puedes escribir un archivo de configuración para escaneo de código. Un archivo de configuración puede especificar qué consultas ejecutar y qué directorios escanear.

Utiliza el parámetro config-file de la acción init para especificar el archivo de configuración. El valor de config-file es la ruta del 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 debe ubicarse dentro del repositorio local. Para encontrar ejemplos de archivos de configuración, consulta la sección "Ejemplos de archivos de configuración".

Ejecutar consultas adicionales

Cuando habilitas escaneo de código, el motor de análisis de CodeQL para GitHub genera una base de datos del código y ejecuta las consultas en él. Para obtener más información, consulta "Acerca de escaneo de código".

Puedes ejecutar consultas adicionales si las especificas en un archivo de configuración. Las consultas que quieras ejecutar deberán pertenecer a un paquete de QL y pueden estar en tu propio repositorio o en cualquier repositorio público. Para obtener más información, consulta la sección "Acerca de los paquetes de QL".

Las consultas solo deberán depender de las bibliotecas estándar (es decir, aquellas referenciadas por una declaración import LANGUAGE en tu consulta), o de aquellas en el mismo paquete de QL que la consulta. Las bibliotecas estándar se ubican en el repositorio github/codeql. Para obtener más información, consulta la sección "Introducción a archivos de consulta".

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 suites de consulta, visita "Crear suites de consulta de odeQL".

Para agregar una o más consultas, agrega una sección de queries a tu archivo de configuración.

queries:
  - name: DESCRIPTION OF YOUR CHOICE
    uses: PATH

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.

Los siguientes conjuntos de consultas se compilan en el escaneo de código y están disponibles para utilizarse en tu archivo de configuración.

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 un conjunto de consultas en tu archivo de configuración, el motor de análisis de CodeQL ejecutará para ti las consultas que se contengan en el conjunto, adicionalmente a aquellas predeterminadas.

Para agregar uno o más conjuntos de consultas, agrega una sección de queries a tu archivo de configuración.

queries:
 - uses: security-and-quality

No recomendamos referenciar conjuntos de consultas para uses directamente desde el repositorio github/codeql, como github/codeql/cpp/ql/src@master. Dichas consultas podrían no compilarse con la misma versión del CodeQL como la versión que se utiliza en tu archivo de configuración, lo cual puede causar errores durante el análisis.

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 que son compatibles con CodeQL (Python y JavaScript/TypeScript), puedes restringir escaneo de código a archivos en directorios específicos utilizando la palabra clave paths en el archivo de configuración. Puedes excluir del escaneo a los archivos en directorios específicos si utilizas la palabra clave paths-ignore.

Nota: Las palabras clave paths y paths-ignore que se utilizan en el contexto del archivo de configuración de escaneo de código no deberán confundirse con las mismas palabras clave cuando se utilicen para on.<push|pull_request>.paths. Cuando se tulizan para modificar on.<push|pull_request> en un archivo de 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".

Para C/C++, C# y Java, si quieres limitar el escaneo de código para directorios específicos en tu proyecto, deberás 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 "Agregar pasos de compilación para un lenguaje compilado".

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

Este archivo de configuración inhabilita las consultas predeterminadas y, en vez de esto, especifica un conjunto de consultas personalizadas para su ejecución. También configura a CodeQL para escanear archivos en el directorio /src directory, incluyendo todos sus subdirectorios, con excepción de aquél llamado node_modules.

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@master
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@master
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths-ignore: 
  - '/node_modules/'
paths:
  - '/src' 

Utilizar una herramienta de escaneo de código 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".

¿Pudiste encontrar lo que estabas buscando?

Pregunta a una persona

¿No puedes encontrar lo que estás buscando?

Contáctanos