Opciones de extractor

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 tipo object.

En el ejemplo anterior, el extractor declara dos opciones:

• option1 es una opción de tipo string con un valor [a-z]+.
• group1.option2 es una opción de tipo array 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 option1en 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:

1. 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.
2. 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.