Synopsis

codeql bqrs interpret --format=<format> --output=<output> -t=<String=String> [--threads=<num>] [--source-archive=<sourceArchive>] [--source-location-prefix=<sourceLocationPrefix>] <options>... -- <bqrs-file>

codeql bqrs interpret --format=<format> --output=<output> -t=<String=String> [--threads=<num>] [--source-archive=<sourceArchive>] [--source-location-prefix=<sourceLocationPrefix>] <options>... -- <bqrs-file>

Description

[Plumbing] Interpret data in a single BQRS.

A command that interprets a single BQRS file according to the providedmetadata and generates output in the specified format.

Options

Primary Options

<bqrs-file>

[Mandatory] The BQRS file to interpret.

--format=<format>

[Mandatory] The format in which to write the results. One of:

csv: Formatted comma-separated values, including columns with bothrule and alert metadata.

sarif-latest: Static Analysis Results Interchange Format (SARIF), aJSON-based format for describing static analysis results. This formatoption uses the most recent supported version (v2.1.0). This option isnot suitable for use in automation as it will produce different versionsof SARIF between different CodeQL versions.

sarifv2.1.0: SARIF v2.1.0.

graphtext: A textual format representing a graph. Only compatible withqueries with @kind graph.

dgml: Directed Graph Markup Language, an XML-based format fordescribing graphs. Only compatible with queries with @kind graph.

dot: Graphviz DOT language, a text-based format for describing graphs.Only compatible with queries with @kind graph.

-o, --output=<output>

[Mandatory] The output path to write results to. For graph formatsthis should be a directory, and the result (or results if this commandsupports interpreting more than one query) will be written within thatdirectory.

-t=<String=String>

[Mandatory] A query metadata key value pair. Repeat for each piece ofmetadata. At least the keys 'kind' and 'id' must be specified. Keysdo not need to be prefixed with @.

--max-paths=<maxPaths>

The maximum number of paths to produce for each alert with paths.(Default: 4)

--[no-]sarif-add-file-contents

[SARIF formats only] Include the full file contents for all filesreferenced in at least one result.

--[no-]sarif-add-snippets

[SARIF formats only] Include code snippets for each location mentionedin the results, with two lines of context before and after the reportedlocation.

--[no-]sarif-add-query-help

[SARIF formats only] [Deprecated] Include Markdown query help forall queries. It loads query help for /path/to/query.ql from the/path/to/query.md file. If this flag is not supplied the defaultbehavior is to include help only for custom queries i.e. those in querypacks which are not of the form `codeql/<lang&rt;-queries`. Thisoption has no effect when passed tocodeql bqrs interpret.

--sarif-include-query-help=<mode>

[SARIF formats only] Specify whether to include query help in theSARIF output. One of:

always: Include query help for all queries.

custom_queries_only(default): Include query help only for customqueries i.e. those in query packs which are not of the form`codeql/<lang&rt;-queries`.

never: Do not include query help for any queries.

This option has no effect when passed tocodeql bqrs interpret.

Available sincev2.15.2.

--no-sarif-include-alert-provenance

[Advanced] [SARIF formats only] Do not include alert provenanceinformation in the SARIF output.

Available sincev2.18.1.

--[no-]sarif-group-rules-by-pack

[SARIF formats only] Place the rule object for each query under itscorresponding QL pack in the<run>.tool.extensions property. Thisoption has no effect when passed tocodeql bqrs interpret.

--[no-]sarif-multicause-markdown

[SARIF formats only] For alerts that have multiple causes, includethem as a Markdown-formatted itemized list in the output in addition toas a plain string.

--no-sarif-minify

[SARIF formats only] Produce pretty-printed SARIF output. By default,SARIF output is minified to reduce the size of the output file.

--sarif-run-property=<String=String>

[SARIF formats only] A key value pair to add to the generated SARIF'run' property bag. Can be repeated.

--no-group-results

[SARIF formats only] Produce one result per message, rather than oneresult per unique location.

--csv-location-format=<csvLocationFormat>

The format in which to produce locations in CSV output. One of: uri,line-column, offset-length. (Default: line-column)

--dot-location-url-format=<dotLocationUrlFormat>

A format string defining the format in which to produce file locationURLs in DOT output. The following place holders can be used {path}{start:line} {start:column} {end:line} {end:column}, {offset}, {length}

--[no-]sublanguage-file-coverage

[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Usesub-language file coverage information. This calculates, displays, andexports separate file coverage information for languages which share aCodeQL extractor like C and C++, Java and Kotlin, and JavaScript andTypeScript.

Available sincev2.15.2.

--sarif-category=<category>

[SARIF formats only] [Recommended] Specify a category for thisanalysis to include in the SARIF output. A category can be used todistinguish multiple analyses performed on the same commit andrepository, but on different languages or different parts of the code.

If you analyze the same version of a code base in several different ways(e.g., for different languages) and upload the results to GitHub forpresentation in Code Scanning, this value should differ between each ofthe analyses, which tells Code Scanning that the analysessupplementrather thansupersede each other. (The values should be consistentbetween runs of the same analysis fordifferent versions of the codebase.)

This value will appear (with a trailing slash appended if not alreadypresent) as the<run>.automationDetails.id property.

-j, --threads=<num>

The number of threads used for computing paths.

Defaults to 1. You can pass 0 to use one thread per core on the machine,or -N to leaveN cores unused (except still use at least onethread).

--column-kind=<columnKind>

[SARIF only] The column kind used to interpret location columns. Oneof: utf8, utf16, utf32, bytes.

--[no-]unicode-new-lines

[SARIF only] Whether the unicode newline characters LS (LineSeparator, U+2028) and PS (Paragraph Separator, U+2029) are consideredas new lines when interpreting location line numbers.

Source archive options - must be given together or not at all

-s, --source-archive=<sourceArchive>

The directory or zip file containing the source archive.

-p, --source-location-prefix=<sourceLocationPrefix>

The file path on the original file system where the source code wasstored.

Common options

-h, --help

Show this help text.

-J=<opt>

[Advanced] Give option to the JVM running the command.

(Beware that options containing spaces will not be handled correctly.)

-v, --verbose

Incrementally increase the number of progress messages printed.

-q, --quiet

Incrementally decrease the number of progress messages printed.

--verbosity=<level>

[Advanced] Explicitly set the verbosity level to one of errors,warnings, progress, progress+, progress++, progress+++. Overrides-vand-q.

--logdir=<dir>

[Advanced] Write detailed logs to one or more files in the givendirectory, with generated names that include timestamps and the name ofthe running subcommand.

(To write a log file with a name you have full control over, insteadgive--log-to-stderr and redirect stderr as desired.)

--common-caches=<dir>

[Advanced] Controls the location of cached data on disk that willpersist between several runs of the CLI, such as downloaded QL packs andcompiled query plans. If not set explicitly, this defaults to adirectory named.codeql in the user's home directory; it will becreated if it doesn't already exist.

Available sincev2.15.2.