diff options
Diffstat (limited to 'doc/user/application_security/policies/index.md')
-rw-r--r-- | doc/user/application_security/policies/index.md | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md new file mode 100644 index 00000000000..208fbdfa5f3 --- /dev/null +++ b/doc/user/application_security/policies/index.md @@ -0,0 +1,183 @@ +--- +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/#designated-technical-writers +--- + +# Scan Policies **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> - Deployed behind a feature flag, disabled by default. +> - Disabled on GitLab.com. + +Scan Policies in GitLab provide security teams a way to require scans of their choice to be run +whenever a project pipeline runs according to the configuration specified. Security teams can +therefore be confident that the scans they set up have not been changed, altered, or disabled. You +can access these by navigating to your project's **Security & Compliance > Scan Policies** page. + +GitLab supports the following security policies: + +- [Scan Execution Policy](#scan-execution-policy-schema) + +WARNING: +Scan Policies is under development and is not ready for production use. It's deployed behind a +feature flag that's disabled by default. + +NOTE: +We recommend using the [Security Policies project](#security-policies-project) +exclusively for managing policies for the project. Do not add your application's source code to such +projects. + +## Enable or disable scan policies + +Scan Policies is under development and is not ready for production use. It's deployed behind a +feature flag that's disabled by default. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it for your instance. Scan Policies can be enabled or disabled per-project. + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:security_orchestration_policies_configuration) +# or by project +Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:security_orchestration_policies_configuration) +# or by project +Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +``` + +## Security Policies project + +The Security Policies feature is a repository to store policies. All security policies are stored as +the `.gitlab/security-policies/policy.yml` YAML file with this format: + +```yaml +--- +scan_execution_policy: +- name: Enforce DAST in every pipeline + description: This policy enforces pipeline configuration to have a job with DAST scan + enabled: true + rules: + - type: pipeline + branch: master + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B +- name: Enforce DAST in every pipeline in main branch + description: This policy enforces pipeline configuration to have a job with DAST scan for main branch + enabled: true + rules: + - type: pipeline + branch: main + actions: + - scan: dast + scanner_profile: Scanner Profile C + site_profile: Site Profile D +``` + +### Scan Execution Policies Schema + +The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan_execution_policy` | `array` of Scan Execution Policy | | List of scan execution policies (maximum 5) | + +### Scan Execution 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. | + +### `pipeline` rule type + +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. | +| `branch` | `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | + +### `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` | `dast` | The action's type. | +| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. | +| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. | + +Note the following: + +- You must create the [site profile](../dast/index.md#site-profile) and [scanner profile](../dast/index.md#scanner-profile) + with selected names for each project that is assigned to the selected Security Policy Project. + Otherwise, the policy is not applied and a job with an error message is created instead. +- Once you associate the site profile and scanner profile by name in the policy, it is not possible + to modify or delete them. If you want to modify them, you must first disable the policy by setting + the `active` flag to `false`. + +Here's an example: + +```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 + branch: release/* + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B +- name: Enforce DAST in every pipeline in main branch + description: This policy enforces pipeline configuration to have a job with DAST scan for main branch + enabled: true + rules: + - type: pipeline + branch: main + actions: + - scan: dast + scanner_profile: Scanner Profile C + site_profile: Site Profile D +``` + +In this example, the DAST scan runs with the scanner profile `Scanner Profile A` and the site +profile `Site Profile B` for every pipeline executed on branches that match the +`release/*` wildcard (for example, branch name `release/v1.2.1`); and the DAST scan runs with +the scanner profile `Scanner Profile C` and the site profile `Site Profile D` for every pipeline executed on `main` branch. + +NOTE: +All scanner and site profiles must be configured and created for each project that is assigned to the selected Security Policy Project. +If they are not created, the job will fail with the error message. + +## Security Policy project selection + +When the Security Policy project is created and policies are created within that repository, you +must create an association between that project and the project you want to apply policies to. To do +this, navigate to your project's **Security & Compliance > Policies**, select +**Security policy project** from the dropdown menu, then select the **Create policy** button to save +changes. + +You can always change the **Security policy project** by navigating to your project's +**Security & Compliance > Policies** and modifying the selected project. + +## Roadmap + +See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) +for more information on the product direction of Container Network Security. |