You can use the CodeQL CLI to run CodeQL processes locally on software projects or to generate code scanning results for upload to GitHub.
Software developers and security researchers can secure their code
using CodeQL analysis. For more information about CodeQL, see Code scanning with CodeQL.
The CodeQL CLI is a standalone, command-line tool that you can use to analyze code. Its main purpose is to generate a database representation of a codebase, a CodeQL database. Once the database is ready, you can query it interactively, or run a suite of queries to generate a set of results in SARIF format and upload the results to GitHub.
You can use the CodeQL CLI to:
The CodeQL CLI can analyze:
You can use the CodeQL CLI to run code scanning on code that you're processing in a third-party continuous integration (CI) system. Code scanning is a feature that you use to analyze the code in a GitHub repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are shown in your repository. For an overview of using code scanning with external CI systems, see Using code scanning with your existing CI system. For recommended specifications (RAM, CPU cores, and disk) for running CodeQL analysis, see Recommended hardware resources for running CodeQL.
Alternatively, you can use GitHub Actions or Azure DevOps pipelines to scan code using the CodeQL CLI. For more information, see Configuring default setup for code scanning or Configure GitHub Advanced Security for Azure DevOps in Microsoft Learn.
For an overview of all the options for using CodeQL analysis for code scanning, see Code scanning with CodeQL.
Note
If you choose to run the CodeQL CLI directly, you first have to install the CodeQL CLI locally. If you are planning to use the CodeQL CLI with an external CI system, you need to make the CodeQL CLI available to servers in your CI system.
Once the CodeQL CLI is set up, you can use three different commands to generate results and upload them to GitHub:
database create to create a CodeQL database to represent the hierarchical structure of each supported programming language in the repository. For more information, see Preparing your code for CodeQL analysis.database analyze to run queries to analyze each CodeQL database and summarize the results in a SARIF file. For more information, see Analyzing your code with CodeQL queries.github upload-results to upload the resulting SARIF files to GitHub where the results are matched to a branch or pull request and displayed as code scanning alerts. For more information, see Uploading CodeQL analysis results to GitHub.Note
Uploading SARIF data to display as code scanning results in GitHub is supported for organization-owned repositories with GitHub Code Security enabled, and public repositories on GitHub.com. For more information, see Managing security and analysis settings for your repository.
This is an example of the full series of commands for the CodeQL CLI that you might use to analyze a codebase with two supported languages and then upload the results to GitHub.
# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'
codeql database create codeql-dbs --source-root=src \
--db-cluster --language=java,python --command=./myBuildScript
# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'
codeql database analyze codeql-dbs/java java-code-scanning.qls \
--format=sarif-latest --sarif-category=java --output=java-results.sarif
# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'
codeql database analyze codeql-dbs/python python-code-scanning.qls \
--format=sarif-latest --sarif-category=python --output=python-results.sarif
# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.
codeql github upload-results \
--repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=java-results.sarif
# Upload the SARIF file with the Python results: 'python-results.sarif'
codeql github upload-results \
--repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=python-results.sarif
The CodeQL CLI uses special programs, called extractors, to extract information from the source code of a software system into a database that can be queried. You can customize the behavior of extractors by setting extractor configuration options through the CodeQL CLI. See Extractor options.
License notice: If you don’t have a license for GitHub Code Security then, by installing this product, you are agreeing to the GitHub CodeQL Terms and Conditions.
For information about how you can try GitHub Enterprise with GitHub Advanced Security for free, see Setting up a trial of GitHub Enterprise Cloud and Setting up a trial of GitHub Advanced Security in the GitHub Enterprise Cloud documentation.
The CodeQL CLI database bundle command can be used to create a relocatable archive of a CodeQL database.
A copy of a database bundle can be used to share troubleshooting information with your team members or with GitHub Support. See Creating CodeQL CLI database bundles.
For the simplest way to get started, see Setting up the CodeQL CLI.
More advanced setup options are available if you need them. For example, if you: