diff options
Diffstat (limited to 'doc/user/application_security/policies/scan-execution-policies.md')
| -rw-r--r-- | doc/user/application_security/policies/scan-execution-policies.md | 101 |
1 files changed, 78 insertions, 23 deletions
diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index 574d466cd53..de36cb30257 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -205,23 +205,18 @@ The keys for a schedule rule are: ## `scan` action type -> - Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. -> - The `custom` scan action type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126457) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. On GitLab.com, this feature is not available. On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. +> Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Disabled by default. This action executes the selected `scan` with additional parameters when conditions for at least one rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning`, `custom` | The action's type. | +| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning` | The action's type. | | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/on-demand_scan.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | | `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/on-demand_scan.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| | `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | | `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs are run by runner with the specified tags. | -| `ci_configuration` <sup>1</sup> | `string` | | GitLab CI YAML as formatted as string. | -| `ci_configuration_path` <sup>1</sup> | object | Object with project path and file name pointing to a CI configuration. | - -1. For `custom` scans, you must specify one of `ci_configuration` or `ci_configuration_path`. Note the following: @@ -241,16 +236,6 @@ Note the following: - A container scanning scan that is configured for the `pipeline` rule type ignores the agent defined in the `agents` object. The `agents` object is only considered for `schedule` rule types. An agent with a name provided in the `agents` object must be created and configured for the project. - Variables defined in a Scan Execution Policy follow the standard [CI/CD variable precedence](../../../ci/variables/index.md#cicd-variable-precedence). -- `custom` scans are not executed for scheduled rules. -- Jobs variables and stages definitions from `custom` scans take precedence over the project's CI/CD configuration. - -### `ci_configuration_path` object - -| Field | Type | Description | -|-------|------|-------------| -| `project` | `string` | A project namespace path. | -| `file` | `string` | The filename of the CI/CD YAML file. | -| `ref` | `string` (optional) | The branch name, tag name, or commit SHA. | ## Example security policies project @@ -271,12 +256,6 @@ scan_execution_policy: - scan: dast scanner_profile: Scanner Profile A site_profile: Site Profile B - - scan: custom - ci_configuration: |- - test job: - stage: test - script: - - echo "Hello World" - name: Enforce DAST and secret detection scans every 10 minutes description: This policy enforces DAST and secret detection scans to run every 10 minutes enabled: true @@ -344,3 +323,79 @@ this case, two SAST jobs run in the pipeline, one with the developer's variables If you want to avoid running duplicate scans, you can either remove the scans from the project's `.gitlab-ci.yml` file or disable your local jobs by setting `SAST_DISABLED: "true"`. Disabling jobs this way does not prevent the security jobs defined by scan execution policies from running. + +## Experimental features **(EXPERIMENT)** + +These experimental features have limitations: + +1. Enforcing pipeline execution using the pipeline execution action in projects + without a `.gitlab-ci.yml` is not supported. +1. The pipeline execution action cannot be used with a scheduled trigger type. + +### Pipeline execution policy action + +> The `custom` scan action type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126457) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +an administrator can [enable the feature flag](../../../administration/feature_flags.md) +named `compliance_pipeline_in_policies`. +On GitLab.com, this feature is not available. + +The pipeline execution policy action introduces a new scan action type into +scan execution policies for creating and enforcing custom CI in your target +development projects. + +This custom scan type uses a remote CI configuration file to define the custom +CI you want enforced. Scan execution policies then merge this file with the +project's `.gitlab-ci.yml` to execute the compliance jobs for each project +enforced by the policy. + +#### `ci_configuration_path` object + +| Field | Type | Description | +|-----------|---------------------|-------------| +| `project` | `string` | A project namespace path. | +| `file` | `string` | The file name of the CI/CD YAML file. | +| `ref` | `string` (optional) | The branch name, tag name, or commit SHA. | + +#### `scan` action type + +This action executes the selected `scan` with additional parameters when +conditions for at least one rule in the defined policy are met. + +| Field | Type | Possible values | Description | +|-------------------------|----------|-----------------|-------------| +| `scan` | `string` | `custom` | The action's type. | +| `ci_configuration` | `string` | | GitLab CI YAML as formatted as string. | +| `ci_configuration_path` | object | | Object with project path and file name pointing to a CI configuration. | + +Note the following: + +- For `custom` scans, you must specify one of `ci_configuration` or `ci_configuration_path`. +- `custom` scans are being executed for triggered rules only. +- Jobs variables and stages definitions from `custom` scans take precedence over the project's CI/CD configuration. + +#### Example security policies project + +You can use this example in a `.gitlab/security-policies/policy.yml` file stored in a +[security policy project](index.md#security-policy-project): + +```yaml +--- +scan_execution_policy: +- name: Create a custom scan that injects test job + 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: custom + ci_configuration: |- + test job: + stage: test + script: + - echo "Hello World" +``` |