Analyzing your code with CodeQL queries - GitHub Docs
Skip to main content Skip to content Collapse sidebar Expand sidebar Analyzing your code with CodeQL queries You can run queries against a CodeQL database extracted from a codebase. Who can use this feature? CodeQL is available for the following repository types: Public repositories on GitHub.com, see GitHub CodeQL Terms and Conditions Organization-owned repositories on GitHub Team with GitHub Code Security enabled In this article About analyzing databases with the CodeQL CLI To analyze a codebase, you run queries against a CodeQL database extracted from the code.
CodeQL analyses produce results that can be uploaded to GitHub to generate code scanning alerts. Prerequisites Before starting an analysis you must: Set up the CodeQL CLI to run commands locally. Create a CodeQL database for the source code you want to analyze. The simplest way to run codeql database analyze is using the standard queries included in the CodeQL CLI bundle. Running codeql database analyze When you run database analyze , it: Optionally downloads any referenced CodeQL packages that are not available locally.
Executes one or more query files, by running them over a CodeQL database. Interprets the results, based on certain query metadata, so that alerts can be displayed in the correct location in the source code. Reports the results of any diagnostic and summary queries to standard output. You can analyze a database by running the following command: codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...
Note If you analyze more than one CodeQL database for a single commit, you must specify a SARIF category for each set of results generated by this command. When you upload the results to GitHub, code scanning uses this category to store the results for each language separately. If you forget to do this, each upload overwrites the previous results. codeql database analyze <database> --format=<format> \ --sarif-category=<language-specifier> --output=<output> \ <packs,queries> You must specify <database> , --format , and --output .
You can specify additional options depending on what analysis you want to do. Option Required Usage <database> Specify the path for the directory that contains the CodeQL database to analyze. <packs,queries> Specify CodeQL packs or queries to run. To run the standard queries used for code scanning, omit this parameter. To see the other query suites included in the CodeQL CLI bundle, run codeql resolve queries . The suites listed there can be provided with or without the .qls extension.
For information about creating your own query suite, see Creating CodeQL query suites in the documentation for the CodeQL CLI. --format Specify the format for the results file generated during analysis. A number of different formats are supported, including CSV, SARIF , and graph formats. For upload to GitHub this should be: sarif-latest . For more information, see SARIF support for code scanning . --output Specify the location where you want to save the SARIF results file, including the desired filename with the .sarif extension. --sarif-category Optional for single database analysis.
Required to define the language when you analyze multiple databases for a single commit in a repository. Specify a category to include in the SARIF results file for this analysis. A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. --sarif-add-baseline-file-info Recommended. Use to submit file coverage information to the tool status page.
For more information, see Use the tool status page for code scanning . --sarif-include-query-help Specify whether to include query help in the SARIF output. One of: always : Include query help for all queries. custom_queries_ only (default): Include query help only for custom queries, that is, queries in query packs which are not of the form codeql/ <lang>-queries . never : Do not include query help for any queries. Any query help for custom queries included in the SARIF output will be displayed in any code scanning alerts for the query.
For more information, see Writing custom queries for the CodeQL CLI . <packs> Use if you want to include CodeQL query packs in your analysis. For more information, see Downloading and using CodeQL packs . --download Use if some of your CodeQL query packs are not yet on disk and need to be downloaded before running queries. --threads Use if you want to use more than one thread to run queries. The default value is 1 . You can specify more threads to speed up query execution.
To set the number of threads to the number of logical processors, specify 0 . --verbose Use to get more detailed information about the analysis process and diagnostic data from the database creation process. --threat-model (Public preview) Use to add threat models to configure additional sources in your CodeQL analysis. During the public preview, threat models are supported only by Java analysis. For more information, see database analyze .
Note Upgrading databases For databases that were created by CodeQL CLI v2.3.3 or earlier, you will need to explicitly upgrade the database before you can run an analysis with a newer version of the CodeQL CLI. If this step is necessary, then you will see a message telling you that your database needs to be upgraded when you run database analyze . For databases that were created by CodeQL CLI v2.3.4 or later, the CLI will implicitly run any required upgrades.
Explicitly running the upgrade command is not necessary. For full details of all the options you can use when analyzing databases, see database analyze . Basic example of analyzing a CodeQL database This example analyzes a CodeQL database stored at /codeql-dbs/example-repo and saves the results as a SARIF file: /temp/example-repo-js.sarif . It uses --sarif-category to include extra information in the SARIF file that identifies the results as JavaScript.
This is essential when you have more than one CodeQL database to analyze for a single commit in a repository. $ codeql database analyze /codeql-dbs/example-repo \ javascript-code-scanning.qls --sarif-category=javascript-typescript \ --format=sarif-latest --output=/temp/example-repo-js.sarif > Running queries. > Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql. ... > Shutting down query evaluator. > Interpreting results.
Adding file coverage information to your results for monitoring You can optionally submit file coverage information to GitHub for display on the tool status page for code scanning. For more information about file coverage information, see Use the tool status page for code scanning . To include file coverage information with your code scanning results, add the --sarif-add-baseline-file-info flag to the codeql database analyze invocation in your CI system, for example: $ codeql database analyze /codeql-dbs/example-repo \ javascript-code-scanning.qls --sarif-category=javascript-typescript \ --sarif-add-baseline-file-info \ --format=sarif-latest \ --output=/temp/example-repo-js.sarif Examples of running database analyses The following examples show how to run database analyze using CodeQL packs, and how to use a local checkout of the CodeQL repository.
These examples assume your CodeQL databases have been created in a directory that is a sibling of your local copies of the CodeQL repository. Running a CodeQL query pack To run an existing CodeQL query pack from the GitHub Container registry, you can specify one or more pack names: codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download This command runs the default query suite of two CodeQL query packs: microsoft/coding-standards version 1.0.0 and the latest version of github/security-queries on the specified database.
For further information about default suites, see Publishing
The rest of this page is on the live site.