# Opciones de configuración de flujo de trabajo para el examen de código
Edite el archivo de flujo de trabajo para configurar la forma en que la configuración avanzada examina el código del proyecto en busca de vulnerabilidades y errores.
## Prerrequisitos
Debe usar la configuración avanzada para code scanning y poder editar el archivo de flujo de trabajo donde se define la configuración.
Los ejemplos proporcionados en este artículo se relacionan con el Flujo de trabajo de análisis de CodeQL archivo. De forma predeterminada, este archivo se define en `.github/workflows/codeql-analysis.yml`.
## Frecuencia de examen
Puede configurar el Flujo de trabajo de análisis de CodeQL para escanear el código según una programación o cuando se produzcan 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. El análisis de código según una programación le informa sobre las vulnerabilidades y errores más recientes que GitHub, los investigadores de seguridad y la comunidad detectan, incluso cuando los desarrolladores no mantienen activamente el repositorio.
### Escanear cuando se carga información
De forma predeterminada, Flujo de trabajo de análisis de CodeQL usa el evento `on:push` para desencadenar un examen de código en cada envío a la rama predeterminada del repositorio y en las ramas protegidas. Para que code scanning se desencadene en una rama especificada, el flujo de trabajo debe existir en dicha rama. Para más información, consulta [Sintaxis del flujo de trabajo para GitHub Actions](/es/actions/using-workflows/workflow-syntax-for-github-actions#on).
Si escanea en la acción de inserción, los resultados aparecen en la ** Security and quality** pestaña de su repositorio. Para más información, consulta [Evaluación de alertas de análisis de código para el repositorio](/es/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository).
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 las alertas code scanning en las solicitudes de extracción, consulte [Clasificar las alertas del escaneo de código en las solicitudes de cambios](/es/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests).
### Escanear las solicitudes de extracción
El valor predeterminado Flujo de trabajo de análisis de CodeQL usa el `pull_request` evento para desencadenar un examen de código en las solicitudes de incorporación de cambios destinadas a la rama predeterminada.
Si una solicitud de incorporación de cambios procede de una bifurcación privada, el `pull_request` evento solo se desencadenará si ha seleccionado la opción "Ejecutar flujos de trabajo desde solicitudes de incorporación de cambios" en la configuración del repositorio. Para obtener más información, consulte [Administración de la configuración de GitHub Actions para un repositorio](/es/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks).
Para obtener más información sobre el evento `pull_request`, consulte [Eventos que desencadenan flujos de trabajo](/es/actions/using-workflows/events-that-trigger-workflows#pull_request).
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 más información, consulta [Clasificar las alertas del escaneo de código en las solicitudes de cambios](/es/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests).
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 activarse con las solicitudes de incorporación de cambios, puede seguir utilizando el `on:push` disparador, y code scanning asignará los resultados a las solicitudes de incorporación de cambios abiertas en la rama, añadiendo las alertas como anotaciones en la solicitud de incorporación de cambios. Para obtener más información, consulte [Examinar al insertar](#scanning-on-push).
> \[!NOTE]
> Si el repositorio está configurado con una cola de fusión, debe incluir el evento `merge_group` como un desencadenador adicional para code scanning. Esto garantizará que las solicitudes de incorporación de cambios también se examinen cuando se agreguen a una cola de fusión. Para más información, consulta [Administración de una cola de fusión](/es/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue).
### 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 code scanning flujo de trabajo. 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.
```yaml copy
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
paths-ignore:
- '**/*.md'
- '**/*.txt'
```
> \[!NOTE]
```
`on:pull_request:paths-ignore` y `on:pull_request:paths` establecen condiciones que determinan si las acciones del flujo de trabajo se ejecutarán en una solicitud de incorporación de cambios. No determinan qué archivos se analizarán cuando _se ejecuten_ las acciones. Cuando una solicitud de incorporación de cambios contiene archivos que no coinciden con `on:pull_request:paths-ignore` o `on:pull_request:paths`, el flujo de trabajo ejecuta las acciones y analiza todos los archivos modificados en la solicitud de incorporación de cambios, incluidos los que coinciden con `on:pull_request:paths-ignore` o `on:pull_request:paths`, a menos que se hayan excluido. Para obtener información sobre cómo excluir archivos del análisis, consulte [Especificar directorios para escanear](#specifying-directories-to-scan).
```
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 GitHub Actions](/es/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore).
### Escanear de forma pre-programada
Si usa el valor predeterminado Flujo de trabajo de análisis de CodeQL, el flujo de trabajo examinará el código del repositorio una vez a la semana, además de los exámenes desencadenados por eventos. Para ajustar esta programación, edita el valor `cron` del evento `on.schedule` en el flujo de trabajo. Para más información, consulta [Sintaxis del flujo de trabajo para GitHub Actions](/es/actions/reference/workflows-and-actions/workflow-syntax#onschedule).
> \[!NOTE]
> Este evento solo desencadenará una ejecución de flujo de trabajo si el archivo de flujo de trabajo existe en la rama predeterminada.
### Ejemplo
En el ejemplo siguiente se muestra un Flujo de trabajo de análisis de CodeQL para un repositorio determinado que tiene una rama predeterminada denominada `main` y una rama protegida denominada `protected`.
```yaml copy
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
## Sistema operativo
> \[!NOTE]
>
> * El examen de código de Swift usa ejecutores de macOS de forma predeterminada.
```
GitHubLos ejecutores de macOS hospedados son más caros que los ejecutores de Linux y Windows, por lo que debe considerar la posibilidad de examinar solo el paso de compilación. Para obtener más información sobre cómo configurar el examen de código para Swift, consulte [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#considerations-for-building-swift). Para obtener más información sobre los precios de GitHublos ejecutores hospedados, consulte [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions).
```
> * Code scanning del código Swift no se admite para los ejecutores que forman parte de un Actions Runner Controller (ARC), ya que los ejecutores de ARC solo usan Linux y Swift requiere ejecutores de macOS. Sin embargo, puedes tener una combinación de ejecutores de ARC y ejecutores de macOS autohospedados. Para más información, consulta [Controlador del ejecutor de acciones](/es/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller).
Si el código requiere que se compile un sistema operativo específico, puede configurar el sistema operativo en Flujo de trabajo de análisis de CodeQL. Edite el valor de `jobs.analyze.runs-on` para especificar el sistema operativo para la máquina que ejecuta las code scanning acciones.
```yaml copy
jobs:
analyze:
name: Analyze
runs-on: [ubuntu-latest]
```
Si decide usar un runner autohospedado para el escaneo de código, puede especificar un sistema operativo mediante una etiqueta adecuada como segundo elemento de una matriz de dos elementos, después de `self-hosted`.
```yaml copy
jobs:
analyze:
name: Analyze
runs-on: [self-hosted, ubuntu-latest]
```
```
CodeQL
code scanning admite 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 más información, consulta [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job) y [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners).
Si usa un ejecutor autohospedado, debe asegurarse de que Git está en la variable PATH. Para más información, consulta [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) y [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners).
```
Para obtener especificaciones recomendadas (RAM, núcleos de CPU y disco) para ejecutar CodeQL análisis en máquinas
autohospedadas, consulte [Recursos de hardware recomendados para ejecutar CodeQL](/es/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql).
##
```
CodeQL ubicación de la base de datos
```
En general, no es necesario preocuparse por dónde se Flujo de trabajo de análisis de CodeQL colocan las CodeQL bases de datos, ya que los pasos posteriores encontrarán automáticamente las bases de datos creadas por los pasos anteriores. Sin embargo, si va a escribir un paso de flujo de trabajo personalizado que requiere que la CodeQL base de datos esté en una ubicación de disco específica, por ejemplo, para cargar la base de datos como un artefacto de flujo de trabajo, puede especificar esa ubicación mediante el `db-location` parámetro en la `init` acción.
```yaml copy
- uses: github/codeql-action/init@v4
with:
db-location: '${{ github.runner_temp }}/my_location'
```
```
Flujo de trabajo de análisis de CodeQL espera que la ruta de acceso proporcionada en `db-location` sea grabable y 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 trabajos que se ejecutan en GitHubejecutores hospedados, que obtienen una instancia nueva y un sistema de archivos limpio cada vez que se ejecutan. Para más información, consulta [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners).
```
Si no se usa 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. Actualmente, el valor predeterminado es `${{ github.runner_temp }}/codeql_databases`.
## Idiomas que se van a analizar
```
CodeQL
code scanning admite el código escrito en los siguientes idiomas:
```
* C/C++
* C#
* Go
* Java/Kotlin
* JavaScript/TypeScript
* Python
* Ruby
* Rust
* Swift
> \[!NOTE]
>
> * Usa `java-kotlin` para analizar el código escrito en Java, Kotlin o ambos.
> * Usa `javascript-typescript` para analizar el código escrito en JavaScript, TypeScript o ambos.
Para más información, consulta la documentación en el sitio web de CodeQL: [Lenguajes y marcos admitidos](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/).
```
CodeQL usa los siguientes identificadores de idioma:
```
| Lenguaje | Identificador | Identificadores alternativos opcionales (si los hay) |
| -------- | ------------- | ---------------------------------------------------- |
| C/C++ | `c-cpp` | |
```
`c` o `cpp` |
```
\| C# | `csharp` |
\| |
Flujos de trabajo de GitHub Actions | `actions`
|
\| Go | `go` |
\| Java/Kotlin | `java-kotlin` |
`java` o `kotlin` |
\| JavaScript/TypeScript | `javascript-typescript` |
`javascript` o `typescript` |
\| Python | `python` |
\| Ruby | `ruby` |
\| |
Rust | `rust`
|
\| Swift | `swift` |
> \[!NOTE]
> Si especificas uno de los identificadores alternativos, esto equivale a usar el identificador de idioma estándar. Por ejemplo, especificar `javascript` en lugar de `javascript-typescript` no excluirá el análisis del código TypeScript. En su lugar, puedes usar un archivo de configuración personalizado para excluir archivos del análisis mediante la configuración `paths-ignore`. Para obtener más información, consulta [Usar un archivo de configuración personalizado](/es/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#custom-configuration-files) y [Especificar directorios para examinar](/es/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#specifying-directories-to-scan).
Estos identificadores de lenguaje se pueden usar como argumentos para la entrada `languages` de la acción `init`. Se recomienda que solo se proporcione un lenguaje como argumento:
```yaml copy
- uses: github/codeql-action/init@v4
with:
languages: javascript-typescript
```
El archivo predeterminado Flujo de trabajo de análisis de CodeQL creado después [de configurar la configuración avanzada para el análisis de código con CodeQL](/es/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql) define una matriz que contiene una propiedad denominada `language` que enumera los idiomas del repositorio que se analizarán. Esta matriz se ha rellenado previamente automáticamente con los lenguajes admitidos detectados en el repositorio. El uso de la `language` matriz permite CodeQL ejecutar cada análisis de lenguaje en paralelo y personalizar el análisis de cada idioma. En un análisis individual, el nombre del lenguaje de la matriz se proporciona a la acción `init` como argumento de la entrada `languages`. Se recomienda que todos los flujos de trabajo adopten esta configuración. Para obtener más información sobre las matrices, consulta [Ejecución de variaciones de trabajos en un flujo de trabajo](/es/actions/using-jobs/using-a-matrix-for-your-jobs).
```yaml copy
- uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
```
Si el flujo de trabajo usa la `language` matriz, CodeQL solo analizará los idiomas de la matriz. Para cambiar los lenguajes que deseas analizar, edita la configuración de la matriz. Puedes quitar un lenguaje para evitar que se analice. 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. También puede agregar un idioma que no estaba presente en el repositorio cuando code scanning se configuró. Por ejemplo, si el repositorio solo contenía JavaScript inicialmente cuando code scanning se configuró y más adelante agregó código de Python, deberá agregarlo `python` a la matriz.
```yaml copy
jobs:
analyze:
name: Analyze
...
strategy:
fail-fast: false
matrix:
include:
- language: javascript-typescript
build-mode: none
- language: python
build-mode: none
```
En el caso de los lenguajes compilados, la matriz también se puede usar para configurar qué modo de compilación se debe usar para el análisis cambiando el valor de la propiedad `build-mode`. Para obtener más información sobre los modos de compilación, consulta [Análisis de código de CodeQL para lenguajes compilados](/es/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#about-build-mode-none-for-codeql).
Si el flujo de trabajo no proporciona un argumento a la `languages` entrada de la `init` acción, CodeQL se configura para ejecutar análisis secuencialmente. En este caso, CodeQL detecta e intenta analizar automáticamente los idiomas admitidos en el repositorio. Según el tamaño del repositorio y el número de lenguajes, esto puede tardar mucho tiempo. Si se produce un error en el análisis de un lenguaje en este modo, se produce un error en el análisis de todos los lenguajes. Por lo tanto, no se recomienda esta configuración.
> \[!NOTE]
> Al analizar lenguajes secuencialmente, se usará el modo de compilación predeterminado para cada lenguaje. Como alternativa, si proporciona un paso explícito `autobuild`, cada lenguaje que admita el modo `autobuild` lo usará mientras que otros lenguajes usan su modo predeterminado. Si se requiere una configuración de modo de compilación más compleja de la necesaria, deberás configurar una matriz.
## Niveles de gravedad de alerta para fallos de verificación
Puede usar conjuntos de reglas para evitar que las solicitudes de incorporación de cambios se combinen cuando se cumple una de las condiciones siguientes:
* Una herramienta necesaria encuentra una alerta code scanning con una gravedad definida en el conjunto de reglas.
* El análisis de una herramienta necesaria todavía está en curso.
* No se ha configurado una herramienta necesaria para el repositorio.
Para más información, consulta [Establecimiento de la protección contra la fusión de análisis de códigos](/es/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection). Para obtener información más general sobre los conjuntos de reglas, consulta [Acerca de los conjuntos de reglas](/es/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets).
## Categoría de 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 trabaja en monorepositorios y tiene varios archivos SARIF para diferentes componentes del monorepositorio.
```yaml copy
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v4
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 un `category` parámetro en el flujo de trabajo, GitHub generará un nombre de categoría automáticamente, en función del nombre del archivo de flujo de trabajo que desencadene la acción, el nombre de la acción y las variables de 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-typescript, os: linux}` generarán la categoría `.github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux`.
El valor `category` aparecerá como la propiedad `.automationDetails.id` en SARIF v2.1.0. Para más información, consulta [Soporte de SARIF para escaneo de código](/es/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#runautomationdetails-object).
La categoría especificada no sobrescribirá los detalles del objeto `runAutomationDetails` en el archivo SARIF, si se incluye.
##
```
CodeQL paquetes de modelos
```
Si la base de código depende de una biblioteca o framework que las consultas estándar no reconocen en CodeQL, puede ampliar la cobertura de CodeQL en el code scanning flujo de trabajo especificando paquetes de modelos publicados CodeQL. Para obtener más información sobre cómo crear sus propios paquetes de modelos, consulte [Creación y uso de paquetes de CodeQL](/es/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack).
> \[!NOTE]
> Los paquetes de modelo de CodeQL se encuentran actualmente en versión preliminar pública y están sujetos a cambios. Los paquetes de modelo son compatibles con el análisis de C/C++, C#, Java/Kotlin, Python, Ruby y Rust.
>
> El editor de modelos de CodeQL de la extensión CodeQL para Visual Studio Code admite el modelado de dependencias para C#, Java/Kotlin, Python y Ruby.
### Uso de CodeQL paquetes de modelos
Para agregar uno o varios paquetes de modelos publicados CodeQL , especifíquelos dentro de la `with: packs:` entrada dentro de la `uses: github/codeql-action/init@v4` sección del flujo de trabajo. Dentro de `packs`, especifique uno o varios paquetes para usar y, opcionalmente, la versión que desea descargar. Cuando no se especifica una versión, se descarga la más reciente. Si quiere usar paquetes que no están disponibles públicamente, debe establecer la variable de entorno `GITHUB_TOKEN` en un secreto que tenga acceso a los paquetes. Para más información, consulta [Uso de GITHUB\_TOKEN para la autenticación en flujos de trabajo](/es/actions/security-guides/automatic-token-authentication) y [Uso de secretos en Acciones de GitHub](/es/actions/security-guides/encrypted-secrets).
```yaml copy
- uses: github/codeql-action/init@v4
with:
config-file: ./.github/codeql/codeql-config.yml
queries: security-extended
packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack
```
En este ejemplo, las consultas predeterminadas se ejecutarán para Java, así como las consultas de una versión mayor o igual que `7.8.9` y menos de `7.9.0` del paquete de consultas `my-company/my-java-queries`. Las dependencias modeladas en la última versión del paquete de modelos `my-repo/my-java-model-pack` estarán disponibles para las consultas predeterminadas y las de `my-company/my-java-queries`.
## Consultas no predeterminadas
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 análisis de CodeQL utiliza un conjunto predeterminado de consultas, pero puedes especificar más consultas para ejecutar, además de las predeterminadas.
> \[!TIP]
> También puedes especificar las consultas que deseas excluir del análisis o incluirlas en el análisis. Esto requiere el uso de un archivo de configuración personalizado. Para obtener más información, consulte [Archivos de configuración personalizados](#custom-configuration-files) y [Exclusión de consultas específicas del análisis](#excluding-specific-queries-from-analysis) siguiente.
Puede ejecutar consultas adicionales si son parte de un paquete CodeQL publicado en el GitHub Container registry o de un paquete CodeQL almacenado en un repositorio. Para más información, consulta [Acerca del examen de código con CodeQL](/es/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql-queries).
Las opciones disponibles para especificar las consultas adicionales que se quieren ejecutar son las siguientes:
* `packs` para instalar uno o más paquetes de consulta de CodeQL y ejecutar el conjunto de consultas predeterminado o las consultas para estos paquetes.
* `queries` para 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 obtener más información sobre las definiciones de conjuntos de consultas, consulte [Creación de conjuntos de consultas de CodeQL](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/).
Puede usar `packs` y `queries` en el mismo flujo de trabajo.
No se recomienda hacer referencia a conjuntos de consultas directamente desde el repositorio `github/codeql`, como `github/codeql/cpp/ql/src@main`. Estas consultas tendrían que volver a compilarse y es posible que no sean compatibles con la versión de CodeQL actualmente activa en GitHub Actions, lo que podría provocar errores durante el análisis.
### Usar los paquetes de la consulta
Para agregar uno o varios CodeQL paquetes de consultas, agregue una `with: packs:` entrada dentro de la `uses: github/codeql-action/init@v4` sección del flujo de trabajo. Dentro de `packs`, especifique uno o varios paquetes para usar y, opcionalmente, la versión que desea descargar. Cuando no se especifica una versión, se descarga la más reciente. Si quiere usar paquetes que no están disponibles públicamente, debe establecer la variable de entorno `GITHUB_TOKEN` en un secreto que tenga acceso a los paquetes. Para más información, consulta [Uso de GITHUB\_TOKEN para la autenticación en flujos de trabajo](/es/actions/security-guides/automatic-token-authentication) y [Uso de secretos en Acciones de GitHub](/es/actions/security-guides/encrypted-secrets).
> \[!NOTE]
> En el caso de los flujos de trabajo que generan CodeQL bases de datos para varios lenguajes, debe especificar en su lugar los CodeQL paquetes de consulta en un archivo de configuración. Para obtener más información, consulte [Especificación CodeQL de paquetes de consulta](#specifying-codeql-query-packs) a continuación.
En el ejemplo siguiente, `scope` es la cuenta personal o de la organización que ha publicado el paquete. Cuando se ejecuta el flujo de trabajo, los cuatro CodeQL paquetes de consulta se descargan de GitHub y se ejecutan las consultas predeterminadas o el conjunto de consultas predeterminado para cada paquete:
* Se descarga la versión más reciente de `pack1` y se ejecutan todas las consultas predeterminadas.
* Se descarga la versión 1.2.3 de `pack2` y se ejecutan todas las consultas predeterminadas.
* Se descarga la versión más reciente de `pack3` que es compatible con la versión 3.2.1 y se ejecutan todas las consultas.
* Se descarga la versión 4.5.6 de `pack4` y solo se ejecutan las consultas que se encuentran en `path/to/queries`.
```yaml copy
- uses: github/codeql-action/init@v4
with:
# Comma-separated list of packs to download
packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries
```
> \[!NOTE]
> Si especifica una versión determinada de un paquete de consultas para utilizar, tenga en cuenta que la versión que especifique puede llegar a ser demasiado antigua para que el motor predeterminado CodeQL sea usado de manera eficiente por la acción CodeQL. Para garantizar un rendimiento óptimo, si necesitas especificar una versión concreta de un paquete de consultas, deberías revisar periódicamente si es necesario actualizar la versión anclada del paquete de consultas.
>
> Para obtener más información sobre la compatibilidad de los paquetes, consulte [Referencia de paquetes de consulta de CodeQL](/es/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility).
### Descarga de CodeQL paquetes desde GitHub Enterprise Server
Si el flujo de trabajo usa paquetes publicados en una GitHub Enterprise Server instalación, debe indicar al flujo de trabajo dónde encontrarlos. Puede hacerlo con la entrada `registries` de la acción github/codeql-action/init\@v4. Esta entrada acepta una lista de propiedades `url`, `packages` y `token`, como se muestra a continuación.
```yaml copy
- uses: github/codeql-action/init@v4
with:
registries: |
# URL to the container registry, usually in this format
- url: https://containers.GHEHOSTNAME1/v2/
# List of package glob patterns to be found at this registry
packages:
- my-company/*
- my-company2/*
# Token, which should be stored as a secret
token: ${{ secrets.GHEHOSTNAME1_TOKEN }}
# URL to the default container registry
- url: https://ghcr.io/v2/
# Packages can also be a string
packages: "*/*"
token: ${{ secrets.GHCR_TOKEN }}
```
Los patrones de paquete de la lista de registros se examinan en orden, por lo que generalmente debes colocar primero los patrones de paquete más específicos. Los valores de `token` deben ser un personal access token (classic) generado por la instancia de GitHub desde la que estás descargando, con permiso de `read:packages`.
Fíjate en `|` después del nombre de la propiedad `registries`. Esto es importante, ya que GitHub Actions las entradas solo pueden aceptar cadenas. El uso de `|` convierte el texto subsiguiente en una cadena de texto, que la acción github/codeql-action/init\@v4 analiza más adelante.
### Utilizar las consultas en los paquetes de QL
Para agregar una o varias consultas, agregue una entrada `with: queries:` dentro de la sección `uses: github/codeql-action/init@v4` 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.
```yaml copy
- uses: github/codeql-action/init@v4
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.
| Conjunto de consultas | Descripción |
| :--------------------- | :------------------------------------------------------------------------------------------- |
| `security-extended` | Consultas del conjunto predeterminado, además de consultas de gravedad y precisión más bajas |
| `security-and-quality` | Consultas de `security-extended`, además de consultas de mantenimiento y confiabilidad. |
Para obtener más información, consulta [Conjuntos de consultas codeQL](/es/code-security/code-scanning/managing-your-code-scanning-configuration/built-in-codeql-query-suites).
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](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/).
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.
### Trabajar con archivos de configuración personalizados
Si también usa un archivo de configuración para la configuración personalizada, se usan los paquetes o consultas adicionales especificados en el flujo de trabajo en lugar de los especificados en el archivo de configuración. Si quiere ejecutar el conjunto combinado de paquetes o consultas adicionales, use el símbolo `packs` como prefijo del valor `queries` o `+` en el flujo de trabajo. Para obtener más información, consulte [Archivos de configuración personalizados](#custom-configuration-files).
En el ejemplo siguiente, el símbolo `+` garantiza que los paquetes y consultas adicionales especificados se usan junto con los especificados en el archivo de configuración al que se hace referencia.
```yaml copy
- uses: github/codeql-action/init@v4
with:
config-file: ./.github/codeql/codeql-config.yml
queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries
```
## Archivos de configuración personalizados
Un archivo de configuración personalizado es una manera alternativa de especificar paquetes y consultas adicionales para ejecutar. También puede usar el archivo para deshabilitar las consultas predeterminadas, excluir o incluir consultas concretas, o especificar los directorios que se examinarán 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*.
```yaml copy
- uses: github/codeql-action/init@v4
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.
```yaml copy
- uses: github/codeql-action/init@v4
with:
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
```
Los valores del archivo de configuración se escriben en formato YAML.
### Especificación de CodeQL paquetes de consultas
Se especifican los paquetes de consulta CodeQL en una matriz. Tenga en cuenta que el formato es diferente del que utiliza el archivo del flujo de trabajo.
```yaml copy
packs:
# Use the latest version of 'pack1' published by 'scope'
- scope/pack1
# Use version 1.2.3 of 'pack2'
- scope/pack2@1.2.3
# Use the latest version of 'pack3' compatible with 3.2.1
- scope/pack3@~3.2.1
# Use pack4 and restrict it to queries found in the 'path/to/queries' directory
- scope/pack4:path/to/queries
# Use pack5 and restrict it to the query 'path/to/single/query.ql'
- scope/pack5:path/to/single/query.ql
# Use pack6 and restrict it to the query suite 'path/to/suite.qls'
- scope/pack6:path/to/suite.qls
```
El formato completo para especificar un paquete de consulta es `scope/name[@version][:path]`. Ambos `version` y `path` son opcionales.
`version` es el intervalo de versiones de SemVer. Si falta, se usa la versión más reciente. Para obtener más información sobre los intervalos de SemVer, consulta la [documentación de SemVer en npm](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges).
Si tiene un flujo de trabajo que genera más de una CodeQL base de datos, puede especificar los CodeQL paquetes de consulta que se ejecuten en un archivo de configuración personalizado mediante un mapa anidado de paquetes.
```yaml copy
packs:
# Use these packs for JavaScript and TypeScript analysis
javascript:
- scope/js-pack1
- scope/js-pack2
# Use these packs for Java and Kotlin analysis
java:
- scope/java-pack1
- scope/java-pack2@v1.0.0
```
### Ampliando la cobertura de CodeQL con modelos de amenazas
> \[!NOTE]
> Los modelos de riesgos se encuentran actualmente en versión preliminar pública y están sujetos a cambios. Durante la versión preliminar pública, los modelos de riesgos solo son compatibles con el análisis de Java/Kotlin y C#.
El modelo de riesgos predeterminado incluye orígenes remotos de datos que no son de confianza. Puede ampliar el CodeQL modelo de amenazas para incluir orígenes locales de datos que no son de confianza (por ejemplo: argumentos de línea de comandos, variables de entorno, sistemas de archivos y bases de datos) especificando `threat-models: local` en un archivo de configuración personalizado. Si extiende el modelo de riesgos, también se usará el modelo de riesgos predeterminado.
### 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.
```yaml copy
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 [Consultas no predeterminadas](#non-default-queries) anteriores.
### Inhabilitar las consultas predeterminadas
Si solo desea ejecutar consultas personalizadas, puede deshabilitar las consultas de seguridad predeterminadas mediante `disable-default-queries: true`.
### Exclusión de consultas específicas del análisis
Puedes agregar filtros `exclude` y `include` al archivo de configuración personalizado para especificar las consultas que deseas excluir o incluir en el análisis.
Esto es útil si deseas excluir, por ejemplo:
* Consultas específicas de los conjuntos predeterminados (`security``security-extended` y `security-and-quality`).
* Consultas específicas cuyos resultados no te interesan.
* Todas las consultas que generan advertencias y recomendaciones.
Puedes usar `exclude` filtros similares a los del archivo de configuración siguiente para excluir las consultas que deseas quitar del análisis predeterminado. En el ejemplo de archivo de configuración siguiente, las consultas `js/redundant-assignment` y `js/useless-assignment-to-local` se excluyen del análisis.
```yaml copy
query-filters:
- exclude:
id: js/redundant-assignment
- exclude:
id: js/useless-assignment-to-local
```
Para buscar el identificador de una consulta, puede hacer clic en la alerta en la lista de alertas de la ** Security and quality** pestaña . Se abrirá la página de detalles de la alerta. El campo `Rule ID` contiene el identificador de consulta. Para obtener más información sobre la página de detalles de la alerta, consulte [Acerca de las alertas de análisis de código](/es/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-details).
> \[!TIP]
>
> * El orden de los parámetros es importante. La primera instrucción de filtro que aparece después de las instrucciones sobre las consultas y los paquetes de consultas determina si las consultas se incluyen o excluyen de forma predeterminada.
> * Las instrucciones posteriores se ejecutan en orden y las instrucciones que aparecen más adelante en el archivo tienen prioridad sobre las instrucciones anteriores.
Puede encontrar otro ejemplo que ilustra el uso de estos filtros en la sección [Archivos de configuración de ejemplo](#example-configuration-files).
Para obtener más información sobre el uso de los filtros `exclude` y `include` en su archivo de configuración personalizado, consulte [Creación de conjuntos de consultas de CodeQL](/es/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites#filtering-the-queries-in-a-query-suite). Para obtener información sobre los metadatos de consulta en los que puede filtrar, consulte [Metadatos para consultas CodeQL](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/).
### Especificar directorios para escanear
Cuando se analizan los códigos base sin compilar el código, puede restringir code scanning los archivos de directorios específicos agregando una `paths` matriz al archivo de configuración. También puede excluir los archivos de directorios específicos del análisis agregando una matriz `paths-ignore`. Puede usar esta opción al ejecutar las CodeQL acciones en un lenguaje interpretado (Python, Ruby y JavaScript/TypeScript) o al analizar un lenguaje compilado sin necesidad de compilar el código (actualmente compatible para C/C++, C#, Java y Rust).
```yaml copy
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
```
> \[!NOTE]
>
> * Las `paths` palabras clave y `paths-ignore` , que se usan en el contexto del code scanning archivo de configuración, no deben confundirse con las mismas palabras clave cuando se usan para `on..paths` en un flujo de trabajo. Cuando se usan para modificar `on.` en un flujo de trabajo, determinan si las acciones se ejecutarán cuando alguien modifique el código en los directorios especificados. Para más información, consulta [Sintaxis del flujo de trabajo para GitHub Actions](/es/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore).
> * Los caracteres de patrón de filtro `?`, `+`, `[`, `]` y `!` no se admiten y coincidirán literalmente.
> * ```
> Los caracteres `**` solo pueden colocarse al principio o al final de una línea, o rodeados por barras diagonales, y no se puede mezclar `**` ni otros caracteres. Por ejemplo, `foo/**`, `**/foo` y `foo/**/bar` son una sintaxis permitida, pero `**foo` no lo es. Sin embargo, puede usar un solo asterisco junto con otros caracteres, como se muestra en el ejemplo. Tendrá que citar todo lo que contenga un carácter `*`.
> ```
Para analizar dónde se compila el código, si desea limitar code scanning a directorios específicos del proyecto, debe 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 más información, consulta [Análisis de código de CodeQL para lenguajes compilados](/es/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language).
Puede analizar rápidamente pequeñas partes de un repositorio mono al modificar el código en directorios específicos. Deberá excluir los directorios en los pasos de compilación y usar las palabras clave `paths-ignore` y `paths` para [`on.`](/es/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) en el flujo de trabajo.
### Archivos de configuración de ejemplo
Este archivo de configuración incorpora la suite de consultas `security-and-quality` a la lista de consultas ejecutadas por CodeQL al analizar tu código. Para obtener más información sobre los conjuntos de consultas disponibles para su uso, consulte [Consultas no predeterminadas](#non-default-queries).
```yaml
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.
```yaml
name: "My CodeQL config"
disable-default-queries: true
queries:
- name: Use an in-repository CodeQL pack (run queries in the my-queries directory)
uses: ./my-queries
- name: Use an external JavaScript CodeQL pack (run queries from an external repo)
uses: octo-org/javascript-codeql-pack@main
- name: Use an external query (run a single query from an external CodeQL pack)
uses: octo-org/python-codeql-pack/show_ifs.ql@main
- name: Use a query suite file (run queries from a query suite in this repo)
uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
```
El siguiente archivo de configuración solo ejecuta consultas que generan alertas de error de gravedad. La configuración selecciona primero todas las consultas predeterminadas, todas las consultas en `./my-queries`, así como el conjunto predeterminado en `codeql/java-queries`y, a continuación, excluye todas las consultas que generan advertencias o recomendaciones.
```yaml
queries:
- name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
uses: ./my-queries
packs:
- codeql/java-queries
query-filters:
- exclude:
problem.severity:
- warning
- recommendation
```
## Detalles de configuración
Si prefiere especificar detalles de configuración adicionales en el archivo de flujo de trabajo, puede usar la entrada `config` del comando `init` de la acción CodeQL. El valor de esta entrada debe ser una cadena YAML que siga el formato de archivo de configuración documentado en [Archivos de configuración personalizados](#custom-configuration-files) anteriores.
### Configuración de ejemplo
En este paso de un GitHub Actions archivo de flujo de trabajo se usa una `config` entrada para deshabilitar las consultas predeterminadas, agregar el `security-extended` conjunto de consultas y excluir las consultas etiquetadas con `cwe-020`.
```yaml
- uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
config: |
disable-default-queries: true
threat-models: local
queries:
- uses: security-extended
query-filters:
- exclude:
tags: /cwe-020/
```
Puedes usar el mismo enfoque para especificar las opciones de configuración válidas en el archivo de flujo de trabajo.
> \[!TIP]
> Puede compartir una configuración entre varios repositorios mediante GitHub Actions variables. Una ventaja de este enfoque es que puedes actualizar la configuración en un solo lugar sin editar el archivo de flujo de trabajo.
>
> En el ejemplo siguiente, `vars.CODEQL_CONF` es una GitHub Actions variable. Su valor puede ser el contenido de cualquier archivo de configuración válido. Para más información, consulta [Almacenamiento de información en variables](/es/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
>
> ```yaml
> - uses: github/codeql-action/init@v4
> with:
> languages: ${{ matrix.language }}
> config: ${{ vars.CODEQL_CONF }}
> ```
## Lenguajes compilados
En el caso de los lenguajes compilados, puede decidir cómo la CodeQL acción crea una CodeQL base de datos para su análisis. Para más información sobre las opciones de compilación disponibles, consulta [Análisis de código de CodeQL para lenguajes compilados](/es/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages).
## Carga de datos
```
GitHub puede mostrar datos de análisis de código generados externamente por una herramienta de terceros. Puede cargar datos de análisis de código con la acción `upload-sarif`. Para más información, consulta [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github).
```