Skip to content

Commit

Permalink
Merge pull request #34664 from github/repo-sync
Browse files Browse the repository at this point in the history
Repo sync
  • Loading branch information
docs-bot authored Sep 20, 2024
2 parents 74279fc + 6e0c543 commit f2d3f93
Show file tree
Hide file tree
Showing 22 changed files with 36 additions and 145 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -296,8 +296,6 @@ In this example, the default queries will be run for Java, as well as the querie

{% data reusables.code-scanning.run-additional-queries %}

{% ifversion codeql-packs %}

### Using query packs

To add one or more {% data variables.product.prodname_codeql %} query packs, add a `with: packs:` entry within the `uses: {% data reusables.actions.action-codeql-action-init %}` 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 "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)" and "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
Expand All @@ -321,7 +319,6 @@ In the example below, `scope` is the organization or personal account that publi
packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries
```

{% ifversion query-pack-compatibility %}
{% note %}

**Note:** If you specify a particular version of a query pack to use,
Expand All @@ -334,7 +331,6 @@ To ensure optimal performance, if you need to specify exact query pack versions,
For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)."

{% endnote %}
{% endif %}

### Downloading {% data variables.product.prodname_codeql %} packs from {% data variables.product.prodname_ghe_server %}

Expand Down Expand Up @@ -370,7 +366,6 @@ Notice the `|` after the `registries` property name. This is important since {%

### Using queries in QL packs

{% endif %}
To add one or more queries, add a `with: queries:` entry within the `uses: {% data reusables.actions.action-codeql-action-init %}` 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.

You can also specify query suites in the value of `queries`. Query suites are collections of queries, usually grouped by purpose or language.
Expand All @@ -388,24 +383,18 @@ You can also specify query suites in the value of `queries`. Query suites are co

{% data reusables.code-scanning.codeql-query-suites-explanation %}

{% ifversion codeql-packs %}

### Working with custom configuration files

{% endif %}

If you also use a configuration file for custom settings, any additional {% ifversion 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 {% ifversion codeql-packs %}packs or {% endif %}queries, prefix the value of {% ifversion 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)."
If you also use a configuration file for custom settings, any additional packs or 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 packs or queries, prefix the value of `packs` or `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 {% ifversion codeql-packs %}packs and {% endif %}queries are used together with any specified in the referenced configuration file.
In the following example, the `+` symbol ensures that the specified additional packs and queries are used together with any specified in the referenced configuration file.

