Skip to content
Snippets Groups Projects
Unverified Commit 32d51f08 authored by Russell Dickenson's avatar Russell Dickenson Committed by GitLab
Browse files

Apply 3 suggestion(s) to 2 file(s) 


Co-authored-by: default avatarRyan Lehmann <rlehmann@gitlab.com>
parent 5754e241
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 133 additions and 211 deletions
doc/user/application_security/policies/index.md
+ 101
− 10
View file @ 32d51f08
@@ -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
### Enforcement
 
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.
To enforce policies to meet your requirements, consider the following factors:
 
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.
- **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
+ 8
− 66
View file @ 32d51f08
@@ -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
## Policy scope schema
 
> - [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
```
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
+ 5
− 38
View file @ 32d51f08
@@ -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
### Policy scope schema
 
> - 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
```
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
+ 14
− 92
View file @ 32d51f08
@@ -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`.
## Policy scope schema
 
```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
```
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
+ 3
− 3
View file @ 32d51f08
@@ -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
+ 1
− 1
View file @ 32d51f08
@@ -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
+ 1
− 1
View file @ 32d51f08
@@ -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`,
);
});
 
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment