diff options
Diffstat (limited to 'doc/user/application_security/security_dashboard/index.md')
| -rw-r--r-- | doc/user/application_security/security_dashboard/index.md | 245 |
1 files changed, 121 insertions, 124 deletions
diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 5afbe1ca54e..937ca33c3a1 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -7,193 +7,186 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboards and Security Center **(ULTIMATE)** -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). +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. -GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: +To use the Security Dashboards, you must: -- 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. +- 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. -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. +## When Security Dashboards are updated -To benefit from these features, you must first configure one of the -[security scanners](../index.md). +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. -## Supported reports +To run a daily security scan, +[configure a scheduled pipeline](../../../ci/pipelines/schedules.md). -The security dashboard and vulnerability report displays information about vulnerabilities detected by scanners such as: +## Reduce false negatives in dependency scans -- [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)! +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. -## Prerequisites +To reduce false negatives in [dependency scans](../../../user/application_security/dependency_scanning/index.md) in scheduled pipelines, ensure you: -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. +- 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). -## Pipeline Security +## View vulnerabilities in a pipeline > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. -At the pipeline level, the Security section displays the vulnerabilities present in the branch of -the project the pipeline ran against. - - +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. From the list, select the pipeline you want to check for vulnerabilities. +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: - +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. - +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.  +### 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**. - - -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 +199,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) |