Extraktoroptionen

Du kannst die CodeQL CLI verwenden, um CodeQL-Prozesse lokal in Softwareprojekten auszuführen.

Wer kann dieses Feature verwenden?

CodeQL ist für die folgenden Repositorytypen verfügbar:

In diesem Artikel

Informationen zu Extraktoren

Die CodeQL CLI verwendet spezielle Programme (sogenannte Extraktoren) zum Extrahieren von Informationen aus dem Quellcode eines Softwaresystems in eine Datenbank, die abgefragt werden kann. Du kannst das Verhalten von Extraktoren anpassen, indem du die Extraktorkonfigurationsoptionen über die CodeQL CLI festlegst.

Informationen zu Extraktoroptionen

Jeder Extraktor definiert einen eigenen Satz von Konfigurationsoptionen. Um herauszufinden, welche Optionen für einen bestimmten Extraktor verfügbar sind, kannst du codeql resolve languages oder codeql resolve extractor mit der --format=betterjson-Option ausführen. Das betterjson-Ausgabeformat stellt die Stammpfade von Extraktoren sowie zusätzliche Informationen bereit. Die Ausgabe von codeql resolve extractor --format=betterjson wird häufig wie im folgenden Beispiel formatiert:

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

Die Namen und Beschreibungen der Extraktoroptionen sind unter extractor_options aufgeführt. Jede Option kann die folgenden Felder enthalten:

  • title (erforderlich): Titel der Option
  • description (erforderlich): Beschreibung der Option
  • type (erforderlich): Typ der Option, der wie folgt lauten kann:
    • string: Gibt an, dass die Option einen einzelnen Zeichenfolgenwert aufweisen kann
    • array: Gibt an, dass die Option eine Sequenz von Zeichenfolgenwerten aufweisen kann
    • object: Gibt an, dass es sich nicht um eine Option selbst handelt, sondern um eine Gruppierung, die andere Optionen und Optionsgruppen enthalten kann
  • pattern (optional): Muster für reguläre Ausdrücke, mit denen alle Werte der Option übereinstimmen sollen. Beachte, dass der Extraktor zusätzliche Einschränkungen für Optionswerte erzwingen kann, die nicht in diesem Muster für reguläre Ausdrücke vorliegen oder ausgedrückt werden können. Solche Einschränkungen werden (sofern vorhanden) im Beschreibungsfeld beschrieben.
  • properties (optional): Zuordnung von Extraktoroptionsnamen in der Optionsgruppe zu den entsprechenden Extraktoroptionsbeschreibungen. Dieses Feld kann nur für Optionsgruppen vorhanden sein. Beispiel: Optionen vom object-Typ.

Im obigen Beispiel deklariert der Extraktor zwei Optionen:

  • option1 ist eine string-Option mit einem Wert, der mit [a-z]+ übereinstimmt.
  • group1.option2 ist eine array-Option mit Werten, die mit [1-9][0-9]\* übereinstimmen.

Festlegen von Extraktoroptionen mit der CodeQL CLI

Die CodeQL CLI unterstützt das Festlegen von Extraktoroptionen in Unterbefehlen, die direkt oder indirekt Extraktoren aufrufen. Diese Befehle lauten wie folgt:

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

Wenn du diese Unterbefehle ausführst, kannst du Extraktoroptionen mit der CLI-Option --extractor-option festlegen. Zum Beispiel:

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

--extractor-option erfordert genau ein Argument in der Form extractor_option_name=extractor_option_value. extractor_option_name ist der Name des Extraktors (in diesem Beispiel java), gefolgt von einem Punkt und dem Namen der Extraktoroption (in diesem Beispiel entweder option1 oder group1.option2). extractor_option_value ist der Wert, der der Extraktoroption zugewiesen wird. Der Wert muss dem Muster des regulären Ausdrucks der Extraktoroption (sofern vorhanden) entsprechen und darf keine Zeilenvorschubzeichen enthalten.

Die Verwendung von --extractor-option zum Zuweisen einer nicht vorhandenen Extraktoroption ist ein Fehler.

