database init

En este contenido se describe la versión más reciente de CodeQL CLI. Para obtener más información sobre esta versión, consulta https://github.com/github/codeql-cli-binaries/releases.

Para ver detalles de las opciones disponibles para este comando en una versión anterior, ejecuta el comando con la opción --help en el terminal.

Sinopsis

Shell

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Descripción

[Asociación] Crea una base de datos CodeQL vacía.

Crea una estructura de esqueleto para una base de datos CodeQL que aún no tiene un conjunto de datos de QL sin procesar, pero que está listo para ejecutar los pasos del extractor. Una vez que se complete este comando, ejecuta uno o más comandos codeql database trace-command seguidos de codeql database finalize para preparar la base de datos para consultas.

(Parte de lo que esto hace es resolver la ubicación del paquete de lenguaje adecuado y almacenarlo en los metadatos de la base de datos, de modo que no sea necesario rehacerlo en cada comando de extracción. De todos modos, no se permite cambiar extractores en medio de una operación de extracción).

Opciones

Opciones principales

`<database>`

[Obligatorio] Ruta de acceso a la base de datos CodeQL que se va a crear. Se creará este directorio y no debe existir previamente (por el contrario, su elemento primario sí debe existir).

Si se brinda la opción --db-cluster, no será una base de datos en sí misma, sino un directorio que contendrá bases de datos para varios lenguajes creadas a partir de la misma raíz de origen.

Es importante que este directorio no esté en una ubicación con la que interfiera el proceso de compilación. Por ejemplo, el directorio target de un proyecto de Maven no sería una opción adecuada.

`-s, --source-root=<dir>`

[Obligatorio] Directorio de código fuente raíz. En muchos casos, será la raíz de la extracción. Los archivos que se encuentran en su interior se consideran los archivos de origen principales para esta base de datos. En algunos formatos de salida, la ruta de acceso relativa de este directorio hará referencia a los archivos.

`--[no-]overwrite`

[Avanzado] Si la base de datos ya existe, elimínala y sigue con este comando en lugar de generar un error. Si el directorio existe, pero no parece una base de datos, se producirá un error.

`--[no-]force-overwrite`

[Avanzado] Si la base de datos ya existe, elimínala incluso si no parece una base de datos y sigue con este comando en lugar de generar un error. Esta opción se debe usar con precaución, ya que puede eliminar de manera recursiva todo el directorio de base de datos.

`--codescanning-config=<file>`

[Avanzado] Lee un archivo de configuración de examen de código que especifique las opciones para crear las bases de datos CodeQL y las consultas que se van a ejecutar en pasos posteriores. Para información más detallada sobre el formato de este archivo de configuración, consulta Personalización de la configuración avanzada para el examen de código. Para ejecutar consultas desde este archivo en un paso posterior, invoca codeql database analyze sin ninguna otra consulta especificada.

`--[no-]db-cluster`

En lugar de crear una base de datos única, crea un "clúster" de bases de datos para distintos lenguajes, cada una de los cuales es un subdirectorio del directorio especificado en la línea de comandos.

`-l, --language=<lang>[,<lang>...]`

Lenguaje que la base de datos nueva usará para realizar el análisis.

Usa codeql resolve languages para obtener una lista de los extractores de lenguaje conectables que se encuentran en la ruta de búsqueda.

Cuando se proporciona la opción --db-cluster, puede aparecer varias veces, o bien el valor puede ser una lista de lenguajes separados por coma.

Si se omite esta opción y la raíz de origen que se analiza es una extracción de un repositorio de GitHub, la CLI de CodeQL llamará a la API de GitHub para intentar determinar automáticamente los lenguajes que se van a analizar. Ten en cuenta que, para poder hacerlo, se debe proporcionar un token de acceso personal de GitHub en la variable de entorno GITHUB_TOKEN o a través de la entrada estándar con la opción --github-auth-stdin.

`--build-mode=<mode>`

Modo de compilación que se usará para crear la base de datos.

Elija el modo de compilación en función del lenguaje que está analizando:

none: la base de datos se creará sin compilar la raíz de origen. Disponible para C#, Java, JavaScript/TypeScript, Python y Ruby.

autobuild: la base de datos se creará intentando compilar automáticamente la raíz de origen. Disponible para C/C++, C#, Go, Java/Kotlin y Swift.

manual: la base de datos se creará mediante la compilación de la raíz de origen mediante un comando de compilación especificado manualmente. Disponible para C/C++, C#, Go, Java/Kotlin y Swift.

Al crear una base de datos con --command, no es necesario especificar además "--build-mode manual".

Disponible desde la versión v2.16.4.

`--[no-]allow-missing-source-root`

[Avanzado] Continúa incluso si la raíz de origen especificada no existe.

`--[no-]begin-tracing`

[Avanzado] Crea algunos scripts que se puedan usar para configurar el "seguimiento indirecto de la compilación", que permite la integración en flujos de trabajo de compilación existentes cuando no hay disponible ningún comando de compilación explícito. Para información sobre cómo y cuándo usar esta característica, consulta nuestra documentación en Preparación del código para el análisis de CodeQL.

Opciones de cálculo de línea base

`--[no-]calculate-baseline`

[Avanzado] Calcula la información de línea de base sobre el código que se está analizando y agrégala a la base de datos. De manera predeterminada, esta opción se encuentra habilitada, a menos que la raíz de origen sea la raíz de un sistema de archivos. Esta marca se puede usar para deshabilitar o forzar la habilitación del comportamiento incluso en la raíz del sistema de archivos.

`--[no-]sublanguage-file-coverage`

[GitHub.com y GitHub Enterprise Server v3.12.0 y versiones posteriores solamente] Use la información de cobertura de archivos de sublenguaje. Esto calcula, muestra y exporta información de cobertura de archivos independiente para lenguajes que comparten un extractor de CodeQL como C y C++, Java y Kotlin, y JavaScript y TypeScript.

Disponible desde la versión v2.15.2.

Opciones de selección del extractor

`--search-path=<dir>[:<dir>...]`

Lista de directorios en los que pueden encontrarse los paquetes extractores. Los directorios pueden ser los paquetes extractores en sí o directorios que contienen extractores como subdirectorios inmediatos.

Si la ruta de acceso contiene varios árboles de directorios, su orden define la prioridad entre ellos: si el lenguaje de destino tiene coincidencias en más de uno de los árboles de directorio, tiene prioridad el que aparece primero.

Los extractores agrupados con la propia cadena de herramientas CodeQL siempre se encontrarán, pero si necesita usar extractores distribuidos por separado, debe proporcionar esta opción (o mejor aún, configurar --search-path en un archivo de configuración por usuario).

(Nota: En Windows, el separador de ruta de acceso es ;).

Opciones para configurar cómo llamar a la API de GitHub para detectar lenguajes automáticamente.

`-a, --github-auth-stdin`

Acepta un token de GitHub Apps o un token de acceso personal por medio de la entrada estándar.

Esto invalida la variable de entorno GITHUB_TOKEN.

`-g, --github-url=<url>`

Dirección URL de la instancia de GitHub que se va a usar. Si se omite, la CLI intentará detectarlo automáticamente a partir de la ruta de acceso de extracción del repositorio y, si no es posible, se establece https://github.com/ como predeterminada.

Opciones para configurar el administrador de paquetes.

`--registries-auth-stdin`

Autentícate en los registros de contenedores de servidor de GitHub Enterprise; para ello, pasa una lista separada por comas de pares <registry_url>=<token>.

Por ejemplo, puedes pasar https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 para autenticarte en dos instancias del servidor de GitHub Enterprise.

Esto invalida las variables de entorno CODEQL_REGISTRIES_AUTH y GITHUB_TOKEN. Si solo necesitas autenticarte en el registro de contenedor de github.com, puedes hacerlo mediante la opción --github-auth-stdin más sencilla.

Opciones para configurar el seguimiento de Windows

`--trace-process-name=<process-name>`

[Solo Windows] Al inicializar el seguimiento, inserta el rastreador en un proceso primario de la CLI de CodeQL cuyo nombre coincide con este argumento. Si más de un proceso primario tiene este nombre, se seleccionará el más bajo del árbol de procesos. Esta opción reemplaza a --trace-process-level, por lo que si se pasan ambas, solo se usará esta opción.

`--trace-process-level=<process-level>`

[Solo Windows] Al inicializar el seguimiento, inserta el rastreador el número indicado de procesos primarios sobre el proceso actual, donde 0 corresponde al proceso que invoca a la CLI de CodeQL. El comportamiento predeterminado de la CLI si no se pasa ningún argumento consiste en realizar la inserción en el elemento primario del proceso de llamada, con algunos casos especiales para Acciones de GitHub y Azure Pipelines.

Opciones para configurar el seguimiento indirecto de la compilación

`--no-tracing`

[Avanzando] No hagas un seguimiento del comando especificado. En lugar de eso, úsalo para generar directamente todos los datos necesarios.

