diff --git a/doc/user/application_security/detect/security_configuration.md b/doc/user/application_security/detect/security_configuration.md index a57c5cbd34b572ec7bc0221e0febc88fa59c2857..bc91230784b8aec49b0d8187a04b5b93cb063cdb 100644 --- a/doc/user/application_security/detect/security_configuration.md +++ b/doc/user/application_security/detect/security_configuration.md @@ -119,39 +119,46 @@ each project individually, including: - Configuration changes only have to be made once instead of for each project. - Permission to make configuration changes is restricted, providing separation of duties. -### Scan execution policy compared to compliance framework +### Policy comparison -Consider the following when deciding between using a scan execution policy or compliance framework. +Consider the following when deciding between using scan execution policies, pipeline execution policies, or compliance frameworks. - Use a [compliance framework pipeline](../../compliance/compliance_pipelines.md) when: - - Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST IaC, DAST, Dependency Scanning, - API Fuzzing, or Coverage-guided Fuzzing. + - Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST + IaC, DAST, Dependency Scanning, API Fuzzing, or Coverage-guided Fuzzing. - Scan execution enforcement is required for scanners external to GitLab. - Scan execution enforcement is required for custom jobs other than security scans. - Use a [scan execution policy](../policies/scan_execution_policies.md) when: - Scan execution enforcement is required for DAST which uses a DAST site or scan profile. - - Scan execution enforcement is required for SAST, SAST IaC, Secret Detection, Dependency Scanning, or Container Scanning with project-specific - variable customizations. To accomplish this, users must create a separate security policy per project. + - Scan execution enforcement is required for SAST, SAST IaC, Secret Detection, Dependency + Scanning, or Container Scanning with project-specific variable customizations. To accomplish + this, users must create a separate security policy per project. - Scans are required to run on a regular, scheduled cadence. -- Either solution can be used equally well when: +- Use a [pipeline execution policy](../policies/pipeline_execution_policies.md) when: + + - You need to enforce the execution of entire CI/CD pipelines across multiple projects. + - You want to ensure specific pipeline configurations are consistently applied. + - You need to control pipeline execution based on conditions like branch patterns or user roles. + +- Any of these solutions can be used equally well when: - Scan execution enforcement is required for Container Scanning with no project-specific variable customizations. Additional details about the differences between these solutions are outlined below: -| | Compliance Framework Pipelines | Scan Execution Policies | -| ------ | ------ | ------ | -| **Flexibility** | Supports anything that can be done in a CI/CD file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, SAST IaC, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | -| **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | -| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job. | -| **Schedulable** | Has to be scheduled through a scheduled pipeline on each project. | Can be scheduled natively through the policy configuration itself. | -| **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | -| **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | +| | Compliance Framework Pipelines | Scan Execution Policies | Pipeline Execution Policies | +|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| **Flexibility** | Supports anything that can be done in a CI/CD file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, SAST IaC, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | Supports enforcement of entire pipeline configurations and can control pipeline execution based on various conditions. | +| **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | Uses a policy-based YAML structure with conditions and actions for pipeline control. | +| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job. | Enforces pipeline execution based on defined conditions and can prevent or allow pipeline execution across multiple projects. | +| **Schedulable** | Has to be scheduled through a scheduled pipeline on each project. | Can be scheduled natively through the policy configuration itself. | Pipeline execution is controlled by policy conditions rather than direct scheduling. | +| **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | Only project owners can define a linked security policy project. The ability to make or approve changes to pipeline execution policies is limited to individuals who are explicitly given access to the security policy project. | +| **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | Feedback is welcome on our vision for [unifying the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312) diff --git a/doc/user/compliance/compliance_pipelines.md b/doc/user/compliance/compliance_pipelines.md index a5178ab6e1fa242d8853c3af33fad3bf574f8dfb..9e7f8f43b283ead326c0e076efac0190d69eb545 100644 --- a/doc/user/compliance/compliance_pipelines.md +++ b/doc/user/compliance/compliance_pipelines.md @@ -125,8 +125,9 @@ The user running the pipeline in the labeled project must at least have the Repo When used to enforce scan execution, this feature has some overlap with [scan execution policies](../application_security/policies/scan_execution_policies.md). We have not -[unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on -the similarities and differences between these features, see [Scan execution policy compared to compliance framework](../application_security/detect/security_configuration.md#scan-execution-policy-compared-to-compliance-framework). +[unified the user experience for these features](https://gitlab.com/groups/gitlab-org/-/epics/7312). +For details on the similarities and differences between these features, see +[Policy comparison](../application_security/detect/security_configuration.md#policy-comparison). ### Example configuration