Merge branch 'update-policy-documentation' into 'master'

Update documentation for security policies

See merge request gitlab-org/gitlab!69308

doc/development/fe_guide/source_editor.md

@@ -15,7 +15,7 @@ GitLab features use it, including:
 - [CI Linter](../../ci/lint.md)
 - [Snippets](../../user/snippets.md)
 - [Web Editor](../../user/project/repository/web_editor.md)
-- [Security Policies](../../user/application_security/threat_monitoring/index.md)
+- [Security Policies](../../user/application_security/policies/index.md)
 
 ## How to use Source Editor
 

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 not 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**.
+
+![Policies List Page](img/policies_list_v14_3.png)
+
+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.
+
+  ![Policy Editor Rule Mode](img/container_policy_rule_mode_v14_3.png)
+
+- 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.
+
+  ![Policy Editor YAML Mode](img/container_policy_yaml_mode_v14_3.png)
 
-## Enable or disable scan policies
+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.
 
-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.
+## Container Network Policy
 
-To enable it:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9.
 
-```ruby
-# Instance-wide
-Feature.enable(:security_orchestration_policies_configuration)
-# or by project
-Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>))
+The **Container Network Policy** section provides packet flow metrics for
+your application's Kubernetes namespace. This section has the following
+prerequisites:
+
+- 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:
 
-```ruby
-# Instance-wide
-Feature.disable(:security_orchestration_policies_configuration)
-# or by project
-Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>))
+- 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
+
+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**.
+
+   ![Security Policy Project](img/security_policy_project_v14_3.png)
+
+### 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.
+
+![Scan Execution Policy Editor YAML Mode](img/scan_execution_policy_yaml_mode_v14_3.png)
+
+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.
@@ -198,21 +364,6 @@ In this example:
   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.
-
 ## Roadmap
 
 See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/)

doc/user/application_security/threat_monitoring/index.md

@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9.
 
-The **Threat Monitoring** page provides metrics and policy management
+The **Threat Monitoring** page provides alerts and metrics 
 for the GitLab application runtime security features. You can access
 these by navigating to your project's **Security & Compliance > Threat
 Monitoring** page.
@@ -18,153 +18,7 @@ GitLab supports statistics for the following security features:
 
 - [Container Network Policies](../../../topics/autodevops/stages.md#network-policy)
 
-## Container Network Policy
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9.
-
-The **Container Network Policy** section provides packet flow metrics for
-your application's Kubernetes namespace. This section has the following
-prerequisites:
-
-- 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'
-```
-
-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
-
-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
-```
-
-## Container Network Policy management
-
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3328) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1.
-
-The **Threat Monitoring** page's **Policy** tab displays deployed
-network policies for all available environments. You can check a
-network policy's `yaml` manifest, its enforcement
-status, and create and edit deployed policies. This section has the
-following prerequisites:
-
-- 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)
-
-Network policies are fetched directly from the selected environment's
-deployment platform. Changes performed outside of this tab are
-reflected upon refresh.
-
-By default, the network policy list contains predefined 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).
-
-### Changing enforcement status
-
-To change a network policy's enforcement status:
-
-- Click the network policy you want to update.
-- Click the **Edit policy** button.
-- Click the **Policy status** toggle to update the selected policy.
-- Click the **Save changes** button 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
-
-> [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.
-
-- To create a new policy, click the **New policy** button located in the **Policy** tab's header.
-- To edit an existing policy, click **Edit policy** in the selected policy drawer.
-
-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.
-
-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, Rule mode is automatically
-disabled. You must use YAML mode to fix your policy before Rule mode
-is available again.
-
-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 pressing the **Save policy**
-button at the bottom of the editor. Existing policies can also be
-removed from the editor interface by clicking the **Delete policy**
-button at the bottom of the editor.
-
-### Configuring Network Policy Alerts
-
-> - [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.
-
-### Container Network Policy Alert list
+## Container Network Policy Alert list
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9.
 
@@ -184,7 +38,7 @@ the selector menu in the **Status** column to set the status for each alert:
 
 By default, the list doesn't display resolved or dismissed alerts.
 
-![Policy Alert List](img/threat_monitoring_policy_alert_list_v13_12.png)
+![Policy Alert List](img/threat_monitoring_policy_alert_list_v14_3.png)
 
 Clicking an alert's row opens the alert drawer, which shows more information about the alert. A user
 can also create an incident from the alert and update the alert status in the alert drawer.

doc/user/clusters/agent/index.md

@@ -20,7 +20,7 @@ tasks in a secure and cloud-native way. It enables:
 - Pull-based GitOps deployments.
 - [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster.
 - Real-time access to API endpoints in a cluster.
-- Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy).
+- Alert generation based on [Container network policy](../../application_security/policies/index.md#container-network-policy).
 - [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster.
 
 Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329)
@@ -435,8 +435,8 @@ There are several components that work in concert for the Agent to generate the
   - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an
     existing installation.
 - One or more network policies through any of these options:
-  - Use the [Container Network Policy editor](../../application_security/threat_monitoring/index.md#container-network-policy-editor) to create and manage policies.
-  - Use an [AutoDevOps](../../application_security/threat_monitoring/index.md#container-network-policy-management) configuration.
+  - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies.
+  - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration.
   - Add the required labels and annotations to existing network policies.
 - A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab)
 

doc/user/project/clusters/protect/container_network_security/quick_start_guide.md

@@ -137,7 +137,7 @@ Network Policies can be managed through GitLab in one of two ways:
 - Management through a YAML file in each application's project (for projects using Auto DevOps). For
   more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy).
 - Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more
-  information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate only).
+  information, see the [Container Network Policy documentation](../../../../application_security/policies/index.md#container-network-policy) (Ultimate only).
 
 Each method has benefits and drawbacks:
 
@@ -167,7 +167,7 @@ hubble:
 ```
 
 Additional information about the statistics page is available in the
-[documentation that describes the Threat Management UI](../../../../application_security/threat_monitoring/index.md#container-network-policy).
+[documentation that describes the Threat Management UI](../../../../application_security/policies/index.md#container-network-policy).
 
 ## Forwarding logs to a SIEM
 

ee/app/helpers/projects/security/policies_helper.rb

@@ -28,7 +28,7 @@ module Projects::Security::PoliciesHelper
       create_agent_help_path: help_page_url('user/clusters/agent/index.md', anchor: 'create-an-agent-record-in-gitlab'),
       environments_endpoint: project_environments_path(project),
       environment_id: environment&.id,
-      network_documentation_path: help_page_path('user/application_security/threat_monitoring/index'),
+      network_documentation_path: help_page_path('user/application_security/policies/index'),
       no_environment_svg_path: image_path('illustrations/monitoring/unable_to_connect.svg'),
       policy: policy&.to_json,
       policy_type: policy_type,