``` yaml copy
- uses: {% data reusables.actions.action-codeql-action-init %}
with:
config-file: ./.github/codeql/codeql-config.yml
queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
{%- ifversion codeql-packs %}
packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries
{%- endif %}
```
<!-- Anchor to maintain the current CodeQL CLI manual pages link: https://aka.ms/code-scanning-docs/config-file -->
<a name="using-a-custom-configuration-file"></a>
Expand All @@ -415,7 +404,7 @@ In the following example, the `+` symbol ensures that the specified additional {

## Using a custom configuration file

A custom configuration file is an alternative way to specify additional {% ifversion codeql-packs %}packs and {% endif %}queries to run. You can also use the file to disable the default queries{% ifversion code-scanning-exclude-queries-from-analysis %}, exclude or include specific queries,{% endif %} and to specify which directories to scan during analysis.
A custom configuration file is an alternative way to specify additional packs and queries to run. You can also use the file to disable the default queries, exclude or include specific 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_.

Expand All @@ -437,8 +426,6 @@ If the configuration file is located in an external private repository, use the

The settings in the configuration file are written in YAML format.

{% ifversion codeql-packs %}

### Specifying {% data variables.product.prodname_codeql %} query packs

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.
Expand Down Expand Up @@ -482,7 +469,6 @@ packs:
```

{% endraw %}
{% endif %}

{% ifversion codeql-threat-models %}

Expand Down Expand Up @@ -511,8 +497,6 @@ Optionally, you can give each array element a name, as shown in the example conf

If you only want to run custom queries, you can disable the default security queries by using `disable-default-queries: true`.

{% ifversion code-scanning-exclude-queries-from-analysis %}

### Excluding specific queries from analysis

You can add `exclude` and `include` filters to your custom configuration file, to specify the queries you want to exclude or include in the analysis.
Expand Down Expand Up @@ -546,8 +530,6 @@ You can find another example illustrating the use of these filters in the "[Exam

For more information about using `exclude` and `include` filters in your custom configuration file, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites#filtering-the-queries-in-a-query-suite)." For information on the query metadata you can filter on, see "[Metadata for CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/)."

{% endif %}

### Specifying directories to scan

When codebases are analyzed without building the code, you can restrict {% data variables.product.prodname_code_scanning %} to files in specific directories by adding a `paths` array to the configuration file. You can also exclude the files in specific directories from analysis by adding a `paths-ignore` array. You can use this option when you run the {% data variables.product.prodname_codeql %} actions on an interpreted language (Python, Ruby, and JavaScript/TypeScript){% ifversion codeql-no-build %} or when you analyze a compiled language without building the code (currently supported for {% data variables.code-scanning.no_build_support %}){% endif %}.
Expand Down Expand Up @@ -578,8 +560,6 @@ You can quickly analyze small portions of a monorepo when you modify code in spe

{% data reusables.code-scanning.example-configuration-files %}

{% ifversion code-scanning-config-input %}

## Specifying configuration details using the `config` input

If you'd prefer to specify additional configuration details in the workflow file, you can use the `config` input of the `init` command of the {% data variables.product.prodname_codeql %} action. The value of this input must be a YAML string that follows the configuration file format documented at "[Using a custom configuration file](#using-a-custom-configuration-file)" above.
Expand Down Expand Up @@ -619,7 +599,6 @@ In the following example, `vars.CODEQL_CONF` is a {% data variables.product.prod
```

{% endtip %}
{% endif %}

## Configuring {% data variables.product.prodname_code_scanning %} for compiled languages

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -55,27 +55,13 @@ If you configure {% data variables.product.prodname_code_scanning %} using {% da

When {% data variables.product.prodname_code_scanning %} reports data-flow alerts, {% data variables.product.prodname_dotcom %} shows you how data moves through the code. {% data variables.product.prodname_code_scanning_caps %} allows you to identify the areas of your code that leak sensitive information, and that could be the entry point for attacks by malicious users.

### About {% ifversion remove-code-scanning-configurations %}alerts from multiple configurations{% else %}analysis origins{% endif %}
### About alerts from multiple configurations

{% ifversion remove-code-scanning-configurations %}
You can run multiple configurations of code analysis on a repository, using different tools and targeting different languages or areas of the code. Each configuration of {% data variables.product.prodname_code_scanning %} generates a unique set of alerts. For example, an alert generated using the default {% data variables.product.prodname_codeql %} analysis with {% data variables.product.prodname_actions %} comes from a different configuration than an alert generated externally and uploaded via the {% data variables.product.prodname_code_scanning %} API.

If you use multiple configurations to analyze a file, any problems detected by the same query are reported as alerts generated by multiple configurations. If an alert exists in more than one configuration, the number of configurations appears next to the branch name in the "Affected branches" section on the right-hand side of the alert page. To view the configurations for an alert, in the "Affected branches" section, click a branch. A "Configurations analyzing" modal appears with the names of each configuration generating the alert for that branch. Below each configuration, you can see when that configuration's alert was last updated.

An alert may display different statuses from different configurations. To update the alert statuses, re-run each out-of-date configuration. Alternatively, you can delete stale configurations from a branch to remove outdated alerts. For more information on deleting stale configurations and alerts, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/managing-code-scanning-alerts-for-your-repository#removing-stale-configurations-and-alerts-from-a-branch)."
{% else %}
You can run multiple configurations of code analysis on a repository, using different tools and targeting different languages or areas of the code. Each configuration of {% data variables.product.prodname_code_scanning %} is the analysis origin for all the alerts it generates. For example, an alert generated using the default {% data variables.product.prodname_codeql %} analysis with {% data variables.product.prodname_actions %} will have a different analysis origin from an alert generated externally and uploaded via the {% data variables.product.prodname_code_scanning %} API.

If you use multiple configurations to analyze a file, any problems detected by the same query are reported as alerts with multiple analysis origins. If an alert has more than one analysis origin, a {% octicon "workflow" aria-label="The workflow icon" %} icon will appear next to any relevant branch in the **Affected branches** section on the right-hand side of the alert page. You can hover over the {% octicon "workflow" aria-label="The workflow icon" %} icon to see the names of each analysis origin and the status of the alert for that analysis origin. You can also view the history of when alerts appeared in each analysis origin in the timeline on the alert page. If an alert only has one analysis origin, no information about analysis origins is displayed on the alert page.

![Screenshot showing a code scanning alert with multiple analysis origins.](/assets/images/help/repository/code-scanning-analysis-origins.png)

{% note %}

**Note:** Sometimes a {% data variables.product.prodname_code_scanning %} alert displays as fixed for one analysis origin but is still open for a second analysis origin. You can resolve this by re-running the second {% data variables.product.prodname_code_scanning %} configuration to update the alert status for that analysis origin.

{% endnote %}
{% endif %}

### About labels for alerts that are not found in application code

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -166,11 +166,9 @@ Alerts may be fixed in one branch but not in another. You can use the "Branch" f
{% note %}

**Note:**
{%- ifversion remove-code-scanning-configurations %}

If you run {% data variables.product.prodname_code_scanning %} using multiple configurations, the same alert will sometimes be generated by more than one configuration. Unless you run all configurations regularly, you may see alerts that are fixed in one configuration but not in another. These stale configurations and alerts can be removed from a branch. For more information, see "[Removing stale configurations and alerts from a branch](#removing-stale-configurations-and-alerts-from-a-branch)."
{% else %}
If you run {% data variables.product.prodname_code_scanning %} using multiple configurations, then sometimes an alert will have multiple analysis origins. Unless you run all configurations regularly, you may see alerts that are fixed in one analysis origin but not in another. For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-analysis-origins)."
{% endif %}

{% endnote %}

## Dismissing alerts
Expand All @@ -184,8 +182,8 @@ When you dismiss an alert:
* It's dismissed in all branches.
* The alert is removed from the number of current alerts for your project.
* The alert is moved to the "Closed" list in the summary of alerts, from where you can reopen it, if required.
* The reason why you closed the alert is recorded.{% ifversion comment-dismissed-code-scanning-alert %}
* Optionally, you can comment on a dismissal to record the context of an alert dismissal.{% endif %}
* The reason why you closed the alert is recorded.
* Optionally, you can comment on a dismissal to record the context of an alert dismissal.
* Next time {% data variables.product.prodname_code_scanning %} runs, the same code won't generate an alert.

To dismiss alerts:
Expand All @@ -194,13 +192,8 @@ To dismiss alerts:
{% data reusables.repositories.sidebar-security %}
{% data reusables.repositories.sidebar-code-scanning-alerts %}
1. If you want to dismiss an alert, it's important to explore the alert first, so that you can choose the correct dismissal reason. Click the alert you'd like to explore.
{%- ifversion comment-dismissed-code-scanning-alert %}
1. Review the alert, then click **Dismiss alert** and choose, or type, a reason for closing the alert.
![Screenshot of the check failure for a {% data variables.product.prodname_code_scanning %} alert in a pull request. The "Dismiss alert" button in the check failure is highlighted in dark orange. The "Dismiss alert" drop-down is displayed. ](/assets/images/help/repository/code-scanning-alert-dropdown-reason.png)
{%- else %}
1. Review the alert, then click **Dismiss** and choose a reason for closing the alert.
![Choosing a reason for dismissing an alert.](/assets/images/help/repository/code-scanning-alert-close-drop-down.png)
{%- endif %}
{% data reusables.code-scanning.choose-alert-dismissal-reason %}

{% data reusables.code-scanning.false-positive-fix-codeql %}
Expand All @@ -213,8 +206,6 @@ If a project has multiple alerts that you want to dismiss for the same reason, y

If you dismiss an alert but later realize that you need to fix the alert, you can re-open it and fix the problem with the code. Display the list of closed alerts, find the alert, display it, and reopen it. You can then fix the alert in the same way as any other alert.

{% ifversion remove-code-scanning-configurations %}

## Removing stale configurations and alerts from a branch

You may have multiple code scanning configurations on a single repository. When run, multiple configurations can generate the same alert. Additionally, if the configurations are run on different schedules, the alert statuses may become out-of-date for infrequent or stale configurations. For more information on alerts from multiple configurations, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alerts-from-multiple-configurations)."
Expand Down Expand Up @@ -242,8 +233,6 @@ You may have multiple code scanning configurations on a single repository. When

{% endnote %}

{% endif %}

## Auditing responses to {% data variables.product.prodname_code_scanning %} alerts

{% data reusables.code-scanning.audit-code-scanning-events %}
Expand Down
Loading

0 comments on commit f2d3f93

Please sign in to comment.