Opções do extrator

Sobre os extratores

O CodeQL CLI usa programas especiais, chamados de extratores, para extrair informações do código-fonte de um sistema de software em um banco de dados que pode ser consultado. Você pode personalizar o comportamento dos extratores definindo as opções de configuração do extrator por meio da CodeQL CLI.

Sobre as opções do extrator

Cada extrator define seu próprio conjunto de opções de configuração. Para descobrir quais opções estão disponíveis para um extrator específico, você pode executar codeql resolve languages ou codeql resolve extractor com a opção --format=betterjson. O formato de saída betterjson fornece os caminhos raiz dos extratores e informações adicionais. A saída de codeql resolve extractor --format=betterjson geralmente será formatada como o seguinte exemplo:

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

Os nomes e as descrições das opções do extrator estão listados em extractor_options. Cada opção pode conter os seguintes campos:

• title (obrigatório): o título da opção
• description (obrigatório): a descrição da opção
• type (obrigatório): o tipo da opção, que pode ser
  • string: indicando que a opção pode ter um só valor de cadeia de caracteres
  • array: indicando que a opção pode ter uma sequência de valores de cadeia de caracteres
  • object: indicando que não é uma opção em si, mas um agrupamento que pode conter outras opções e grupos de opções
• pattern (opcional): os padrões de expressão regular aos quais todos os valores da opção devem corresponder. Observe que o extrator pode impor restrições adicionais aos valores de opção que não são ou não podem ser expressos nesse padrão de expressão regular. Essas restrições, se existirem, serão explicadas no campo de descrição.
• properties (opcional): um mapa dos nomes de opção do extrator no grupo de opções para as descrições da opção do extrator correspondentes. Esse campo só pode estar presente para grupos de opções. Por exemplo, opções do tipo object.

No exemplo acima, o extrator declara duas opções:

• option1 é uma opção string com valor correspondente a [a-z]+
• group1.option2 é uma opção array com valores correspondentes a [1-9][0-9]\*

Como definir as opções do extrator com a CodeQL CLI

A CodeQL CLI dá suporte à configuração de opções do extrator em subcomandos que invocam extratores direta ou indiretamente. Estes comandos são:

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

Ao executar esses subcomandos, você pode definir as opções do extrator com a opção da CLI --extractor-option. Por exemplo:

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

--extractor-option requer exatamente um argumento no formato extractor_option_name=extractor_option_value. extractor_option_name é o nome do extrator (neste exemplo, java) seguido por um ponto e depois o nome da opção extrator (neste exemplo, option1 ou group1.option2). extractor_option_value é o valor que está sendo atribuído à opção do extrator. O valor precisa corresponder ao padrão de expressão regular da opção do extrator (se existir) e não pode conter caracteres de nova linha.

O uso de --extractor-option para atribuir uma opção do extrator que não existe é um erro.

A CodeQL CLI aceita várias opções --extractor-option na mesma invocação. Se você definir uma opção stringdo extrator várias vezes, o último valor da opção substituirá todos os anteriores. Se você definir uma opção do extrator de matriz várias vezes, todos os valores da opção serão concatenados na ordem.

Você também pode especificar nomes de opção do extrator sem o nome do extrator. Por exemplo:

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

Se você não especificar um nome de extrator, as configurações de opção do extrator serão aplicadas a todos os extratores que declaram uma opção com o nome fornecido. No exemplo acima, o primeiro comando define a opção option1 do extrator como abc para o extrator java e para cada extrator que tem uma opção option1, por exemplo, o extrator cpp, caso a opção option1 do extrator exista para esse extrator.

Como definir opções do extrator por meio de arquivos

Você também pode definir opções do extrator por meio de um arquivo. Os subcomandos da CodeQL CLI que aceitam --extractor-option também aceitam --extractor-options-file, que tem um argumento necessário do caminho para um arquivo YAML (com a extensão .yaml ou .yml) ou um arquivo JSON (com a extensão .json). Por exemplo:

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

Cada arquivo de opção contém uma estrutura de árvore de mapas aninhados. Na raiz, há uma chave de mapa do extrator e, abaixo dela, estão as chaves de mapa que correspondem aos nomes do extrator. A partir do terceiro nível, há opções e grupos de opções do extrator.

Em JSON:

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

No YAML:

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

O valor de uma opção string do extrator precisa ser uma cadeia de caracteres ou um número (que será convertido em uma cadeia de caracteres antes que o processamento continue).

O valor de uma opção array do extrator precisa ser uma matriz de cadeias de caracteres ou números.

O valor de um grupo de opções (do tipo object) precisa ser um mapa, que pode conter opções e grupos de opções aninhados do extrator.

Cada valor de opção do extrator precisa corresponder ao padrão de expressão regular da opção do extrator (caso exista) e não pode conter caracteres de nova linha.

A atribuição de uma opção do extrator que não existe é um erro. Você pode fazer com que a CodeQL CLI ignore as opções do extrator desconhecidas usando o campo booliano especial __allow_unknown_properties. Por exemplo, o seguinte arquivo de opção solicita que a CodeQL CLI ignore todas as opções e os grupos de opções do extrator desconhecidos em group1:

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

Você pode especificar --extractor-options-file várias vezes. As atribuições de opção do extrator são processadas na seguinte ordem:

1. Todos os arquivos de opção do extrator especificados por --extractor-options-file são processados na ordem em que aparecem na linha de comando, depois
2. Todas as atribuições de opção do extrator especificadas por --extractor-option são processadas na ordem em que aparecem na linha de comando

As mesmas regras regem o que acontece quando a mesma opção do extrator é definida várias vezes, sejam as atribuições feitas usando --extractor-option, --extractor-options-fileou alguma combinação das duas opções. Se você definir uma opção string do extrator várias vezes, o último valor da opção substituirá todos os valores anteriores. Se você definir uma opção array do extrator várias vezes, todos os valores da opção serão concatenados na ordem.