Merge branch 'russell/schartz-application-security-default-behavior-explanation' into 'master'

Describe default behaviour of GitLab security scanning tools

See merge request gitlab-org/gitlab!61557

doc/user/application_security/index.md

@@ -104,6 +104,47 @@ rules:
   - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 ```
 
+## Security Scanning with Auto DevOps
+
+When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools are configured using default settings.
+
+- [Auto SAST](../../topics/autodevops/stages.md#auto-sast)
+- [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection)
+- [Auto DAST](../../topics/autodevops/stages.md#auto-dast)
+- [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning)
+- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance)
+- [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning)
+
+While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customizing-gitlab-ciyml).
+
+## Default behavior of GitLab security scanning tools
+
+### Secure jobs in your pipeline
+
+If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#security-scanning-tools) behave as described below.
+
+For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch. Please note that one tool may use many analyzers.
+
+Our language and package manager specific jobs attempt to assess which analyzer(s) they should run for your project so that you can do less configuration.
+
+If you want to override this to increase the pipeline speed you may choose which analyzers to exclude if you know they are not applicable (languages or package managers not contained in your project) by following variable customization directions for that specific tool.
+
+### Secure job status
+
+Jobs pass if they are able to complete a scan. A _pass_ result does NOT indicate if they did, or did not, identify findings. The only exception is coverage fuzzing, which fails if it identifies findings.
+
+Jobs fail if they are unable to complete a scan. You can view the pipeline logs for more information.
+
+All jobs are permitted to fail by default. This means that if they fail it do not fail the pipeline.
+
+If you want to prevent vulnerabilities from being merged, you should do this by adding [Security Approvals in Merge Requests](#security-approvals-in-merge-requests) which prevents unknown, high or critical findings from being merged without an approval from a specific group of people that you choose.
+
+We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/README.md#allow_failure) as that fails the entire pipeline.
+
+### JSON Artifact
+
+The artifact generated by the secure analyzer contains all findings it discovers on the target branch, regardless of whether they were previously found, dismissed, or completely new (it puts in everything that it finds).
+
 ## View security scan information in merge requests **(FREE)**
 
 > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5.
@@ -111,12 +152,44 @@ rules:
 > - Report download dropdown [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249550) in GitLab 13.9.
 
+### All tiers
+
 Merge requests which have run security scans let you know that the generated
 reports are available to download. To download a report, click on the
 **Download results** dropdown, and select the desired report.
 
 ![Security widget](img/security_widget_v13_7.png)
 
+### Ultimate
+
+A merge request contains a security widget which displays a summary of the NEW results. New results are determined by comparing the current findings against existing findings in the target (default) branch (if there are prior findings).
+
+We recommended you run a scan of the `default` branch before enabling feature branch scans for your developers. Otherwise, there is no base for comparison and all feature branches display the full scan results in the merge request security widget.
+
+The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both NEW and EXISTING findings.
+
+From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View Full Report** to go directly to the **Security** tab in the latest branch pipeline.
+
+## View security scan information in the pipeline Security tab
+
+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).
+
+## View security scan information in the Security Dashboard
+
+The Security Dashboard show vulnerabilities present in a project's default branch. Data is updated every 24 hours. Vulnerability count updates resulting from any feature branches introducing new vulnerabilities that are merged to default are included after the daily data refresh.
+
+For more details, see [Security Dashboard](security_dashboard/index.md).
+
+## View security scan information in the Vulnerability Report
+
+The vulnerability report shows the results of the last completed pipeline on the default branch. It is updated on every pipeline completion. All detected vulnerabilities are shown as well as any previous ones that are no longer detected in the latest scan. Vulnerabilities that are no longer detected may have been remediated or otherwise removed and can be marked as `Resolved` after proper verification. Vulnerabilities that are no longer detected are denoted with an icon for filtering and review.
+
+By default, the vulnerability report does not show vulnerabilities of `dismissed` or `resolved` status so you can focus on open vulnerabilities. You can change the Status filter to see these.
+
+[Read more about the Vulnerability report](vulnerability_report/index.md).
+
 ## Security approvals in merge requests
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2.
@@ -258,6 +331,10 @@ You can do it quickly by following the hyperlink given to run a new pipeline.
 
 ![Run a new pipeline](img/outdated_report_pipeline_v12_9.png)
 
+## DAST On-Demand Scans
+
+If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report.
+
 ## Security report validation
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11.
@@ -298,6 +375,26 @@ For example, the configuration below enables validation for only the `sast` job:
     stage: security-scan
   ```
 
+## Interacting with findings and vulnerabilities
+
+There are a variety of locations and ways to interact with the results of the security scanning tools:
+
+- [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)
+- [Security Center](security_dashboard/#security-center)
+- [Vulnerability Report](vulnerability_report/index.md)
+- [Vulnerability Pages](vulnerabilities/index.md)
+- [Dependency List](dependency_list/index.md)
+
+For more details about which findings or vulnerabilities you can view in each of those locations, select the respective link. Each page details the ways in which you can interact with the findings and vulnerabilities. As an example, in most cases findings start out as _detected_ status. You have the option to:
+
+- 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).
+
 ## Troubleshooting
 
 ### Getting error message `sast job: stage parameter should be [some stage name here]`