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.