Merge branch 'g.hickman-srp-approval-logic' into 'master'

Explain scan result policy approval scenarios

See merge request !134703



Merged-by: Grant Hickman <ghickman@gitlab.com>

doc/user/application_security/policies/scan-result-policies.md

@@ -279,7 +279,22 @@ actions:
   - adalberto.dare
 ```
 
-## Example situations where scan result policies require additional approval
+## Understanding scan result policy approvals 
+
+### Scope of scan result policy comparison
+
+- To determine when approval is required on a merge request, we compare the latest completed pipelines for each supported pipeline source for the source and target branch (e.g. feature/main). This ensures the most comprehensive evaluation of scan results.
+- We compare findings from the `main tip` of the target branch.
+- Scan result policies consider multiple pipeline sources (based on the [CI_PIPELINE_SOURCE variable](../ci/variables/predefined_variables.html)) when comparing results from each branch and determining when a merge request requires approval. Pipeline sources that are supported include: `:unknown`, `:push`, `:web`,`:trigger`, `:schedule`, `:api`, `:external`, `:pipeline`, `:chat`, `:merge_request_event`, `:external_pull_request_event`, `:security_orchestration_policy`.
+- The following pipeline sources are currently unsupported in scan result policies: `:webide`,`parent_pipeline`.
+
+### Accepting risk and ignoring vulnerabilities in future merge requests
+
+For policies that are scoped to `newly_detected` findings, approved merge requests create "exceptions" to the policy for future merge requests. Any findings that violate a policy that are merged into the `default` branch are used in future scan result policy evaluations and therefore are no longer "newly detected".
+
+For license approval policies, if a license is approved as an exception, future merge requests will no longer require approval for the same combination of license + dependency/component + project. The component version will not be considered in this case. If a previously approved package gets updated to a new version, approvers will not need to re-approve.
+
+### Multiple approvals
 
 There are several situations where the scan result policy requires an additional approval step. For example:
 
@@ -296,3 +311,10 @@ There are several situations where the scan result policy requires an additional
 - Someone stops a pipeline security job, and users can't skip the security scan.
 - A job in a merge request fails and is configured with `allow_failure: false`. As a result, the pipeline is in a blocked state.
 - A pipeline has a manual job that must run successfully for the entire pipeline to pass.
+
+### Known issues
+
+We are identifying common areas of confusion in scan result findings in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/11020) to be addressed. Below are a few of the known issues:
+
+- When using `newly_detected`, some findings may require approval when they are not introduced by the merge request (such as a new CVE on a related dependency). We currently use `main tip` of the target branch for comparison. In the future, we plan to use `merge base` for `newly_detected` policies (see [epic](https://gitlab.com/gitlab-org/gitlab/-/issues/428518)).
+- Findings or errors that cause approval to be required on a scan result policy may not be evident in the Security MR Widget. By using `merge base` in [this epic](https://gitlab.com/gitlab-org/gitlab/-/issues/428518) some cases will be addressed. We will additionally be [displaying more granular details](https://gitlab.com/groups/gitlab-org/-/epics/11185) about what caused security policy violations.