Merge branch 'rd-combine-policy-scope-docs' into 'master'

Combine scope policy docs

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164144



Merged-by: Artur Fedorov <afedorov@gitlab.com>
Approved-by: Grant Hickman <ghickman@gitlab.com>
Approved-by: Ryan Lehmann <rlehmann@gitlab.com>
Approved-by: Artur Fedorov <afedorov@gitlab.com>
Reviewed-by: Evan Read <eread@gitlab.com>
Reviewed-by: Artur Fedorov <afedorov@gitlab.com>
Reviewed-by: Ryan Lehmann <rlehmann@gitlab.com>
Co-authored-by: Russell Dickenson <rdickenson@gitlab.com>

doc/user/application_security/policies/index.md

@@ -54,16 +54,26 @@ When designing your policies, your goals should be to:
 - Design policy enforcement for minimum overhead but maximum coverage
 - Ensure separation of duties
-### Policy enforcement design
-To maximize policy coverage, link a security policy project at the highest level that achieves your objectives: group
-level, subgroup level, or project level. Enforcement at the highest level minimizes the number of
-security policy projects and therefore the management overhead. Policies cascade down from each level to a project, such that policies may be enforced from the group level, each subgroup above it, and then for any policies created at the project level itself.
-Policy inheritance not only ensures maximum coverage with the minimum
-number of security policy projects, but also helps when implementing policy changes. For example, to test a policy change
-you could copy an existing policy and enforce the modified policy first to a project, then to a
-subgroup, and, if applicable, to a group.
+### Enforcement
+To enforce policies to meet your requirements, consider the following factors:
+- **Inheritance:** By default, a policy is enforced on the organizational units it's linked to, and
+  all their descendent subgroups and their projects.
+- **Scope:** To customize policy enforcement, you can define a policy's scope to match your needs.
+
+#### Inheritance
+
+To maximize policy coverage, link a security policy project to the highest organizational units that
+achieves your objectives: groups, subgroups, or projects. A policy is enforced on the organizational
+units it's linked to, and all their descendent subgroups and their projects. Enforcement at the
+highest point minimizes the number of security policies required, minimizing the management
+overhead.
+
+You can use policy inheritance to incrementally roll out policies. For example, when rolling out a
+new policy, you can enforce it on a single project, then conduct testing. If the tests pass, you can
+then remove it from the project and enforce it on a group, moving up the hierarchy until the policy
+is enforced on all applicable projects.
 Policies enforced on an existing group or subgroup are automatically enforced in any new subgroups and projects created under them, provided that all of the following are true:
@@ -71,7 +81,9 @@ Policies enforced on an existing group or subgroup are automatically enforced in
 - The existing group or subgroup is already linked to the security policy project.
 NOTE:
-GitLab SaaS users may enforce policies against their top-level group or across subgroups, but cannot enforce policies across GitLab SaaS top-level groups. GitLab self-managed users can enforce policies across multiple top-level groups in their instance.
+GitLab SaaS users can enforce policies against their top-level group or across subgroups, but cannot
+enforce policies across GitLab SaaS top-level groups. GitLab self-managed users can enforce policies
+across multiple top-level groups in their instance.
 The following example illustrates two groups and their structure:
@@ -105,9 +117,88 @@ Assuming no policies are enforced, consider the following examples:
   "SAST" policy applies to project A.
 - If the "SAST" policy is enforced at subgroup "Accounts receiving", it applies only to projects B
   and C. No policy applies to project A.
-- If the "Secret Detection" is enforced at project K, it applies only to project K. No other
+- If the "Secret Detection" policy is enforced at project K, it applies only to project K. No other
   subgroups or projects have a policy apply to them.