Die CodeQL CLI akzeptiert mehrere --extractor-option-Optionen im gleichen Aufruf. Wenn du eine string-Extraktoroption mehrmals festlegst, überschreibt der letzte Optionswert alle vorherigen Werte. Wenn du eine Arrayextraktoroption mehrmals festlegst, werden alle Optionswerte in der Reihenfolge verkettet.

Du kannst auch Extraktoroptionsnamen ohne den Extraktornamen angeben. Zum Beispiel:

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

Wenn du keinen Extraktornamen angibst, gelten die Extraktoroptionseinstellungen für alle Extraktoren, die eine Option mit dem angegebenen Namen deklarieren. Im obigen Beispiel würde der erste Befehl die Extraktoroption option1 für den Extraktor java und jeden Extraktor mit einer Option von option1 auf abc festlegen (z. B. der Extraktor cpp, wenn die Extraktoroption option1 für diesen Extraktor vorhanden ist).

Festlegen von Extraktoroptionen über Dateien

Du kannst auch Extraktoroptionen über eine Datei festlegen. Die CodeQL CLI-Unterbefehle, die --extractor-option akzeptieren, akzeptieren auch --extractor-options-file mit einem erforderlichen Argument des Pfads zu einer YAML-Datei (mit der Erweiterung .yaml oder .yml) oder einer JSON-Datei (mit der Erweiterung .json). Zum Beispiel:

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

Jede Optionsdatei enthält eine Baumstruktur geschachtelter Zuordnungen. Im Stamm befindet sich ein Extraktorzuordnungsschlüssel, und darunter befinden sich Zuordnungsschlüssel, die den Extraktornamen entsprechen. Ab der dritten Ebene gibt es Extraktoroptionen und Optionsgruppen.

In JSON:

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

In YAML:

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

Der Wert für eine string-Extraktoroption muss eine Zeichenfolge oder eine Zahl sein (die vor der weiteren Verarbeitung in eine Zeichenfolge konvertiert wird).

Der Wert für eine array-Extraktoroption muss ein Array von Zeichenfolgen oder Zahlen sein.

Der Wert für eine Optionsgruppe (vom Typ object) muss eine Zuordnung sein, die möglicherweise geschachtelte Extraktoroptionen und Optionsgruppen enthalten kann.

Der Extraktoroptionswert muss dem Muster des regulären Ausdrucks der Extraktoroption (sofern vorhanden) entsprechen und darf keine Zeilenvorschubzeichen enthalten.

Das Zuweisen einer nicht vorhandenen Extraktoroption ist ein Fehler. Mithilfe des speziellen Booleschen Felds __allow_unknown_properties kannst du festlegen, dass die CodeQL CLI unbekannte Extraktoroptionen ignorieren soll. In der folgenden Optionsdatei wird die CodeQL CLI beispielsweise aufgefordert, alle unbekannten Extraktoroptionen und Optionsgruppen unter group1 zu ignorieren:

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

Du kannst --extractor-options-file mehrmals angeben. Die Extraktoroptionszuweisungen werden in der folgenden Reihenfolge verarbeitet:

  1. Alle durch --extractor-options-file angegebenen Extraktoroptionsdateien werden in der Reihenfolge verarbeitet, in der sie in der Befehlszeile angezeigt werden.
  2. Anschließend werden alle durch --extractor-option angegebenen Extraktoroptionszuweisungen in der Reihenfolge verarbeitet, in der sie in der Befehlszeile angezeigt werden.

Die gleichen Regeln geben vor, was geschieht, wenn dieselbe Extraktoroption mehrmals festgelegt wird, unabhängig davon, ob die Zuweisungen mit --extractor-option, --extractor-options-file oder einer Kombination der beiden Optionen ausgeführt werden. Wenn du eine string-Extraktoroption mehrmals festlegst, überschreibt der letzte Optionswert alle vorherigen Werte. Wenn du eine array-Extraktoroption mehrmals festlegst, werden alle Optionswerte in der Reihenfolge verkettet.