`--extra-tracing-config=<tracing-config.lua>`

[Avanzado] Ruta de acceso a un archivo de configuración de seguimiento. Se puede usar para modificar el comportamiento del seguimiento de compilación. Se puede usar para seleccionar los procesos del compilador que se ejecutan como parte del comando de compilación y desencadenar la ejecución de otras herramientas. Los extractores proporcionarán archivos de configuración de seguimiento predeterminados que deben funcionar en la mayoría de las situaciones.

Opciones para controlar el comportamiento del extractor: solo se aplica al entorno de seguimiento indirecto

`-O, --extractor-option=<extractor-option-name=value>`

Establece opciones para los extractores de CodeQL. extractor-option-name debe tener el formato extractor_name.group1.group2.option_name o group1.group2.option_name. Si extractor_option_name comienza con un nombre de extractor, el extractor indicado debe declarar la opción group1.group2.option_name. De lo contrario, cualquier extractor que declare la opción group1.group2.option_name tendrá la opción establecida. value puede ser cualquier cadena que no contenga una nueva línea.

Puedes usar esta opción de línea de comandos repetidamente para establecer varias opciones de extractor. Si proporcionas varios valores para la misma opción de extractor, el comportamiento depende del tipo que espera la opción de extractor. Las opciones de cadena usarán el último valor proporcionado. Las opciones de matriz usarán todos los valores proporcionados, en orden. Las opciones de extractor especificadas mediante esta opción de línea de comandos se procesan después de las opciones de extractor dadas a través de --extractor-options-file.

Cuando se pasa a codeql database init o codeql database begin-tracing, las opciones solo se aplican al entorno de seguimiento indirecto. Si el flujo de trabajo también realiza llamadas a codeql database trace-command, las opciones también deben pasarse allí si así lo quieres.

Consulta https://codeql.github.com/docs/codeql-cli/extractor-options para más información sobre las opciones de extractor de CodeQL, incluido cómo enumerar las opciones declaradas por cada extractor.

`--extractor-options-file=<extractor-options-bundle-file>`

Especifica los archivos de agrupación de opciones de extractor. Un archivo de agrupación de opciones de extractor es un archivo JSON (extensión .json) o un archivo YAML (extensión .yaml o .yml) que establece las opciones de extractor. El archivo debe tener la clave de mapa de nivel superior "extractor" y, debajo, los nombres del extractor como claves de mapa de segundo nivel. Otros niveles de mapas representan grupos de extractores anidados y las opciones de cadena y matriz son entradas de mapa con valores de cadena y matriz.

Los archivos de agrupación de opciones de extractor se leen en el orden en que se especifican. Si diferentes archivos de agrupación de opciones de extractor especifican la misma opción de extractor, el comportamiento depende del tipo que espera la opción de extractor. Las opciones de cadena usarán el último valor proporcionado. Las opciones de matriz usarán todos los valores proporcionados, en orden. Las opciones de extractor especificadas mediante esta opción de línea de comandos se procesan antes que las opciones de extractor proporcionadas a través de --extractor-option.

Opciones comunes

`-h, --help`

Muestra este texto de ayuda.

`-J=<opt>`

[Avanzado] Asigna la opción a la JVM que ejecuta el comando.

(Ten en cuenta que las opciones que contienen espacios no se administrarán correctamente).

`-v, --verbose`

Aumenta incrementalmente el número de mensajes de progreso impresos.

`-q, --quiet`

Reduce incrementalmente el número de mensajes de progreso impresos.

`--verbosity=<level>`

[Avanzado] Establece explícitamente el nivel de detalle en errores, advertencias, progreso, progreso+, progreso++, progreso+++. Invalida -v y -q.

`--logdir=<dir>`

[Avanzado] Escribe registros detallados en uno o varios archivos del directorio especificado, con nombres generados que incluyen marcas de tiempo y el nombre del subcomando en ejecución.

(Para escribir un archivo de registro con un nombre sobre el que tienes control total, proporciona --log-to-stderr y redirige stderr como quieras).

`--common-caches=<dir>`

[Avanzado] Controla la ubicación de los datos en caché del disco que se conservarán entre varias ejecuciones de la CLI, como paquetes QL descargados y planes de consulta compilada. Si no se define explícitamente, se toma como predeterminado un directorio denominado .codeql en el directorio principal del usuario, que se creará en caso de que no exista.

Disponible desde la versión v2.15.2.

¿Quién puede utilizar esta característica?

En este artículo