Merge branch 'docs-policies-reorg' into 'master'

Reorganize security policy docs

See merge request gitlab-org/gitlab!80111

doc/user/application_security/dast/index.md

@@ -1196,7 +1196,7 @@ To edit an existing site profile:
 1. Edit the fields then select **Save profile**.
 
 If a site profile is linked to a security policy, a user cannot edit the profile from this page. See
-[Scan Execution Policies](../policies/index.md#scan-execution-policy-editor)
+[Scan execution policies](../policies/scan-execution-policies.md)
 for more information.
 
 #### Delete a site profile
@@ -1210,7 +1210,7 @@ To delete an existing site profile:
 1. Select **Delete** to confirm the deletion.
 
 If a site profile is linked to a security policy, a user cannot delete the profile from this page.
-See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor)
+See [Scan execution policies](../policies/scan-execution-policies.md)
 for more information.
 
 #### Validate a site profile
@@ -1353,7 +1353,7 @@ To edit a scanner profile:
 1. Select **Save profile**.
 
 If a scanner profile is linked to a security policy, a user cannot edit the profile from this page.
-See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor)
+See [Scan execution policies](../policies/scan-execution-policies.md)
 for more information.
 
 #### Delete a scanner profile
@@ -1367,7 +1367,7 @@ To delete a scanner profile:
 1. Select **Delete**.
 
 If a scanner profile is linked to a security policy, a user cannot delete the profile from this
-page. See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor)
+page. See [Scan execution policies](../policies/scan-execution-policies.md)
 for more information.
 
 ## Auditing

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

+---
+stage: Protect
+group: Container Security
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Scan result policies **(ULTIMATE)**
+
+You can use scan result policies to take action based on scan results. For example, one type of scan
+result policy is a security approval policy that allows approval to be required based on the
+findings of one or more security scan jobs. Scan result policies are evaluated after a CI scanning
+job is fully executed.
+
+## Scan result policy editor
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8 with a flag named `scan_result_policy`. Disabled by default.
+
+NOTE:
+Only project Owners have the [permissions](../../permissions.md#project-members-permissions)
+to select Security Policy Project.
+
+Once your policy is complete, save it by selecting **Create merge request** at the bottom of the
+editor. This redirects you to the merge request on the project's configured security policy project.
+If a security policy project doesn't link to your project, GitLab creates such a project for you.
+Existing policies can also be removed from the editor interface by selecting **Delete policy** at
+the bottom of the editor.
+
+All scan result policy changes are applied through a background job that runs once every 10 minutes.
+Allow up to 10 minutes for any policy changes committed to this project to take effect.
+
+The policy editor only supports YAML mode. To follow work on Rule mode, see the epic
+[Allow Users to Edit Rule-mode scan result policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363).
+
+![Scan Result Policy Editor YAML Mode](img/scan_result_policy_yaml_mode_v14_6.png)
+
+## Scan result policies schema
+
+The YAML file with scan result policies consists of an array of objects matching the scan result
+policy schema nested under the `scan_result_policy` key. You can configure a maximum of five
+policies under the `scan_result_policy` key.
+
+When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json).
+If you're not familiar with how to read [JSON schemas](https://json-schema.org/),
+the following sections and tables provide an alternative.
+
+| Field | Type | Possible values | Description |
+|-------|------|-----------------|-------------|
+| `scan_result_policy` | `array` of Scan Result Policy |  | List of scan result policies (maximum 5). |
+
+## Scan result policy schema
+
+| Field | Type | Possible values | Description |
+|-------|------|-----------------|-------------|
+| `name` | `string` |  | Name of the policy. |
+| `description` (optional) | `string` |  | Description of the policy. |
+| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. |
+| `rules` | `array` of rules |  | List of rules that the policy applies. |
+| `actions` | `array` of actions |  | List of actions that the policy enforces. |
+
+## `scan_finding` rule type
+
+This rule enforces the defined actions based on the information provided.
+
+| Field      | Type | Possible values | Description |
+|------------|------|-----------------|-------------|
+| `type`     | `string` | `scan_finding` | The rule's type. |
+| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). |
+| `scanners`  | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. |
+| `vulnerabilities_allowed`  | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. |
+| `severity_levels`  | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. |
+| `vulnerability_states`  | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. |
+
+## `require_approval` action type
+
+This action sets an approval rule to be required when conditions are met for at least one rule in
+the defined policy.
+
+| Field | Type | Possible values | Description |
+|-------|------|-----------------|-------------|
+| `type` | `string` | `require_approval` | The action's type. |
+| `approvals_required` | `integer` | Greater than or equal to zero | The number of MR approvals required. |
+| `user_approvers` | `array` of `string` | Username of one of more users | The users to consider as approvers. |
+| `user_approvers_ids` | `array` of `integer` | ID of one of more users | The IDs of users to consider as approvers. |
+| `group_approvers` | `array` of `string` | Path of one of more groups | The groups to consider as approvers. |
+| `group_approvers_ids` | `array` of `integer` | ID of one of more groups | The IDs of groups to consider as approvers. |
+
+Requirements and limitations:
+
+- You must add the respective [security scanning tools](../index.md#security-scanning-tools).
+  Otherwise, scan result policies won't have any effect.
+- The maximum number of policies is five.
+- Each policy can have a maximum of five rules.
+
+## Example security scan result policies project
+
+You can use this example in a `.gitlab/security-policies/policy.yml`, as described in
+[Security policies project](index.md#security-policies-project):
+
+```yaml
+---
+scan_result_policy:
+- name: critical vulnerability CS approvals
+  description: critical severity level only for container scanning
+  enabled: true
+  rules:
+  - type: scan_finding
+    branches:
+    - main
+    scanners:
+    - container_scanning
+    vulnerabilities_allowed: 0
+    severity_levels:
+    - critical
+    vulnerability_states:
+    - newly_detected
+  actions:
+  - type: require_approval
+    approvals_required: 1
+    user_approvers:
+    - adalberto.dare
+- name: secondary CS approvals
+  description: secondary only for container scanning
+  enabled: true
+  rules:
+  - type: scan_finding
+    branches:
+    - main
+    scanners:
+    - container_scanning
+    vulnerabilities_allowed: 1
+    severity_levels:
+    - low
+    - unknown
+    vulnerability_states:
+    - newly_detected
+  actions:
+  - type: require_approval
+    approvals_required: 1
+    user_approvers:
+    - sam.white
+```
+
+In this example:
+
+- Every MR that contains new `critical` vulnerabilities identified by container scanning requires
+  one approval from `alberto.dare`.
+- Every MR that contains more than one new `low` or `unknown` vulnerability identified by container
+  scanning requires one approval from `sam.white`.
+
+## Example for Scan Result Policy editor
+
+You can use this example in the YAML mode of the [Scan Result Policy editor](#scan-result-policy-editor).
+It corresponds to a single object from the previous example:
+
+```yaml
+- name: critical vulnerability CS approvals
+  description: critical severity level only for container scanning
+  enabled: true
+  rules:
+  - type: scan_finding
+    branches:
+    - main
+    scanners:
+    - container_scanning
+    vulnerabilities_allowed: 1
+    severity_levels:
+    - critical
+    vulnerability_states:
+    - newly_detected
+  actions:
+  - type: require_approval
+    approvals_required: 1
+    user_approvers:
+    - adalberto.dare
+```