Merge branch 'docs-security-notes' into 'master'

Removing notes from security docs

See merge request gitlab-org/gitlab!43766

doc/user/application_security/configuration/index.md

@@ -30,12 +30,11 @@ The status of each security control is determined by the project's latest defaul
 If a job with the expected security report artifact exists in the pipeline, the feature's status is
 _enabled_.
 
-For SAST, click **View history** to see the `.gitlab-ci.yml` file’s history.
-
-NOTE: **Note:**
 If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md),
 all security features are configured by default.
 
+For SAST, click **View history** to see the `.gitlab-ci.yml` file's history.
+
 ## Manage
 
 You can configure the following security controls:

doc/user/application_security/container_scanning/index.md

@@ -17,7 +17,6 @@ By default, container scanning in GitLab is based on [Clair](https://github.com/
 containers. [GitLab's Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/)
 scans the containers and serves as a wrapper for Clair.
 
-NOTE: **Note:**
 To integrate security scanners other than Clair and Klar into GitLab, see
 [Security scanner integration](../../../development/integrations/secure.md).
 
@@ -217,8 +216,7 @@ To use container scanning in an offline environment, you need:
 - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
 - To configure a local Docker container registry with copies of the container scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [container scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry).
 
-NOTE: **Note:**
-GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
+Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
 meaning the runner tries to pull Docker images from the GitLab container registry even if a local
 copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
 in an offline environment if you prefer using only locally available Docker images. However, we

doc/user/application_security/dast/index.md

@@ -9,17 +9,17 @@ type: reference, howto
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4.
 
-NOTE: **Note:**
-The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/)
-explains how **4 of the top 6 attacks were application based**. Download it
-to learn how to protect your organization.
-
 Running [static checks](../sast/index.md) on your code is the first step to detect
 vulnerabilities that can put the security of your code at risk. Yet, once
 deployed, your application is exposed to a new category of possible attacks,
 such as cross-site scripting or broken authentication flaws. This is where
 Dynamic Application Security Testing (DAST) comes into place.
 
+NOTE: **Note:**
+The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/)
+explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your
+organization.
+
 ## Overview
 
 If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web applications
@@ -32,9 +32,8 @@ provided by [Auto DevOps](../../../topics/autodevops/index.md).
 GitLab checks the DAST report, compares the found vulnerabilities between the source and target
 branches, and shows the information on the merge request.
 
-NOTE: **Note:**
-This comparison logic uses only the latest pipeline executed for the target branch's base commit.
-Running the pipeline on any other commit has no effect on the merge request.
+Note that this comparison logic uses only the latest pipeline executed for the target branch's base
+commit. Running the pipeline on any other commit has no effect on the merge request.
 
 ![DAST Widget](img/dast_v13_4.png)
 
@@ -53,12 +52,11 @@ However, DAST can be [configured](#full-scan)
 to also perform an *active scan*: attack your application and produce a more extensive security report.
 It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md).
 
