Commit ecefdd6e authored by Russell Dickenson's avatar Russell Dickenson

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

Removing notes from security docs

See merge request gitlab-org/gitlab!43766
parents 93f98b74 58720e99
......@@ -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:
......
......@@ -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
......
......@@ -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:
......
......@@ -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
......
......@@ -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)
......
......@@ -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:
......
......@@ -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
......
......@@ -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.
......
......@@ -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.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment