[July 27/28] Update code scanning docs for CodeQL query packs (part of CodeQL Package Manager) (#20417)
This commit is contained in:
Felicity Chapman
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: About code scanning with CodeQL
|
||||
shortTitle: Code scanning with CodeQL
|
||||
intro: 'You can use {% data variables.product.prodname_codeql %} to identify vulnerabilities and errors in your code. The results are shown as {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.prodname_dotcom %}.'
|
||||
product: '{% data reusables.gated-features.code-scanning %}'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '>=3.0'
|
||||
ghae: '*'
|
||||
type: overview
|
||||
topics:
|
||||
- Advanced Security
|
||||
- Code scanning
|
||||
- CodeQL
|
||||
---
|
||||
|
||||
{% data reusables.code-scanning.beta %}
|
||||
{% data reusables.code-scanning.enterprise-enable-code-scanning %}
|
||||
|
||||
## About {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}
|
||||
|
||||
{% data reusables.code-scanning.about-codeql-analysis %}
|
||||
|
||||
There are two main ways to use {% data variables.product.prodname_codeql %} analysis for {% data variables.product.prodname_code_scanning %}:
|
||||
|
||||
- Add the {% data variables.product.prodname_codeql %} workflow to your repository. This uses the [github/codeql-action](https://github.com/github/codeql-action/) to run the {% data variables.product.prodname_codeql_cli %}. For more information, see "[Setting up {% data variables.product.prodname_code_scanning %} for a repository](/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository#setting-up-code-scanning-using-actions)."
|
||||
- Run the {% data variables.product.prodname_codeql %} {% ifversion fpt or ghes > 3.1 or ghae-next %}CLI directly {% elsif ghes = 3.0 %}CLI or runner {% else %}runner {% endif %} in an external CI system and upload the results to {% data variables.product.prodname_dotcom %}. For more information, see "[About {% data variables.product.prodname_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)."
|
||||
|
||||
## About {% data variables.product.prodname_codeql %}
|
||||
|
||||
{% data variables.product.prodname_codeql %} treats code like data, allowing you to find potential vulnerabilities in your code with greater confidence than traditional static analyzers.
|
||||
|
||||
1. You generate a {% data variables.product.prodname_codeql %} database to represent your codebase.
|
||||
2. Then you run {% data variables.product.prodname_codeql %} queries on that database to identify problems in the codebase.
|
||||
3. The query results are shown as {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.product_name %} when you use {% data variables.product.prodname_codeql %} with {% data variables.product.prodname_code_scanning %}.
|
||||
|
||||
{% data variables.product.prodname_codeql %} supports both compiled and interpreted languages, and can find vulnerabilities and errors in code that's written in the supported languages.
|
||||
|
||||
{% data reusables.code-scanning.codeql-languages-bullets %}
|
||||
|
||||
## About {% data variables.product.prodname_codeql %} queries
|
||||
|
||||
{% data variables.product.company_short %} experts, security researchers, and community contributors write and maintain the default {% data variables.product.prodname_codeql %} queries used for {% data variables.product.prodname_code_scanning %}. The queries are regularly updated to improve analysis and reduce any false positive results. The queries are open source, so you can view and contribute to the queries in the [`github/codeql`](https://github.com/github/codeql) repository. For more information, see [{% data variables.product.prodname_codeql %}](https://securitylab.github.com/tools/codeql) on the GitHub Security Lab website. You can also write your own queries. For more information, see "[About {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/)" in the {% data variables.product.prodname_codeql %} documentation.
|
||||
|
||||
You can run additional queries as part of your code scanning analysis.
|
||||
|
||||
{%- if codeql-packs %}
|
||||
These queries must belong to a published {% data variables.product.prodname_codeql %} query pack (beta) or a QL pack in a repository. {% data variables.product.prodname_codeql %} packs (beta) provide the following benefits over traditional QL packs:
|
||||
|
||||
- When a {% data variables.product.prodname_codeql %} query pack (beta) is published to the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}, all the transitive dependencies required by the queries and a compilation cache are included in the package. This improves performance and ensures that running the queries in the pack gives identical results every time until you upgrade to a new version of the pack or the CLI.
|
||||
- QL packs do not include transitive dependencies, so queries in the pack can depend only on the standard libraries (that is, the libraries referenced by an `import LANGUAGE` statement in your query), or libraries in the same QL pack as the query.
|
||||
|
||||
For more information, see "[About {% data variables.product.prodname_codeql %} packs](https://codeql.github.com/docs/codeql-cli/about-codeql-packs/)" and "[About {% data variables.product.prodname_ql %} packs](https://codeql.github.com/docs/codeql-cli/about-ql-packs/)" in the {% data variables.product.prodname_codeql %} documentation.
|
||||
|
||||
{% data reusables.code-scanning.beta-codeql-packs-actions %}
|
||||
|
||||
{%- else %}
|
||||
The queries you want to run must belong to a QL pack in a repository. Queries must only depend on the standard libraries (that is, the libraries referenced by an `import LANGUAGE` statement in your query), or libraries in the same QL pack as the query. For more information, see "[About {% data variables.product.prodname_ql %} packs](https://codeql.github.com/docs/codeql-cli/about-ql-packs/)."
|
||||
{% endif %}
|
||||
@@ -14,7 +14,6 @@ type: overview
|
||||
topics:
|
||||
- Advanced Security
|
||||
- Code scanning
|
||||
- CodeQL
|
||||
---
|
||||
<!--For this article in earlier GHES versions, see /content/github/finding-security-vulnerabilities-and-errors-in-your-code-->
|
||||
|
||||
@@ -34,18 +33,6 @@ To monitor results from {% data variables.product.prodname_code_scanning %} acro
|
||||
|
||||
To get started with {% data variables.product.prodname_code_scanning %}, see "[Setting up {% data variables.product.prodname_code_scanning %} for a repository](/code-security/secure-coding/setting-up-code-scanning-for-a-repository)."
|
||||
|
||||
## About {% data variables.product.prodname_codeql %}
|
||||
|
||||
You can use {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}, a semantic code analysis engine. {% data variables.product.prodname_codeql %} treats code as data, allowing you to find potential vulnerabilities in your code with greater confidence than traditional static analyzers.
|
||||
|
||||
{% data variables.product.prodname_ql %} is the query language that powers {% data variables.product.prodname_codeql %}. {% data variables.product.prodname_ql %} is an object-oriented logic programming language. {% data variables.product.company_short %}, language experts, and security researchers create the queries used for {% data variables.product.prodname_code_scanning %}, and the queries are open source. The community maintains and updates the queries to improve analysis and reduce false positives. For more information, see [{% data variables.product.prodname_codeql %}](https://securitylab.github.com/tools/codeql) on the GitHub Security Lab website.
|
||||
|
||||
{% data variables.product.prodname_code_scanning_capc %} with {% data variables.product.prodname_codeql %} supports both compiled and interpreted languages, and can find vulnerabilities and errors in code that's written in the supported languages.
|
||||
|
||||
{% data reusables.code-scanning.codeql-languages-bullets %}
|
||||
|
||||
You can view and contribute to the queries for {% data variables.product.prodname_code_scanning %} in the [`github/codeql`](https://github.com/github/codeql) repository. For more information, see [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/) in the {% data variables.product.prodname_codeql %} documentation.
|
||||
|
||||
{% ifversion fpt %}
|
||||
|
||||
## About billing for {% data variables.product.prodname_code_scanning %}
|
||||
@@ -54,14 +41,16 @@ You can view and contribute to the queries for {% data variables.product.prodnam
|
||||
|
||||
{% endif %}
|
||||
|
||||
## About third-party {% data variables.product.prodname_code_scanning %} tools
|
||||
## About tools for {% data variables.product.prodname_code_scanning %}
|
||||
|
||||
You can set up {% data variables.product.prodname_code_scanning %} to use the {% data variables.product.prodname_codeql %} product maintained by {% data variables.product.company_short%} or a third-party {% data variables.product.prodname_code_scanning %} tool.
|
||||
|
||||
### About {% data variables.product.prodname_codeql %} analysis
|
||||
|
||||
{% data reusables.code-scanning.about-codeql-analysis %} For more information about {% data variables.product.prodname_codeql %}, see "[About code scanning with CodeQL](/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql)."
|
||||
|
||||
### About third-party {% data variables.product.prodname_code_scanning %} tools
|
||||
|
||||
{% data reusables.code-scanning.interoperable-with-tools-that-output-sarif %}
|
||||
|
||||
You can run third-party analysis tools within {% data variables.product.product_name %} using actions or within an external CI system. For more information, see "[Setting up code scanning for a repository](/code-security/secure-coding/setting-up-code-scanning-for-a-repository)" or "[Uploading a SARIF file to GitHub](/code-security/secure-coding/uploading-a-sarif-file-to-github)."
|
||||
|
||||
## Further reading
|
||||
|
||||
- "[Securing your repository](/code-security/getting-started/securing-your-repository)"
|
||||
- [{% data variables.product.prodname_security %}](https://securitylab.github.com/)
|
||||
- [OASIS Static Analysis Results Interchange Format (SARIF) TC](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sarif) on the OASIS Committee website
|
||||
|
||||
@@ -275,13 +275,13 @@ This parameter is particularly useful if you work with monorepos and have multip
|
||||
|
||||
{% raw %}
|
||||
``` yaml
|
||||
- name: Perform CodeQL Analysis
|
||||
- name: Perform CodeQL Analysis
|
||||
uses: github/codeql-action/analyze
|
||||
with:
|
||||
# Optional. Specify a category to distinguish between multiple analyses
|
||||
# for the same tool and ref. If you don't use `category` in your workflow,
|
||||
# GitHub will generate a default category name for you
|
||||
category: "my_category"
|
||||
# Optional. Specify a category to distinguish between multiple analyses
|
||||
# for the same tool and ref. If you don't use `category` in your workflow,
|
||||
# GitHub will generate a default category name for you
|
||||
category: "my_category"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
@@ -299,14 +299,40 @@ Your specified category will not overwrite the details of the `runAutomationDeta
|
||||
|
||||
{% data reusables.code-scanning.run-additional-queries %}
|
||||
|
||||
To add one or more queries, add a `with: queries:` entry within the `uses: github/codeql-action/init@v1` section of the workflow. If the queries are in a private repository, use the `external-repository-token` parameter to specify a token that has access to the private repository.
|
||||
{% if codeql-packs %}
|
||||
### Using {% data variables.product.prodname_codeql %} query packs
|
||||
|
||||
{% data reusables.code-scanning.beta-codeql-packs-actions %}
|
||||
|
||||
To add one or more {% data variables.product.prodname_codeql %} query packs (beta), add a `with: packs:` entry within the `uses: github/codeql-action/init@v1` section of the workflow. Within `packs` you specify one or more packages to use and, optionally, which version to download. Where you don't specify a version, the latest version is downloaded. If you want to use packages that are not publicly available, you need to set the `GITHUB_TOKEN` environment variable to a secret that has access to the packages. For more information, see "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)" and "[Encrypted secrets](/actions/reference/encrypted-secrets)."
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** For workflows that generate {% data variables.product.prodname_codeql %} databases for multiple languages, you must instead specify the {% data variables.product.prodname_codeql %} query packs in a configuration file. For more information, see "[Specifying {% data variables.product.prodname_codeql %} query packs](#specifying-codeql-query-packs)" below.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
In the example below, `scope` is the organization or personal account that published the package. When the workflow runs, the three {% data variables.product.prodname_codeql %} query packs are downloaded from {% data variables.product.product_name %} and the default queries or query suite for each pack run. The latest version of `pack1` is downloaded as no version is specified. Version 1.2.3 of `pack2` is downloaded, as well as the latest version of `pack3` that is compatible with version 1.2.3.
|
||||
|
||||
{% raw %}
|
||||
``` yaml
|
||||
- uses: github/codeql-action/init@v1
|
||||
with:
|
||||
# Comma-separated list of packs to download
|
||||
packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~1.2.3
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Using queries in QL packs
|
||||
{% endif %}
|
||||
To add one or more queries, add a `with: queries:` entry within the `uses: github/codeql-action/init@v1` section of the workflow. If the queries are in a private repository, use the `external-repository-token` parameter to specify a token that has access to checkout the private repository.
|
||||
|
||||
{% raw %}
|
||||
``` yaml
|
||||
- uses: github/codeql-action/init@v1
|
||||
with:
|
||||
queries: COMMA-SEPARATED LIST OF PATHS
|
||||
# Optional. Provide a token to access private repositories.
|
||||
# Optional. Provide a token to access queries stored in private repositories.
|
||||
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
|
||||
```
|
||||
{% endraw %}
|
||||
@@ -315,23 +341,27 @@ You can also specify query suites in the value of `queries`. Query suites are co
|
||||
|
||||
{% data reusables.code-scanning.codeql-query-suites %}
|
||||
|
||||
If you are also using a configuration file for custom settings, any additional queries specified in your workflow are used instead of any specified in the configuration file. If you want to run the combined set of additional queries specified here and in the configuration file, prefix the value of `queries` in the workflow with the `+` symbol. For more information, see "[Using a custom configuration file](#using-a-custom-configuration-file)."
|
||||
{% if codeql-packs %}
|
||||
### Working with custom configuration files
|
||||
{% endif %}
|
||||
|
||||
In the following example, the `+` symbol ensures that the specified additional queries are used together with any queries specified in the referenced configuration file.
|
||||
If you also use a configuration file for custom settings, any additional {% if codeql-packs %}packs or {% endif %}queries specified in your workflow are used instead of those specified in the configuration file. If you want to run the combined set of additional {% if codeql-packs %}packs or {% endif %}queries, prefix the value of {% if codeql-packs %}`packs` or {% endif %}`queries` in the workflow with the `+` symbol. For more information, see "[Using a custom configuration file](#using-a-custom-configuration-file)."
|
||||
|
||||
In the following example, the `+` symbol ensures that the specified additional {% if codeql-packs %}packs and {% endif %}queries are used together with any specified in the referenced configuration file.
|
||||
|
||||
{% raw %}
|
||||
``` yaml
|
||||
- uses: github/codeql-action/init@v1
|
||||
with:
|
||||
config-file: ./.github/codeql/codeql-config.yml
|
||||
queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
|
||||
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
|
||||
{%- if codeql-packs %}
|
||||
packs: +scope/pack1,scope/pack2@v1.2.3
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Using a custom configuration file
|
||||
|
||||
As an alternative to specifying which queries to run in the workflow file, you can do this in a separate configuration file. You can also use a configuration file to disable the default queries and to specify which directories to scan during analysis.
|
||||
A custom configuration file is an alternative way to specify additional {% if codeql-packs %}packs and {% endif %}queries to run. You can also use the file to disable the default queries and to specify which directories to scan during analysis.
|
||||
|
||||
In the workflow file, use the `config-file` parameter of the `init` action to specify the path to the configuration file you want to use. This example loads the configuration file _./.github/codeql/codeql-config.yml_.
|
||||
|
||||
@@ -347,14 +377,50 @@ If the configuration file is located in an external private repository, use the
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
uses: github/codeql-action/init@v1
|
||||
with:
|
||||
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
|
||||
- uses: github/codeql-action/init@v1
|
||||
with:
|
||||
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The settings in the configuration file are written in YAML format.
|
||||
|
||||
{% if codeql-packs %}
|
||||
### Specifying {% data variables.product.prodname_codeql %} query packs
|
||||
|
||||
{% data reusables.code-scanning.beta-codeql-packs-actions %}
|
||||
|
||||
You specify {% data variables.product.prodname_codeql %} query packs in an array. Note that the format is different from the format used by the workflow file.
|
||||
|
||||
{% raw %}
|
||||
``` yaml
|
||||
packs:
|
||||
# Use the latest version of 'pack1' published by 'scope'
|
||||
- scope/pack1
|
||||
# Use version 1.23 of 'pack2'
|
||||
- scope/pack2@v1.2.3
|
||||
# Use the latest version of 'pack3' compatible with 1.23
|
||||
- scope/pack3@~1.2.3
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
If you have a workflow that generates more than one {% data variables.product.prodname_codeql %} database, you can specify any {% data variables.product.prodname_codeql %} query packs to run in a custom configuration file using a nested map of packs.
|
||||
|
||||
{% raw %}
|
||||
``` yaml
|
||||
packs:
|
||||
# Use these packs for JavaScript analysis
|
||||
javascript:
|
||||
- scope/js-pack1
|
||||
- scope/js-pack2
|
||||
# Use these packs for Java analysis
|
||||
java:
|
||||
- scope/java-pack1
|
||||
- scope/java-pack2@v1.0.0
|
||||
```
|
||||
{% endraw %}
|
||||
{% endif %}
|
||||
|
||||
### Specifying additional queries
|
||||
|
||||
You specify additional queries in a `queries` array. Each element of the array contains a `uses` parameter with a value that identifies a single query file, a directory containing query files, or a query suite definition file.
|
||||
@@ -363,12 +429,10 @@ You specify additional queries in a `queries` array. Each element of the array c
|
||||
queries:
|
||||
- uses: ./my-basic-queries/example-query.ql
|
||||
- uses: ./my-advanced-queries
|
||||
- uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls
|
||||
- uses: ./query-suites/my-security-queries.qls
|
||||
```
|
||||
|
||||
Optionally, you can give each array element a name, as shown in the example configuration files below.
|
||||
|
||||
For more information about additional queries, see "[Running additional queries](#running-additional-queries)" above.
|
||||
Optionally, you can give each array element a name, as shown in the example configuration files below. For more information about additional queries, see "[Running additional queries](#running-additional-queries)" above.
|
||||
|
||||
### Disabling the default queries
|
||||
|
||||
|
||||
@@ -18,6 +18,7 @@ children:
|
||||
- /setting-up-code-scanning-for-a-repository
|
||||
- /managing-code-scanning-alerts-for-your-repository
|
||||
- /configuring-code-scanning
|
||||
- /about-code-scanning-with-codeql
|
||||
- /configuring-the-codeql-workflow-for-compiled-languages
|
||||
- /troubleshooting-the-codeql-workflow
|
||||
- /running-codeql-code-scanning-in-a-container
|
||||
|
||||
@@ -28,7 +28,7 @@ topics:
|
||||
|
||||
## Options for setting up {% data variables.product.prodname_code_scanning %}
|
||||
|
||||
You decide how to generate {% data variables.product.prodname_code_scanning %} alerts, and which tools to use, at a repository level. {% data variables.product.product_name %} provides fully integrated support for {% data variables.product.prodname_codeql %} analysis, and also supports analysis using third-party tools. For more information, see "[About {% data variables.product.prodname_codeql %}](/code-security/secure-coding/about-code-scanning#about-codeql)."
|
||||
You decide how to generate {% data variables.product.prodname_code_scanning %} alerts, and which tools to use, at a repository level. {% data variables.product.product_name %} provides fully integrated support for {% data variables.product.prodname_codeql %} analysis, and also supports analysis using third-party tools. For more information, see "[About {% data variables.product.prodname_code_scanning %}](/code-security/secure-coding/about-code-scanning#about-tools-for-code-scanning)."
|
||||
|
||||
{% data reusables.code-scanning.enabling-options %}
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ redirect_from:
|
||||
|
||||
## About {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} in your CI system
|
||||
|
||||
{% data reusables.code-scanning.about-code-scanning %} For information, see "[About {% data variables.product.prodname_code_scanning %}](/code-security/secure-coding/about-code-scanning)."
|
||||
{% data reusables.code-scanning.about-code-scanning %} For information, see "[About {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}](/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql)."
|
||||
|
||||
You can run {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} within {% data variables.product.product_name %} using {% data variables.product.prodname_actions %}. Alternatively, if you use a third-party continuous integration or continuous delivery/deployment (CI/CD) system, you can run {% data variables.product.prodname_codeql %} analysis in your existing system and upload the results to {% data variables.product.product_location %}.
|
||||
|
||||
|
||||
@@ -135,11 +135,16 @@ $
|
||||
|
||||
## Analyzing a {% data variables.product.prodname_codeql %} database
|
||||
|
||||
1. Create a {% data variables.product.prodname_codeql %} database (see above).
|
||||
2. Run `codeql database analyze` on the database and specify which queries to use.
|
||||
1. Create a {% data variables.product.prodname_codeql %} database (see above).{% if codeql-packs %}
|
||||
2. Optional, run `codeql pack download` to download any {% data variables.product.prodname_codeql %} packs (beta) that you want to run during analysis. For more information, see "[Downloading and using {% data variables.product.prodname_codeql %} query packs](#downloading-and-using-codeql-query-packs)" below.
|
||||
```shell
|
||||
codeql pack download <packs>
|
||||
```
|
||||
{% endif %}
|
||||
3. Run `codeql database analyze` on the database and specify which {% if codeql-packs %}packs and/or{% endif %}queries to use.
|
||||
```shell
|
||||
codeql database analyze <database> --format=<format> \
|
||||
--output=<output> <queries>
|
||||
--output=<output> {% if codeql-packs %}<packs,queries>{% else %} <queries>{% endif %}
|
||||
```
|
||||
|
||||
{% ifversion fpt or ghes > 3.1 or ghae-next %}
|
||||
@@ -149,7 +154,8 @@ $
|
||||
|
||||
```shell
|
||||
codeql database analyze <database> --format=<format> \
|
||||
--sarif-category=<language-specifier> --output=<output> <queries>
|
||||
--sarif-category=<language-specifier> --output=<output> \
|
||||
{% if codeql-packs %}<packs,queries>{% else %}<queries>{% endif %}
|
||||
```
|
||||
{% endnote %}
|
||||
{% endif %}
|
||||
@@ -160,7 +166,8 @@ codeql database analyze <database> --format=<format> \
|
||||
| `<queries>` | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the queries to run. To run the standard queries used for {% data variables.product.prodname_code_scanning %}, use: `<language>-code-scanning.qls` where `<language>` is the short code for the language of the database. To see the other query suites included in the {% data variables.product.prodname_codeql_cli %} bundle, look in `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. For information about creating your own query suite, see [Creating CodeQL query suites](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/) in the documentation for the {% data variables.product.prodname_codeql_cli %}.
|
||||
| <nobr>`--format`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the format for the results file generated by the command. For upload to {% data variables.product.company_short %} this should be: {% ifversion fpt or ghae %}`sarif-latest`{% else %}`sarifv2.1.0`{% endif %}. For more information, see "[SARIF support for {% data variables.product.prodname_code_scanning %}](/code-security/secure-coding/sarif-support-for-code-scanning)."
|
||||
| <nobr>`--output`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify where to save the SARIF results file.{% ifversion fpt or ghes > 3.1 or ghae-next %}
|
||||
| <nobr>`--sarif-category`<nobr> | {% octicon "question" aria-label="Required with multiple results sets" %} | 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.|{% endif %}
|
||||
| <nobr>`--sarif-category`<nobr> | {% octicon "question" aria-label="Required with multiple results sets" %} | 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.|{% endif %}{% if codeql-packs %}
|
||||
| `<packs>` | | Optional. Use if you have downloaded CodeQL query packs and want to run the default queries or query suites specified in the packs. For more information, see "[Downloading and using {% data variables.product.prodname_codeql %} packs](#downloading-and-using-codeql-query-packs)."{% endif %}
|
||||
| <nobr>`--threads`</nobr> | | Optional. 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`.
|
||||
| <nobr>`--verbose`</nobr> | | Optional. Use to get more detailed information about the analysis process{% ifversion fpt or ghes > 3.1 or ghae-next %} and diagnostic data from the database creation process{% endif %}.
|
||||
|
||||
@@ -216,7 +223,7 @@ For more information, see [github upload-results](https://codeql.github.com/docs
|
||||
This example uploads results from the SARIF file `temp/example-repo-js.sarif` to the repository `my-org/example-repo`. It tells the {% data variables.product.prodname_code_scanning %} API that the results are for the commit `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` on the `main` branch.
|
||||
|
||||
```
|
||||
$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
|
||||
$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
|
||||
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
|
||||
--sarif=/temp/example-repo-js.sarif {% ifversion ghes > 3.0 or ghae-next %}--github-url={% data variables.command_line.git_url_example %} \
|
||||
{% endif %}--github-auth-stdin
|
||||
@@ -224,6 +231,47 @@ $ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example
|
||||
|
||||
There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.product_name %} shortly afterward. You can see alerts directly in the pull request or on the **Security** tab for branches, depending on the code you checked out. For more information, see "[Triaging {% data variables.product.prodname_code_scanning %} alerts in pull requests](/code-security/secure-coding/triaging-code-scanning-alerts-in-pull-requests)" and "[Managing {% data variables.product.prodname_code_scanning %} alerts for your repository](/code-security/secure-coding/managing-code-scanning-alerts-for-your-repository)."
|
||||
|
||||
{% if codeql-packs %}
|
||||
## Downloading and using {% data variables.product.prodname_codeql %} query packs
|
||||
|
||||
{% data reusables.code-scanning.beta-codeql-packs-cli %}
|
||||
|
||||
The {% data variables.product.prodname_codeql_cli %} bundle includes queries that are maintained by {% data variables.product.company_short %} experts, security researchers, and community contributors. If you want to run queries developed by other organizations, {% data variables.product.prodname_codeql %} query packs provide an efficient and reliable way to download and run queries. For more information, see "[About code scanning with CodeQL](/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql#about-codeql-queries)."
|
||||
|
||||
Before you can use a {% data variables.product.prodname_codeql %} pack to analyze a database, you must download any packages you require from the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %} by running `codeql pack download` and specifying the packages you want to download. If a package is not publicly available, you will need to use a {% data variables.product.prodname_github_app %} or personal access token to authenticate. For more information and an example, see "[Uploading results to {% data variables.product.product_name %}](#uploading-results-to-github)" above.
|
||||
|
||||
```shell
|
||||
codeql pack download <scope/name@version>,...
|
||||
```
|
||||
|
||||
| Option | Required | Usage |
|
||||
|--------|:--------:|-----|
|
||||
| <nobr>`<scope/name@version>`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | 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. |
|
||||
| <nobr>`--github-auth-stdin`</nobr> | | Optional. Pass the {% data variables.product.prodname_github_app %} or personal access token created for authentication with {% data variables.product.company_short %}'s REST API to the CLI via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
|
||||
|
||||
### Basic example
|
||||
|
||||
This example runs two commands to download the latest version of the `octo-org/security-queries` pack and then analyze the database `/codeql-dbs/example-repo`.
|
||||
|
||||
```
|
||||
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download octo-org/security-queries
|
||||
|
||||
> Download location: /Users/mona/.codeql/packages
|
||||
> Installed fresh octo-org/security-queries@1.0.0
|
||||
|
||||
$ codeql database analyze /codeql-dbs/example-repo octo-org/security-queries \
|
||||
--format=sarif-latest --output=/temp/example-repo-js.sarif
|
||||
|
||||
> Running queries.
|
||||
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
|
||||
> [1/1] 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.
|
||||
> [1/1 eval 394ms] Evaluation done; writing results to docto-org/security-queries/query1.bqrs.
|
||||
> Shutting down query evaluator.
|
||||
> Interpreting results.
|
||||
```
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.1 or ghae-next %}
|
||||
## Example CI configuration for {% data variables.product.prodname_codeql %} analysis
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ redirect_from:
|
||||
|
||||
## 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 information, see "[About {% data variables.product.prodname_code_scanning %}](/code-security/secure-coding/about-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 information, see "[About {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}](/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql)."
|
||||
|
||||
{% data reusables.code-scanning.what-is-codeql-cli %}
|
||||
|
||||
@@ -44,6 +44,8 @@ You should download the {% data variables.product.prodname_codeql %} bundle from
|
||||
|
||||
You should always use the {% data variables.product.prodname_codeql %} bundle as this ensures compatibility and also gives much better performance than a separate download of the {% data variables.product.prodname_codeql_cli %} and checkout of the {% data variables.product.prodname_codeql %} queries. If you will only be running the CLI on one specific platform, download the appropriate `codeql-bundle-PLATFORM.tar.gz` file. Alternatively, you can download `codeql-bundle.tar.gz`, which contains the CLI for all supported platforms.
|
||||
|
||||
{% data reusables.code-scanning.beta-codeql-packs-cli %}
|
||||
|
||||
## Setting up the {% data variables.product.prodname_codeql_cli %} in your CI system
|
||||
|
||||
You need to make the full contents of the {% data variables.product.prodname_codeql_cli %} bundle available to every CI server that you want to run CodeQL {% data variables.product.prodname_code_scanning %} analysis on. For example, you might configure each server to copy the bundle from a central, internal location and extract it. Alternatively, you could use the REST API to get the bundle directly from {% data variables.product.prodname_dotcom %}, ensuring that you benefit from the latest improvements to queries. Updates to the {% data variables.product.prodname_codeql_cli %} are released every 2-3 weeks. For example:
|
||||
|
||||
@@ -32,7 +32,7 @@ topics:
|
||||
|
||||
## About the {% data variables.product.prodname_codeql_runner %}
|
||||
|
||||
The {% data variables.product.prodname_codeql_runner %} is a tool you can use 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 information, see "[About {% data variables.product.prodname_code_scanning %}](/code-security/secure-coding/about-code-scanning)."
|
||||
The {% data variables.product.prodname_codeql_runner %} is a tool you can use 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 information, see "[About {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}](/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql)."
|
||||
|
||||
{% ifversion fpt or ghes > 3.0 or ghae-next %}
|
||||
In many cases it is easier to set up {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} using the {% data variables.product.prodname_codeql_cli %} directly in your CI system. The runner is more complex and less forgiving to set up than the CLI, and is recommended only if you need its capability to analyze multiple compiled languages with a single build, or to integrate with complex build processes. For more information, see "[About CodeQL code scanning in your CI system](/code-security/secure-coding/about-codeql-code-scanning-in-your-ci-system)".
|
||||
|
||||
Reference in New Issue
Block a user