Note: The CodeQL package management functionality, including CodeQL packs, is currently available as a beta release and is subject to change. During the beta release, CodeQL packs are available only using GitHub Packages - the Container registry. To use this beta functionality, install the latest version of the CodeQL CLI bundle from: https://github.com/github/codeql-action/releases.
Note: This article describes the features available with the CodeQL CLI 2.12.7 bundle included in the initial release of GitHub Enterprise Server 3.7.
If your site administrator has updated your CodeQL CLI version to a newer release, please see the GitHub Enterprise Cloud version of this article for information on the latest features.
CodeQL packs are used to create, share, depend on, and run CodeQL queries and libraries. You can publish your own CodeQL packs and download packs created by others. CodeQL packs contain queries, library files, query suites, and metadata.
There are two types of CodeQL packs: query packs and library packs.
Query packs contain a set of pre-compiled queries that can be evaluated on a CodeQL database. Query parks are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and a compilation cache. This ensures consistent and efficient execution of the queries in the pack.
Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled and there is no compilation cache included when the pack is published.
You can use the package management commands in the CodeQL CLI to create CodeQL packs, add dependencies to packs, and install or update dependencies. For more information, see "Creating and working with CodeQL packs." You can also publish and download CodeQL packs using the CodeQL CLI. For more information, see "Publishing and using CodeQL packs."
The standard CodeQL packages for all supported languages are published in the Container registry. The CodeQL repository contains source files for the standard CodeQL packs for all supported languages.
A CodeQL pack must contain a file called
qlpack.yml in its root directory. In the
qlpack.yml file, the
name: field must have a value that follows the format of
<scope> is the GitHub organization or user account that the pack will be published to and
<pack> is the name of the pack. Additionally, query packs and library packs with CodeQL tests contain a
codeql-pack.lock.yml file that contains the resolved dependencies of the pack. This file is generated during a call to the
codeql pack install command, is not meant to be edited by hand, and should be added to your version control system.
The other files and directories within the pack should be logically organized. For example, typically:
Queries are organized into directories for specific categories.
Queries for specific products, libraries, and frameworks are organized into their own top-level directories.
The CodeQL CLI bundle includes queries that are maintained by GitHub experts, security researchers, and community contributors. If you want to run queries developed by other organizations, CodeQL query packs provide an efficient and reliable way to download and run queries. For more information about query packs, see "About code scanning with CodeQL."
Before you can use a CodeQL query pack to analyze a database, you must download any packages you require from the GitHub Container registry. This can be done either by using the
--download flag as part of the
codeql database analyze command, or running
codeql pack download. If a package is not publicly available, you will need to use a GitHub App or personal access token to authenticate. For more information and an example, see "Uploading results to GitHub Enterprise Server".
|Specify the scope and name of one or more CodeQL query packs to download using a comma-separated list. Optionally, include the version to download and unzip. By default the latest version of this pack is downloaded. Optionally, include a path to a query, directory, or query suite to run. If no path is included, then run the default queries of this pack.|
|Pass the CLI the GitHub App or personal access token created for authentication with GitHub's REST API from your secret store via standard input. This is not needed if the command has access to a |
This example runs the
codeql database analyze command with the
--download option to:
- Download the latest version of the
- Download a version of the
octo-org/optional-security-queriespack that is compatible with version 1.0.1 (in this case, it is version 1.0.2). For more information on semver compatibility, see npm's semantic version range documentation.
- Run all the default queries in
- Run only the query
echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \ octo-org/security-queries \ octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \ --format=sarif-latest --output=/temp/example-repo-js.sarif Download location: /Users/mona/.codeql/packages Installed fresh firstname.lastname@example.org Installed fresh email@example.com Running queries. Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql. [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql. Starting evaluation of octo-org/security-queries/query1.ql. Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql. [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql. Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql. [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs. Shutting down query evaluator. Interpreting results.
If you want to download a CodeQL pack without running it immediately, then you can use the
codeql pack download command. This is useful if you want to avoid accessing the internet when running CodeQL queries. When you run the CodeQL analysis, you can specify packs, versions, and paths in the same way as in the previous example:
echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...
If your CodeQL packs reside on multiple container registries, then you must instruct the CodeQL CLI where to find each pack. For more information, see "Customizing code scanning."
Query specifiers are used by
codeql database analyze and other commands that operate on a set of queries.
The complete form of a query specifier is
scope/nameis the qualified name of a CodeQL pack.
rangeis a semver range.
pathis a file system path to a single query, a directory containing queries, or a query suite file.
When you specify a
optional. If you omit a
range then the latest version of the
specified pack is used. If you omit a
path then the default query suite
of the specified pack is used.
path can be one of: a
.ql query file, a directory
containing one or more queries, or a
.qls query suite file. If
you omit a pack name, then you must provide a
which will be interpreted relative to the working directory
of the current process. Glob patterns are not supported.
If you specify both a
path, then the
be absolute. It is considered relative to the root of the CodeQL
codeql/python-queries- All the queries in the default query suite of the latest version of the
firstname.lastname@example.org- All the queries in the default query suite of version
codeql/python-queries@~1.2.3- All the queries in the default query suite of the latest version of the
codeql/python-queriespack that is >=
codeql/python-queries:Functions- All queries in the
Functionsdirectory in the latest version of the
email@example.com:Functions- All queries in the
Functionsdirectory in version 1.2.3 of the
firstname.lastname@example.org:codeql-suites/python-code-scanning.qls- All queries in the
codeql-suites/python-code-scanning.qlsdirectory in version 1.2.3 of the
suites/my-suite.qls- All queries in the
suites/my-suite.qlsfile relative to the current working directory.
The default query suite of the standard CodeQL query packs are
codeql-suites/<lang>-code-scanning.qls. Several other useful query suites can also be found in the
codeql-suites directory of each pack. For example, the
codeql/cpp-queries pack contains the following query suites:
cpp-code-scanning.qls- Standard Code Scanning queries for C++. The default query suite for this pack.
cpp-security-extended.qls- Queries from the default
cpp-code-scanning.qlssuite for C++, plus lower severity and precision queries.
cpp-security-and-quality.qls- Queries from
cpp-security-extended.qls, plus maintainability and reliability queries.
You can see the sources for these query suites in the CodeQL repository. Query suites for other languages are similar.