Skip to content

Commit

Permalink
Remove redundant versioning from articles part 3: Code scanning (#52350)
Browse files Browse the repository at this point in the history
Co-authored-by: Vanessa <[email protected]>
  • Loading branch information
felicitymay and vgrl authored Sep 20, 2024
1 parent 48c716c commit 6e0c543
Show file tree
Hide file tree
Showing 6 changed files with 10 additions and 41 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -404,7 +404,7 @@ In the following example, the `+` symbol ensures that the specified additional p

## Using a custom configuration file

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{% 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 Down Expand Up @@ -497,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 @@ -532,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 @@ -564,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 @@ -605,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 @@ -182,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 @@ -192,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 Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ In repositories where {% data variables.product.prodname_code_scanning %} is con

If the lines of code changed in the pull request generate {% data variables.product.prodname_code_scanning %} alerts, the alerts are reported in the following places on the pull request.

* Check results in the pull request {% ifversion code-scanning-pr-conversations-tab %}
* The **Conversation** tab of the pull request, as part of a pull request review {% endif %}
* Check results in the pull request
* The **Conversation** tab of the pull request, as part of a pull request review
* The **Files changed** tab of the pull request

{% note %}
Expand Down Expand Up @@ -88,19 +88,12 @@ As with other pull request checks, you can see full details of the check failure

## Viewing an alert on your pull request

{% ifversion code-scanning-pr-conversations-tab %}
You can see any {% data variables.product.prodname_code_scanning %} alerts that are inside the diff of the changes introduced in a pull request by viewing the **Conversation** tab. {% data variables.product.prodname_code_scanning_caps %} posts a pull request review that shows each alert as an annotation on the lines of code that triggered the alert. You can comment on the alerts, dismiss the alerts, and view paths for the alerts, directly from the annotations. You can view the full details of an alert by clicking the "Show more details" link, which will take you to the alert details page.

![Screenshot of an alert annotation on the "Conversations" tab of a pull request. The "Show more details" link is outlined in dark orange.](/assets/images/help/repository/code-scanning-pr-conversation-tab.png)

You can also view all {% data variables.product.prodname_code_scanning %} alerts that are inside the diff of the changes introduced in the pull request in the **Files changed** tab.

{% else %}
You can see any {% data variables.product.prodname_code_scanning %} alerts introduced in a pull request by displaying the **Files changed** tab. Each alert is shown as an annotation on the lines of code that triggered the alert. The severity of the alert is displayed in the annotation.

![Screenshot showing an alert annotation within a pull request diff.](/assets/images/help/repository/code-scanning-pr-annotation.png)
{% endif %}

If you add a new code scanning configuration in your pull request, you will see a comment on your pull request directing you to the **Security** tab of the repository so you can view all the alerts on the pull request branch. For more information about viewing the alerts for a repository, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/managing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository)."

If you have write permission for the repository, some annotations contain links with extra context for the alert. In the example above, from {% data variables.product.prodname_codeql %} analysis, you can click **user-provided value** to see where the untrusted data enters the data flow (this is referred to as the source). In this case you can also view the full path from the source to the code that uses the data (the sink) by clicking **Show paths**. This makes it easy to check whether the data is untrusted or if the analysis failed to recognize a data sanitization step between the source and the sink. For information about analyzing data flow using {% data variables.product.prodname_codeql %}, see "[About data flow analysis](https://codeql.github.com/docs/writing-codeql-queries/about-data-flow-analysis/)."
Expand All @@ -113,14 +106,11 @@ In the detailed view for an alert, some {% data variables.product.prodname_code_

![Screenshot showing the description for a {% data variables.product.prodname_code_scanning %} alert. A link labeled "Show more" is highlighted with a dark orange outline.](/assets/images/help/repository/code-scanning-pr-alert.png)

{% ifversion code-scanning-pr-conversations-tab %}

## Commenting on an alert in a pull request

You can comment on any {% data variables.product.prodname_code_scanning %} alert that appears in a pull request. Alerts appear as annotations in the **Conversation** tab of a pull request, as part of a pull request review, and also are shown in the **Files changed** tab.

You can choose to require all conversations in a pull request, including those on {% data variables.product.prodname_code_scanning %} alerts, to be resolved before a pull request can be merged. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-conversation-resolution-before-merging)."
{% endif %}

## Fixing an alert on your pull request

Expand Down Expand Up @@ -176,11 +166,9 @@ If you decide to reject a {% data variables.product.prodname_copilot_autofix_sho
## Dismissing an alert on your pull request

An alternative way of closing an alert is to dismiss it. You can dismiss an alert if you don't think it needs to be fixed. {% data reusables.code-scanning.close-alert-examples %} If you have write permission for the repository, a **Dismiss alert** button is available in code annotations and in the alerts summary. When you click **Dismiss alert** you will be prompted to choose a reason for closing the alert.
{% ifversion comment-dismissed-code-scanning-alert %}

![Screenshot of a check failure for code scanning. The "Dismiss alert" button is highlighted in dark orange. The "Dismiss alert" drop-down is shown.](/assets/images/help/repository/code-scanning-alert-dropdown-reason.png)
{% else %}
![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 Down
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
It's important to choose the appropriate reason from the drop-down menu as this may affect whether a query continues to be included in future analysis. {% ifversion comment-dismissed-code-scanning-alert %}Optionally, you can comment on a dismissal to record the context of an alert dismissal. The dismissal comment is added to the alert timeline and can be used as justification during auditing and reporting. You can retrieve or set a comment by using the code scanning REST API. The comment is contained in `dismissed_comment` for the `alerts/{alert_number}` endpoint. For more information, see "[AUTOTITLE](/rest/code-scanning#update-a-code-scanning-alert)."
{% endif %}
It's important to choose the appropriate reason from the drop-down menu as this may affect whether a query continues to be included in future analysis. Optionally, you can comment on a dismissal to record the context of an alert dismissal. The dismissal comment is added to the alert timeline and can be used as justification during auditing and reporting. You can retrieve or set a comment by using the code scanning REST API. The comment is contained in `dismissed_comment` for the `alerts/{alert_number}` endpoint. For more information, see "[AUTOTITLE](/rest/code-scanning#update-a-code-scanning-alert)."
8 changes: 2 additions & 6 deletions data/reusables/code-scanning/example-configuration-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,14 +25,12 @@ queries:
uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls

paths:
- src
paths-ignore:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
```
{% ifversion code-scanning-exclude-queries-from-analysis %}
The following configuration file only runs queries that generate alerts of severity error. The configuration first selects all the default queries, all queries in `./my-queries`, and the default suite in `codeql/java-queries`, then excludes all the queries that generate warnings or recommendations.

``` yaml
Expand All @@ -47,5 +45,3 @@ query-filters:
- warning
- recommendation
```

{% endif %}
2 changes: 0 additions & 2 deletions data/reusables/code-scanning/run-additional-queries.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
When you use {% data variables.product.prodname_codeql %} to scan code, the {% data variables.product.prodname_codeql %} analysis engine generates a database from the code and runs queries on it. {% data variables.product.prodname_codeql %} analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries.

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

You can also specify the queries you want to exclude from analysis, or include in the analysis. This requires the use of a custom configuration file. For more information, see "[Using a custom configuration file](#using-a-custom-configuration-file)" and "[Excluding specific queries from analysis](#excluding-specific-queries-from-analysis)" below.

{% endtip %}
{% endif %}

You can run extra queries if they are part of a {% data variables.product.prodname_codeql %} pack published to the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %} or a {% data variables.product.prodname_codeql %} pack stored in a repository. For more information, see "[AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql-queries)."

Expand Down

0 comments on commit 6e0c543

Please sign in to comment.