# Personalización del análisis con paquetes de CodeQL

Puede usar CodeQL paquetes para ejecutar CodeQL consultas mantenidas por otras personas o para compartir CodeQL consultas desarrolladas.

Puede personalizar el CodeQL análisis descargando paquetes creados por otros usuarios y ejecutándolos en el código base. Para obtener más información, vea [Paquetes de consultas de CodeQL](/es/enterprise-server@3.18/code-security/concepts/code-scanning/codeql/codeql-query-packs).

## Descargar y usar CodeQL paquetes de consultas

Antes de poder usar un paquete de consultas CodeQL para analizar una base de datos, debe descargar los paquetes necesarios desde GitHubContainer registry. Puede hacerlo si usa la marca `--download` como parte del comando `codeql database analyze` o ejecutar `codeql pack download`. Si un paquete no está disponible públicamente, deberá utilizar un GitHub App o personal access token para autenticarse. Para obtener más información y un ejemplo, consulta [Carga de resultados de análisis de CodeQL en GitHub](/es/enterprise-server@3.18/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github#uploading-results-to-github).

| Opción                                                                             |                                                                                                                                                                                                           Obligatorio                                                                                                                                                                                                          | Uso                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <code><span style="white-space: nowrap;">\<scope/name\@version:path></span></code> |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | Especifique el ámbito y el nombre de uno o varios CodeQL paquetes de consulta que se van a descargar mediante una lista separada por comas. Opcionalmente, incluye la versión para descargar y descomprimir. Se descarga la versión más reciente de este paquete predeterminadamente. Opcionalmente, incluye una ruta de acceso a una consulta, directorio o conjunto de consultas que se vaya a ejecutar. Si no se incluye ninguna ruta de acceso, ejecuta las consultas predeterminadas de este paquete. |
| <code><span style="white-space: nowrap;">--github-auth-stdin</span></code>         | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-x" aria-label="Optional" role="img"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"></path></svg> | Pase el CLI, el GitHub App o personal access token creados para la autenticación con la API REST de GitHub desde su almacén de secretos a través de la entrada estándar. Esto no es necesario si el comando tiene acceso a una variable de entorno `GITHUB_TOKEN` establecida con este token.                                                                                                                                                                                                              |

> \[!NOTE]
> Si especifica una versión concreta de un paquete de consultas para usar, tenga en cuenta que la versión que especifique puede llegar a ser demasiado antigua para que la versión más reciente de CodeQL pueda aprovecharla de forma eficaz. Para garantizar un rendimiento óptimo, si necesita especificar versiones concretas del paquete de consultas, debe volver a evaluar a qué versiones ancla cada vez que actualices la CLI de CodeQL CLI que usa.
>
> Para obtener más información sobre la compatibilidad de los paquetes, consulte [Referencia de paquetes de consulta de CodeQL](/es/enterprise-server@3.18/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility).

### Ejemplo básico de descarga y uso de paquetes de consulta

En este ejemplo se ejecuta el comando `codeql database analyze` con la opción `--download` para:

1. Descargar la versión más reciente del paquete `octo-org/security-queries`.
2. Descargar una versión del paquete `octo-org/optional-security-queries` que sea *compatible* con la versión 1.0.1 (en este caso, es la versión 1.0.2). Para obtener más información sobre la compatibilidad de SemVer, consulta la [documentación del intervalo de versiones semánticas de npm](https://github.com/npm/node-semver#ranges).
3. Ejecutar todas las consultas predeterminadas en `octo-org/security-queries`.
4. Ejecutar solo la consulta `queries/csrf.ql` de `octo-org/optional-security-queries`

```shell
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.
```

### Descarga directa de CodeQL paquetes

Si desea descargar un CodeQL paquete sin ejecutarlo inmediatamente, puede usar el `codeql pack download` comando . Esto resulta útil si desea evitar el acceso a Internet al ejecutar CodeQL consultas. Al ejecutar el CodeQL análisis, puede especificar paquetes, versiones y rutas de acceso de la misma manera que en el ejemplo anterior:

```shell
echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...
```

### Descarga de CodeQL paquetes de varios GitHub registros de contenedor

Si sus CodeQL packs residen en varios registros de contenedores, debe indicar a CodeQL CLI dónde encontrar cada pack. Para obtener más información, vea [Opciones de configuración de flujo de trabajo para el examen de código](/es/enterprise-server@3.18/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#downloading-codeql-packs-from-github-enterprise-server).

## Especificación de las consultas que se van a ejecutar en un CodeQL paquete

Los especificadores de consulta se usan en `codeql database analyze` y en otros comandos que operan en un conjunto de consultas.
La forma completa de un especificador de consulta es `scope/name@range:path`, donde:

* `scope/name` es el nombre cualificado de un paquete CodeQL.
* `range` es un [intervalo de SemVer](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges).
* `path` es una ruta de acceso del sistema de archivos a una sola consulta, un directorio que contiene consultas o un archivo de conjunto de consultas.

Cuando se especifica `scope/name`, `range` y `path` son opcionales. Si `range` se omite, se usa la versión más reciente del paquete especificado. Si `path` se omite, se usa el conjunto de consultas predeterminado del paquete especificado.

`path` puede ser un archivo de consulta `.ql`, un directorio que contiene una o varias consultas o un archivo de conjunto de consultas `.qls`. Si se omite el nombre de paquete, debes proporcionar `path`, que se interpretará en relación con el directorio de trabajo del proceso actual. No se admiten patrones globales.

Si se especifica `scope/name` y `path`, el valor de `path` no puede ser absoluto. Se interpreta en relación con la raíz del paquete de CodeQL
.

### Especificadores de consulta de ejemplo

* `codeql/python-queries`: todas las consultas del conjunto de consultas predeterminado de la versión más reciente del paquete `codeql/python-queries`.

* `codeql/python-queries@1.2.3`: todas las consultas del conjunto de consultas predeterminado de la versión `1.2.3` del paquete `codeql/python-queries`.

* `codeql/python-queries@~1.2.3`: todas las consultas del conjunto de consultas predeterminado de la versión más reciente del paquete `codeql/python-queries` que es >= `1.2.3` y < `1.3.0`.

* `codeql/python-queries:Functions`: todas las consultas del directorio `Functions` en la versión más reciente del paquete `codeql/python-queries`.

* `codeql/python-queries@1.2.3:Functions`: todas las consultas del directorio `Functions` de la versión 1.2.3 del paquete `codeql/python-queries`.

* `codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls`: todas las consultas del directorio `codeql-suites/python-code-scanning.qls` de la versión 1.2.3 del paquete `codeql/python-queries`.

* `suites/my-suite.qls`: todas las consultas del archivo `suites/my-suite.qls` en relación con el directorio de trabajo actual.

> \[!TIP]
> El conjunto de consultas predeterminado de los paquetes de consultas estándar CodeQL son `codeql-suites/<lang>-code-scanning.qls`. También se pueden encontrar otros conjuntos de consultas útiles en el directorio `codeql-suites` de cada paquete. Por ejemplo, el paquete `codeql/cpp-queries` contiene los siguientes conjuntos de consultas:
>
> *

`cpp-code-scanning.qls`: consultas de análisis de código estándar para C++. Es el conjunto de consultas predeterminado para este paquete.

> \*
> `cpp-security-extended.qls`: consultas del conjunto `cpp-code-scanning.qls` predeterminado para C++, además de consultas de gravedad y precisión más bajas.
> \*
> `cpp-security-and-quality.qls`: consultas de `cpp-security-extended.qls`, además de consultas de mantenimiento y fiabilidad.
>
> Puede ver los orígenes de estos conjuntos de consultas en el [CodeQL repositorio](https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites). Los conjuntos de consultas de otros lenguajes son similares.

## Uso de paquetes de modelos para analizar llamadas a dependencias personalizadas

Puede incluir paquetes de modelos publicados en un análisis code scanning con la opción `--model-packs`. Por ejemplo:

```shell
$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --model-packs my-repo/my-java-model-pack \
  --output=/temp/my-company.sarif codeql/java-queries
```

En este ejemplo, las consultas pertinentes del paquete de consultas estándar `codeql/java-queries` usarán la información de dependencia del paquete de modelos, `my-repo/my-java-model-pack`, para comprobar si hay vulnerabilidades en el código que llama a esas dependencias.

Puede especificar varios paquetes de modelos publicados en un análisis.

Para obtener más información sobre cómo escribir sus propios paquetes de modelos, consulte [Creación y uso de paquetes de CodeQL](/es/enterprise-server@3.18/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack).

### Acerca de los paquetes publicados

Cuando se publica un paquete para su uso en análisis, el comando `codeql pack create` o `codeql pack publish` comprueba que el contenido está completo y también le agrega algunos fragmentos de contenido adicionales:

* En el caso de los paquetes de consultas, una copia de cada uno de los paquetes de biblioteca de los que depende, en las versiones específicas con las que se ha desarrollado. Los usuarios del paquete de consultas no tendrán que descargar estos paquetes de biblioteca por separado.

* En el caso de los paquetes de consultas, representaciones precompiladas de cada una de las consultas. Son más rápidos de ejecutar que si se compilara el origen de QL para la consulta en cada análisis.

La mayoría de estos datos se encuentran en un directorio denominado `.codeql` en el paquete publicado, pero las consultas precompiladas están en archivos con un sufijo `.qlx` junto al origen `.ql` de cada consulta. Al analizar una base de datos con una consulta de un paquete publicado, CodeQL cargará estos archivos en lugar del `.ql` origen. Si necesitas modificar el contenido de un paquete *publicado*, asegúrate de quitar todos los archivos `.qlx`, ya que podrían impedir que las modificaciones de los archivos `.ql` surtieran efecto.