diff options
Diffstat (limited to 'doc/user/application_security/policies/index.md')
| -rw-r--r-- | doc/user/application_security/policies/index.md | 281 |
1 files changed, 233 insertions, 48 deletions
diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 3d0135678b7..bd143d8608a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -4,57 +4,189 @@ 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)** +# 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. +> - [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. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.3. -Scan Policies in GitLab provide security teams a way to require scans of their choice to be run +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the `security_orchestration_policies_configuration` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available. + +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. +can access these by navigating to your project's **Security & Compliance > Policies** page. GitLab supports the following security policies: +- [Container Network Policy](#container-network-policy) - [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. +## Policy management -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. +The Policies page displays deployed +policies for all available environments. You can check a +policy's information (for example description, enforcement +status, etc.), and create and edit deployed policies: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. + + + +Network policies are fetched directly from the selected environment's +deployment platform while other policies are fetched from the project's +security policy project. Changes performed outside of this tab are +reflected upon refresh. + +By default, the policy list contains predefined network policies in a +disabled state. Once enabled, a predefined policy deploys to the +selected environment's deployment platform and you can manage it like +the regular policies. + +Note that if you're using [Auto DevOps](../../../topics/autodevops/index.md) +and change a policy in this section, your `auto-deploy-values.yaml` file doesn't update. Auto DevOps +users must make changes by following the +[Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). + +## Policy editor + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +You can use the policy editor to create, edit, and delete policies: + +1. On the top bar, select **Menu > Projects** and find your group. +1. On the left sidebar, select **Security & Compliance > Policies**. + - To create a new policy, select **New policy** which is located in the **Policies** page's header. + - To edit an existing policy, select **Edit policy** in the selected policy drawer. + +The policy editor has two modes: + +- The visual _Rule_ mode allows you to construct and preview policy + rules using rule blocks and related controls. + +  + +- YAML mode allows you to enter a policy definition in `.yaml` format + and is aimed at expert users and cases that the Rule mode doesn't + support. + +  + +You can use both modes interchangeably and switch between them at any +time. If a YAML resource is incorrect or contains data not supported +by the Rule mode, Rule mode is automatically +disabled. If the YAML is incorrect, you must use YAML +mode to fix your policy before Rule mode is available again. -## Enable or disable scan policies +## Container Network Policy -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. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -To enable it: +The **Container Network Policy** section provides packet flow metrics for +your application's Kubernetes namespace. This section has the following +prerequisites: -```ruby -# Instance-wide -Feature.enable(:security_orchestration_policies_configuration) -# or by project -Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +- Your project contains at least one [environment](../../../ci/environments/index.md). +- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). +- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration). + +If you're using custom Helm values for Cilium, you must enable Hubble +with flow metrics for each namespace by adding the following lines to +your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium): + +```yaml +hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` -To disable it: +The **Container Network Policy** section displays the following information +about your packet flow: + +- The total amount of the inbound and outbound packets +- The proportion of packets dropped according to the configured + policies +- The per-second average rate of the forwarded and dropped packets + accumulated over time window for the requested time interval -```ruby -# Instance-wide -Feature.disable(:security_orchestration_policies_configuration) -# or by project -Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +If a significant percentage of packets is dropped, you should +investigate it for potential threats by +examining the Cilium logs: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor ``` +### Change the enforcement status + +To change a network policy's enforcement status: + +- Select the network policy you want to update. +- Select **Edit policy**. +- Select the **Policy status** toggle to update the selected policy. +- Select **Save changes** to deploy network policy changes. + +Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside +the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect +any pods. The policy itself is still deployed to the corresponding deployment namespace. + +### Container Network Policy editor + +The policy editor only supports the [CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/) +specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) +resources aren't supported. + +Rule mode supports the following rule types: + +- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). +- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). +- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only + the `toCIDR` block without `except` is supported. +- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). +- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) + can be added to all other rules. + +Once your policy is complete, save it by selecting **Save policy** +at the bottom of the editor. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + +### Configure a Network Policy Alert + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. + +You can use policy alerts to track your policy's impact. Alerts are only available if you've +[installed](../../clusters/agent/repository.md) +and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) +a Kubernetes Agent for this project. + +There are two ways to create policy alerts: + +- In the [policy editor UI](#container-network-policy-editor), + by clicking **Add alert**. +- In the policy editor's YAML mode, through the `metadata.annotations` property: + + ```yaml + metadata: + annotations: + app.gitlab.com/alert: 'true' + ``` + +Once added, the UI updates and displays a warning about the dangers of too many alerts. + ## Security Policies project +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. + 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: @@ -85,6 +217,40 @@ scan_execution_policy: site_profile: Site Profile D ``` +## Security Policy project selection + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +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: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Select **Edit Policy Project**, and search for and select the + project you would like to link from the dropdown menu. +1. Select **Save**. + +  + +### Scan Execution Policy editor + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +Once your policy is complete, save it by selecting **Create merge request** +at the bottom of the editor. You will be redirected to the merge request on the project's +configured security policy project. If one does not link to your project, a security +policy project will be automatically created. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + + + +The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. + ### 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. @@ -121,6 +287,16 @@ This rule enforces the defined actions and schedules a scan on the provided date | `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). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | +| `clusters` | `object` | | The cluster where the given policy will enforce running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that will be scanned. | + +#### `cluster` schema + +| Field | Type | Possible values | Description | +|--------------|---------------------|--------------------------|-------------| +| `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name that will be scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace that will be scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | ### `scan` action type @@ -149,6 +325,9 @@ Note the following: - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-scan) mode when executed as part of a scheduled scan. +- A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. + They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. + Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). Here's an example: @@ -179,8 +358,8 @@ scan_execution_policy: scanner_profile: Scanner Profile C site_profile: Site Profile D - scan: secret_detection -- name: Enforce Secret Detection in every default branch pipeline - description: This policy enforces pipeline configuration to have a job with Secret Detection scan for the default branch +- 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 @@ -188,6 +367,25 @@ scan_execution_policy: - main actions: - scan: secret_detection + - scan: container_scanning +- name: Enforce Cluster Image Scanning on production-cluster every 24h + description: This policy enforces Cluster Image Scanning scan to run every 24 hours + enabled: true + rules: + - type: schedule + cadence: '15 3 * * *' + clusters: + production-cluster: + containers: + - database + resources: + - production-application + namespaces: + - production-namespace + kinds: + - deployment + actions: + - scan: cluster_image_scanning ``` In this example: @@ -196,22 +394,9 @@ In this example: `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. -- Secret detection scans run for every pipeline executed on the `main` branch. - -## 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. - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. +- Secret detection and container scanning scans run for every pipeline executed on the `main` branch. +- Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities + from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. ## Roadmap |