Acerca de los extractores
CodeQL CLI usa programas especiales, denominados extractores, para extraer información del código fuente de un sistema de software a una base de datos que se puede consultar. Puedes personalizar el comportamiento de los extractores estableciendo las opciones de configuración de extractor mediante la CodeQL CLI.
Acerca de las opciones de extractor
Cada extractor define su propio conjunto de opciones de configuración. Para averiguar qué opciones están disponibles para un extractor determinado, puedes ejecutar codeql resolve languages
o codeql resolve extractor
con la opción --format=betterjson
. El formato de salida betterjson
proporciona las rutas de acceso raíz de los extractores e información adicional. A menudo, la salida de codeql resolve extractor --format=betterjson
tendrá un formato similar al ejemplo siguiente:
{
"extractor_root" : "/home/user/codeql/java",
"extractor_options" : {
"option1" : {
"title" : "Java extractor option 1",
"description" : "An example string option for the Java extractor.",
"type" : "string",
"pattern" : "[a-z]+"
},
"group1" : {
"title" : "Java extractor group 1",
"description" : "An example option group for the Java extractor.",
"type" : "object",
"properties" : {
"option2" : {
"title" : "Java extractor option 2",
"description" : "An example array option for the Java extractor",
"type" : "array",
"pattern" : "[1-9][0-9]*"
}
}
}
}
}
Los nombres y las descripciones de las opciones de extractor se enumeran en extractor_options
. Cada opción puede contener los siguientes campos:
title
(obligatorio): el título de la opción.description
(obligatorio): la descripción de la opción.type
(obligatorio): el tipo de opción, que puede ser:string
: indica que la opción puede tener un único valor de cadena.array
: indica que la opción puede tener una secuencia de valores de cadena.object
: indica que no es una opción en sí, sino una agrupación que puede contener otras opciones y grupos de opciones.
pattern
(opcional): los patrones de expresión regular con los que deben coincidir todos los valores de la opción. Ten en cuenta que el extractor puede imponer restricciones adicionales en los valores de opción que no están expresadas o no se pueden expresar en este patrón de expresión regular. Estas restricciones, si existen, se explican en el campo de descripción.properties
(opcional): una asignación de los nombres de las opciones de extractor en el grupo de opciones con sus correspondientes descripciones de las opciones de extractor. Este campo solo puede estar presente para los grupos de opciones. Por ejemplo, para opciones de tipoobject
.
En el ejemplo anterior, el extractor declara dos opciones:
option1
es una opción de tipostring
con un valor[a-z]+
.group1.option2
es una opción de tipoarray
con los valores[1-9][0-9]\*
.
Definición de las opciones de extractor con la CodeQL CLI
La CodeQL CLI admite la configuración de opciones de extractor en subcomandos que invocan extractores directa o indirectamente. Estos comandos son los siguientes:
codeql database create
codeql database start-tracing
codeql database trace-command
codeql database index-files
Al ejecutar estos subcomandos, puedes establecer las opciones de extractor con la opción --extractor-option
de la CLI. Por ejemplo:
codeql database create --extractor-option java.option1=abc ...
codeql database start-tracing --extractor-option java.group1.option2=102 ...
--extractor-option
requiere exactamente un argumento con el formato extractor_option_name=extractor_option_value
. extractor_option_name
es el nombre del extractor (en este ejemplo, java
) seguido de un punto y del nombre de la opción de extractor (en este ejemplo, option1
o group1.option2
). extractor_option_value
es el valor que se asigna a la opción de extractor. Este valor debe coincidir con el patrón de expresión regular de la opción de extractor (si existe) y no debe contener caracteres de nueva línea.
El uso de --extractor-option
para asignar una opción de extractor que no existe provoca un error.
La CodeQL CLI acepta varias opciones --extractor-option
en la misma invocación. Si estableces una opción de extractor string
varias veces, el último valor de la opción sobrescribe todos los anteriores. Si estableces una opción de extractor array varias veces, todos los valores de la opción se concatenan en orden.
También puedes especificar nombres de opción de extractor sin el nombre del extractor. Por ejemplo:
codeql database create --extractor-option option1=abc ...
codeql database start-tracing --extractor-option group1.option2=102 ...
Si no especificas un nombre de extractor, la configuración de la opción de extractor se aplicará a todos los extractores que declaren una opción con el nombre indicado. En el ejemplo anterior, el primer comando establecería la opción de extractor option1
en abc
para el extractor java
y también para cada extractor que tenga una opción option1
, por ejemplo, el extractor cpp
, si la opción de extractor option1
existe para ese extractor.
Configuración de opciones de extractor desde archivos
También puedes definir las opciones de extractor mediante un archivo. Los subcomandos de la CodeQL CLI que aceptan --extractor-option
también aceptan --extractor-options-file
, que requiere un argumento de la ruta de acceso a un archivo YAML (con la extensión .yaml
o .yml
) o a un archivo JSON (con la extensión .json
). Por ejemplo:
codeql database create --extractor-options-file options.yml ...
codeql database start-tracing --extractor-options-file options.json ...
Cada archivo de opciones contiene una estructura de árbol de asignaciones anidadas. En la raíz hay una clave de asignación de extractores y, debajo de esta, hay claves de asignación que corresponden a los nombres de extractor. A partir del tercer nivel, están las opciones de extractor y los grupos de opciones.
En JSON:
{
"extractor" : {
"java": {
"option1" : "abc",
"group1" : {
"option2" : [ 102 ]
}
}
}
}
En YAML:
extractor:
java:
option1: "abc"
group1:
option2: [ 102 ]
El valor de una opción de extractor string
debe ser una cadena o un número (que se convertirá en una cadena antes de continuar con el procesamiento).
El valor de una opción de extractor array
debe ser una matriz de cadenas o números.
El valor de un grupo de opciones (de tipo object
) debe ser una asignación, que puede contener opciones de extractor anidadas y grupos de opciones.
El valor de la opción de extractor debe coincidir con el patrón de expresión regular de la opción de extractor (si existe) y no debe contener caracteres de nueva línea.
Asignar una opción de extractor que no existe provoca un error. Puedes hacer que la CodeQL CLI omita las opciones de extractor desconocidas usando un campo booleano __allow_unknown_properties
especial. Por ejemplo, el siguiente archivo de opciones pide a la CodeQL CLI que omita todas las opciones y los grupos de opciones de extractor desconocidos en group1
:
extractor:
java:
option1: "abc"
group1:
__allow_unknown_properties: true
option2: [ 102 ]
Puedes especificar la opción --extractor-options-file
varias veces. Las asignaciones de opciones de extractor se procesan en el siguiente orden:
- Todos los archivos de opciones de extractor especificados mediante
--extractor-options-file
se procesan en el orden en que aparecen en la línea de comandos. - Todas las asignaciones de opciones de extractor especificadas mediante
--extractor-option
se procesan en el orden en que aparecen en la línea de comandos.
Las mismas reglas rigen lo que sucede cuando se establece la misma opción de extractor varias veces, independientemente de si las asignaciones se realizan mediante --extractor-option
, mediante --extractor-options-file
o con una combinación de ambas opciones. Si estableces una opción de extractor string
varias veces, el último valor de la opción sobrescribe todos los valores anteriores. Si estableces una opción de extractor array
varias veces, todos los valores de la opción se concatenan en orden.