-NOTE: **Note:**
-A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any
-job fails to finish for any reason, the security dashboard doesn't show DAST scanner
-output. For example, if the DAST job finishes but the SAST job fails, the security
-dashboard doesn't show DAST results. The analyzer outputs an
-[exit code](../../../development/integrations/secure.md#exit-code) on failure.
+Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job
+fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For
+example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST
+results. On failure, the analyzer outputs an
+[exit code](../../../development/integrations/secure.md#exit-code).
 
 ## Use cases
 
@@ -206,8 +204,8 @@ variables:
   DAST_FULL_SCAN_ENABLED: "true"
 ```
 
-NOTE: **Note:**
-If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/).
+If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some
+tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/).
 
 #### Domain validation
 
@@ -398,11 +396,9 @@ variables:
   DAST_API_HOST_OVERRIDE: api-test.host.com
 ```
 
-NOTE: **Note:**
-Using a host override is ONLY supported when importing the API
-specification from a URL. It does not work and will be ignored when importing
-the specification from a file. This is due to a limitation in the ZAP OpenAPI
-extension.
+Note that using a host override is ONLY supported when importing the API specification from a URL.
+It doesn't work and is ignored when importing the specification from a file. This is due to a
+limitation in the ZAP OpenAPI extension.
 
 #### Authentication using headers
 
@@ -427,7 +423,8 @@ A URL scan allows you to specify which parts of a website are scanned by DAST.
 
 #### Define the URLs to scan
 
-To specify the paths to be scanned, add a comma-separated list of the paths to the `DAST_PATHS` environment variable. Note that you can only scan paths of a single host.
+To specify the paths to scan, add a comma-separated list of the paths to the `DAST_PATHS`
+environment variable. Note that you can only scan paths of a single host.
 
 ```yaml
 include:
@@ -437,9 +434,10 @@ variables:
   DAST_PATHS=/page1.html,/category1/page1.html,/page3.html
 ```
 
-NOTE: **Note:**
+When using `DAST_PATHS`, note the following:
 
-- The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths greater than this it is recommended creating multiple DAST jobs and split the paths over each.
+- The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths
+  greater than this, you should create multiple DAST jobs and split the paths over each job.
 - The `DAST_AUTH_EXCLUDE_URLS` environment variable is ignored when `DAST_PATHS` is set.
 
 #### Full Scan
@@ -592,8 +590,7 @@ To use DAST in an offline environment, you need:
   [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the
   [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry).
 
-NOTE: **Note:**
-GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
+Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
 meaning the runner tries to pull Docker images from the GitLab container registry even if a local
 copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
 in an offline environment if you prefer using only locally available Docker images. However, we
@@ -730,7 +727,8 @@ An on-demand DAST scan:
 
 NOTE: **Note:**
 You must have permission to run an on-demand DAST scan against a protected branch.
-The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches).
+The default branch is automatically protected. For more information, see
+[Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches).
 
 To run an on-demand DAST scan, you need:
 

doc/user/application_security/dependency_scanning/index.md

@@ -361,8 +361,7 @@ Here are the requirements for using dependency scanning in an offline environmen
 - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db).
 - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases.
 
-NOTE: **Note:**
-GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
+Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
 meaning the runner tries to pull Docker images from the GitLab container registry even if a local
 copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
 in an offline environment if you prefer using only locally available Docker images. However, we

doc/user/application_security/sast/index.md

@@ -11,8 +11,8 @@ type: reference, howto
 
 NOTE: **Note:**
 The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/)
-explains how **4 of the top 6 attacks were application based**. Download it
-to learn how to protect your organization.
+explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your
+organization.
 
 If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known
 vulnerabilities using Static Application Security Testing (SAST). GitLab checks the SAST report and
@@ -31,8 +31,10 @@ The results are sorted by the priority of the vulnerability:
 1. Unknown
 1. Everything else
 
-NOTE: **Note:**
-A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. The analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
+A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish
+for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST
+job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure,
+the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code).
 
 ## Use cases
 
@@ -82,10 +84,10 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu
 | Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/))  | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin     | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven)        |
 | TypeScript                                                                                                                                       | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security)                              | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2                                                                               |
 
-NOTE: **Note:**
-The Java analyzers can also be used for variants like the
+Note that the Java analyzers can also be used for variants like the
 [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html),
