Merge branch 'russell/correct-vulnerability-instructions' into 'master'

Correct vulnerability instructions

See merge request gitlab-org/gitlab!62271

doc/development/integrations/secure.md

@@ -550,7 +550,7 @@ of the available SAST Analyzers and what data is currently available.
 
 The `remediations` field of the report is an array of remediation objects.
 Each remediation describes a patch that can be applied to
-[automatically fix](../../user/application_security/vulnerabilities/index.md#remediate-a-vulnerability-automatically)
+[resolve](../../user/application_security/vulnerabilities/index.md#resolve-a-vulnerability)
 a set of vulnerabilities.
 
 Here is an example of a report that contains remediations.

doc/development/integrations/secure_partner_integration.md

@@ -101,7 +101,7 @@ and complete an integration with the Secure stage.
    - Users can interact with the findings from your artifact within their workflow. They can dismiss the findings or accept them and create a backlog issue.
    - To automatically create issues without user interaction, use the [issue API](../../api/issues.md).
 1. Optional: Provide auto-remediation steps:
-   - If you specified `remediations` in your artifact, it is proposed through our [automatic remediation](../../user/application_security/vulnerabilities/index.md#remediate-a-vulnerability-automatically)
+   - If you specified `remediations` in your artifact, it is proposed through our [remediation](../../user/application_security/vulnerabilities/index.md#resolve-a-vulnerability)
      interface.
 1. Demo the integration to GitLab:
    - After you have tested and are ready to demo your integration please

doc/user/application_security/container_scanning/index.md

@@ -717,7 +717,7 @@ file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.m
 your `.gitlab-ci.yml` file by following the instructions described in this document's
 [overriding the container scanning template](#overriding-the-container-scanning-template) section.
 
-Read more about the [solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically).
+Read more about the [solutions for vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability).
 
 ## Troubleshooting
 

doc/user/application_security/dependency_scanning/index.md

@@ -231,11 +231,11 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m
 Once a vulnerability is found, you can interact with it. Read more on how to
 [address the vulnerabilities](../vulnerabilities/index.md).
 
-## Solutions for vulnerabilities (auto-remediation)
+## Solutions for vulnerabilities
 
 Some vulnerabilities can be fixed by applying the solution that GitLab
 automatically generates. Read more about the
-[solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically).
+[solutions for vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability).
 
 ## Security Dashboard
 

doc/user/application_security/index.md

@@ -383,7 +383,7 @@ For more details about which findings or vulnerabilities you can view in each of
 - Change the status.
 - Create an issue.
 - Link it to an existing issue.
-- In some cases, [apply an automatic remediation for a vulnerability](vulnerabilities/index.md#remediate-a-vulnerability-automatically).
+- [Resolve the vulnerability](vulnerabilities/index.md#resolve-a-vulnerability), if a solution is known.
 
 ## Troubleshooting
 

doc/user/application_security/offline_deployments/index.md

@@ -64,9 +64,9 @@ Once a vulnerability is found, you can interact with it. Read more on how to
 Please note that in some cases the reported vulnerabilities provide metadata that can contain
 external links exposed in the UI. These links might not be accessible within an offline environment.
 
-### Automatic remediation for vulnerabilities
+### Resolving vulnerabilities
 
-The [automatic remediation for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically) feature is available for offline Dependency Scanning and Container Scanning, but may not work
+The [resolving vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability) feature is available for offline Dependency Scanning and Container Scanning, but may not work
 depending on your instance's configuration. We can only suggest solutions, which are generally more
 current versions that have been patched, when we are able to access up-to-date registry services
 hosting the latest versions of that dependency or image.

doc/user/application_security/vulnerabilities/index.md

@@ -9,44 +9,47 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0.
 
-Each security vulnerability in a project's [Vulnerability Report](../vulnerability_report/index.md) has an individual page which includes:
+Each vulnerability in a project has a Vulnerability Page. This page contains details of the
+vulnerability. The details included vary according to the type of vulnerability. Details of each
+vulnerability include:
 
-- Details of the vulnerability.
-- The status of the vulnerability in the project.
-- Available actions for the vulnerability.
-- Any issues related to the vulnerability.
+- Description
+- When it was detected
+- Current status
+- Available actions
+- Linked issues
+- Actions log
 
 On the vulnerability's page, you can:
 
 - [Change the vulnerability's status](#change-vulnerability-status).
 - [Create an issue](#create-an-issue-for-a-vulnerability).
-- [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability).
-- [Remediate a vulnerability automatically](#remediate-a-vulnerability-automatically), if an
-  automatic solution is available.
-- [Remediate a vulnerability manually](#remediate-a-vulnerability-manually), if a solution is
+- [Link issues to the vulnerability](#linked-issues).
+- [Resolve a vulnerability](#resolve-a-vulnerability), if a solution is
   available.
 
-## Change vulnerability status
+## Vulnerability status values
+
+A vulnerability's status can be one of the following:
 
-You can change the status of a vulnerability using the **Status** dropdown to one of
-the following values:
+| Status    | Description |
+|:----------|:------------|
+| Detected  | The default state for a newly discovered vulnerability. |
+| Confirmed | A user has seen this vulnerability and confirmed it to be accurate. |
+| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. |
+| Resolved  | The vulnerability has been fixed and is no longer valid. |
 
-| Status    | Description                                                                                                    |
-|-----------|----------------------------------------------------------------------------------------------------------------|
-| Detected  | The default state for a newly discovered vulnerability                                                         |
-| Confirmed | A user has seen this vulnerability and confirmed it to be accurate                                             |
-| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved |
-| Resolved  | The vulnerability has been fixed and is no longer valid                                                        |
+## Change vulnerability status
 
-A timeline shows you when the vulnerability status has changed
-and allows you to comment on a change.
+To change a vulnerability's status, select a new value from the **Status** dropdown then select
+**Change status**. Optionally, add a comment to the log entry at the bottom of the page.
 
 ## Create an issue for a vulnerability
 
 From a vulnerability's page you can create an issue to track all action taken to resolve or
 mitigate it.
 
-From a vulnerability you can create either:
+You can create either:
 
 - [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default).
 - [A Jira issue](#create-a-jira-issue-for-a-vulnerability).
@@ -111,35 +114,45 @@ To disable it:
 Feature.disable(:jira_for_vulnerabilities)
 ```
 
-## Link GitLab issues to the vulnerability
+## Linked issues
 
 NOTE:
 If Jira issue support is enabled, GitLab issues are disabled so this feature is not available.
 
-You can link one or more existing GitLab issues to the vulnerability. This allows you to
-indicate that this vulnerability affects multiple issues. It also allows you to indicate
-that the resolution of one issue would resolve multiple vulnerabilities.
+You can link one or more existing GitLab issues to a vulnerability. Adding a link helps track
+the issue that resolves or mitigates a vulnerability.
 
-Linked issues are shown in the Vulnerability Report and the vulnerability's page.
+Issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page.
 
-## Link to an existing issue
-
-If you already have an open issue, you can link to it from the vulnerability.
+NOTE:
 
 - The vulnerability page shows related issues, but the issue page doesn't show the vulnerability it's related to.
 - An issue can only be related to one vulnerability at a time.
 - Issues can be linked across groups and projects.
 
-To link to an existing issue:
+## Link to existing issues
 
-1. Open the vulnerability.
-1. [Add a linked issue](../../project/issues/related_issues.md).
+To link a vulnerability to existing issues:
 
-## Remediate a vulnerability automatically
+1. Go to the vulnerability's page.
+1. In the **Linked issues** section, select the plus icon (**{plus}**).
+1. For each issue to be linked, either:
+   - Paste a link to the issue.
+   - Enter the issue's ID (prefixed with a hash `#`).
+1. Select **Add**.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7.
+The selected issues are added to the **Linked issues** section, and the linked issues counter is updated.
+
+## Resolve a vulnerability
+
+For some vulnerabilities a solution is already known. In those instances, a vulnerability's page
+includes a **Resolve with merge request** option.
+
+To resolve a vulnerability, you can either:
+
+- [Resolve a vulnerability with a merge request](#resolve-a-vulnerability-with-a-merge-request).
+- [Resolve a vulnerability manually](#resolve-a-vulnerability-manually).
 
-Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates.
 The following scanners are supported:
 
 - [Dependency Scanning](../dependency_scanning/index.md).
@@ -147,35 +160,26 @@ The following scanners are supported:
   `yarn`.
 - [Container Scanning](../container_scanning/index.md).
 
-### Remediate a vulnerability manually
+![Create merge request from vulnerability](img/create_mr_from_vulnerability_v13_4.png)
 
-To manually apply the patch that GitLab generated for a vulnerability:
+### Resolve a vulnerability with a merge request
 
-1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**:
+To resolve the vulnerability with a merge request, go to the vulnerability's page and from the
+**Resolve with merge request** dropdown select **Resolve with merge request**.
 
-   ![Resolve with Merge Request button dropdown](img/vulnerability_page_merge_request_button_dropdown_v13_1.png)
+A merge request is created which applies the patch required to resolve the vulnerability.
+Process the merge request according to your standard workflow.
 
+### Resolve a vulnerability manually
+
+To manually apply the patch that GitLab generated for a vulnerability:
+
+1. Go to the vulnerability's page and from the **Resolve with merge request** dropdown select
+   **Download patch to resolve**.
 1. Ensure your local project has the same commit checked out that was used to generate the patch.
 1. Run `git apply remediation.patch`.
 1. Verify and commit the changes to your branch.
 
-### Create a merge request with the suggested patch
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9.
-
-In some cases, you can create a merge request that automatically remediates the
-vulnerability. Any vulnerability that has a
-[solution](#remediate-a-vulnerability-automatically) can have a merge
-request created to automatically solve the issue.
-
-If this action is available:
-
-1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**.
-
-   ![Create merge request from vulnerability](img/create_mr_from_vulnerability_v13_4.png)
-
-A merge request is created. It applies the solution to the source branch.
-
 ## Vulnerability scanner maintenance
 
 The following vulnerability scanners and their databases are regularly updated: