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 | 102 |
1 files changed, 68 insertions, 34 deletions
diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index e18d4d1787e..b84d4d2e49e 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -6,16 +6,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Scan execution policies **(ULTIMATE)** -> - Group-level security policies were [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. -> - Group-level security policies were [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. +> - Group-level security policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. +> - Group-level security policies [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. > - Operational container scanning [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3410) in GitLab 15.5 - -Group, subgroup, or project owners can use scan execution policies to require that security scans run on a specified -schedule or with the project pipeline. The security scan runs with multiple project pipelines if you define the policy -at a group or subgroup level. GitLab injects the required scans into the CI pipeline as new jobs. In the event -of a job name collision, GitLab adds a dash and a number to the job name. GitLab increments the number until the name -no longer conflicts with existing job names. If you create a policy at the group level, it applies to every child project -or subgroup. You cannot edit a group-level policy from a child project or subgroup. +> - Support for custom CI variables in the Scan Execution Policies editor [introduced](https://gitlab.com/groups/gitlab-org/-/epics/9566) in GitLab 16.2. +> - Enforcement of scan execution policies on projects with an existing GitLab CI/CD configuration [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6880) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `scan_execution_policy_pipelines`. Enabled by default. + +FLAG: +On self-managed GitLab, this feature is enabled by default. To disable it, ask an +administrator to [disable the feature flag](../../../administration/feature_flags.md) named +`scan_execution_policy_pipelines`. On GitLab.com, this feature is enabled. + +Group, subgroup, or project owners can use scan execution policies to require that security scans +run on a specified schedule or with the project pipeline. The security scan runs with multiple +project pipelines if you define the policy at a group or subgroup level. GitLab injects the required +scans into the CI/CD pipeline as new jobs. + +Scan execution policies are enforced for all applicable projects, even those without a GitLab +CI/CD configuration file or where AutoDevOps is disabled. Security policies create the file +implicitly so that the policies can be enforced. This ensures policies enabling execution of +secret detection, static analysis, or other scanners that do not require a build in the +project, are still able to execute and be enforced. + +In the event of a job name collision, GitLab appends a hyphen and a number to the job name. GitLab +increments the number until the name no longer conflicts with existing job names. If you create a +policy at the group level, it applies to every child project or subgroup. You cannot edit a +group-level policy from a child project or subgroup. This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#compliance-pipelines), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). @@ -46,6 +62,13 @@ before the policy changes take effect.  +NOTE: +Selection of site and scanner profiles using the rule mode editor for DAST execution policies differs based on +whether the policy is being created at the project or group level. For project-level policies the rule mode editor +presents a list of profiles to choose from that are already defined in the project. For group-level policies +you are required to type in the names of the profiles to use, and to prevent pipeline errors, profiles with +matching names must exist in all of the group's projects. + ## Scan execution policies schema The YAML file with scan execution policies consists of an array of objects matching scan execution @@ -57,41 +80,52 @@ 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 | Possible values | Description | -|-------|------|-----------------|-------------| -| `scan_execution_policy` | `array` of scan execution policy | | List of scan execution policies (maximum 5) | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `scan_execution_policy` | `array` of scan execution policy | true | | List of scan execution policies (maximum 5) | ## Scan execution policy schema -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `name` | `string` | | Name of the policy. Maximum of 255 characters.| -| `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. | +| 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. | ## `pipeline` rule type +> - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. +> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. + This rule enforces the defined actions whenever the pipeline runs for a selected branch. -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `type` | `string` | `pipeline` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | `default`, `protected` or `all` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `type` | `string` | true | `pipeline` | The rule's type. | +| `branches` <sup>1</sup> | `array` of `string` | true if `branch_type` field does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `branch_type` <sup>1</sup> | `string` | true if `branches` field does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | + +1. You must specify only one of `branches` or `branch_type`. ## `schedule` rule type +> - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. +> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. + This rule enforces the defined actions and schedules a scan on the provided date/time. -| Field | Type | Possible values | Description | -|------------|------|-----------------|-------------| -| `type` | `string` | `schedule` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). This field is required if the `agents` field is not set. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | `default`, `protected` or `all` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | -| `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. Minimum of 15 minute intervals when used together with the `branches` field. | -| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | +| Field | Type | Required | Possible values | Description | +|------------|------|----------|-----------------|-------------| +| `type` | `string` | true | `schedule` | The rule's type. | +| `branches` <sup>1</sup> | `array` of `string` | true if either `branch_type` or `agents` fields does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `branch_type` <sup>1</sup> | `string` | true if either `branches` or `agents` fields does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | +| `cadence` | `string` | true | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. Minimum of 15 minute intervals when used together with the `branches` field. | +| `timezone` | `string` | false | Time zone identifier (for example, `America/New_York`) | Time zone to apply to the cadence. Value must be an IANA Time Zone Database identifier. | +| `agents` <sup>1</sup> | `object` | true if either `branch_type` or `branches` fields do not exists | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. | + +1. You must specify only one of `branches`, `branch_type`, or `agents`. GitLab supports the following types of CRON syntax for the `cadence` field: @@ -118,9 +152,9 @@ When using the `schedule` rule type in conjunction with the `branches` field, no Use this schema to define `agents` objects in the [`schedule` rule type](#schedule-rule-type). -| Field | Type | Possible values | Description | -|--------------|---------------------|--------------------------|-------------| -| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces are scanned. | +| Field | Type | Required | Possible values | Description | +|--------------|---------------------|----------|--------------------------|-------------| +| `namespaces` | `array` of `string` | true | The namespace that is scanned. If empty, all namespaces are scanned. | #### Policy example |