-[Grails](https://grails.org/) and the [Maven wrapper](https://github.com/takari/maven-wrapper).
+[Grails](https://grails.org/),
+and the [Maven wrapper](https://github.com/takari/maven-wrapper).
 
 ### Making SAST analyzers available to all GitLab tiers
 
@@ -268,11 +270,10 @@ spotbugs-sast:
       sast: gl-sast-report.json
 ```
 
-NOTE: **Note:**
-The path to the vendored directory must be specified explicitly to allow
-the analyzer to recognize the compiled artifacts. This configuration can vary per
-analyzer but in the case of Java above, `MAVEN_REPO_PATH` can be used.
-See [Analyzer settings](#analyzer-settings) for the complete list of available options.
+To allow the analyzer to recognize the compiled artifacts, you must explicitly specify the path to
+the vendored directory. This configuration can vary per analyzer but in the case of Java above, you
+can use `MAVEN_REPO_PATH`. See
+[Analyzer settings](#analyzer-settings) for the complete list of available options.
 
 ### Available variables
 
@@ -478,7 +479,6 @@ To use SAST in an offline environment, you need:
 - A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images.
 - Configure certificate checking of packages (optional).
 
-NOTE: **Note:**
 GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
 meaning the runner tries to pull Docker images from the GitLab container registry even if a local
 copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)

doc/user/application_security/secret_detection/index.md

@@ -65,26 +65,27 @@ as shown in the following table:
 
 ## Configuration
 
-NOTE: **Note:**
-From GitLab 13.1, Secret Detection was split from the [SAST configuration](../sast#configuration) into its own CI/CD template. If using GitLab 13.1 or earlier, and SAST is enabled, Secret Detection is already enabled.
+> GitLab 13.1 splits Secret Detection from the [SAST configuration](../sast#configuration) into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled.
 
 Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml)
-during the `secret-detection` job. It runs regardless of the programming
-language of your app.
+during the `secret-detection` job. It runs regardless of your app's programming language.
 
-The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) checks.
+The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and
+[TruffleHog](https://github.com/dxa4481/truffleHog) checks.
 
-NOTE: **Note:**
-The Secret Detection analyzer will ignore "Password in URL" vulnerabilities if the password begins
-with a dollar sign (`$`) as this likely indicates the password being used is an environment
-variable. For example, `https://username:$password@example.com/path/to/repo` won't be
-detected, whereas `https://username:password@example.com/path/to/repo` would be detected.
+Note that the Secret Detection analyzer ignores Password-in-URL vulnerabilities if the password
+begins with a dollar sign (`$`), as this likely indicates the password is an environment variable.
+For example, `https://username:$password@example.com/path/to/repo` isn't detected, while
+`https://username:password@example.com/path/to/repo` is.
 
 NOTE: **Note:**
-You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection)
+You don't have to configure Secret Detection manually as shown in this section if you're using
+[Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection)
 provided by [Auto DevOps](../../../topics/autodevops/index.md).
 
-To enable Secret Detection for GitLab 13.1 and later, you must include the `Secret-Detection.gitlab-ci.yml` template that’s provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined in that template.
+To enable Secret Detection for GitLab 13.1 and later, you must include the
+`Secret-Detection.gitlab-ci.yml` template that's provided as a part of your GitLab installation. For
+GitLab versions earlier than 11.9, you can copy and use the job as defined in that template.
 
 Add the following to your `.gitlab-ci.yml` file:
 

doc/user/application_security/security_dashboard/index.md

@@ -46,15 +46,19 @@ To use the security dashboards and vulnerability reports:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3.
 
-At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against.
+At the pipeline level, the Security section displays the vulnerabilities present in the branch of
+the project the pipeline ran against.
 
 ![Pipeline Security Dashboard](img/pipeline_security_dashboard_v13_3.png)
 
 Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view
 the pipeline's security findings, select the **Security** tab when viewing the pipeline.
 
-NOTE: **Note:**
-A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
+A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish
+for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST
+job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure,
+the analyzer outputs an
+[exit code](../../../development/integrations/secure.md#exit-code).
 
 ## Project Security Dashboard
 
@@ -95,9 +99,9 @@ after selecting your group. By default, the Security Dashboard displays all dete
 vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you
 have not selected a group.
 
-NOTE: **Note:**
-The Security Dashboard only shows projects with [security reports](#supported-reports) enabled in a
-group.
+Note that the Security Dashboard only shows projects with
+[security reports](#supported-reports)
+enabled in a group.
 
 ![Dashboard with action buttons and metrics](img/group_security_dashboard_v13_3.png)
 
@@ -164,6 +168,10 @@ You can export all your vulnerabilities in CSV (comma separated values) format b
 ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for
 the projects defined in the Security Dashboard, as filters don't apply to the export function.
 
+NOTE: **Note:**
+It may take several minutes for the download to start if your project contains
+thousands of vulnerabilities. Don't close the page until the download finishes.
+
 The fields in the export include:
 
 - Scanner Type
@@ -177,10 +185,6 @@ The fields in the export include:
 
 ![Export vulnerabilities](img/instance_security_dashboard_export_csv_v13_4.png)
 
-NOTE: **Note:**
-It may take several minutes for the download to start if your project contains
-thousands of vulnerabilities. Do not close the page until the download finishes.
-
 ## Keeping the dashboards up to date
 
 The Security Dashboard displays information from the results of the most recent

doc/user/application_security/terminology/index.md

@@ -13,7 +13,6 @@ This terminology list for GitLab Secure and Defend aims to:
 - Improve the effectiveness of communication regarding GitLab's application security features.
 - Get new contributors up to speed faster.
 
-NOTE: **Note:**
 This document defines application security terms in the specific context of GitLab's Secure and
 Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend.
 

doc/user/application_security/threat_monitoring/index.md

@@ -105,11 +105,10 @@ 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: **Note:**
-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).
+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
 
@@ -119,12 +118,9 @@ To change a network policy's enforcement status:
 - Click the **Enforcement status** toggle to update the selected policy.
 - Click the **Apply changes** button to deploy network policy changes.
 
-NOTE: **Note:**
-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.
+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
 
@@ -135,10 +131,8 @@ 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.
 
-NOTE: **Note:**
-The policy editor only supports the
-[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular
-Kubernetes
+Note that 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.