Merge branch 'create-dast-scan-schedule-docs' into 'master'

Create DAST scan schedule documentation

See merge request gitlab-org/gitlab!56277

doc/user/application_security/dast/index.md

@@ -969,7 +969,9 @@ To edit an existing site profile:
 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**.
 1. Edit the fields then select **Save profile**.
 
-The site profile is updated with the edited details.
+If a site profile is linked to a security policy, a user cannot edit the profile from this page. See
+[Scan Policies](../policies/index.md)
+for more information.
 
 #### Delete a site profile
 
@@ -981,7 +983,9 @@ To delete an existing site profile:
 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**.
 1. Select **Delete** to confirm the deletion.
 
-The site profile is deleted.
+If a site profile is linked to a security policy, a user cannot delete the profile from this page.
+See [Scan Policies](../policies/index.md)
+for more information.
 
 #### Validate a site profile
 
@@ -1103,7 +1107,9 @@ To edit a scanner profile:
 1. Edit the form.
 1. Select **Save profile**.
 
-The scanner profile is updated with the edited details.
+If a scanner profile is linked to a security policy, a user cannot edit the profile from this page.
+See [Scan Policies](../policies/index.md)
+for more information.
 
 #### Delete a scanner profile
 
@@ -1115,7 +1121,9 @@ To delete a scanner profile:
 1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**.
 1. Select **Delete**.
 
-The scanner profile is deleted.
+If a scanner profile is linked to a security policy, a user cannot delete the profile from this
+page. See [Scan Policies](../policies/index.md)
+for more information.
 
 ## Reports
 

doc/user/application_security/policies/index.md

+---
+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 in
+the `.gitlab/security-policies` directory as a YAML file with this format:
+
+```yaml
+---
+type: 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
+```
+
+### Scan Execution Policy Schema
+
+| Field | Type | Possible values | Description |
+|-------|------|-----------------|-------------|
+| `type` | `string` | `scan_execution_policy` | The policy's type. |
+| `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 the 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
+---
+type: 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: release/*
+actions:
+- scan: dast
+  scanner_profile: Scanner Profile A
+  site_profile: Site Profile B
+```
+
+In this example, the DAST scan runs with the scanner profile `Scanner Profile A` and the site
+profile `Site Profile B`. The scan runs for every pipeline executed on branches that match the
+`release/*` wildcard (for example, branch name `release/v1.2.1`).
+
+## 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.