Skip to content

about-the-codeql-cli.md

Latest commit

 

History

History
130 lines (92 loc) · 11 KB

about-the-codeql-cli.md

File metadata and controls

130 lines (92 loc) · 11 KB
title About the CodeQL CLI
shortTitle CodeQL CLI
intro You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_codeql %} processes locally on software projects or to generate {% data variables.product.prodname_code_scanning %} results for upload to {% data variables.product.github %}.
product {% data reusables.gated-features.codeql %}
versions
fpt ghes ghec
*
*
*
redirect_from
/code-security/codeql-cli/about-the-codeql-cli
/code-security/codeql-cli/using-the-codeql-cli/about-the-codeql-cli
/code-security/secure-coding/about-codeql-code-scanning-in-your-ci-system
/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system
/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/running-codeql-runner-in-your-ci-system
/github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system/running-codeql-code-scanning-in-your-ci-system
/github/finding-security-vulnerabilities-and-errors-in-your-code/running-codeql-code-scanning-in-your-ci-system
/github/finding-security-vulnerabilities-and-errors-in-your-code/troubleshooting-codeql-code-scanning-in-your-ci-system
/github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system/troubleshooting-codeql-code-scanning-in-your-ci-system
/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/migrating-from-the-codeql-runner-to-codeql-cli
/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system
/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli
/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli
/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/advanced-setup-of-the-codeql-cli
contentType concepts
category
Customize vulnerability detection with CodeQL

Software developers and security researchers can secure their code using {% data variables.product.prodname_codeql %} analysis. For more information about {% data variables.product.prodname_codeql %}, see AUTOTITLE.

The {% data variables.product.prodname_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 {% data variables.product.prodname_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 {% data variables.product.github %}.

You can use the {% data variables.product.prodname_codeql_cli %} to:

  • Run {% data variables.product.prodname_codeql %} analyses using queries provided by {% data variables.product.prodname_dotcom %} engineers and the open source community
  • Generate code scanning alerts that you can upload to display in {% data variables.product.github %}
  • Create {% data variables.product.prodname_codeql %} databases to use in the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension.
  • Develop and test custom {% data variables.product.prodname_codeql %} queries to use in your own analyses

The {% data variables.product.prodname_codeql_cli %} can analyze:

  • Dynamic languages, for example, JavaScript and Python.
  • Compiled languages, for example, {% data variables.code-scanning.compiled_languages %}
  • Codebases written in a mixture of languages.

About using the {% data variables.product.prodname_codeql_cli %} for {% data variables.product.prodname_code_scanning %}

You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_code_scanning %} on code that you're processing in a third-party continuous integration (CI) system. {% data reusables.code-scanning.about-code-scanning %} For an overview of using code scanning with external CI systems, see AUTOTITLE. For recommended specifications (RAM, CPU cores, and disk) for running {% data variables.product.prodname_codeql %} analysis, see AUTOTITLE.

Alternatively, you can use {% data variables.product.prodname_actions %} or Azure DevOps pipelines to scan code using the {% data variables.product.prodname_codeql_cli %}. For more information, see AUTOTITLE or Configure {% data variables.product.prodname_ghas_azdo %} in Microsoft Learn.

For an overview of all the options for using {% data variables.product.prodname_codeql %} analysis for code scanning, see AUTOTITLE.

{% data reusables.code-scanning.licensing-note %}

About generating code scanning results with the {% data variables.product.prodname_codeql_cli %}

If you choose to run the {% data variables.product.prodname_codeql_cli %} directly, you first have to install the {% data variables.product.prodname_codeql_cli %} locally. If you are planning to use the {% data variables.product.prodname_codeql_cli %} with an external CI system, you need to make the {% data variables.product.prodname_codeql_cli %} available to servers in your CI system.

Once the {% data variables.product.prodname_codeql_cli %} is set up, you can use three different commands to generate results and upload them to {% data variables.product.github %}:

  1. database create to create a {% data variables.product.prodname_codeql %} database to represent the hierarchical structure of each supported programming language in the repository. For more information, see AUTOTITLE.
  2. database analyze to run queries to analyze each {% data variables.product.prodname_codeql %} database and summarize the results in a SARIF file. For more information, see AUTOTITLE.
  3. github upload-results to upload the resulting SARIF files to {% data variables.product.github %} where the results are matched to a branch or pull request and displayed as {% data variables.product.prodname_code_scanning %} alerts. For more information, see AUTOTITLE.

{% data reusables.code-scanning.upload-sarif-ghas %}

Example CI configuration for {% data variables.product.prodname_codeql %} analysis

This is an example of the full series of commands for the {% data variables.product.prodname_codeql_cli %} that you might use to analyze a codebase with two supported languages and then upload the results to {% data variables.product.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 {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication
# with {% data variables.product.company_short %}'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

Database extraction

The {% data variables.product.prodname_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 {% data variables.product.prodname_codeql_cli %}. See AUTOTITLE.

{% data reusables.code-scanning.codeql-license %}

About {% data variables.product.prodname_codeql_cli %} database bundles

The {% data variables.product.prodname_codeql_cli %} database bundle command can be used to create a relocatable archive of a {% data variables.product.prodname_codeql %} database.

A copy of a database bundle can be used to share troubleshooting information with your team members or with {% data variables.contact.github_support %}. See AUTOTITLE.

Getting started

For the simplest way to get started, see AUTOTITLE.

More advanced setup options are available if you need them. For example, if you:

  • Want to contribute to open source shared {% data variables.product.prodname_codeql %} queries and prefer working with the {% data variables.product.prodname_codeql %} source code directly. See AUTOTITLE.
  • Need to install multiple versions of the {% data variables.product.prodname_codeql_cli %} side by side. For example, if one codebase requires a specific version while another uses the latest. You can download each version and unpack both CLI archives in the same parent directory.
  • Are researching or developing queries and want to download databases from {% data variables.product.prodname_dotcom_the_website %}. See AUTOTITLE.