diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-12-20 16:37:47 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-12-20 16:37:47 +0300 |
| commit | aee0a117a889461ce8ced6fcf73207fe017f1d99 (patch) | |
| tree | 891d9ef189227a8445d83f35c1b0fc99573f4380 /doc/user/application_security | |
| parent | 8d46af3258650d305f53b819eabf7ab18d22f59e (diff) | |
Add latest changes from gitlab-org/gitlab@14-6-stable-eev14.6.0-rc42
Diffstat (limited to 'doc/user/application_security')
32 files changed, 783 insertions, 279 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 5cef0040ac3..a0f14ea59a1 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -12,6 +12,10 @@ parameters to unexpected values in an effort to cause unexpected behavior and er backend. This helps you discover bugs and potential security issues that other QA processes may miss. +INFO: +Try fuzz testing in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-api-fuzzing-docs). + We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run fuzz tests as part your CI/CD workflow. @@ -1181,7 +1185,7 @@ A bug exists in versions of the API Fuzzing analyzer prior to v1.6.196 that can The version information can be found in the job details for the `apifuzzer_fuzz` job. -If the issue is occuring with versions v1.6.196 or greater, please contact Support and provide the following information: +If the issue is occurring with versions v1.6.196 or greater, please contact Support and provide the following information: 1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. 1. The full console output of the job. @@ -1289,6 +1293,25 @@ The API Fuzzing template supports launching a docker container containing an API TODO --> +## Get support or request an improvement + +To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). + +The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and API Fuzzing. +Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding API fuzzing to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](../../../development/code_review.md#review-response-slo) to understand when you should receive a response. + +[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. + +When experiencing a behavior not working as expected, consider providing contextual information: + +- GitLab version if using a self-managed instance. +- `.gitlab-ci.yml` job definition. +- Full job console output. +- Scanner log file available as a job artifact named `gl-api-security-scanner.log`. + +WARNING: +**Sanitize data attached to a support issue**. Please remove sensitive information, including: credentials, passwords, tokens, keys, and secrets. + ## Glossary - Assert: Assertions are detection modules used by checks to trigger a fault. Many assertions have diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index 790b428bac9..c3a2c179590 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -29,7 +29,7 @@ To integrate GitLab with security scanners other than those listed here, see You can use cluster image scanning through the following methods: - [The cluster image scanning analyzer](#use-the-cluster-image-scanning-analyzer) -- [The GitLab Kubernetes agent](#cluster-image-scanning-with-the-gitlab-kubernetes-agent) +- [The GitLab Agent](#cluster-image-scanning-with-the-gitlab-agent) ## Use the cluster image scanning analyzer @@ -153,7 +153,7 @@ The included template: fetches vulnerabilities found by [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/). GitLab saves the results as a -[Cluster Image Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscluster_image_scanning) +[Cluster Image Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscluster_image_scanning) that you can download and analyze later. When downloading, you always receive the most recent artifact. @@ -177,6 +177,7 @@ You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by | `CIS_RESOURCE_NAMESPACE` | `""` | Namespace of the Kubernetes resource you want to filter vulnerabilities for. For example, `production`. | | `CIS_RESOURCE_KIND` | `""` | Kind of the Kubernetes resource you want to filter vulnerabilities for. For example, `deployment`. | | `CIS_CLUSTER_IDENTIFIER` | `""` | ID of the Kubernetes cluster integrated with GitLab. This is used to map vulnerabilities to the cluster so they can be filtered in the Vulnerability Report page. | +| `CIS_CLUSTER_AGENT_IDENTIFIER` | `""` | ID of the Kubernetes cluster agent integrated with GitLab. This maps vulnerabilities to the agent so they can be filtered in the Vulnerability Report page. | #### Override the cluster image scanning template @@ -274,26 +275,22 @@ Here's an example cluster image scanning report: } ``` -## Cluster image scanning with the GitLab Kubernetes Agent +## Cluster image scanning with the GitLab Agent -You can use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to +You can use the [GitLab Agent](../../clusters/agent/index.md) to scan images from within your Kubernetes cluster and record the vulnerabilities in GitLab. ### Prerequisites - [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) installed and configured in your cluster. -- [GitLab Kubernetes Agent](../../clusters/agent/install/index.md) +- [GitLab Agent](../../clusters/agent/install/index.md) set up in GitLab, installed in your cluster, and configured using a configuration repository. ### Configuration -The GitLab Kubernetes agent begins to run cluster image scanning once the `cluster_image_scanning` -directive is added to your Kubernetes Agent configuration repository. - -See the [Kubernetes agent configuration repository](../../clusters/agent/repository.md#scan-your-container-images-for-vulnerabilities) -reference to learn more about the cluster image scanning configuration options for the -GitLab Kubernetes agent. +The Agent runs the cluster image scanning once the `cluster_image_scanning` +directive is added to your [Agent's configuration repository](../../clusters/agent/repository.md#scan-your-container-images-for-vulnerabilities). ## Security Dashboard diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index a913d5fba92..cdcd334dba6 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -46,14 +46,14 @@ You can configure the following security controls: - Select **Manage scans** to manage the saved DAST scans, site profiles, and scanner profiles. For more details, read [DAST on-demand scans](../dast/index.md#on-demand-scans). - [Dependency Scanning](../dependency_scanning/index.md) - - Select **Configure via Merge Request** to create a merge request with the changes required to + - Select **Configure with a merge request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). - [Container Scanning](../container_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). - [Cluster Image Scanning](../cluster_image_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). - [Secret Detection](../secret_detection/index.md) - - Select **Configure via Merge Request** to create a merge request with the changes required to + - Select **Configure with a merge request** to create a merge request with the changes required to enable Secret Detection. For more details, read [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - [API Fuzzing](../api_fuzzing/index.md) - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index da2816ab6ed..bea9284873c 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,11 +9,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. +INFO: +Try out Container Scanning in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-container-scanning-docs). + Your application's Docker image may itself be based on Docker images that contain known -vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and -displays them in a merge request, you can use GitLab to audit your Docker-based apps. +vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those +vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based +apps. + +Container Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain +aspects of inspecting the items your code uses. These items typically include application and system +dependencies that are almost always imported from external sources, rather than sourced from items +you wrote yourself. + +GitLab offers both Container Scanning and [Dependency Scanning](../dependency_scanning/) +to ensure coverage for all of these dependency types. To cover as much of your risk area as +possible, we encourage you to use all of our security scanners. -GitLab provides integration with open-source tools for vulnerability static analysis in containers: +## Overview + +GitLab integrates with open-source tools for vulnerability static analysis in containers: - [Trivy](https://github.com/aquasecurity/trivy) - [Grype](https://github.com/anchore/grype) @@ -43,19 +59,9 @@ To enable container scanning in your pipeline, you need the following: - An image matching the [supported distributions](#supported-distributions). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) the Docker image to your project's container registry. -- The name of the Docker image to scan, in the `DOCKER_IMAGE` [configuration variable](#available-cicd-variables). - If you're using a third-party container registry, you might need to provide authentication credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). - For example, if you are connecting to AWS ECR, you might use the following: - -```yaml -export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) - -include: - - template: Security/Container-Scanning.gitlab-ci.yml - DOCKER_USER: AWS - DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" -``` + For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). ## Configuration @@ -75,31 +81,29 @@ The included template: (see [requirements](#requirements)) and scans it for possible vulnerabilities. GitLab saves the results as a -[Container Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscontainer_scanning) +[Container Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscontainer_scanning) that you can download and analyze later. When downloading, you always receive the most-recent -artifact. +artifact. If [dependency scan is enabled](#dependency-list), +a [Dependency Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsdependency_scanning) +is also created. The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container registry, and scans the image: ```yaml -build: - image: docker:latest - stage: build - services: - - docker:dind - variables: - IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA - script: - - docker info - - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - - docker build -t $IMAGE . - - docker push $IMAGE - include: + - template: Jobs/Build.gitlab-ci.yml - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DEFAULT_BRANCH_IMAGE: $CI_REGISTRY_IMAGE/$CI_DEFAULT_BRANCH:$CI_COMMIT_SHA ``` +Setting `CS_DEFAULT_BRANCH_IMAGE` avoids duplicate vulnerability findings when an image name differs across branches. +The value of `CS_DEFAULT_BRANCH_IMAGE` indicates the name of the scanned image as it appears on the default branch. +For more details on how this deduplication is achieved, see [Setting the default branch image](#setting-the-default-branch-image). + ### Customizing the container scanning settings There may be cases where you want to customize how GitLab scans your containers. For example, you @@ -120,6 +124,92 @@ variables: SECURE_LOG_LEVEL: 'debug' ``` +#### Scan an image in a remote registry + +To scan images located in a registry other than the project's, use the following `.gitlab-ci.yml`: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + DOCKER_IMAGE: example.com/user/image:tag +``` + +##### Authenticate to a remote registry + +Scanning an image in a private registry requires authentication. Provide the username in the `DOCKER_USER` +variable, and the password in the `DOCKER_PASSWORD` configuration variable. + +For example, to scan an image from AWS Elastic Container Registry: + +```yaml +container_scanning: + before_script: + - curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" --output "awscliv2.zip" + - unzip awscliv2.zip + - ./aws/install + - aws --version + - export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) + +include: + - template: Security/Container-Scanning.gitlab-ci.yml + DOCKER_IMAGE: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<image>:<tag> + DOCKER_USER: AWS + DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" +``` + +#### Dependency list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. + +The `CS_DISABLE_DEPENDENCY_LIST` CI/CD variable controls whether the scan creates a +[Dependency List](../dependency_list/) +report. The variable's default setting of `false` causes the scan to create the report. To disable +the report, set the variable to `true`: + +For example: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DISABLE_DEPENDENCY_LIST: "true" +``` + +#### Report language-specific findings + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7277) in GitLab 14.6. + +The `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` CI/CD variable controls whether the scan reports +findings related to programming languages. The languages supported depend on the +[scanner used](#change-scanners): + +- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/language/). +- [Grype](https://github.com/anchore/grype#features). + +By default, the report only includes packages managed by the Operating System (OS) package manager +(for example, `yum`, `apt`, `apk`, `tdnf`). To report security findings in non-OS packages, set +`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` to `"false"`: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN: "false" +``` + +When you enable this feature, you may see [duplicate findings](../terminology/#duplicate-finding) +in the [Vulnerability Report](../vulnerability_report/) +if [Dependency Scanning](../dependency_scanning/) +is enabled for your project. This happens because GitLab can't automatically deduplicate the +findings reported by the two different analyzers. + #### Available CI/CD variables You can [configure](#customizing-the-container-scanning-settings) analyzers by using the following CI/CD variables: @@ -130,6 +220,9 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | All | | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | | `CS_ANALYZER_IMAGE` | `registry.gitlab.com/security-products/container-scanning:4` | Docker image of the analyzer. | All | +| `CS_DEFAULT_BRANCH_IMAGE` | `""` | The name of the `DOCKER_IMAGE` on the default branch. See [Setting the default branch image](#setting-the-default-branch-image) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. | All | +| `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | +| `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | | `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | @@ -225,6 +318,51 @@ Prior to the GitLab 14.0 release, any variable defined under the scope `containe considered for scanners other than Clair. In GitLab 14.0 and later, all variables can be defined either as a global variable or under `container_scanning`. +### Setting the default branch image + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. + +By default, container scanning assumes that the image naming convention stores any branch-specific +identifiers in the image tag rather than the image name. When the image name differs between the +default branch and the non-default branch, previously-detected vulnerabilities show up as newly +detected in merge requests. + +When the same image has different names on the default branch and a non-default branch, you can use +the `CS_DEFAULT_BRANCH_IMAGE` variable to indicate what that image's name is on the default branch. +GitLab then correctly determines if a vulnerability already exists when running scans on non-default +branches. + +As an example, suppose the following: + +- Non-default branches publish images with the naming convention + `$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA`. +- The default branch publishes images with the naming convention + `$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA`. + +In this example, you can use the following CI/CD configuration to ensure that vulnerabilities aren't +duplicated: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DEFAULT_BRANCH_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + before_script: + - export DOCKER_IMAGE="$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA" + - | + if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then + export DOCKER_IMAGE="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" + fi +``` + +`CS_DEFAULT_BRANCH_IMAGE` should remain the same for a given `DOCKER_IMAGE`. If it changes, then a +duplicate set of vulnerabilities are created, which must be manually dismissed. + +When using [Auto DevOps](../../../topics/autodevops/index.md), `CS_DEFAULT_BRANCH_IMAGE` is +automatically set to `$CI_REGISTRY_IMAGE/$CI_DEFAULT_BRANCH:$CI_APPLICATION_TAG`. + ### Using a custom SSL CA certificate authority You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: @@ -496,7 +634,7 @@ Here's an example container scanning report: ```json-doc { - "version": "3.0.0", + "version": "14.0.0", "vulnerabilities": [ { "id": "df52bc8ce9a2ae56bbcb0c4ecda62123fbd6f69b", @@ -518,7 +656,8 @@ Here's an example container scanning report: "version": "1.4.8" }, "operating_system": "debian:9.4", - "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e" + "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e", + "default_branch_image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0:latest" }, "identifiers": [ { diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 9bb13d26d90..b35c2ed79cf 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -213,7 +213,7 @@ is a good way to balance the needs of letting a developer's per-commit pipeline and also giving the fuzzer a large amount of time to fully explore and test the app. Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs -in your latest codebase. THe following is an example of what `.gitlab-ci.yml` looks like in this +in your latest codebase. The following is an example of what `.gitlab-ci.yml` looks like in this workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): ```yaml diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 10ca3430b48..5d1e57553f4 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -61,14 +61,15 @@ The browser-based crawler can be configured using CI/CD variables. | `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com, we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but are likely to produce little benefit after five to seven instances. | | `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | | `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | -| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another. | -| `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action. | -| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. | -| `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes. | -| `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action. | -| `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or navigations. | -| `DAST_BROWSER_EXTRACT_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `5s` | The maximum amount of time to allow the browser to extract newly found elements or navigations. | -| `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis. | +| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another. | +| `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action. | +| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. | +| `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes. | +| `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action. | +| `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or navigations. | +| `DAST_BROWSER_EXTRACT_ELEMENT_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `5s` | The maximum amount of time to allow the browser to extract newly found elements or navigations. | +| `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis. | +| `DAST_BROWSER_PAGE_READY_SELECTOR` | selector | `css:#page-is-ready` | Selector that when detected as visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Note: When this selector is set, but the element is not found, the scanner waits for the period defined in `DAST_BROWSER_STABILITY_TIMEOUT` before continuing the scan. This can significantly increase scanning time if the element is not present on multiple pages within the site. | The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, `DAST_AUTH_URL`, `DAST_USERNAME`, `DAST_PASSWORD`, `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, `DAST_SUBMIT_FIELD`, `DAST_EXCLUDE_URLS`, `DAST_AUTH_VERIFICATION_URL`, `DAST_BROWSER_AUTH_VERIFICATION_SELECTOR`, `DAST_BROWSER_AUTH_VERIFICATION_LOGIN_FORM`, `DAST_BROWSER_AUTH_REPORT`, @@ -99,7 +100,7 @@ You can manage the trade-off between coverage and scan time with the following m Due to poor network conditions or heavy application load, the default timeouts may not be applicable to your application. -Browser-based scans offer the ability to adjust various timeouts to ensure it continues smoothly as it transitions from one page to the next. These values are configured using a [Duration string](https://golang.org/pkg/time/#ParseDuration), which allow you to configure durations with a prefix: `m` for minutes, `s` for seconds, and `ms` for milliseconds. +Browser-based scans offer the ability to adjust various timeouts to ensure it continues smoothly as it transitions from one page to the next. These values are configured using a [Duration string](https://pkg.go.dev/time#ParseDuration), which allow you to configure durations with a prefix: `m` for minutes, `s` for seconds, and `ms` for milliseconds. Navigations, or the act of loading a new page, usually require the most amount of time because they are loading multiple new resources such as JavaScript or CSS files. Depending on the size of these resources, or the speed at which they are returned, the default `DAST_BROWSER_NAVIGATION_TIMEOUT` may not be sufficient. diff --git a/doc/user/application_security/dast/checks/1004.1.md b/doc/user/application_security/dast/checks/1004.1.md index cbbcea1d34d..dfbc600b05b 100644 --- a/doc/user/application_security/dast/checks/1004.1.md +++ b/doc/user/application_security/dast/checks/1004.1.md @@ -36,6 +36,6 @@ Set-Cookie: {cookie_name}=<random secure value>; HttpOnly ## Links -- [owasp](https://owasp.org/www-community/HttpOnly) -- [cwe](https://cwe.mitre.org/data/definitions/1004.html) +- [OWASP](https://owasp.org/www-community/HttpOnly) +- [CWE](https://cwe.mitre.org/data/definitions/1004.html) - [Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) diff --git a/doc/user/application_security/dast/checks/16.1.md b/doc/user/application_security/dast/checks/16.1.md index bb030d2f9c4..157b2b96ed4 100644 --- a/doc/user/application_security/dast/checks/16.1.md +++ b/doc/user/application_security/dast/checks/16.1.md @@ -29,5 +29,5 @@ header to disable user agents from mis-interpreting resources. ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) - [Mozilla Blog on MIME Confusion attacks](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) diff --git a/doc/user/application_security/dast/checks/16.3.md b/doc/user/application_security/dast/checks/16.3.md index e4dcf3ece4b..6f80a2a32c6 100644 --- a/doc/user/application_security/dast/checks/16.3.md +++ b/doc/user/application_security/dast/checks/16.3.md @@ -31,5 +31,5 @@ information from the `X-Powered-By` header. ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) -- [PHP expose_php](https://www.php.net/manual/en/ini.core.php#ini.expose-php) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) +- [PHP `expose_php`](https://www.php.net/manual/en/ini.core.php#ini.expose-php) diff --git a/doc/user/application_security/dast/checks/16.4.md b/doc/user/application_security/dast/checks/16.4.md index c0161c910b0..1f72a80cb29 100644 --- a/doc/user/application_security/dast/checks/16.4.md +++ b/doc/user/application_security/dast/checks/16.4.md @@ -25,4 +25,4 @@ Consult your proxy/load balancer documentation or provider on how to disable rev ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) diff --git a/doc/user/application_security/dast/checks/16.5.md b/doc/user/application_security/dast/checks/16.5.md index 8a6f3cd8b6a..28bb9f7ee4b 100644 --- a/doc/user/application_security/dast/checks/16.5.md +++ b/doc/user/application_security/dast/checks/16.5.md @@ -4,7 +4,7 @@ group: Dynamic Analysis 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/#assignments --- -# AspNet Header(s) exposes version information +# AspNet header exposes version information ## Description @@ -26,5 +26,5 @@ section of the `Web.config` file. ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) - [IIS Remove Unwanted Headers](https://techcommunity.microsoft.com/t5/iis-support-blog/remove-unwanted-http-response-headers/ba-p/369710) diff --git a/doc/user/application_security/dast/checks/16.6.md b/doc/user/application_security/dast/checks/16.6.md new file mode 100644 index 00000000000..ddd3a10c5f8 --- /dev/null +++ b/doc/user/application_security/dast/checks/16.6.md @@ -0,0 +1,37 @@ +--- +stage: Secure +group: Dynamic Analysis +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/#assignments +--- + +# AspNetMvc header exposes version information + +## Description + +The target website returns AspNet header(s) along with version information of this website. By +exposing these values attackers may attempt to identify if the target software is vulnerable to known +vulnerabilities. Or catalog known sites running particular versions to exploit in the future when a +vulnerability is identified in the particular version. + +## Remediation + +To remove the `X-AspNetMvc-Version` information set `MvcHandler.DisableMvcResponseHeader = true;` in the +`Global.asax.cs` file in the `Application_Start()` method. + +```cs +protected void Application_Start() +{ + MvcHandler.DisableMvcResponseHeader = true; +} +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.6 | true | 16 | Passive | Low | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/16.html) +- [IIS Remove Unwanted Headers](https://techcommunity.microsoft.com/t5/iis-support-blog/remove-unwanted-http-response-headers/ba-p/369710) diff --git a/doc/user/application_security/dast/checks/614.1.md b/doc/user/application_security/dast/checks/614.1.md index 74ac73935f1..46f7f61b0c7 100644 --- a/doc/user/application_security/dast/checks/614.1.md +++ b/doc/user/application_security/dast/checks/614.1.md @@ -36,5 +36,5 @@ Set-Cookie: {cookie_name}=<random secure value>; Secure ## Links - [owasp](https://owasp.org/www-community/controls/SecureCookieAttribute) -- [cwe](https://cwe.mitre.org/data/definitions/614.html) +- [CWE](https://cwe.mitre.org/data/definitions/614.html) - [Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) diff --git a/doc/user/application_security/dast/checks/693.1.md b/doc/user/application_security/dast/checks/693.1.md index 07cb368b39a..d3f4c72c676 100644 --- a/doc/user/application_security/dast/checks/693.1.md +++ b/doc/user/application_security/dast/checks/693.1.md @@ -30,7 +30,7 @@ misinterpreted. ## Links -- [owasp](https://owasp.org/www-project-secure-headers/#x-content-type-options) -- [cwe](https://cwe.mitre.org/data/definitions/693.html) +- [OWASP](https://owasp.org/www-project-secure-headers/#x-content-type-options) +- [CWE](https://cwe.mitre.org/data/definitions/693.html) - [Mozilla Blog on MIME Confusion attacks](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) - [Mozilla MDN on X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index f1a68387eb1..a3b89e09751 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -15,6 +15,7 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [16.2](16.2.md) | Server header exposes version information | Low | Passive | | [16.3](16.3.md) | X-Powered-By header exposes version information | Low | Passive | | [16.4](16.4.md) | X-Backend-Server header exposes server information | Info | Passive | -| [16.5](16.5.md) | AspNet Header(s) exposes version information | Low | Passive | +| [16.5](16.5.md) | AspNet header exposes version information | Low | Passive | +| [16.6](16.6.md) | AspNetMvc header exposes version information | Low | Passive | | [614.1](614.1.md) | Sensitive cookie without `Secure` attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 0d8b55a92a9..4de7a566769 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -16,6 +16,10 @@ Dynamic Application Security Testing (DAST) examines applications for vulnerabilities like these in deployed environments. DAST uses the open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. +INFO: +Want to try out security scanning? +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dast-docs). + After DAST creates its report, GitLab evaluates it for discovered vulnerabilities between the source and target branches. Relevant findings are noted in the merge request. @@ -254,7 +258,7 @@ The included template creates a `dast` job in your CI/CD pipeline and scans your project's running application for possible vulnerabilities. The results are saved as a -[DAST report artifact](../../../ci/yaml/index.md#artifactsreportsdast) +[DAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/security-products/dast) @@ -956,9 +960,34 @@ An on-demand scan can be run in active or passive mode: ### View on-demand DAST scans -To view running and completed on-demand DAST scans for a project, go to +To view running completed and scheduled on-demand DAST scans for a project, go to **Security & Compliance > On-demand Scans** in the left sidebar. +- To view both running and completed scans, select **All**. +- To view running scans only, select **Running**. +- To view finished scans, select **Finished**. A finished scan is a scan that either succeeded, + failed, or was canceled. +- To view scheduled scans, select **Scheduled**. It shows on-demand scans that have a schedule + set up. Those are _not_ included in the **All** tab. + +#### Cancel an on-demand scan + +To cancel a pending or running on-demand scan, select **Cancel** (**{cancel}**) in the +on-demand scans list. + +#### Retry an on-demand scan + +To retry a scan that failed or succeeded with warnings, select **Retry** (**{retry}**) in the +on-demand scans list. + +#### View an on-demand scan's results + +To view a finished scan's results, select **View results** in the on-demand scans list. + +#### Edit an on-demand scan + +To edit an on-demand scan's settings, select **Edit** (**{pencil}**) in the **Scheduled** tab. + ### Run an on-demand DAST scan Prerequisites: @@ -1023,7 +1052,7 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. -> - [Feature flag dast_on_demand_scans_scheduler removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. +> - [Feature flag `dast_on_demand_scans_scheduler` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. To schedule a scan: @@ -1344,27 +1373,6 @@ The DAST tool always emits a JSON report file called `gl-dast-report.json` and sample reports can be found in the [DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect). -### Other formats - -Reports can also be generated in Markdown, HTML, and XML. These can be published as artifacts using the following configuration: - -```yaml -include: - template: DAST.gitlab-ci.yml - -dast: - variables: - DAST_HTML_REPORT: report.html - DAST_MARKDOWN_REPORT: report.md - DAST_XML_REPORT: report.xml - artifacts: - paths: - - $DAST_HTML_REPORT - - $DAST_MARKDOWN_REPORT - - $DAST_XML_REPORT - - gl-dast-report.json -``` - ## Optimizing DAST By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index f3ab25ccffa..0db5fb2d868 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -1138,7 +1138,7 @@ A bug exists in versions of the DAST API analyzer prior to v1.6.196 that can cau The version information can be found in the job details for the `dast_api` job. -If the issue is occuring with versions v1.6.196 or greater, please contact Support and provide the following information: +If the issue is occurring with versions v1.6.196 or greater, please contact Support and provide the following information: 1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. 1. The full console output of the job. @@ -1209,6 +1209,25 @@ deploy-test-target: - environment_url.txt ``` +## Get support or request an improvement + +To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). + +The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and DAST API. +Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](../../../development/code_review.md#review-response-slo) to understand when you should receive a response. + +[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. + +When experiencing a behavior not working as expected, consider providing contextual information: + +- GitLab version if using a self-managed instance. +- `.gitlab-ci.yml` job definition. +- Full job console output. +- Scanner log file available as a job artifact named `gl-api-security-scanner.log`. + +WARNING: +**Sanitize data attached to a support issue**. Please remove sensitive information, including: credentials, passwords, tokens, keys, and secrets. + ## Glossary - Assert: Assertions are detection modules used by checks to trigger a vulnerability. Many assertions have diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index b0d8af2606f..baafdcda6e0 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency list **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab 12.0. +> - Application dependencies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab 12.0. +> - System dependencies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6698) in GitLab 14.6. Use the dependency list to review your project's dependencies and key details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. @@ -22,8 +23,9 @@ The dependency list only shows the results of the last successful pipeline to ru To view your project's dependencies, ensure you meet the following requirements: -- The [Dependency Scanning](../dependency_scanning/index.md) CI job must be - configured for your project. +- The [Dependency Scanning](../dependency_scanning/index.md) + or [Container Scanning](../container_scanning/index.md) + CI job must be configured for your project. - Your project uses at least one of the [languages and package managers](../dependency_scanning/index.md#supported-languages-and-package-managers) supported by Gemnasium. @@ -38,7 +40,7 @@ GitLab displays dependencies with the following information: |-----------|-------------| | Component | The dependency's name and version. | | Packager | The packager used to install the dependency. | -| Location | A link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | +| Location | For system dependencies, this lists the image that was scanned. For application dependencies, this shows a link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | | License | Links to dependency's software licenses. | Displayed dependencies are initially sorted by the severity of their known vulnerabilities, if any. They @@ -63,6 +65,7 @@ Dependency paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) - [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) +- [sbt](https://www.scala-sbt.org) ## Licenses @@ -82,4 +85,4 @@ You can download your project's list of dependencies and their details in JSON f ### Using the API -You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). +You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the Gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 8559d5af02e..1b502b306bb 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -32,6 +32,9 @@ to launch dedicated containers for each analysis. Dependency Scanning is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. +WARNING: +The `bundler-audit` analyzer is deprecated and will be removed in GitLab 15.0 since it duplicates the functionality of the `gemnasium` analyzer. For more information, read the [deprecation announcement](../../../update/deprecations.md#deprecation-of-bundler-audit-dependency-scanning-tool). + ## Official default analyzers Any custom change to the official analyzers can be achieved by using a @@ -118,12 +121,12 @@ The following table lists the data available for each official analyzer. | File | ✓ | ⚠ | ✓ | | Start line | 𐄂 | 𐄂 | 𐄂 | | End line | 𐄂 | 𐄂 | 𐄂 | -| External ID (e.g., CVE) | ✓ | ✓ | ⚠ | +| External ID (for example, CVE) | ✓ | ✓ | ⚠ | | URLs | ✓ | ✓ | ✓ | | Internal doc/explanation | ✓ | 𐄂 | 𐄂 | | Solution | ✓ | ✓ | 𐄂 | | Confidence | 𐄂 | 𐄂 | 𐄂 | -| Affected item (e.g. class or package) | ✓ | ✓ | ✓ | +| Affected item (for example, class or package) | ✓ | ✓ | ✓ | | Source code extract | 𐄂 | 𐄂 | 𐄂 | | Internal ID | ✓ | 𐄂 | 𐄂 | | Date | ✓ | 𐄂 | 𐄂 | @@ -134,4 +137,4 @@ The following table lists the data available for each official analyzer. - 𐄂 => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it. The values provided by these tools are heterogeneous, so they are sometimes -normalized into common values (e.g., `severity`, `confidence`, etc). +normalized into common values (for example, `severity`, `confidence`, etc). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 3c6db8c3ee9..192d8449297 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -7,10 +7,43 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning **(ULTIMATE)** +INFO: +Try out Dependency Scanning in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dependency-scanning-docs). + The Dependency Scanning feature can automatically find security vulnerabilities in your -dependencies while you're developing and testing your applications. For example, dependency scanning -lets you know if your application uses an external (open source) library that is known to be -vulnerable. You can then take action to protect your application. +software dependencies while you're developing and testing your applications. For example, +dependency scanning lets you know if your application uses an external (open source) +library that is known to be vulnerable. You can then take action to protect your application. + +Dependency Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain +aspects of inspecting the items your code uses. These items typically include application and system +dependencies that are almost always imported from external sources, rather than sourced from items +you wrote yourself. + +GitLab offers both Dependency Scanning and Container Scanning +to ensure coverage for all of these dependency types. To cover as much of your risk area as +possible, we encourage you to use all of our security scanners: + +- Dependency Scanning analyzes your project and tells you which software dependencies, + including upstream dependencies, have been included in your project, and what known + risks the dependencies contain. Dependency Scanning modifies its behavior based + on the language and package manager of the project. It typically looks for a lock file + then performs a build to fetch upstream dependency information. In the case of + containers, Dependency Scanning uses the compatible manifest and reports only these + declared software dependencies (and those installed as a sub-dependency). + Dependency Scanning can not detect software dependencies that are pre-bundled + into the container's base image. To identify pre-bundled dependencies, enable + [Container Scanning](../container_scanning/) language scanning using the + [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/#report-language-specific-findings). +- [Container Scanning](../container_scanning/) analyzes your containers and tells + you about known risks in the operating system's (OS) packages. You can configure it + to also report on software and language dependencies, if you enable it and use + the [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/#report-language-specific-findings). + Turning this variable on can result in some duplicate findings, as we do not yet + de-duplicate results between Container Scanning and Dependency Scanning. For more details, + efforts to de-duplicate these findings can be tracked in + [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348655). ## Overview @@ -142,7 +175,7 @@ table.supported-languages ul { <tr> <td>Go</td> <td>N/A</td> - <td><a href="https://golang.org/">Go</a></td> + <td><a href="https://go.dev/">Go</a></td> <td><code>go.sum</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> @@ -279,10 +312,10 @@ table.supported-languages ul { GitLab analyzers obtain dependency information using one of the following two methods: -1. [Parsing lockfiles directly.](#obtaining-dependendency-information-by-parsing-lockfiles) -1. [Running a package manager or build tool to generate a dependency information file which is then parsed.](#obtaining-dependendency-information-by-running-a-package-manager-to-generate-a-parsable-file) +1. [Parsing lockfiles directly.](#obtaining-dependency-information-by-parsing-lockfiles) +1. [Running a package manager or build tool to generate a dependency information file which is then parsed.](#obtaining-dependency-information-by-running-a-package-manager-to-generate-a-parsable-file) -#### Obtaining dependendency information by parsing lockfiles +#### Obtaining dependency information by parsing lockfiles The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: @@ -296,7 +329,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/master/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/lockfile-v2-FREEZE/package-lock.json#L4) | | yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/js-yarn/-/blob/master/yarn.lock) | -#### Obtaining dependendency information by running a package manager to generate a parsable file +#### Obtaining dependency information by running a package manager to generate a parsable file To support the following package managers, the GitLab analyzers proceed in two steps: @@ -309,7 +342,7 @@ To support the following package managers, the GitLab analyzers proceed in two s | sbt | [1.3.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L263), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L272), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L281), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L290), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L299) | | Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | | Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5) | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3) | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | | pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | | Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | @@ -370,7 +403,7 @@ We only execute one build in the directory where a build file has been detected, Please note, we support the following types of Java project structures: - [multi-project sbt builds](https://www.scala-sbt.org/1.x/docs/Multi-Project.html) -- [multi-project gradle builds](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) +- [multi-project Gradle builds](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) - [multi-module maven projects](https://maven.apache.org/pom.html#Aggregation) #### JavaScript @@ -425,7 +458,7 @@ include: The included template creates dependency scanning jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[dependency scanning report artifact](../../../ci/yaml/index.md#artifactsreportsdependency_scanning) +[dependency scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsdependency_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest dependency scanning artifact available. @@ -440,7 +473,7 @@ from the Security Configuration page. 1. In the project where you want to enable Dependency Scanning, navigate to **Security & Compliance > Configuration**. -1. In the **Dependency Scanning** row, select **Configure via Merge Request**. +1. In the **Dependency Scanning** row, select **Configure with a merge request**. This automatically creates a merge request with the changes necessary to enable Dependency Scanning that you can review and merge to complete the configuration. @@ -506,7 +539,7 @@ The following variables allow configuration of global dependency scanning settin | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | | `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_DEFAULT_ANALYZERS` | ([**DEPRECATED - use `DS_EXCLUDED_ANALYZERS` instead**](https://gitlab.com/gitlab-org/gitlab/-/issues/287691)) Override the names of the official default images. For more information, see [Dependency Scanning Analyzers](analyzers.md). | -| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | +| `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info`. | @@ -596,7 +629,7 @@ The dependency scanning tool emits a JSON report file. For more information, see Here's an example dependency scanning report: -```json-doc +```json { "version": "2.0", "vulnerabilities": [ @@ -709,7 +742,7 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s ## Contributing to the vulnerability database -You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project +You can search the [`gemnasium-db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project to find a vulnerability in the Gemnasium database. You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). @@ -781,7 +814,7 @@ Support for custom certificate authorities was introduced in the following versi Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry. You must also change the value of `GEMNASIUM_DB_REMOTE_URL` to the location of your offline Git copy of the -[gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/): +[`gemnasium-db` advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/): ```yaml include: @@ -1033,3 +1066,19 @@ scan occurs. Because the cache is downloaded before the analyzer run occurs, the file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. We recommend committing the lock files, which prevents this warning. + +### I no longer get the latest Docker image after setting `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` + +If you have manually set `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` for specific reasons, +and now must update your configuration to again get the latest patched versions of our +analyzers, edit your `gitlab-ci.yml` file and either: + +- Set your `DS_MAJOR_VERSION` to match the latest version as seen in + [our current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml#L18). +- If you hardcoded the `DS_ANALYZER_IMAGE` variable directly, change it to match the latest + line as found in our [current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml). + The line number will vary depending on which scanning job you edited. + + For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest + `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to + `"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"`. diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index a58a00a869b..c17ebc68b4d 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -32,14 +32,14 @@ GitLab IaC scanning supports a variety of IaC configuration files. Our IaC secur | Configuration File Type | Scan tool | Introduced in GitLab Version | |------------------------------------------|----------------------------------|-------------------------------| -| Ansible | [kics](https://kics.io/) | 14.5 | -| AWS CloudFormation | [kics](https://kics.io/) | 14.5 | -| Kubernetes | [kics](https://kics.io/) | 14.5 | -| Terraform | [kics](https://kics.io/) | 14.5 | +| Ansible | [KICS](https://kics.io/) | 14.5 | +| AWS CloudFormation | [KICS](https://kics.io/) | 14.5 | +| Kubernetes | [KICS](https://kics.io/) | 14.5 | +| Terraform | [KICS](https://kics.io/) | 14.5 | ### Making IaC analyzers available to all GitLab tiers -All open source (OSS) analyzers are availibile with the GitLab Free tier. Future propietary analyzers may be restricted to higher tiers. +All open source (OSS) analyzers are available with the GitLab Free tier. Future proprietary analyzers may be restricted to higher tiers. #### Summary of features per tier @@ -74,7 +74,7 @@ The included template creates IaC scanning jobs in your CI/CD pipeline and scans your project's configuration files for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/yaml/index.md#artifactsreportssast) +[SAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssast) that you can download and analyze. ### Enable IaC Scanning via an automatic merge request @@ -84,7 +84,7 @@ from the Security Configuration page: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. -1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure via Merge Request**. +1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. This automatically creates a merge request with the changes necessary to enable IaC Scanning that you can review and merge to complete the configuration. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index d5e801ced9c..5500f5a10c4 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -16,6 +16,10 @@ GitLab can check your application for security vulnerabilities including: Statistics and details on vulnerabilities are included in the merge request. Providing actionable information _before_ changes are merged enables you to be proactive. +INFO: +Want to try out security scanning? +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-application-security-docs). + GitLab also provides high-level statistics of vulnerabilities across projects and groups: - The [Security Dashboard](security_dashboard/index.md) provides a @@ -42,7 +46,7 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | -| [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) | Analyze your IaC coniguration files for known vulnerabilities. | +| [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) | Analyze your IaC configuration files for known vulnerabilities. | | [Coverage fuzzing](coverage_fuzzing/index.md) | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | | [Cluster Image Scanning](cluster_image_scanning/index.md) | Scan Kubernetes clusters for known vulnerabilities. | diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_3.png b/doc/user/application_security/policies/img/security_policy_project_v14_3.png Binary files differdeleted file mode 100644 index 5e3aefaeb81..00000000000 --- a/doc/user/application_security/policies/img/security_policy_project_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_6.png b/doc/user/application_security/policies/img/security_policy_project_v14_6.png Binary files differnew file mode 100644 index 00000000000..feea1b1b01c --- /dev/null +++ b/doc/user/application_security/policies/img/security_policy_project_v14_6.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 4d8be411dc5..e6dbd96537f 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -159,8 +159,8 @@ at the bottom of the editor. 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/install/index.md#create-an-agent-record-in-gitlab) -a Kubernetes Agent for this project. +and [configured](../../clusters/agent/install/index.md#register-an-agent-with-gitlab) +an agent for this project. There are two ways to create policy alerts: @@ -228,7 +228,13 @@ must create an association between that project and the project you want to appl project you would like to link from the dropdown menu. 1. Select **Save**. -  +  + +### Unlink Security Policy projects + +Project owners can unlink Security Policy projects from development projects. To do this, follow +the steps described in [Security Policy project selection](#security-policy-project-selection), +but select the trash can icon in the modal. ### Scan Execution Policy editor @@ -237,9 +243,9 @@ Only project Owners have the [permissions](../../permissions.md#project-members- 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 +at the bottom of the editor. You are 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 +policy project is automatically created. Existing policies can also be removed from the editor interface by selecting **Delete policy** at the bottom of the editor. @@ -287,7 +293,7 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | -| `clusters` | `object` | | The cluster where the given policy will enforce running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that will be scanned. | +| `clusters` | `object` | | The cluster where the given policy enforces running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. | #### `cluster` schema @@ -295,10 +301,10 @@ Use this schema to define `clusters` objects in the [`schedule` rule type](#sche | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | -| `resources` | `array` of `string` | | The resource name that will be scanned (only the first value is currently supported). | -| `namespaces` | `array` of `string` | | The namespace that will be scanned (only the first value is currently supported). | -| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | +| `containers` | `array` of `string` | | The container name to be scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name to be scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace to be scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind to be scanned (only the first value is currently supported). | ### `scan` action type @@ -307,9 +313,10 @@ rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `dast`, `secret_detection` | The action's type. | +| `scan` | `string` | `dast`, `secret_detection`, `sast`, `container_scanning`, `cluster_image_scanning` | 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. This field should only be set if `scan` type is `dast`. | | `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. This field should only be set if `scan` type is `dast`.| +| `variables` | `object` | | Set of variables applied and enforced for the selected scan. The object's key is the variable name with a value provided as a string. | Note the following: @@ -327,9 +334,10 @@ Note the following: - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-detection) mode when executed as part of a scheduled scan. -- A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. - They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. +- A container scanning and cluster image scanning scans configured for the `pipeline` rule type ignores the cluster defined in the `clusters` object. + They use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). +- The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/parent_child_pipelines.md). ### Example security policies project @@ -357,7 +365,7 @@ scan_execution_policy: - type: schedule branches: - main - cadence: */10 * * * * + cadence: "*/10 * * * *" actions: - scan: dast scanner_profile: Scanner Profile C @@ -372,13 +380,16 @@ scan_execution_policy: - main actions: - scan: secret_detection + - scan: sast + variables: + SAST_EXCLUDED_ANALYZERS: brakeman - scan: container_scanning - name: Enforce Cluster Image Scanning on production-cluster every 24h description: This policy enforces Cluster Image Scanning scan to run every 24 hours enabled: true rules: - type: schedule - cadence: '15 3 * * *' + cadence: "15 3 * * * clusters: production-cluster: containers: @@ -399,7 +410,8 @@ In this example: `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. -- Secret detection and container scanning scans run for every pipeline executed on the `main` branch. +- Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` + branch. The SAST scan runs with the `SAST_EXCLUDED_ANALYZER` variable set to `"brakeman"`. - Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 06c57e68121..8c7e03f69fd 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -59,7 +59,7 @@ support the following features: ## Official default analyzers Any custom change to the official analyzers can be achieved by using a -[CI/CD variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). +[CI/CD variable in your `.gitlab-ci.yml`](index.md#available-cicd-variables). ### Using a custom Docker mirror diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index af8585c6a18..fd05ecad8f2 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -144,7 +144,7 @@ as shown in the following table: | Capability | In Free | In Ultimate | |:---------------------------------------------------------------------------------------|:--------------------|:-------------------| | [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -184,7 +184,7 @@ The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/yaml/index.md#artifactsreportssast) +[SAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssast) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. @@ -242,25 +242,6 @@ The configuration tool works best with no existing `.gitlab-ci.yml` file, or wit configuration file. If you have a complex GitLab configuration file it may not be parsed successfully, and an error may occur. -### Customizing the SAST settings - -The SAST settings can be changed through [CI/CD variables](#available-cicd-variables) -by using the -[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. -In the following example, we include the SAST template and at the same time we -set the `SAST_GOSEC_LEVEL` variable to `2`: - -```yaml -include: - - template: Security/SAST.gitlab-ci.yml - -variables: - SAST_GOSEC_LEVEL: 2 -``` - -Because the template is [evaluated before](../../../ci/yaml/index.md#include) -the pipeline configuration, the last mention of the variable takes precedence. - ### Overriding SAST jobs WARNING: @@ -305,16 +286,16 @@ spotbugs-sast: ### Customize rulesets **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for +> passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. You can customize the default scanning rules provided by our SAST analyzers. +Ruleset customization supports two capabilities that can be used +simultaneously: -Ruleset customization supports two capabilities: - -1. Disabling predefined rules (available for all analyzers). -1. Modifying the default behavior of a given analyzer (only available for `nodejs-scan` and `gosec`). - -These capabilities can be used simultaneously. +- [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). Available for all analyzers. +- Modifying the default behavior of a given analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`. To customize the default scanning rules, create a file containing custom rules. These rules are passed through to the analyzer's underlying scanner tools. @@ -323,81 +304,303 @@ To create a custom ruleset: 1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. 1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. -1. In the `sast-ruleset.toml` file, do one of the following: - - - Disable predefined rules belonging to SAST analyzers. In this example, the three disabled rules - belong to `eslint` and `sobelow` by matching the corresponding identifiers' `type` and `value`: - - ```toml - [eslint] - [[eslint.ruleset]] - disable = true - [eslint.ruleset.identifier] - type = "eslint_rule_id" - value = "security/detect-object-injection" - - [[eslint.ruleset]] - disable = true - [eslint.ruleset.identifier] - type = "cwe" - value = "185" - - [sobelow] - [[sobelow.ruleset]] - disable = true - [sobelow.ruleset.identifier] - type = "sobelow_rule_id" - value = "sql_injection" - ``` - - - Define a custom analyzer configuration. In this example, customized rules are defined for the - `nodejs-scan` scanner: - - ```toml - [nodejs-scan] - description = 'custom ruleset for nodejs-scan' - - [[nodejs-scan.passthrough]] - type = "raw" - value = ''' - - nodejs-extensions: - - .js - - template-extensions: - - .new - - .hbs - - '' - - ignore-filenames: - - skip.js - - ignore-paths: - - __MACOSX - - skip_dir - - node_modules - - ignore-extensions: - - .hbs - - ignore-rules: - - regex_injection_dos - - pug_jade_template - - express_xss - - ''' - ``` - - - Provide the name of the file containing a custom analyzer configuration. In this example, - customized rules for the `gosec` scanner are contained in the file `gosec-config.json`: - - ```toml - [gosec] - description = 'custom ruleset for gosec' - - [[gosec.passthrough]] - type = "file" - value = "gosec-config.json" - ``` + +#### Disable predefined analyzer rules + +To disable analyzer rules: + +1. Set the `disabled` flag to `true` in the context of a `ruleset` section + +1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: + +- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. + +- a `value` field, to name the rule to be disabled. + +##### Example: Disable predefined rules of SAST analyzers + +In the following example, the disabled rules are assigned to `eslint` +and `sobelow` by matching the `type` and `value` of identifiers: + +```toml +[eslint] + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "eslint_rule_id" + value = "security/detect-object-injection" + + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "cwe" + value = "185" + +[sobelow] + [[sobelow.ruleset]] + disable = true + [sobelow.ruleset.identifier] + type = "sobelow_rule_id" + value = "sql_injection" +``` + +#### Synthesize a custom configuration + +To create a custom configuration, you can use passthrough chains. + +A passthrough is a single step in a passthrough chain. The passthrough is evaluated +in a sequence to incrementally build a configuration. The configuration is then +passed to the target analyzer. + +A configuration section for an analyzer has the following +parameters: + +| Parameter | Explanation | +| ------------- | ------ | +| `description` | Description about the analyzer configuration section. | +| `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. | +| `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. | +| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | +| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | + +A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20. +There are several types of passthroughs: + +| Type | Description | +| ------ | ------ | +| `file` | Use a file that is already available in the Git repository. | +| `raw` | Provide the configuration inline. | +| `git` | Pull the configuration from a remote Git repository. | +| `url` | Fetch the analyzer configuration through HTTP. | + +If multiple passthrough sections are defined in a passthrough chain, their +position in the chain defines the order in which they are evaluated. + +- Passthroughs listed later in the chain sequence have a higher precedence. +- Passthroughs with a higher precedence overwrite (default) and append data + yielded by previous passthroughs. This is useful for cases where you need to + use or modify an existing configuration. + +Configure a passthrough these parameters: + +| Parameter | Explanation | +| ------------ | ----------- | +| `type` | One of `file`, `raw`, `git` or `url`. | +| `target` | The target file that contains the data written by the passthrough evaluation. If no value is provided, a random target file is generated. | +| `mode` | `overwrite`: if `target` exists, overwrites the file; `append`: append to file instead. The default is `overwrite`. | +| `ref` | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. | +| `subdir` | This option only applies to the `git` passthrough type and can be used to only consider a certain subdirectory of the source Git repository. | +| `value` | For the `file` `url` and `git` types, `value` defines the source location of the file/Git repository; for the `raw` type, `value` carries the raw content to be passed through. | +| `validator` | Can be used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target files after the application of a passthrough. Per default, no validator is set. | + +The amount of data generated by a single passthrough is limited to 1MB. + +#### Passthrough configuration examples + +##### Raw passthrough for nodejs-scan + +Define a custom analyzer configuration. In this example, customized rules are +defined for the `nodejs-scan` scanner: + +```toml +[nodejs-scan] + description = 'custom ruleset for nodejs-scan' + + [[nodejs-scan.passthrough]] + type = "raw" + value = ''' +- nodejs-extensions: + - .js + + template-extensions: + - .new + - .hbs + - '' + + ignore-filenames: +- skip.js + + ignore-paths: + - __MACOSX + - skip_dir + - node_modules + + ignore-extensions: + - .hbs + + ignore-rules: + - regex_injection_dos + - pug_jade_template + - express_xss + +''' +``` + +##### File passthrough for gosec + +Provide the name of the file containing a custom analyzer configuration. In +this example, customized rules for the `gosec` scanner are contained in the +file `gosec-config.json`: + +```toml +[gosec] + description = 'custom ruleset for gosec' + + [[gosec.passthrough]] + type = "file" + value = "gosec-config.json" +``` + +##### Passthrough chain for semgrep + +In the below example, we generate a custom configuration under the `/sgrules` +target directory with a total `timeout` of 60 seconds. + +Several passthrouh types generate a configuration for the target analyzer: + +- Two `git` passthrough sections pull the head of branch + `refs/remotes/origin/test` from the `myrules` Git repository, and revision + `97f7686` from the `sast-rules` Git repostory. From the `sast-rules` Git + repository, only data from the `go` subdirectory is considered. + - The `sast-rules` entry has a higher precedence because it appears later in + the configuration. + - If there is a filename collision between files in both repositories, files + from the `sast` repository overwrite files from the `myrules` repository, + as `sast-rules` has higher precedence. +- The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The + full path is `/sgrules/insecure.yml`. +- The `url` entry fetches a configuration made available through a URL and + stores it in the `/sgrules/gosec.yml` file. + +Afterwards, semgrep is invoked with the final configuration located under +`/sgrules`. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + timeout = 60 + + [[semgrep.passthrough]] + type = "git" + value = "https://gitlab.com/user/myrules.git" + ref = "refs/remotes/origin/test" + + [[semgrep.passthrough]] + type = "git" + value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git" + ref = "97f7686db058e2141c0806a477c1e04835c4f395" + subdir = "go" + + [[semgrep.passthrough]] + type = "raw" + target = "insecure.yml" + value = """ +rules: +- id: "insecure" + patterns: + - pattern: "func insecure() {...}" + message: | + Insecure function insecure detected + metadata: + cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor" + severity: "ERROR" + languages: + - "go" + """ + + [[semgrep.passthrough]] + type = "url" + value = "https://semgrep.dev/c/p/gosec" + target = "gosec.yml" +``` + +##### Interpolation + +The code snippet below shows an example configuration that uses an environment +variable `$GITURL` to access a private repositories with a Git URL. The variable contains +a username and token in the `value` field (for example `https://user:token@url`). +It does not explicitly store credentials in the configuration file. To reduce the risk of leaking secrets through created paths and files, use this feature with caution. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + interpolate = true + + [[semgrep.passthrough]] + type = "git" + value = "$GITURL" + ref = "refs/remotes/origin/main" +``` + +##### Configure the append mode for passthroughs + +To append data to previous passthroughs, use the `append` mode for the +passthrough types `file`, `url`, and `raw`. + +Passthroughs in `override` mode overwrite files +created when preceding passthroughs in the chain find a naming +collision. If `mode` is set to `append`, a passthrough appends data to the +files created by its predecessors instead of overwriting. + +In the below semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: + +- `insecure` +- `secret` + +These rules add a search pattern to the analyzer and extends semgrep capabilities. + +For passthrough chains we recommend that you enable validation. To enable validation, +you can either: + +- set `validate` to `true` + +- set a passthrough `validator` to `xml`, `json`, `yaml`, or `toml`. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + validate = true + + [[semgrep.passthrough]] + type = "raw" + target = "insecure.yml" + value = """ +rules: +- id: "insecure" + patterns: + - pattern: "func insecure() {...}" + message: | + Insecure function insecure detected + metadata: + cwe: "... + severity: "ERROR" + languages: + - "go" +""" + + [[semgrep.passthrough]] + type = "raw" + mode = "append" + target = "insecure.yml" + value = """ +- id: "secret" + patterns: + - pattern-either: + - pattern: "$MASK = \"...\"" + - metavariable-regex: + metavariable: "$MASK" + regex: "(password|pass|passwd|pwd|secret|token)" + message: | + Use of Hard-coded Password + cwe: "..." + severity: "ERROR" + languages: + - "go" +""" +``` ### False Positive Detection **(ULTIMATE)** @@ -483,7 +686,20 @@ can use `MAVEN_REPO_PATH`. See ### Available CI/CD variables -SAST can be [configured](#customizing-the-sast-settings) using CI/CD variables. +SAST can be configured using the [`variables`](../../../ci/yaml/index.md#variables) parameter in +`.gitlab-ci.yml`. + +The following example includes the SAST template to override the `SAST_GOSEC_LEVEL` +variable to `2`. The template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline +configuration, so the last mention of the variable takes precedence. + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml + +variables: + SAST_GOSEC_LEVEL: 2 +``` #### Logging level diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 140f660d729..b5e54e35e58 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -34,33 +34,8 @@ GitLab displays identified secrets visibly in a few places: ## Supported secrets Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). - -The [default ruleset provided by TruffleHog and Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: - -- Cloud services: - - Amazon Web Services (AWS) - - Google Cloud Platform (GCP) - - Heroku API -- Encryption keys: - - PKCS8 - - RSA - - SSH - - PGP - - DSA - - EC -- Social media platforms: - - Facebook API - - Twitter API -- Cloud SaaS vendors: - - GitHub API - - Shopify API - - Slack Token - - Slack Webhook - - Stripe API - - Twilio API - - Generic API key strings starting with `api-` -- Password in URL -- U.S. Social Security Number +The [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes **90+ secret detection patterns**. +You can contribute "well-identifiable" secrets by follow the steps detailed in the [community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). WARNING: Gitleaks does not support scanning binary files. @@ -134,7 +109,7 @@ The included template creates Secret Detection jobs in your CI/CD pipeline and s your project's source code for secrets. The results are saved as a -[Secret Detection report artifact](../../../ci/yaml/index.md#artifactsreportssecret_detection) +[Secret Detection report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssecret_detection) that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. @@ -148,10 +123,10 @@ from the Security Configuration page. 1. In the project where you want to enable Secret Detection, go to **Security & Compliance > Configuration**. -1. In the **Secret Detection** row, select **Configure via Merge Request**. +1. In the **Secret Detection** row, select **Configure with a merge request**. This automatically creates a merge request with the changes necessary to enable Secret Detection -that you can review and merge to complete the configuration. +that you can review and merge to complete the configuration. NOTE: The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal @@ -210,10 +185,12 @@ Secret Detection can be customized by defining available CI/CD variables: ### Custom rulesets **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for +> passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. You can customize the default secret detection rules provided with GitLab. -Customization allows replace the default secret detection rules with rules that you define. +Customization allows replacing the default secret detection rules with rules that you define. To create a custom ruleset: @@ -251,6 +228,9 @@ To create a custom ruleset: value = "config/gitleaks.toml" ``` +Passthroughs can also be chained to build more complex configurations. +For more details, see [SAST Customize ruleset section](../sast/index.md#customize-rulesets). + ### Logging level To control the verbosity of logs set the `SECURE_LOG_LEVEL` CI/CD variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png Binary files differindex ac123d2b528..ad9122ee23c 100644 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 87875ec15ba..5afbe1ca54e 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -7,6 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboards and Security Center **(ULTIMATE)** +INFO: +Want to try out security scanning? +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-security-dashboard-docs). + GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: - Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [groups](#group-security-dashboard), and diff --git a/doc/user/application_security/vulnerability_report/img/operational_vulnerability_tab_v14_6.png b/doc/user/application_security/vulnerability_report/img/operational_vulnerability_tab_v14_6.png Binary files differnew file mode 100644 index 00000000000..52a298584dd --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/operational_vulnerability_tab_v14_6.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index d13647937a2..3773bb59c5a 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -7,8 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** -The Vulnerability Report provides information about vulnerabilities from scans of the branch most -recently merged into the default branch. It is available for groups, projects, and the Security Center. +The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It is available for projects, groups, and the Security Center. At all levels, the Vulnerability Report contains: @@ -215,3 +214,12 @@ You can dismiss a vulnerability for the entire project: 1. Optional. Add a reason for the dismissal and select **Save comment**. To undo this action, select a different status from the same menu. + +## Operational vulnerabilities + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6345) in GitLab 14.6. + +The **Operational vulnerabilities** tab lists vulnerabilities found by the `cluster_image_scanner`. +This tab appears on the project, group, and Security Center vulnerability reports. + + |
