Options d’extracteur

À propos des extracteurs

CodeQL CLI utilise des programmes spéciaux, appelés extracteurs, pour extraire des informations du code source d’un système logiciel dans une base de données pouvant être interrogée. Vous pouvez personnaliser le comportement des extracteurs en définissant les options de configuration d’extracteur via CodeQL CLI.

À propos des options d’extracteur

Chaque extracteur définit son propre ensemble d’options de configuration. Pour savoir quelles options sont disponibles pour un extracteur en particulier, vous pouvez exécuter codeql resolve languages ou codeql resolve extractor avec l’option --format=betterjson. Le format de sortie betterjson fournit les chemins racines des extracteurs et d’autres informations. La sortie de codeql resolve extractor --format=betterjson est souvent mise en forme comme dans l’exemple suivant :

{
    "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]*"
                }
            }
        }
    }
}

Les noms et descriptions des options d’extracteur sont listés sous extractor_options. Chaque option peut contenir les champs suivants :

• title (obligatoire) : titre de l’option
• description (obligatoire) : description de l’option
• type (obligatoire) : type de l’option, qui peut être
  • string : indiquant que l’option peut avoir une seule valeur de chaîne
  • array : indiquant que l’option peut avoir une séquence de valeurs de chaîne
  • object : indiquant qu’il ne s’agit pas d’une option en soi, mais d’un regroupement qui peut contenir d’autres options et groupes d’options
• pattern (facultatif) : modèles d’expression régulière auxquels toutes les valeurs de l’option doivent correspondre. Notez que l’extracteur peut imposer des contraintes supplémentaires aux valeurs d’option qui ne sont pas ou ne peuvent pas être exprimées dans ce modèle d’expression régulière. Ces contraintes, si elles existent, sont expliquées sous le champ de description.
• properties (facultatif) : mappage des noms des options d’extracteur dans le groupe d’options aux descriptions des options d’extracteur correspondantes. Ce champ ne peut être présent que pour les groupes d’options. Par exemple, les options de type object.

Dans l’exemple ci-dessus, l’extracteur déclare deux options :

• option1 est une option string avec une valeur correspondant à [a-z]+
• group1.option2 est une option array avec des valeurs correspondant à [1-9][0-9]\*

Définition des options d’extracteur avec CodeQL CLI

CodeQL CLI prend en charge la définition des options d’extracteur dans les sous-commandes qui appellent directement ou indirectement des extracteurs. Ces commandes sont :

• codeql database create
• codeql database start-tracing
• codeql database trace-command
• codeql database index-files

Lorsque vous exécutez ces sous-commandes, vous pouvez définir les options d’extracteur avec l’option CLI --extractor-option. Par exemple :

• codeql database create --extractor-option java.option1=abc ...
• codeql database start-tracing --extractor-option java.group1.option2=102 ...

--extractor-option nécessite exactement un argument de la forme extractor_option_name=extractor_option_value. extractor_option_name est le nom de l’extracteur (dans cet exemple, java) suivi d’un point, puis du nom de l’option d’extracteur (dans cet exemple, option1 ou group1.option2). extractor_option_value est la valeur affectée à l’option d’extracteur. La valeur doit correspondre au modèle d’expression régulière de l’option d’extracteur (si elle existe), et elle ne doit pas contenir de caractères de nouvelle ligne.

L’utilisation de --extractor-option pour affecter une option d’extracteur qui n’existe pas est une erreur.

CodeQL CLI accepte plusieurs options --extractor-option dans le même appel. Si vous définissez une option d’extracteur string plusieurs fois, la dernière valeur d’option remplace toutes les précédentes. Si vous définissez une option d’extracteur array plusieurs fois, toutes les valeurs d’option sont concaténées dans l’ordre.

Vous pouvez également spécifier des noms d’options d’extracteur sans le nom de l’extracteur. Par exemple :

• codeql database create --extractor-option option1=abc ...
• codeql database start-tracing --extractor-option group1.option2=102 ...

Si vous ne spécifiez pas de nom d’extracteur, les paramètres de l’option d’extracteur s’appliquent à tous les extracteurs qui déclarent une option portant le nom donné. Dans l’exemple ci-dessus, la première commande définit l’option d’extracteur option1 sur abc pour l’extracteur java et chaque extracteur qui a l’option option1, par exemple l’extracteur cpp, si l’option d’extracteur option1 existe pour cet extracteur.

Définition des options d’extracteur à partir de fichiers

Vous pouvez également définir des options d’extracteur via un fichier. Les sous-commandes CodeQL CLI qui acceptent --extractor-option acceptent aussi --extractor-options-file, qui a un argument obligatoire du chemin d’un fichier YAML (avec l’extension .yaml ou .yml) ou un fichier JSON (avec l’extension .json). Par exemple :

• codeql database create --extractor-options-file options.yml ...
• codeql database start-tracing --extractor-options-file options.json ...

Chaque fichier d’options contient une arborescence de mappages imbriqués. À la racine se trouve une clé de mappage d’extracteur, et dessous, se trouvent les clés de mappage qui correspondent aux noms d’extracteur. À partir du troisième niveau, se trouvent les options d’extracteur et les groupes d’options.

Dans JSON :

{
     "extractor" : {
        "java": {
            "option1" : "abc",
            "group1" : {
                "option2" : [ 102 ]
            }
        }
    }
}

Dans YAML :

extractor:
    java:
        option1: "abc"
        group1:
            option2: [ 102 ]

La valeur d’une option d’extracteur string doit être une chaîne ou un nombre (qui sera converti en chaîne avant de poursuivre le traitement).

La valeur d’une option d’extracteur array doit être un tableau de chaînes ou de nombres.

La valeur d’un groupe d’options (de type object) doit être un mappage, qui peut contenir des options d’extracteur et des groupes d’options imbriqués.

Chaque valeur d’option d’extracteur doit correspondre au modèle d’expression régulière de l’option d’extracteur (si elle existe), et elle ne doit pas contenir de caractères de nouvelle ligne.

L’affectation d’une option d’extracteur qui n’existe pas est une erreur. Vous pouvez faire en sorte que CodeQL CLI ignore les options d’extracteur inconnues en utilisant un champ booléen __allow_unknown_properties spécial. Par exemple, le fichier d’options suivant demande à CodeQL CLI d’ignorer toutes les options d’extracteur et groupes d’options inconnus sous group1 :

extractor:
    java:
        option1: "abc"
        group1:
            __allow_unknown_properties: true
            option2: [ 102 ]

Vous pouvez spécifier --extractor-options-file plusieurs fois. Les affectations d’options d’extracteur sont traitées dans l’ordre suivant :

1. Tous les fichiers d’options d’extracteur spécifiés par --extractor-options-file sont traités dans l’ordre dans lequel ils apparaissent sur la ligne de commande, puis
2. Toutes les affectations d’options d’extracteur spécifiées par --extractor-option sont traitées dans l’ordre dans lequel elles apparaissent sur la ligne de commande.

Les mêmes règles régissent ce qui se produit lorsque la même option d’extracteur est définie plusieurs fois, que les affectations soient effectuées avec --extractor-option, avec --extractor-options-file ou une combinaison des deux. Si vous définissez une option d’extracteur string plusieurs fois, la dernière valeur d’option remplace toutes les valeurs précédentes. Si vous définissez une option d’extracteur array plusieurs fois, toutes les valeurs d’option sont concaténées dans l’ordre.