diff options
Diffstat (limited to 'doc/user/application_security')
27 files changed, 353 insertions, 175 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 57c5f8bc1fa..09e38d5048f 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Fuzz Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 type: reference, howto --- @@ -139,7 +139,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Warning:** +WARNING: **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -147,7 +147,7 @@ data. Only run fuzzing against a test server. ### HTTP Archive (HAR) The [HTTP Archive format (HAR)](http://www.softwareishard.com/blog/har-12-spec/) -is an archive file format for logging HTTP transactions. When used with GitLab's API fuzzer, HAR +is an archive file format for logging HTTP transactions. When used with the GitLab API fuzzer, HAR must contain records of calling the web API to test. The API fuzzer extracts all the requests and uses them to perform testing. @@ -155,10 +155,10 @@ You can use various tools to generate HAR files: - [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy - [Insomnia Core](https://insomnia.rest/): API client -- [Chrome](https://www.google.com/chrome): Browser +- [Chrome](https://www.google.com/chrome/): Browser - [Firefox](https://www.mozilla.org/en-US/firefox/): Browser -DANGER: **Warning:** +WARNING: HAR files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the HAR file contents before adding them to a repository. @@ -230,7 +230,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Warning:** +WARNING: **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -243,11 +243,11 @@ developers and testers use to call various types of APIs. The API definitions for use with API Fuzzing. When exporting, make sure to select a supported version of Postman Collection: v2.0 or v2.1. -When used with GitLab's API fuzzer, Postman Collections must contain definitions of the web API to +When used with the GitLab API fuzzer, Postman Collections must contain definitions of the web API to test with valid data. The API fuzzer extracts all the API definitions and uses them to perform testing. -DANGER: **Warning:** +WARNING: Postman Collection files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the Postman Collection file contents before adding them to a repository. @@ -321,7 +321,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Warning:** +WARNING: **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -488,24 +488,24 @@ increases as the numbers go up. To use a configuration file, add it to your repo | Environment variable | Description | |-----------------------------|--------------------| -| `FUZZAPI_VERSION` |Specify API Fuzzing container version. Defaults to `latest`. | -| `FUZZAPI_TARGET_URL` |Base URL of API testing target. | -|[`FUZZAPI_CONFIG`](#configuration-files)|API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | -|[`FUZZAPI_PROFILE`](#configuration-files)|Configuration profile to use during testing. Defaults to `Quick`. | -| `FUZZAPI_REPORT` |Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | -|[`FUZZAPI_OPENAPI`](#openapi-specification)|OpenAPI specification file or URL. | -|[`FUZZAPI_HAR`](#http-archive-har)|HTTP Archive (HAR) file. | -|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection)|Postman Collection file. | -|[`FUZZAPI_OVERRIDES_FILE`](#overrides) |Path to a JSON file containing overrides. | -|[`FUZZAPI_OVERRIDES_ENV`](#overrides) |JSON string containing headers to override. | -|[`FUZZAPI_OVERRIDES_CMD`](#overrides) |Overrides command. | -|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) |How often to run overrides command in seconds. Defaults to `0` (once). | -|[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) |Username for HTTP authentication. | -|[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) |Password for HTTP authentication. | +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | +|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | +|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | +|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | +|[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | +|[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | +|[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | +|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | +|[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | +|[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | <!--|[`FUZZAPI_D_TARGET_IMAGE`](#target-container) |API target docker image | |[`FUZZAPI_D_TARGET_ENV`](#target-container) |Docker environment options | -|[`FUZZAPI_D_TARGET_VOLUME`](#target-container)|Docker volume options | +|[`FUZZAPI_D_TARGET_VOLUME`](#target-container) | Docker volume options | |[`FUZZAPI_D_TARGET_PORTS`](#target-container) |Docker port options | | `FUZZAPI_D_WORKER_IMAGE` |Custom worker docker image | | `FUZZAPI_D_WORKER_ENV` |Custom worker docker environment options | @@ -720,45 +720,43 @@ Repeat this configuration for each profile as needed. ## Running your first scan -When configured correctly, a CI/CD pipeline contains a `Fuzz` stage and a `apifuzzer_fuzz` job. The -job only fails when an invalid configuration is provided. During normal operation, the job always -succeeds even if faults are identified during fuzz testing. +When configured correctly, a CI/CD pipeline contains a `fuzz` stage and an `apifuzzer_fuzz` or +`apifuzzer_fuzz_dnd` job. The job only fails when an invalid configuration is provided. During +normal operation, the job always succeeds even if faults are identified during fuzz testing. -Faults are displayed on the **Tests** pipeline tab with the suite name **API-Fuzzing**. The **Name** -field on the **Tests** page includes the fuzz-tested operation and parameter. The **Trace** field -contains a writeup of the identified fault. This writeup contains information on what the fuzzer -tested and how it detected something wrong. +Faults are displayed on the **Security** pipeline tab with the suite name. When testing against the +repositories default branch, the fuzzing faults are also shown on the Security & Compliance's +Vulnerability Report page. To prevent an excessive number of reported faults, the API fuzzing scanner limits the number of -faults it reports to one per parameter. - -### Fault Writeup - -The faults that API fuzzing finds aren't associated with a specific vulnerability type. They require -investigation to determine what type of issue they are and if they should be fixed. See -[handling false positives](#handling-false-positives) for information about configuration changes -you can make to limit the number of false positives reported. - -This table contains a description of fields in an API fuzzing fault writeup. - -| Writeup Item | Description | -|:-------------|:------------| -| Operation | The operation tested. | -| Parameter | The field modified. This can be a path segment, header, query string, or body element. | -| Endpoint | The endpoint being tested. | -| Check | Check module producing the test. Checks can be turned on and off. | -| Assert | Assert module that detected a failure. Assertions can be configured and turned on and off. | -| CWE | Fuzzing faults always have the same CWE. | -| OWASP | Fuzzing faults always have the same OWASP ID. | -| Exploitability | Fuzzing faults always have an `unknown` exploitability. | -| Impact | Fuzzing faults always have an `unknown` risk impact. | -| Description | Verbose description of what the check did. Includes the original parameter value and the modified (mutated) value. | -| Detection | Why a failure was detected and reported. This is related to the Assert that was used. | -| Original Request | The original, unmodified HTTP request. Useful when reviewing the actual request to see what changes were made. | -| Actual Request | The request that produced the failure. This request has been modified in some way by the Check logic. | -| Actual Response | The response to the actual request. | -| Recorded Request | An unmodified request. | -| Recorded Response | The response to the unmodified request. You can compare this with the actual request when triaging this fault. | +faults it reports. + +## Viewing fuzzing faults + +The API Fuzzing analyzer produces a JSON report that is collected and used +[to populate the faults into GitLab vulnerability screens](../index.md#view-details-of-an-api-fuzzing-vulnerability). +Fuzzing faults show up as vulnerabilities with a severity of Unknown. + +The faults that API fuzzing finds require manual investigation and aren't associated with a specific +vulnerability type. They require investigation to determine if they are a security issue, and if +they should be fixed. See [handling false positives](#handling-false-positives) +for information about configuration changes you can make to limit the number of false positives +reported. + +For additional information, see +[View details of an API Fuzzing vulnerability](../index.md#view-details-of-an-api-fuzzing-vulnerability). + +### Security Dashboard + +Fuzzing faults show up as vulnerabilities with a severity of Unknown. The Security Dashboard is a +good place to get an overview of all the security vulnerabilities in your groups, projects and +pipelines. For more information, see the [Security Dashboard documentation](../security_dashboard/index.md). + +### Interacting with the vulnerabilities + +Fuzzing faults show up as vulnerabilities with a severity of Unknown. +Once a fault is found, you can interact with it. Read more on how to +[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). ## Handling False Positives diff --git a/doc/user/application_security/compliance_dashboard/index.md b/doc/user/application_security/compliance_dashboard/index.md index d9af9d66c36..383d2bf2df7 100644 --- a/doc/user/application_security/compliance_dashboard/index.md +++ b/doc/user/application_security/compliance_dashboard/index.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/compliance_dashboard/index.md' --- This document was moved to [another location](../../compliance/compliance_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index ead34ca227e..fe21fdc1f15 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Static 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/#designated-technical-writers +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 --- # Security Configuration **(ULTIMATE)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index eef15a9c424..9bde2c28972 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Container Scanning **(ULTIMATE)** @@ -14,7 +14,7 @@ vulnerabilities. By including an extra job in your pipeline that scans for those displays them in a merge request, you can use GitLab to audit your Docker-based apps. By default, container scanning in GitLab is based on [Clair](https://github.com/quay/clair) and [Klar](https://github.com/optiopay/klar), which are open-source tools for vulnerability static analysis in -containers. [GitLab's Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) +containers. The GitLab [Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) scans the containers and serves as a wrapper for Clair. To integrate security scanners other than Clair and Klar into GitLab, see @@ -43,6 +43,7 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. +- An image matching [Clair's list of supported distributions](https://quay.github.io/claircore/). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use the following [predefined environment variables](../../../ci/variables/predefined_variables.md): @@ -211,7 +212,7 @@ container_scanning: GIT_STRATEGY: fetch ``` -CAUTION: **Deprecated:** +WARNING: GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic). When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -298,7 +299,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc It can be worthwhile to set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to build a new version of the vulnerabilities database on a preset schedule. Automating -this with a pipeline means you won't have to do it manually each time. You can use the following +this with a pipeline means you do not have to do it manually each time. You can use the following `.gitlab-yml.ci` as a template: ```yaml @@ -318,7 +319,7 @@ build_latest_vulnerabilities: - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db ``` -The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. +The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. ## Running the standalone container scanning tool diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 4c5afcee3d0..0a5a0c3a565 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Fuzz Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 type: reference, howto --- diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index 94cacf2882f..bc0c1e52626 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -2,14 +2,14 @@ type: tutorial stage: Secure group: Vulnerability Research -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # CVE ID Requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. -As part of [GitLab's role as a CVE Numbering Authority](https://about.gitlab.com/security/cve) +As part of [our role as a CVE Numbering Authority](https://about.gitlab.com/security/cve/) ([CNA](https://cve.mitre.org/cve/cna.html)), you may request [CVE](https://cve.mitre.org/index.html) identifiers from GitLab to track vulnerabilities found within your project. @@ -33,7 +33,7 @@ If the following conditions are met, a **Request CVE ID** button appears in your ## Submitting a CVE ID Request Clicking the **Request CVE ID** button in the issue sidebar takes you to the new issue page for -[GitLab's CVE project](https://gitlab.com/gitlab-org/cves). +the [GitLab CVE project](https://gitlab.com/gitlab-org/cves).  diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 2f1ed2faf90..f4401fa6445 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 type: reference, howto --- @@ -15,7 +15,7 @@ deployed, your application is exposed to a new category of possible attacks, such as cross-site scripting or broken authentication flaws. This is where Dynamic Application Security Testing (DAST) comes into place. -NOTE: **Note:** +NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. @@ -91,12 +91,22 @@ There are two ways to define the URL to be scanned by DAST: 1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). 1. Add it in an `environment_url.txt` file at the root of your project. - This is great for testing in dynamic environments. In order to run DAST against - an app dynamically created during a GitLab CI/CD pipeline, have the app - persist its domain in an `environment_url.txt` file, and DAST - automatically parses that file to find its scan target. - You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) - of this in our Auto DevOps CI YAML. + This is useful for testing in dynamic environments. To run DAST against an application + dynamically created during a GitLab CI/CD pipeline, a job that runs prior to the DAST scan must + persist the application's domain in an `environment_url.txt` file. DAST automatically parses the + `environment_url.txt` file to find its scan target. + + For example, in a job that runs prior to DAST, you could include code that looks similar to: + + ```yaml + script: + - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.domain.com > environment_url.txt + artifacts: + paths: [environment_url.txt] + when: always + ``` + + You can see an example of this in our [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) file. If both values are set, the `DAST_WEBSITE` value takes precedence. @@ -161,8 +171,9 @@ headers whose values you want masked. For details on how to mask headers, see It's also possible to authenticate the user before performing the DAST checks. -**Important:** It is highly recommended that you configure the scanner to authenticate to the application, -or it will not be able to check most of the application for security risks, as most +NOTE: +We highly recommended that you configure the scanner to authenticate to the application, +otherwise it cannot check most of the application for security risks, as most of your application is likely not accessible without authentication. It is also recommended that you periodically confirm the scanner's authentication is still working as this tends to break over time due to authentication changes to the application. @@ -183,6 +194,8 @@ variables: DAST_AUTH_URL: https://example.com/sign-in DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + DAST_SUBMIT_FIELD: login # the `id` or `name` of the element that when clicked will submit the login form or the password form of a multi-page login process + DAST_FIRST_SUBMIT_FIELD: next # the `id` or `name` of the element that when clicked will submit the username form of a multi-page login process DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` @@ -191,7 +204,7 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. -DANGER: **Warning:** +WARNING: **NEVER** run an authenticated scan against a production server. When an authenticated scan is run, it may perform *any* function that the authenticated user can. This includes actions like modifying and deleting data, submitting forms, and following links. @@ -486,8 +499,8 @@ variables: When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: -- `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either will use `DAST_WEBSITE` to build the URLs to scan -- Spidering is disabed when `DAST_PATHS` or `DAST_PATHS_FILE` are defined +- `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan +- Spidering is disabled when `DAST_PATHS` or `DAST_PATHS_FILE` are defined - `DAST_PATHS_FILE` and `DAST_PATHS` can not be used together - The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. @@ -498,7 +511,7 @@ To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCA ### Customizing the DAST settings -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -529,7 +542,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | | `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` will be reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | | `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | @@ -551,7 +564,9 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be within `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be in `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | @@ -720,7 +735,7 @@ To delete an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** in the row of the profile to delete. +1. Click **{remove}** (Delete profile) in the row of the profile to delete. ## Scanner profile @@ -762,7 +777,7 @@ To delete a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** in the scanner profile's row. +1. Click **{remove}** (Delete profile) in the scanner profile's row. ## On-demand scans @@ -780,7 +795,7 @@ An on-demand DAST scan: ### Run an on-demand DAST scan -NOTE: **Note:** +NOTE: You must have permission to run an on-demand DAST scan against a protected branch. The default branch is automatically protected. For more information, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). @@ -812,7 +827,7 @@ Click **View details** to view the web console output which includes the list of ### JSON -CAUTION: **Caution:** +WARNING: The JSON report artifacts are not a public API of DAST and their format is expected to change in the future. The DAST tool always emits a JSON report file called `gl-dast-report.json` and @@ -821,8 +836,8 @@ sample reports can be found in the There are two formats of data in the JSON report that are used side by side: -- The proprietary ZAP format that will be eventually deprecated. -- A common format that will be the default in the future. +- The proprietary ZAP format, which is planned to be deprecated. +- A common format that is planned to the default in the future. ### Other formats diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index ddd059707d4..d5f4ce9cc6a 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -2,14 +2,14 @@ type: reference, howto stage: Secure group: Composition 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/#designated-technical-writers +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 --- # Dependency List **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -The Dependency list allows you to see your project's dependencies, and key +The dependency list allows you to see your project's dependencies, and key details about them, including their known vulnerabilities. To see it, navigate to **Security & Compliance > Dependency List** in your project's sidebar. This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. @@ -55,13 +55,14 @@ dependencies, but the UI only shows one of the shortest paths. Dependency Paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) +- [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) ## Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, -the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) will be displayed on this page. +the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. ## Downloading the Dependency List diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 40189235e64..1079a75e32f 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Composition 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/#designated-technical-writers +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 --- # Dependency Scanning Analyzers **(ULTIMATE)** diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 1b164c9cecd..07774f51958 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -2,14 +2,14 @@ type: reference, howto stage: Secure group: Composition 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/#designated-technical-writers +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 --- # Dependency Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -GitLab's Dependency Scanning feature can automatically find security vulnerabilities in your +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. @@ -46,7 +46,7 @@ To run dependency scanning jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure your installed version of Docker is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. @@ -64,7 +64,7 @@ The following languages and dependency managers are supported: | [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | +| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | | [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [sbt](https://www.scala-sbt.org/) 1.2 and below ([Ivy](http://ant.apache.org/ivy/)) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | @@ -123,7 +123,7 @@ configuration, the last mention of the variable takes precedence. ### Overriding dependency scanning jobs -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -141,6 +141,16 @@ gemnasium-dependency_scanning: DS_REMEDIATE: "false" ``` +To override the `dependencies: []` attribute, add an override job as above, targeting this attribute: + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +gemnasium-dependency_scanning: + dependencies: ["build"] +``` + ### Available variables Dependency scanning can be [configured](#customizing-the-dependency-scanning-settings) @@ -173,7 +183,7 @@ The following variables are used for configuring specific analyzers (used for a | `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | -| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1)| +| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1, [removed](https://www.python.org/doc/sunset-python-2/) in GitLab 13.7)| | `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | @@ -356,10 +366,10 @@ Here are the requirements for using dependency scanning in an offline environmen - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -- If you have a limited access environment you will need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. +- If you have a limited access environment you need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` variable to the URL of this repository. For more information on configuration variables, see [Dependency Scanning](#configuring-dependency-scanning). - This advisory database is constantly being updated, so you will need to periodically sync your local copy with GitLab's. + This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab. - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. @@ -510,3 +520,8 @@ uses the [`rules:exists`](../../../ci/yaml/README.md#rulesexists) syntax. This directive is limited to 10000 checks and always returns `true` after reaching this number. Because of this, and depending on the number of files in your repository, a dependency scanning job might be triggered even if the scanner doesn't support your project. + +### Issues building projects with npm or yarn packages relying on Python 2 + +Python 2 was removed (see: [Python 2 sunsetting](https://www.python.org/doc/sunset-python-2/)) from the `retire.js` analyzer in GitLab 13.7 (analyzer version 2.10.1). Projects using packages +with a dependency on this version of Python should use `retire.js` version 2.10.0 or lower (for example, `registry.gitlab.com/gitlab-org/security-products/analyzers/retire.js:2.10.0`). diff --git a/doc/user/application_security/img/security_widget_v13_6.png b/doc/user/application_security/img/security_widget_v13_6.png Binary files differdeleted file mode 100644 index 2dd44909dfe..00000000000 --- a/doc/user/application_security/img/security_widget_v13_6.png +++ /dev/null diff --git a/doc/user/application_security/img/security_widget_v13_7.png b/doc/user/application_security/img/security_widget_v13_7.png Binary files differnew file mode 100644 index 00000000000..fb1eaf9a2be --- /dev/null +++ b/doc/user/application_security/img/security_widget_v13_7.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 30852d1bbcd..417ce70665c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: secure +group: secure +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 type: reference, howto --- @@ -92,7 +92,7 @@ rules: ## Security Scanning with Auto DevOps -When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. +When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools are configured using default settings. - [Auto SAST](../../topics/autodevops/stages.md#auto-sast) - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) @@ -110,7 +110,7 @@ The scanning tools and vulnerabilities database are updated regularly. | Secure scanning tool | Vulnerabilities database updates | |:-------------------------------------------------------------|-------------------------------------------| | [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` Docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (GitLab's own tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | @@ -127,19 +127,21 @@ with this approach, however, and there is a > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Core 13.5. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. +> - Report download dropdown [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. > - It's [deployed behind a feature flag](../feature_flags.md), enabled by default. > - It's enabled on GitLab.com. > - It can be enabled or disabled for a single project. > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-basic-security-widget). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Merge requests which have run security scans let you know that the generated -reports are available to download. +reports are available to download. To download a report, click on the +**Download results** dropdown, and select the desired report. - + ## Interacting with the vulnerabilities @@ -199,6 +201,43 @@ authorization credentials. By default, content of specific headers are masked in reports. You can specify the list of all headers to be masked. For details, see [Hide sensitive information](dast/index.md#hide-sensitive-information). +### View details of an API Fuzzing vulnerability + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +Faults detected by API Fuzzing occur in the live web application, and require manual investigation +to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a +severity of Unknown. To facilitate investigation of the fuzzing faults, detailed information is +provided about the HTTP messages sent and received along with a description of the modification(s) +made. + +Follow these steps to view details of a fuzzing fault: + +1. You can view faults in a project, or a merge request: + + - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + page. This page shows all vulnerabilities from the default branch only. + - In a merge request, go the merge request's **Security** section and click the **Expand** + button. API Fuzzing faults are available in a section labeled + **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault + details. + +1. Click the fault's title to display the fault's details. The table below describes these details. + +| Field | Description | +|:-----------------|:------------------------------------------------------------------ | +| Description | Description of the fault including what was modified. | +| Project | Namespace and project in which the vulnerability was detected. | +| Method | HTTP method used to detect the vulnerability. | +| URL | URL at which the vulnerability was detected. | +| Request | The HTTP request that caused the fault. | +| Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | +| Actual Response | Response received from fuzzed request. | +| Evidence | How we determined a fault occurred. | +| Identifiers | The fuzzing check used to find this fault. | +| Severity | Severity of the finding is always Unknown. | +| Scanner Type | Scanner used to perform testing. | + ### Dismissing a vulnerability To dismiss a vulnerability, you must set its status to Dismissed. This dismisses the vulnerability @@ -225,11 +264,11 @@ vulnerability as you learn more over time. > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can dismiss multiple vulnerabilities at once, providing an optional reason. -Selecting the checkboxes on the side of each vulnerability in the list will select that individual vulnerability. +Selecting the checkboxes on the side of each vulnerability in the list selects that individual vulnerability. Alternatively, you can select all the vulnerabilities in the list by selecting the checkbox in the table header. -Deselecting the checkbox in the header will deselect all the vulnerabilities in the list. +Deselecting the checkbox in the header deselects all the vulnerabilities in the list. Once you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. -Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabilities at once, with the reason you chose. +Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose.  diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/application_security/license_compliance/index.md +++ b/doc/user/application_security/license_compliance/index.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/license_compliance/index.md' --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md index df44041600b..bd67fca529f 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -3,3 +3,6 @@ redirect_to: ../../compliance/license_compliance/index.md --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 35582aa20ed..14ca27cdabe 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Static 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/#designated-technical-writers +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 --- # Offline environments @@ -34,7 +34,7 @@ must come in through physical media (USB drive, hard drive, writeable DVD, etc.) ## Overview -GitLab scanners generally will connect to the internet to download the +GitLab scanners usually connect to the internet to download the latest sets of signatures, rules, and patches. A few extra steps are necessary to configure the tools to function properly by using resources available on your local network. @@ -73,7 +73,7 @@ hosting the latest versions of that dependency or image. ### Scanner signature and rule updates -When connected to the internet, some scanners will reference public databases +When connected to the internet, some scanners reference public databases for the latest sets of signatures and rules to check against. Without connectivity, this is not possible. Depending on the scanner, you must therefore disable these automatic update checks and either use the databases that they came @@ -131,7 +131,7 @@ a bastion, and used only for this specific project. #### Scheduling the updates -By default, this project's pipeline will run only once, when the `.gitlab-ci.yml` is added to the +By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the repo. To update the GitLab security scanners and signatures, it's necessary to run this pipeline regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For example, you can set this up to download and store the Docker images every week. @@ -139,7 +139,7 @@ example, you can set this up to download and store the Docker images every week. Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) for Container Scanning is updated daily. To update this single image, create a new Scheduled Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only -this job will be triggered, and the image will be updated daily and made available in the project +this job is triggered, and the image is updated daily and made available in the project registry. #### Using the secure bundle created diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 4cbd4496dea..15412473ab1 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static 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/#designated-technical-writers +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 --- # SAST Analyzers **(CORE)** diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 49e194a9319..fb3bc256e11 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,15 +1,16 @@ --- stage: Secure group: Static 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/#designated-technical-writers +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 type: reference, howto --- # Static Application Security Testing (SAST) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - All open source (OSS) analyzers were moved to GitLab Core in GitLab 13.3. -NOTE: **Note:** +NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. @@ -50,16 +51,16 @@ To run SAST jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: Our SAST jobs require a Linux container type. Windows containers are not yet supported. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks -GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. +GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we automatically run the appropriate SAST analyzers. You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). @@ -93,6 +94,31 @@ Note that the Java analyzers can also be used for variants like the [Grails](https://grails.org/), and the [Maven wrapper](https://github.com/takari/maven-wrapper). +### Multi-project support + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4895) in GitLab 13.7. + +GitLab SAST can scan repositories that contain multiple projects. All projects must be in the same +language. + +The following analyzers have multi-project support: + +- Bandit +- ESLint +- Gosec +- Kubesec +- NodeJsScan +- MobSF +- PMD +- Security Code Scan +- SpotBugs +- Sobelow + +#### Enable multi-project support for Security Code Scan + +Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of +the repository. For details on the Solution format, see the Microsoft reference [Solution (.sln) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). + ### Making SAST analyzers available to all GitLab tiers All open source (OSS) analyzers have been moved to the GitLab Core tier as of GitLab 13.3. @@ -188,7 +214,7 @@ the pipeline configuration, the last mention of the variable takes precedence. ### Overriding SAST jobs -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -330,13 +356,13 @@ variables: If your project requires custom build configurations, it can be preferable to avoid compilation during your SAST execution and instead pass all job artifacts from an -earlier stage within the pipeline. This is the current strategy when requiring +earlier stage in the pipeline. This is the current strategy when requiring a `before_script` execution to prepare your scan job. To pass your project's dependencies as artifacts, the dependencies must be included in the project's working directory and specified using the `artifacts:path` configuration. If all dependencies are present, the `COMPILE=false` variable can be provided to the -analyzer and compilation will be skipped: +analyzer and compilation is skipped: ```yaml image: maven:3.6-jdk-8-alpine @@ -379,7 +405,10 @@ SAST can be [configured](#customizing-the-sast-settings) using environment varia #### Logging level -To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. + +To control the verbosity of logs, set the `SECURE_LOG_LEVEL` environment variable. Messages of this +logging level or higher are output. From highest to lowest severity, the logging levels are: @@ -392,7 +421,7 @@ From highest to lowest severity, the logging levels are: #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle -of CA certs that you want to trust within the SAST environment. +of CA certs that you want to trust in the SAST environment. #### Docker images @@ -410,8 +439,8 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | Environment variable | Default value | Description | |-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories will also match patterns. | -| `SEARCH_MAX_DEPTH` | 4 | Maximum number of directories traversed when searching for source code files. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. | +| `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | | `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | @@ -424,7 +453,7 @@ Some analyzers can be customized with environment variables. | Environment variable | Analyzer | Description | |---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | | `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | | `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | | `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | @@ -451,15 +480,20 @@ all [custom environment variables](../../../ci/variables/README.md#custom-enviro to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -CAUTION: **Caution:** +WARNING: Variables having names starting with these prefixes are **not** propagated to the SAST Docker container and/or analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. ### Experimental features -Receive early access to experimental features. +You can receive early access to experimental features. Experimental features might be added, +removed, or promoted to regular features at any time. + +Experimental features available are: + +- Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). -Currently, this will enable scanning of iOS and Android apps via the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +#### Enable experimental features To enable experimental features, add the following to your `.gitlab-ci.yml` file: @@ -571,7 +605,7 @@ Once a vulnerability is found, you can interact with it. Read more on how to ## Vulnerabilities database -Vulnerabilities contained within the vulnerability database can be searched +Vulnerabilities contained in the vulnerability database can be searched and viewed at the [GitLab vulnerability advisory database](https://advisories.gitlab.com). ### Vulnerabilities database update diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 5eba0fa44ba..8f57e2c5535 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Static 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/#designated-technical-writers +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 --- # Secret Detection @@ -40,19 +40,26 @@ The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/securit - Cloud services: - Amazon Web Services (AWS) - Google Cloud Platform (GCP) -Encryption keys: + - Heroku API +- Encryption keys: - PKCS8 - RSA - SSH - PGP + - DSA + - EC - Social media platforms: - Facebook API - Twitter API - Cloud SaaS vendors: - GitHub API - Slack Token + - Slack Webhook - Stripe API + - Twilio API - Generic API key strings starting with `api-` +- Password in URL +- U.S. Social Security Number ## Requirements @@ -61,10 +68,10 @@ To run Secret Detection jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: Our Secret Detection jobs expect a Linux container type. Windows containers are not supported. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. @@ -102,7 +109,7 @@ begins with a dollar sign (`$`), as this likely indicates the password is an env For example, `https://username:$password@example.com/path/to/repo` isn't detected, while `https://username:password@example.com/path/to/repo` is. -NOTE: **Note:** +NOTE: You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -115,7 +122,7 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: Secret-Detection.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml ``` The included template creates Secret Detection jobs in your CI/CD pipeline and scans @@ -130,13 +137,13 @@ always take the latest Secret Detection artifact available. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. -Upon detection of a secret, GitLab supports post processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. +Upon detection of a secret, GitLab supports post processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. GitLab currently supports post-processing for following service providers: - Amazon Web Services (AWS) -Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). +Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). ### Customizing settings @@ -153,7 +160,7 @@ override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` va ```yaml include: - - template: Secret-Detection.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml secret_detection: variables: @@ -163,7 +170,7 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -252,6 +259,27 @@ We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showca <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> </figure> +## Running Secret Detection in an offline environment + +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access +to external resources through the internet, some adjustments are required for the Secret Detection job to +run successfully. For more information, see [Offline environments](../offline_deployments/index.md). + +### Requirements for offline Secret Detection + +To use Secret Detection in an offline environment, you need: + +- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- A Docker Container Registry with locally available copy of Secret Detection [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Configure certificate checking of packages (optional). + +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +in an offline environment if you prefer using only locally available Docker images. However, we +recommend keeping the pull policy setting to `always` if not in an offline environment, as this +enables the use of updated scanners in your CI/CD pipelines. + ### Make GitLab Secret Detection analyzer image available inside your Docker registry Import the following default Secret Detection analyzer images from `registry.gitlab.com` into your @@ -278,8 +306,46 @@ Support for custom certificate authorities was introduced in the following versi | -------- | ------- | | secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) | +### Set Secret Detection CI job variables to use local Secret Detection analyzer + +Add the following configuration to your `.gitlab-ci.yml` file. You must replace +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: + +```yaml +include: + - template: Security/Secret-Detection.gitlab-ci.yml + +variables: + SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" +``` + +The Secret Detection job should now use local copies of the Secret Detection analyzer to scan your code and generate +security reports without requiring internet access. + ## Troubleshooting ### Getting warning message `gl-secret-detection-report.json: no matching files` For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +### Error: `Couldn't run the gitleaks command: exit status 2` + +This error is usually caused by the `GIT_DEPTH` value of 50 that is set for all [projects by default](../../../ci/pipelines/settings.md#git-shallow-clone). + +For example, if a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` is set to 50, the Secret Detection job fails as the clone is not deep enough to contain all of the relevant commits. + +You can confirm this to be the cause of the error by implementing a [logging level](../../application_security/secret_detection/index.md#logging-level) of `debug`. Once implemented, the logs should look similar to the following example, wherein an "object not found" error can be seen: + +```plaintext +ERRO[2020-11-18T18:05:52Z] object not found +[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Couldn't run the gitleaks command: exit status 2 +[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 +``` + +If this is the case, we can resolve the issue by setting the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) to a higher value. In order to apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml`: + +```yaml +secret_detection: + variables: + GIT_DEPTH: 100 +``` diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png Binary files differdeleted file mode 100644 index 0310ef3ea0a..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png Binary files differnew file mode 100644 index 00000000000..cd8dbed48fc --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png Binary files differnew file mode 100644 index 00000000000..b9b228c9430 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png Binary files differdeleted file mode 100644 index 9cf95b197fe..00000000000 --- a/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 9f402cea9dc..2750aa81872 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # GitLab Security Dashboard, Security Center, and Vulnerability Reports **(ULTIMATE)** @@ -87,7 +87,7 @@ display all detected and confirmed vulnerabilities. The Vulnerability Report first displays the time at which the last pipeline completed on the project's default branch. There's also a link to view this in more detail. In the case of any pipeline failures, -you will see the number of failures clearly indicated. The failure notification takes you directly to +the number of failures is indicated. The failure notification takes you directly to the **Failed jobs** tab of the pipeline page. The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, @@ -142,7 +142,7 @@ Next to the timeline chart is a list of projects, grouped and sorted by the seve | B | One or more "low" | | A | Zero vulnerabilities | -Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed +Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed vulnerabilities are excluded. Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. @@ -192,7 +192,7 @@ You can export all your vulnerabilities in CSV (comma separated values) format b ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for the projects defined in the Security Dashboard, as filters don't apply to the export function. -NOTE: **Note:** +NOTE: It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Don't close the page until the download finishes. @@ -225,12 +225,12 @@ are discovered. To ensure the information on the Security Dashboard is regularly updated, [configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a -daily security scan. This will update the information displayed on the Security +daily security scan. This updates the information displayed on the Security Dashboard regardless of how often the default branch is updated. That way, reports are created even if no code change happens. -CAUTION: **Warning:** +WARNING: Running Dependency Scanning from a scheduled pipeline might result in false negatives if your project doesn't have a lock file and isn't configured for Continuous Delivery. A lock file is a file that lists all transient dependencies and keeps track of their exact versions. The false negative @@ -249,7 +249,7 @@ to configure daily security scans. Each vulnerability report contains vulnerabilities from the latest scans that were merged into the default branch. - + You can filter which vulnerabilities the vulnerability report displays by: @@ -264,7 +264,7 @@ Clicking any vulnerability in the table takes you to its [Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. To create an issue associated with the vulnerability, click the **Create Issue** button. - + Once you create the issue, the linked issue icon in the vulnerability list: diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index f975de213ef..e046b18b2a4 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -1,20 +1,20 @@ --- stage: Secure group: Static 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/#designated-technical-writers +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 type: reference --- -# Secure and Defend terminology +# Secure and Protect terminology -This terminology list for GitLab Secure and Defend aims to: +This terminology list for GitLab Secure and Protect aims to: - Promote a ubiquitous language for discussing application security. -- Improve the effectiveness of communication regarding GitLab's application security features. +- Improve the effectiveness of communication regarding GitLab application security features. - Get new contributors up to speed faster. -This document defines application security terms in the specific context of GitLab's Secure and -Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend. +This document defines application security terms in the specific context of GitLab Secure and +Protect features. Terms may therefore have different meanings outside that context. ## Terms @@ -24,7 +24,7 @@ Software that performs a scan. The scan analyzes an attack surface for vulnerabi a report containing findings. Reports adhere to the [Secure report format](#secure-report-format). Analyzers integrate into GitLab using a CI job. The report produced by the analyzer is published as -an artifact once the job is complete. GitLab ingests this report, allowing users to visualize and +an artifact after the job is complete. GitLab ingests this report, allowing users to visualize and manage found vulnerabilities. For more information, see [Security Scanner Integration](../../../development/integrations/secure.md). Many GitLab analyzers follow a standard approach using Docker to run a wrapped scanner. For example, @@ -74,7 +74,7 @@ or creating a merge request. ### Finding -An asset that has the potential to be vulnerable, identified within a project by an analyzer. Assets +An asset that has the potential to be vulnerable, identified in a project by an analyzer. Assets include but are not restricted to source code, binary packages, containers, dependencies, networks, applications, and infrastructure. @@ -98,9 +98,9 @@ A finding's primary identifier is a value unique to that finding. The external t of the finding's [first identifier](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/v2.4.0-rc1/dist/sast-report-format.json#L228) combine to create the value. -Examples of primary identifiers include ZAP's `PluginID`, or `CVE` for Klar. Note that the -identifier must be stable. Subsequent scans must return the same value for the same finding, even if -the location has slightly changed. +Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for +Klar. Note that the identifier must be stable. Subsequent scans must return the same value for the +same finding, even if the location has slightly changed. ### Report finding diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index f85d4f0140c..f7bd201aba9 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Threat Monitoring **(ULTIMATE)** @@ -101,7 +101,7 @@ reflected upon refresh. Enforcement status changes are deployed directly to a deployment namespace of the selected environment. By default, the network policy list contains predefined policies in a -disabled state. Once enabled,a predefined policy deploys to the +disabled state. Once enabled, a predefined policy deploys to the selected environment's deployment platform and you can manage it like the regular policies. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 95bb1ff1a67..705964dba66 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Vulnerability Pages @@ -37,7 +37,7 @@ the following values: |-----------|------------------------------------------------------------------------------------------------------------------| | Detected | The default state for a newly discovered vulnerability | | Confirmed | A user has seen this vulnerability and confirmed it to be accurate | -| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise will not be resolved | +| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved | | Resolved | The vulnerability has been fixed and is no longer valid | A timeline shows you when the vulnerability status has changed @@ -47,9 +47,9 @@ and allows you to comment on a change. You can create an issue for a vulnerability by selecting the **Create issue** button. -This creates a [confidential issue](../../project/issues/confidential_issues.md) in the -project the vulnerability came from and pre-populates it with useful information from -the vulnerability report. After the issue is created, GitLab redirects you to the +This allows the user to create a [confidential issue](../../project/issues/confidential_issues.md) +in the project the vulnerability came from. Fields are pre-populated with pertinent information +from the vulnerability report. After the issue is created, GitLab redirects you to the issue page so you can edit, assign, or comment on the issue. ## Link issues to the vulnerability |