+#### Scope
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135398) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_policy_scope`. Enabled by default.
+> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443594) in GitLab 16.11. Feature flag `security_policies_policy_scope` removed.
+> - Scoping by group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468384) in GitLab 17.4.
+
+You can refine a policy's scope by:
+
+- Compliance frameworks: Enforce a policy on projects with selected compliance frameworks.
+- Group:
+  - All projects in a group, including all its descendent subgroups and their projects. Optionally
+    exclude specific projects.
+  - All projects in multiple groups, including their descendent subgroups and their projects. Only
+    groups linked to the same security policy project can be listed in the policy. Optionally
+    exclude specific projects.
+- Projects: Include or exclude specific projects. Only projects linked to the same security policy
+  project can be listed in the policy.
+
+These options can be used together in the same policy. However, exclusion takes precedence over
+inclusion.
+
+##### `policy_scope` keyword
+
+Use the `policy_scope` keyword to enforce the policy on only those groups, projects, compliance
+frameworks, or a combination, that you specify.
+
+| Field                   | Type     | Possible values          | Description |
+|-------------------------|----------|--------------------------|-------------|
+| `compliance_frameworks` | `array`  | Not applicable           | List of IDs of the compliance frameworks in scope for enforcement, in an array of objects with key `id`. |
+| `projects`              | `object` | `including`, `excluding` | Use `excluding:` or `including:` then list the IDs of the projects you wish to include or exclude, in an array of objects with key `id`. |
+| `groups`                | `object` | `including`              | Use `including:` then list the IDs of the groups you wish to include, in an array of objects with key `id`. Only groups linked to the same security policy project can be listed in the policy. |
+
+##### Scope examples
+
+In this example, the scan execution policy enforces a SAST scan in every release pipeline, on
+every project with the compliance frameworks with an ID either `2` or `11` applied to them.
+
+```yaml
+---
+scan_execution_policy:
+- name: Enforce specified scans in every release pipeline
+  description: This policy enforces a SAST scan for release branches
+  enabled: true
+  rules:
+  - type: pipeline
+    branches:
+    - release/*
+  actions:
+  - scan: sast
+  policy_scope:
+    compliance_frameworks:
+      - id: 2
+      - id: 11
+```
+
+In this example, the scan execution policy enforces a secret detection and SAST scan on pipelines
+for the default branch, on all projects in the group with ID `203` (including all descendent
+subgroups and their projects), excluding the project with ID `64`.
+
+```yaml
+- name: Enforce specified scans in every default branch pipeline
+  description: This policy enforces Secret Detection and SAST scans for the default branch
+  enabled: true
+  rules:
+  - type: pipeline
+    branches:
+    - main
+  actions:
+  - scan: secret_detection
+  - scan: sast
+  policy_scope:
+    groups:
+      including:
+        - id: 203
+    projects:
+      excluding:
+        - id: 64
+```
+
 ### Separation of duties
 Separation of duties is vital to successfully implementing policies. Implement policies that achieve

doc/user/application_security/policies/merge_request_approval_policies.md

@@ -121,9 +121,9 @@ When you save a new policy, GitLab validates its contents against [this JSON sch
 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                          | Required | Possible values | Description                               |
-|-------------------|-------------------------------|----------|-----------------|-------------------------------------------|
-| `approval_policy` | `array` of Merge Request Approval Policy | true     |                 | List of merge request approval policies (maximum 5). |
+| Field             | Type                                     | Required | Description                                          |
+|-------------------|------------------------------------------|----------|------------------------------------------------------|
+| `approval_policy` | `array` of merge request approval policy objects | true     | List of merge request approval policies (maximum 5). |
 ## Merge request approval policy schema
@@ -138,6 +138,7 @@ the following sections and tables provide an alternative.
 | `actions`           | `array` of actions | false    |                 | List of actions that the policy enforces.                |
 | `approval_settings` | `object`           | false    |                 | Project settings that the policy overrides.              |
 | `fallback_behavior` | `object`           | false    |                 | Settings that affect invalid or unenforceable rules.     |
+| `policy_scope`      | `object` of [`policy_scope`](index.md#scope) | false |  | Defines the scope of the policy based on the projects, groups, or compliance framework labels you specify. |
 ## `scan_finding` rule type
@@ -277,70 +278,11 @@ On self-managed GitLab, by default the `fallback_behavior` field is available. T
 |--------|----------|----------|--------------------|----------------------------------------------------------------------------------------------------------------------|
 | `fail` | `string` | false    | `open` or `closed` | `closed` (default): Invalid or unenforceable rules of a policy require approval. `open`: Invalid or unenforceable rules of a policy do not require approval. |
-## Security policy scopes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135398) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_policy_scope`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443594) in GitLab 16.11. Feature flag `security_policies_policy_scope` removed.
-> - Scoping by group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468384) in GitLab 17.4.
-
-Security policy enforcement depends first on establishing a link between the group, subgroup, or
-project on which you want to enforce policies, and the security policy project that contains the
-policies. For example, if you are linking policies to a group, a group owner must create the link to
-the security policy project. Then, all policies in the security policy project are inherited by all
-projects in the group.
-
-You can refine a security policy's scope to:
-
-- _Include_ only projects containing a compliance framework label.
-- _Include_ or _exclude_ selected projects from enforcement.
-- _Include_ selected groups. Optionally use this with the `projects` object to exclude selected projects.
-
-### Policy scope schema
-
-| Field | Type | Required | Possible values | Description |
-|-------|------|----------|-----------------|-------------|
-| `policy_scope` | `object` | false | `compliance_frameworks`, `projects`, `groups` | Scopes the policy based on compliance framework labels, projects, or groups you define. |
-
-### `policy_scope` scope type
-
-| Field | Type | Possible values | Description |
-|-------|------|-----------------|-------------|
-| `compliance_frameworks` | `array` |  | List of IDs of the compliance frameworks in scope of enforcement, in an array of objects with key `id`. |
-| `projects` | `object` |  `including`, `excluding` | Use `excluding:` or `including:` then list the IDs of the projects you wish to include or exclude, in an array of objects with key `id`. |
-| `groups` | `object` | `including` | Use `including:` then list the IDs of the groups you wish to include, in an array of objects with key `id`. |
-
-### Example `policy.yml` with security policy scopes
-
-```yaml
----
-approval_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: 1
-    severity_levels:
-    - critical
-    vulnerability_states: []
-  actions:
-  - type: require_approval
-    approvals_required: 1
-    user_approvers:
-    - adalberto.dare
-  policy_scope:
-    compliance_frameworks:
-      - id: 2
-      - id: 11
-    projects:
-      including:
-        - id: 24
-        - id: 27
-```
+## Policy scope schema
+To customize policy enforcement, you can define a policy's scope to either include or exclude
+specified projects, groups, or compliance framework labels. For more details, see
+[Scope](index.md#scope).
 ## Example security merge request approval policies project

doc/user/application_security/policies/pipeline_execution_policies.md

@@ -46,8 +46,8 @@ the following sections and tables provide an alternative.
 | `enabled` | `boolean` | true | Flag to enable (`true`) or disable (`false`) the policy. |
 | `content` | `object` of [`content`](#content-type) | true | Reference to the CI/CD configuration to inject into project pipelines. |
 | `pipeline_config_strategy` | `string` | false | Can either be `inject_ci` or `override_project_ci`. See [Pipeline strategies](#pipeline-strategies) for more information. |
+| `policy_scope` | `object` of [`policy_scope`](index.md#scope) | false | Scopes the policy based on projects, groups, or compliance framework labels you specify. |
 | `suffix` | `string` | false | Can either be `on_conflict` (default), or `never`. Defines the behavior for handling job naming conflicts. `on_conflict` applies a unique suffix to the job names for jobs that would break the uniqueness. `never` causes the pipeline to fail if the job names across the project and all applicable policies are not unique. |
-| `policy_scope` | `object` of [`policy_scope`](#policy_scope-scope-type) | false | Scopes the policy based on compliance framework labels or projects you define. |
 Note the following:
@@ -144,44 +144,11 @@ Prerequisites:
   Enabling this setting grants the user who triggered the pipeline access to 
   read the CI/CD configuration file enforced by the pipeline execution policy. This setting does not grant the user access to any other parts of the project where the configuration file is stored.
-### `policy_scope` scope type
-> - Scoping by group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468384) in GitLab 17.4.
-
-| Field | Type | Possible values | Description |
-|-------|------|-----------------|-------------|
-| `compliance_frameworks` | `array` |  | List of IDs of the compliance frameworks in scope of enforcement, in an array of objects with key `id`. |
-| `projects` | `object` | `including`, `excluding` | Use `excluding:` or `including:` then list the IDs of the projects you wish to include or exclude, in an array of objects with key `id`. |
-| `groups` | `object` | `including` | Use `including:` then list the IDs of the groups you wish to include, in an array of objects with key `id`. |
-
-For example:
-
-Projects with a specific compliance framework:
-
-```yaml
- policy_scope:
-  compliance_frameworks:
-    - id: 1020076
-```
-
-Only a specific set of projects:
-
-```yaml
-policy_scope:
-  projects:
-    including:
-      - id: 61213118
-      - id: 59560885
- ```
-
-All projects except one specific project:
-
-```yaml
-policy_scope:
-  projects:
-    excluding:
-      - id: 59560885
-```
+### Policy scope schema
+To customize policy enforcement, you can define a policy's scope to either include, or exclude,
+specified projects, groups, or compliance framework labels. For more details, see
+[Scope](index.md#scope).
 ## Pipeline strategies

doc/user/application_security/policies/scan_execution_policies.md

@@ -98,19 +98,20 @@ the following sections and tables provide an alternative.
 ## Scan execution policy schema
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/472213) in GitLab 17.4 [with flags](../../../administration/feature_flags.md) named `scan_execution_policy_action_limit` (for projects) and `scan_execution_policy_action_limit_group` (for groups). Disabled by default.
+> - Limit of actions per policy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/472213) in GitLab 17.4 [with flags](../../../administration/feature_flags.md) named `scan_execution_policy_action_limit` (for projects) and `scan_execution_policy_action_limit_group` (for groups). Disabled by default.
 FLAG:
-The availability of this feature is controlled by a feature flag.
+The availability of the actions per policy limit is controlled by a feature flag.
 For more information, see the history.
-| Field | Type | Required | Possible values | Description |
-|-------|------|----------|-----------------|-------------|
-| `name` | `string` | true |  | Name of the policy. Maximum of 255 characters.|
-| `description` (optional) | `string` | true |  | Description of the policy. |
-| `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. |
-| `rules` | `array` of rules | true |  | List of rules that the policy applies. |
-| `actions` | `array` of actions | true |  | List of actions that the policy enforces. Limited to a maximum of 10 in GitLab 18.0 and later. |
+| Field          | Type                                         | Required | Description |
+|----------------|----------------------------------------------|----------|-------------|
+| `name`         | `string`                                     | true     | Name of the policy. Maximum of 255 characters. |
+| `description`  | `string`                                     | false    | Description of the policy. |
+| `enabled`      | `boolean`                                    | true     | Flag to enable (`true`) or disable (`false`) the policy. |
+| `rules`        | `array` of rules                             | true     | List of rules that the policy applies. |
+| `actions`      | `array` of actions                           | true     | List of actions that the policy enforces. Limited to a maximum of 10 in GitLab 18.0 and later. |
+| `policy_scope` | `object` of [`policy_scope`](index.md#scope) | false    | Defines the scope of the policy based on the projects, groups, or compliance framework labels you specify. |
 ## `pipeline` rule type
@@ -324,90 +325,11 @@ In GitLab 16.9 and earlier:
 - If the CI/CD variables suffixed `_EXCLUDED_ANALYZERS` were declared in a policy, their values were
   ignored, regardless of where they were defined: policy, group, or project.
-## Scope security policies
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135398) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_policy_scope`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443594) in GitLab 16.11. Feature flag `security_policies_policy_scope` removed.
-> - Scoping by group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468384) in GitLab 17.4.
-
-Security policy enforcement depends first on establishing a link between:
-
-- The group, subgroup, or project on which you want to enforce policies
-- The security policy project that contains the policies.
-
-For example, if you are linking policies to a group, a group owner must create the link to
-the security policy project. Then, all policies in the security policy project are inherited by all
-projects in the group.
-
-You scope security policies by setting the scopes in the `policy.yml` file to:
-
-- _Include_ only projects with an applied [compliance framework](../../group/compliance_frameworks.md) by using
-  the compliance framework's ID. To include projects, use `policy_scope.compliance_frameworks.id` to specify IDs of
-  compliance frameworks that are applied to the projects.
-- _Include_ or _exclude_ selected projects from enforcement by using the project's ID.
-- _Include_ selected groups. Optionally use this with the `projects` object to exclude selected projects.
-
-### Policy scope schema
-
-A policy scope must conform to this schema.
-
-| Field | Type | Required | Possible values | Description |
-|-------|------|----------|-----------------|-------------|
-| `policy_scope` | `object` | false | `compliance_frameworks`, `projects`, `groups` | Scopes the policy based on compliance framework labels, projects, or groups you define. |
-
-#### `policy_scope` scope type
-
-Policy scopes are one of two types.
-
-| Field | Type | Possible values | Description |
-|-------|------|-----------------|-------------|
-| `compliance_frameworks` | `array` |  | List of IDs of the compliance frameworks in scope of enforcement, in an array of objects with key `id`. |
-| `projects` | `object` |  `including`, `excluding` | Use `excluding:` or `including:` then list the IDs of the projects you wish to include or exclude, in an array of objects with key `id`. |
-| `groups` | `object` | `including` | Use `including:` then list the IDs of the groups you wish to include, in an array of objects with key `id`. |
-
-#### Example `policy.yml` with security policy scopes
-
-In this example, the security policy:
-
-- Includes any project with compliance frameworks with an ID of either `2` or `11` applied to them.
-- Excludes projects with an ID of either `24` or `27`.
-```yaml
----
-scan_execution_policy:
-- name: Enforce DAST in every release pipeline
-  description: This policy enforces pipeline configuration to have a job with DAST scan for release branches
-  enabled: true
-  rules:
-  - type: pipeline
-    branches:
-    - release/*
-  actions:
-  - scan: dast
-    scanner_profile: Scanner Profile A
-    site_profile: Site Profile B
-  policy_scope:
-    compliance_frameworks:
-      - id: 2
-      - id: 11
-- name: Enforce Secret Detection and Container Scanning in every default branch pipeline
-  description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch
-  enabled: true
-  rules:
-  - type: pipeline
-    branches:
-    - main
-  actions:
-  - scan: secret_detection
-  - scan: sast
-    variables:
-      SAST_EXCLUDED_ANALYZERS: brakeman
-  policy_scope:
-    projects:
-      excluding:
-        - id: 24
-        - id: 27
-```
+## Policy scope schema
+To customize policy enforcement, you can define a policy's scope to either include, or exclude,
+specified projects, groups, or compliance framework labels. For more details, see
+[Scope](index.md#scope).
 ## Example security policy project

doc/user/group/compliance_frameworks.md

@@ -13,9 +13,9 @@ DETAILS:
 You can create a compliance framework that is a label to identify that your project has certain compliance
 requirements or needs additional oversight.
-In the Ultimate tier, the compliance framework can optionally enforce [compliance pipeline configuration](compliance_pipelines.md)
-and [security policies](../application_security/policies/scan_execution_policies.md#scope-security-policies)
-to the projects on which it is applied.
+In the Ultimate tier, the compliance framework can optionally enforce
+[compliance pipeline configuration](compliance_pipelines.md) and
+[security policies](../application_security/policies/index.md#scope) to the projects on which it is applied.
 Compliance frameworks are created on top-level groups. If a project is moved outside of its existing top-level group,
 its frameworks are removed.

ee/app/assets/javascripts/compliance_dashboard/constants.js

@@ -72,7 +72,7 @@ export const i18n = {
   violationsTab: s__('Compliance Center|Violations'),
 };
-export const POLICY_SCOPES_DOCS_URL = `${DOCS_URL_IN_EE_DIR}/user/application_security/policies/scan_execution_policies.html#scope-security-policies`;
+export const POLICY_SCOPES_DOCS_URL = `${DOCS_URL_IN_EE_DIR}/user/application_security/policies/index.html#scope`;
 export const CREATE_FRAMEWORKS_DOCS_URL = `${DOCS_URL_IN_EE_DIR}/user/group/compliance_frameworks.html#prerequisites`;

ee/spec/frontend/compliance_dashboard/components/frameworks_report/framework_info_drawer_spec.js

@@ -98,7 +98,7 @@ describe('FrameworkInfoDrawer component', () => {
           'Use the compliance framework ID in configuration or API requests. Learn more.',
         );
         expect(findIdPopover().findComponent(GlLink).attributes('href')).toBe(
-          `${DOCS_URL_IN_EE_DIR}/user/application_security/policies/scan_execution_policies.html#scope-security-policies`,
+          `${DOCS_URL_IN_EE_DIR}/user/application_security/policies/index.html#scope`,
         );
       });