Synopsis

codeql database interpret-results --format=<format> --output=<output> [--threads=<num>] <options>... -- <database> <file|dir|suite>...

codeql database interpret-results --format=<format> --output=<output> [--threads=<num>] <options>... -- <database> <file|dir|suite>...

Description

[Plumbing] Interpret computed query results into meaningful formatssuch as SARIF or CSV.

The results should have been computed and stored in a CodeQL databasedirectory usingcodeql database run-queries. (Usually you'd want to do these steps together, by usingcodeql database analyze).

Options

Primary Options

<database>

[Mandatory] Path to the CodeQL database that has been queried.

<file|dir|suite>...

Repeat the specification of which queries were executed here.

If omitted, the CLI will determine a suitable set of queries using thesame logic ascodeql database run-queries.

(In a future version it ought to be possible to omit this and insteadinterpret all results that are found in the database. That gloriousfuture is not yet. Sorry.)

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

--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).

--no-database-extension-packs

[Advanced] Omit extension packs stored in the database during databasecreation, either from a Code Scanning configuration file or fromextension files stored in the 'extensions' directory of the analyzedcodebase.

--[no-]print-diagnostics-summary

Print a summary of the analyzed diagnostics to standard output.

--[no-]print-metrics-summary

Print a summary of the analyzed metrics to standard output.

--[no-]print-baseline-loc

Print the baseline lines of code counted to standard output.

Options for configuring the CodeQL package manager

--registries-auth-stdin

Authenticate to GitHub Enterprise Server Container registries by passinga comma-separated list of <registry_url>=<token> pairs.

For example, you can passhttps://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2to authenticate to two GitHub Enterprise Server instances.

This overrides the CODEQL_REGISTRIES_AUTH and GITHUB_TOKEN environmentvariables. If you only need to authenticate to the github.com Containerregistry, you can instead authenticate using the simpler--github-auth-stdin option.

--github-auth-stdin

Authenticate to the github.com Container registry by passing agithub.com GitHub Apps token or personal access token via standardinput.

To authenticate to GitHub Enterprise Server Container registries, pass--registries-auth-stdin or use the CODEQL_REGISTRIES_AUTH environmentvariable.

This overrides the GITHUB_TOKEN environment variable.

Options to specify which extensions to use when interpreting the results

--model-packs=<name@range>...

A list of CodeQL pack names, each with an optional version range, to beused as model packs to customize the queries that are about to beevaluated.

Options for finding QL packs (which may be necessary to interpret query suites)

--search-path=<dir>[:<dir>...]

A list of directories under which QL packs may be found. Each directorycan either be a QL pack (or bundle of packs containing a.codeqlmanifest.json file at the root) or the immediate parent of oneor more such directories.

If the path contains more than one directory, their order definesprecedence between them: when a pack name that must be resolved ismatched in more than one of the directory trees, the one given firstwins.

Pointing this at a checkout of the open-source CodeQL repository oughtto work when querying one of the languages that live there.

If you have checked out the CodeQL repository as a sibling of theunpacked CodeQL toolchain, you don't need to give this option; suchsibling directories will always be searched for QL packs that cannot befound otherwise. (If this default does not work, it is stronglyrecommended to set up--search-path once and for all in a per-userconfiguration file).

(Note: On Windows the path separator is;).

--additional-packs=<dir>[:<dir>...]

If this list of directories is given, they will be searched for packsbefore the ones in--search-path. The order between these doesn'tmatter; it is an error if a pack name is found in two different placesthrough this list.

This is useful if you're temporarily developing a new version of a packthat also appears in the default path. On the other hand, it isnotrecommended to override this option in a config file; some internalactions will add this option on the fly, overriding any configuredvalue.

(Note: On Windows the path separator is;).

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.