Merge branch 'fneill-ctrt-update-security-dashboards-page' into 'master'

CTRT edits for security dashboards page

See merge request gitlab-org/gitlab!76242

doc/api/dependencies.md

@@ -16,7 +16,7 @@ across GitLab releases.
 
 Every call to this endpoint requires authentication. To perform this call, user should be authorized to read repository.
 To see vulnerabilities in response, user should be authorized to read
-[Project Security Dashboard](../user/application_security/security_dashboard/index.md#project-security-dashboard).
+[Project Security Dashboard](../user/application_security/security_dashboard/index.md).
 
 ## List project dependencies
 

doc/ci/pipelines/settings.md

@@ -21,7 +21,7 @@ For public and internal projects, you can change who can see your:
 - Pipelines
 - Job output logs
 - Job artifacts
-- [Pipeline security dashboard](../../user/application_security/security_dashboard/index.md#pipeline-security)
+- [Pipeline security dashboard](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline)
 
 However:
 

doc/ci/yaml/artifacts_reports.md

@@ -52,7 +52,7 @@ GitLab can display the results of one or more reports in:
 
 - The merge request [security widget](../../user/application_security/api_fuzzing/index.md#view-details-of-an-api-fuzzing-vulnerability).
 - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md).
-- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security).
+- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline).
 - The [security dashboard](../../user/application_security/api_fuzzing/index.md#security-dashboard).
 
 ## `artifacts:reports:browser_performance` **(PREMIUM)**
@@ -117,7 +117,7 @@ The collected Container Scanning report uploads to GitLab as an artifact.
 GitLab can display the results of one or more reports in:
 
 - The merge request [container scanning widget](../../user/application_security/container_scanning/index.md).
-- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security).
+- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline).
 - The [security dashboard](../../user/application_security/security_dashboard/index.md).
 - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md).
 
@@ -131,7 +131,7 @@ The collected coverage fuzzing report uploads to GitLab as an artifact.
 GitLab can display the results of one or more reports in:
 
 - The merge request [coverage fuzzing widget](../../user/application_security/coverage_fuzzing/index.md#interacting-with-the-vulnerabilities).
-- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security).
+- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline).
 - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md).
 - The [security dashboard](../../user/application_security/security_dashboard/index.md).
 
@@ -143,7 +143,7 @@ report uploads to GitLab as an artifact.
 GitLab can display the results of one or more reports in:
 
 - The merge request [security widget](../../user/application_security/dast/index.md#view-details-of-a-vulnerability-detected-by-dast).
-- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security).
+- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline).
 - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md).
 - The [security dashboard](../../user/application_security/security_dashboard/index.md).
 
@@ -155,7 +155,7 @@ The collected Dependency Scanning report uploads to GitLab as an artifact.
 GitLab can display the results of one or more reports in:
 
 - The merge request [dependency scanning widget](../../user/application_security/dependency_scanning/index.md#overview).
-- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security).
+- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline).
 - The [security dashboard](../../user/application_security/security_dashboard/index.md).
 - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md).
 - The [dependency list](../../user/application_security/dependency_list/).

doc/development/integrations/secure.md

@@ -440,8 +440,7 @@ Not all vulnerabilities have CVEs, and a CVE can be identified multiple times. A
 isn't a stable identifier and you shouldn't assume it as such when tracking vulnerabilities.
 
 The maximum number of identifiers for a vulnerability is set as 20. If a vulnerability has more than 20 identifiers,
-the system saves only the first 20 of them. Note that vulnerabilities in the [Pipeline
-Security](../../user/application_security/security_dashboard/#pipeline-security)
+the system saves only the first 20 of them. Note that vulnerabilities in the [Pipeline Security](../../user/application_security/security_dashboard/#view-vulnerabilities-in-a-pipeline)
 tab do not enforce this limit and all identifiers present in the report artifact are displayed.
 
 ### Details

doc/user/analytics/index.md

@@ -23,7 +23,7 @@ in one place.
 
 GitLab provides several analytics features at the group level. Some of these features require you to use a higher tier than GitLab Free.
 
-- [Application Security](../application_security/security_dashboard/#group-security-dashboard)
+- [Application Security](../application_security/security_dashboard/index.md)
 - [Contribution](../group/contribution_analytics/index.md)
 - [DevOps Adoption](../group/devops_adoption/index.md)
 - [Insights](../group/insights/index.md)
@@ -36,7 +36,7 @@ GitLab provides several analytics features at the group level. Some of these fea
 
 You can use GitLab to review analytics at the project level. Some of these features require you to use a higher tier than GitLab Free.
 
-- [Application Security](../application_security/security_dashboard/#project-security-dashboard)
+- [Application Security](../application_security/security_dashboard/index.md)
 - [CI/CD](ci_cd_analytics.md)
 - [Code Review](code_review_analytics.md)
 - [Insights](../project/insights/index.md)

doc/user/application_security/index.md

@@ -172,7 +172,7 @@ From the merge request security widget, select **Expand** to unfold the widget,
 
 A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch and existing vulnerabilities that were already present when the branch was created. These results likely do not match the findings displayed in the Merge Request security widget as those do not include the existing vulnerabilities (with the exception of showing any existing vulnerabilities that are no longer detected in the feature branch).
 
-For more details, see [security tab](security_dashboard/index.md#pipeline-security).
+For more details, see [security tab](security_dashboard/index.md#view-vulnerabilities-in-a-pipeline).
 
 ## View security scan information in the Security Dashboard
 
@@ -406,9 +406,9 @@ sast:
 You can interact with the results of the security scanning tools in several locations:
 
 - [Scan information in merge requests](#view-security-scan-information-in-merge-requests)
-- [Project Security Dashboard](security_dashboard/#project-security-dashboard)
-- [Security pipeline tab](security_dashboard/#pipeline-security)
-- [Group Security Dashboard](security_dashboard/#group-security-dashboard)
+- [Project Security Dashboard](security_dashboard/index.md)
+- [Security pipeline tab](security_dashboard/index.md)
+- [Group Security Dashboard](security_dashboard/index.md)
 - [Security Center](security_dashboard/#security-center)
 - [Vulnerability Report](vulnerability_report/index.md)
 - [Vulnerability Pages](vulnerabilities/index.md)

doc/user/application_security/security_dashboard/index.md

@@ -11,189 +11,186 @@ INFO:
 Want to try out security scanning?
 [Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-security-dashboard-docs).
 
-GitLab provides a comprehensive set of features for viewing and managing vulnerabilities:
+You can use Security Dashboards to view details about vulnerabilities
+detected by [security scanners](../index.md#security-scanning-tools).
+These details are shown in pipelines, projects, and groups.
 
-- Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [groups](#group-security-dashboard), and
-  [projects](#project-security-dashboard).
-- [Vulnerability reports](../vulnerability_report/index.md): Detailed lists of all vulnerabilities for the Security Center, group, project, or
-  pipeline. This is where you triage and manage vulnerabilities.
-- [Security Center](#security-center): A dedicated area for personalized vulnerability management. This
-  includes a security dashboard, vulnerability report, and settings.
+To use the Security Dashboards, you must:
 
-You can also drill down into a vulnerability and get extra information on the
-[Vulnerability Page](../vulnerabilities/index.md). This view includes the project it
-comes from, any related file(s), and metadata that helps you analyze the risk it poses.
-You can also confirm, dismiss, or resolve a vulnerability, create an issue for it,
-and in some cases, generate a merge request to fix the vulnerability.
+- Configure at least one [security scanner](../index.md#security-scanning-tools) in a project.
+- Configure jobs to use the [`reports` syntax](../../../ci/yaml/index.md#artifactsreports).
+- Use [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or later. If you use the
+  shared runners on GitLab.com, you are using the correct version.
 
-To benefit from these features, you must first configure one of the
-[security scanners](../index.md).
+## When Security Dashboards are updated
 
-## Supported reports
+The Security Dashboards show results of the most recent security scan on the
+[default branch](../../project/repository/branches/default.md).
+Security scans run only when the default branch updates, so
+information on the Security Dashboard might not reflect newly-discovered vulnerabilities.
 
-The security dashboard and vulnerability report displays information about vulnerabilities detected by scanners such as:
+To run a daily security scan,
+[configure a scheduled pipeline](../../../ci/pipelines/schedules.md).
 
-- [Container Scanning](../container_scanning/index.md)
-- [Dynamic Application Security Testing](../dast/index.md)
-- [Dependency Scanning](../dependency_scanning/index.md)
-- [Static Application Security Testing](../sast/index.md)
-- [Cluster Image Scanning](../cluster_image_scanning/index.md)
-- And [others](../index.md#security-scanning-tools)!
+## Reduce false negatives in dependency scans
 
-## Prerequisites
+WARNING:
+False negatives occur when you resolve dependency versions during a scan, which differ from those
+resolved when your project built and released in a previous pipeline.
 
-1. At least one project inside a group must be configured with at least one of
-   the [supported reports](#supported-reports).
-1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/index.md#artifactsreports).
-1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used.
-   If you're using the shared runners on GitLab.com, this is already the case.
+To reduce false negatives in [dependency scans](../../../user/application_security/dependency_scanning/index.md) in scheduled pipelines, ensure you:
 
-## Pipeline Security
+- Include a lock file in your project. A lock file lists all transient dependencies and tracks their versions.
+  - Java projects can't have lock files.
+  - Python projects can have lock files, but GitLab Secure tools don't support them.
+- Configure your project for [Continuous Delivery](../../../ci/introduction/index.md).
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3.
+## View vulnerabilities in a pipeline
 
-At the pipeline level, the Security section displays the vulnerabilities present in the branch of
-the project the pipeline ran against.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3.
 
-![Pipeline Security Dashboard](img/pipeline_security_dashboard_v14_4.png)
+To view vulnerabilities in a pipeline:
 
-Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view
-the pipeline's security findings, select the **Security** tab when viewing the pipeline.
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **CI/CD > Pipelines**.
+1. Select the **Status** of a branch.
+1. Select the **Security** tab.
 
-A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish
-for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST
+A pipeline consists of multiple jobs, such as SAST and DAST scans. If a job fails to finish,
+the security dashboard doesn't show SAST scanner output. For example, if the SAST
 job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure,
-the analyzer outputs an
-[exit code](../../../development/integrations/secure.md#exit-code).
+the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code).
+
+## View total number of vulnerabilities per scan
+
+To view the total number of vulnerabilities per scan:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **CI/CD > Pipelines**.
+1. Select the **Status** of a branch.
+1. Select the **Security** tab.
 
-### Scan details
+**Scan details** show the total number of vulnerabilities found per scan in the pipeline.
+
+### Download security scan outputs
 
 > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10.
 > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/333660) in GitLab 14.2.
 
-The **Scan details** section lists the scans run in the pipeline and the total number of vulnerabilities
-per scan.
+Depending on the type of security scanner, you can download:
+
+- A JSON artifact that contains the security scanner [report]('https://docs.gitlab.com/ee/development/integrations/secure.html#report').
+- A CSV file that contains URLs and endpoints scanned by the security scanner.
+
+To download a security scan output:
 
-You can download the JSON artifacts from each security scan. Select **Download results** then
-select the JSON artifact. Additionally for the DAST scan, from the **Download results** dropdown select
-**Download scanned resources** to download a CSV file containing details of the resources scanned.
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **CI/CD > Pipelines**.
+1. Select the **Status** of a branch.
+1. Select the **Security** tab.
+1. In **Scan details**, select **Download results**:
+   - To download a JSON file, select the JSON artifact.
+   - To download a CSV file, select **Download scanned resources**.
 
-## Project Security Dashboard
+## View vulnerabilities over time for a project
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in GitLab 13.6.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285476) in GitLab 13.10, options to zoom in on a date range, and download the vulnerabilities chart.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualize data between given dates.
 
-A project's Security Dashboard displays a chart with the total number of vulnerabilities
-over time with up to 365 days of historical data. Data is refreshed daily at 1:15am UTC. By default,
-it shows statistics for all vulnerability severities.
+The project Security Dashboard shows the total number of vulnerabilities
+over time, with up to 365 days of historical data. Data refreshes daily at 01:15 UTC.
+It shows statistics for all vulnerabilities.
 
-To access the dashboard, from your project's home page go to **Security & Compliance > Security Dashboard**.
+To view total number of vulnerabilities over time:
 
-![Project Security Dashboard](img/project_security_dashboard_chart_v13_11.png)
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Security & Compliance > Security Dashboard**.
+1. Filter and search for what you need.
+   - To filter the chart by severity, select the legend name.
+   - To view a specific time frame, use the time range handles (**{scroll-handle}**).
+   - To view a specific area of the chart, select the left-most icon (**{marquee-selection}**) and drag
+     across the chart.
+   - To reset to the original range, select **Remove Selection** (**{redo}**).
 
-### Filter the vulnerabilities chart
+### Download the vulnerabilities chart
 
-To filter the chart by vulnerability severity, select the corresponding legend name.
+To download an SVG image of the vulnerabilities chart:
 
-In the previous example, the chart shows statistics only for vulnerabilities of medium or unknown severity.
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Security & Compliance > Security dashboard**.
+1. Select **Save chart as an image** (**{download}**).
 
-### Customize vulnerabilities chart display
+## View vulnerabilities over time for a group
 
-To customize the view of the vulnerability chart, you can select:
+The group Security Dashboard gives an overview of vulnerabilities found in the default
+branches of projects in a group and its subgroups.
 
-- A specific time frame by using the time range handles (**{scroll-handle}**).
-- A specific area of the chart by using the left-most icon (**{marquee-selection}**) then drag
-  across the chart. To reset to the original range, select **Remove Selection** (**{redo}**).
+To view vulnerabilities over time for a group:
 
-### Download a copy of the vulnerabilities chart
+1. On the top bar, select **Menu > Groups** and select a group.
+1. Select **Security > Security Dashboard**.
+1. Hover over the chart to get more details about vulnerabilities.
+   - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days).
+   - To view aggregated data beyond a 90-day time frame, use the 
+     [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday).
+     GitLab retains the data for 365 days.
 
-To download an SVG image of the chart, select **Save chart to an image** (**{download}**).
+## View project security status for a group
 
-## Group Security Dashboard
+Use the group Security Dashboard to view the security status of projects. The security status is based
+on the number of detected vulnerabilities.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in GitLab 11.5.
+To view project security status for a group:
 
-The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the
-projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard**
-after selecting your group. By default, the Security Dashboard displays all detected and confirmed
-vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you
-have not selected a group.
+1. On the top bar, select **Menu > Groups** and select a group.
+1. Select **Security > Security Dashboard**.
 
-Note that the Security Dashboard only shows projects with
-[security reports](#supported-reports)
-enabled in a group.
+Projects are [graded](#project-vulnerability-grades) by vulnerability severity. Dismissed vulnerabilities are excluded.
 
-![Dashboard with action buttons and metrics](img/group_security_dashboard_v13_3.png)
+To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md).
 
-There is a timeline chart that shows how many open
-vulnerabilities your projects had at various points in time. You can display the vulnerability
-trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get
-more details about the open vulnerabilities at a specific time. Aggregated data beyond 90 days can be accessed by querying our [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). This data is retained for 365 days.
-
-Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found:
+### Project vulnerability grades
 
 | Grade | Description |
-| F | One or more "critical" |
-| D | One or more "high" or "unknown" |
-| C | One or more "medium" |
-| B | One or more "low" |
-| A | Zero vulnerabilities |
-
-Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed
-vulnerabilities are excluded.
-
-Navigate to the group's [vulnerability report](../vulnerability_report/index.md) to view the vulnerabilities found.
+| --- | --- |
+| **F** | One or more `critical` vulnerabilities |
+| **D** | One or more `high` or `unknown` vulnerabilities |
+| **C** | One or more `medium` vulnerabilities |
+| **B** | One or more `low` vulnerabilities |
+| **A** | Zero vulnerabilities |
 
 ## Security Center
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in GitLab 13.4.
 
-The Security Center is personal space where you manage vulnerabilities across all your projects. It
-displays the vulnerabilities present in the default branches of all the projects you configure. It includes
-the following:
+The Security Center is a personal space where you view vulnerabilities across all your projects. It
+shows the vulnerabilities present in the default branches of the projects.
+
+The Security Center includes:
 
-- The [group security dashboard's](#group-security-dashboard) features.
+- The group Security Dashboard.
 - A [vulnerability report](../vulnerability_report/index.md).
-- A dedicated settings area to configure which projects to display.
+- A settings area to configure which projects to display.
 
 ![Security Center Dashboard with projects](img/security_center_dashboard_v13_4.png)
 
+### View the Security Center
+
 To view the Security Center, on the top bar, select **Menu > Security**.
 
-### Adding projects to the Security Center
+### Add projects to the Security Center
 
 To add projects to the Security Center:
 
-1. Click **Settings** in the left navigation bar or click the **Add projects** button.
-1. Search for and add one or more projects using the **Search your projects** field.
-1. Click the **Add projects** button.
+1. On the top bar, select **Menu > Security**.
+1. On the left sidebar, select **Settings**, or select **Add projects**.
+1. Use the **Search your projects** text box to search for and select projects.
+1. Select **Add projects**.
 
-![Adding projects to Security Center](img/security_center_settings_v13_4.png)
-
-After you add projects, the security dashboard and vulnerability report display the vulnerabilities
+After you add projects, the security dashboard and vulnerability report show the vulnerabilities
 found in those projects' default branches.
 
-## Keep dashboards up to date
-
-The Security Dashboard displays results of the most recent security scan on the
-[default branch](../../project/repository/branches/default.md). By default, security scans are run
-only when the default branch is updated. Information on the Security Dashboard may not reflect
-newly-discovered vulnerabilities.
-
-To ensure the information on the Security Dashboard is regularly updated,
-[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a daily security scan.
-This updates the information displayed on the Security Dashboard regardless of how often the default
-branch is updated.
-
-WARNING:
-Running Dependency Scanning from a scheduled pipeline might result in false negatives if your
-project doesn't have a lock file and isn't configured for Continuous Delivery. A lock file is a file
-that lists all transient dependencies and keeps track of their exact versions. The false negative
-can occur because the dependency version resolved during the scan might differ from the ones
-resolved when your project was built and released, in a previous pipeline. Java projects can't have
-lock files. Python projects can have lock files, but GitLab Secure tools don't support them.
-
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues
@@ -206,4 +203,8 @@ Each scenario can be a third-level heading, e.g. `### Getting error message X`.
 If you have none to add when creating a doc, leave this section in place
 but commented out to help encourage others to add to it in the future. -->
 
-Read more on how to [address the vulnerabilities](../vulnerabilities/index.md).
+## Related topics
+
+- [Address the vulnerabilities](../vulnerabilities/index.md)
+- [Vulnerability reports](../vulnerability_report/index.md)
+- [Vulnerability Page](../vulnerabilities/index.md)

doc/user/application_security/vulnerability_report/index.md

@@ -100,7 +100,7 @@ The content of the Project filter depends on the current level:
 
 | Level          | Content of the Project filter |
 |:---------------|:------------------------------|
-| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). |
+| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#add-projects-to-the-security-center). |
 | Group level    | All projects in the group. |
 | Project level  | Not applicable. |