diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 08:27:35 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 08:27:35 +0000 |
| commit | 7e9c479f7de77702622631cff2628a9c8dcbc627 (patch) | |
| tree | c8f718a08e110ad7e1894510980d2155a6549197 /doc/user/application_security | |
| parent | e852b0ae16db4052c1c567d9efa4facc81146e88 (diff) | |
| download | gitlab-ce-7e9c479f7de77702622631cff2628a9c8dcbc627.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-6-stable-eev13.6.0-rc42
Diffstat (limited to 'doc/user/application_security')
29 files changed, 651 insertions, 190 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 145422f8736..57c5f8bc1fa 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -8,9 +8,10 @@ type: reference, howto # Web API Fuzz Testing **(ULTIMATE)** You can add web API fuzzing to your [GitLab CI/CD](../../../ci/README.md) -pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. -API fuzzing performs fuzz testing of API operation parameters. -Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API backend. +pipelines. This helps you discover bugs and potential security issues that other QA processes may +miss. API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation +parameters to unexpected values in an effort to cause unexpected behavior and errors in the API +backend. 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/README.md), @@ -23,7 +24,10 @@ you can run fuzz tests as part your CI/CD workflow. - SOAP - GraphQL - Form bodies, JSON, or XML -- An OpenAPI definition, or HTTP Archive (HAR) of requests to test +- One of the following assets to provide APIs to test: + - OpenAPI v2 API definition + - HTTP Archive (HAR) of API requests to test + - Postman Collection v2.0 or v2.1 ## When fuzzing scans run @@ -48,15 +52,17 @@ changes, other pipelines, or other scanners) during a scan could cause inaccurat ## Configuration -There are two ways to perform scans. See the configuration section for the one you wish to use: +There are three ways to perform scans. See the configuration section for the one you wish to use: - [OpenAPI v2 specification](#openapi-specification) - [HTTP Archive (HAR)](#http-archive-har) +- [Postman Collection v2.0 or v2.1](#postman-collection) Examples of both configurations can be found here: - [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) +- [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) ### OpenAPI Specification @@ -133,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: **Danger:** +DANGER: **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. @@ -224,7 +230,98 @@ 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: **Danger:** +DANGER: **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. + +### Postman Collection + +The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that +developers and testers use to call various types of APIs. The API definitions +[can be exported as a Postman Collection file](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-postman-data) +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 +test with valid data. The API fuzzer extracts all the API definitions and uses them to perform +testing. + +DANGER: **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. + +Follow these steps to configure API fuzzing to use a Postman Collection file that provides +information about the target API to test: + +1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + ``` + +1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) + to your repository's root as `.gitlab-api-fuzzing.yml`. + +1. The [configuration file](#configuration-files) has several testing profiles defined with varying + amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this + profile completes quickly, allowing for easier configuration validation. + + Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + substituting `Quick-10` for the profile you choose: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + ``` + +1. Add the `FUZZAPI_POSTMAN_COLLECTION` variable and set it to the Postman Collection's location: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + ``` + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing + automatically parses that file to find its scan target. 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). + + Here's an example of using `FUZZAPI_TARGET_URL`: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + FUZZAPI_TARGET_URL: http://test-deployment/ + ``` + +This is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +DANGER: **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. @@ -398,6 +495,7 @@ increases as the numbers go up. To use a configuration file, add it to your repo | `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. | @@ -540,6 +638,86 @@ variables: FUZZAPI_OVERRIDES_INTERVAL: 300 ``` +### Header Fuzzing + +Header fuzzing is disabled by default due to the high number of false positives that occur with many +technology stacks. When header fuzzing is enabled, you must specify a list of headers to include in +fuzzing. + +Each profile in the default configuration file has an entry for `GeneralFuzzingCheck`. This check +performs header fuzzing. Under the `Configuration` section, you must change the `HeaderFuzzing` and +`Headers` settings to enable header fuzzing. + +This snippet shows the `Quick-10` profile's default configuration with header fuzzing disabled: + +```yaml +- Name: Quick-10 + DefaultProfile: Empty + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: false + Headers: + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +`HeaderFuzzing` is a boolean that turns header fuzzing on and off. The default setting is `false` +for off. To turn header fuzzing on, change this setting to `true`: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: +``` + +`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. For example, to fuzz a +custom header `X-Custom` used by your APIs, add an entry for it using the syntax +`- Name: HeaderName`, substituting `HeaderName` with the header to fuzz: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom +``` + +You now have a configuration to fuzz the header `X-Custom`. Use the same notation to list additional +headers: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom + - Name: X-AnotherHeader +``` + +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 diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 9e7f98dd4fc..eef15a9c424 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Defend +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 --- @@ -76,6 +76,7 @@ How you enable container scanning depends on your GitLab version: that comes with your GitLab installation. - GitLab versions earlier than 11.9: Copy and use the job from the [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). +- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the `CS_MAJOR_VERSION` from `2` to `3`. To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the following to your `.gitlab-ci.yml` file: @@ -144,6 +145,26 @@ variables: CLAIR_OUTPUT: High ``` +Version `3` of the `container_scanning` Docker image uses [`centos:centos8`](https://hub.docker.com/_/centos) +as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) +script and instead executes the analyzer by default. Any customizations made to the +`container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script) +and [`after_script`](../../../ci/yaml/README.md#after_script) +blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based +Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables) +variable. + +This example [includes](../../../ci/yaml/README.md#include) the container scanning template and +enables version `2` of the analyzer: + +```yaml +include: + - template: Container-Scanning.gitlab-ci.yml + +variables: + CS_MAJOR_VERSION: '2' +``` + <!-- NOTE: The container scanning tool references the following heading in the code, so if you" make a change to this heading, make sure to update the documentation URLs used in the" container scanning tool (https://gitlab.com/gitlab-org/security-products/analyzers/klar)" --> @@ -164,6 +185,8 @@ scanning by using the following environment variables: | `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. | | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | +| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | +| `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | | `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | | `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | @@ -415,11 +438,11 @@ automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by the [`DOCKERFILE_PATH`](#available-variables) environment variable. To ensure that the scanning tool has access to this -file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/yaml/README.md#git-strategy) in +file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation). +Read more about the [solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png b/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png Binary files differnew file mode 100644 index 00000000000..bed3ca4c9df --- /dev/null +++ b/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 9508407ccae..4c5afcee3d0 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -30,6 +30,7 @@ Docker image with the fuzz engine to run your app. | Swift | [libfuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | | Java | [JQF](https://github.com/rohanpadhye/JQF) | [java-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | +| Java | [javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | ## Configuration @@ -221,6 +222,34 @@ This essentially creates two steps: The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). +## Interacting with the vulnerabilities + +After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +The merge request widget lists the vulnerability and contains a button for downloading the fuzzing +artifacts. By clicking one of the detected vulnerabilities, you can see its details. + + + +You can also view the vulnerability from the [Security Dashboard](../security_dashboard/index.md), +which shows an overview of all the security vulnerabilities in your groups, projects, and pipelines. + +Clicking the vulnerability opens a modal that provides additional information about the +vulnerability: + +- Status: The vulnerability's status. As with any type of vulnerability, a coverage fuzzing + vulnerability can be Detected, Confirmed, Dismissed, or Resolved. +- Project: The project in which the vulnerability exists. +- Crash type: The type of crash or weakness in the code. This typically maps to a [CWE](https://cwe.mitre.org/). +- Crash state: A normalized version of the stacktrace, containing the last three functions of the + crash (without random addresses). +- Stacktrace snippet: The last few lines of the stacktrace, which shows details about the crash. +- Identifier: The vulnerability's identifier. This maps to either a [CVE](https://cve.mitre.org/) + or [CWE](https://cwe.mitre.org/). +- Severity: The vulnerability's severity. This can be Critical, High, Medium, Low, Info, or Unknown. +- Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). +- Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the + engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). + ### Glossary - Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds diff --git a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png Binary files differdeleted file mode 100644 index 045221d713c..00000000000 --- a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/dast/img/dast_single_v13_0.png b/doc/user/application_security/dast/img/dast_single_v13_0.png Binary files differindex 91ed4d916ab..1d528fa0ace 100644 --- a/doc/user/application_security/dast/img/dast_single_v13_0.png +++ b/doc/user/application_security/dast/img/dast_single_v13_0.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index fffaf4ad26b..2f1ed2faf90 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -161,6 +161,12 @@ 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 +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. + Create masked variables to pass the credentials that DAST uses. To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). Note that the key of the username variable must be `DAST_USERNAME` @@ -185,7 +191,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: **Danger:** +DANGER: **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. @@ -423,7 +429,51 @@ A URL scan allows you to specify which parts of a website are scanned by DAST. #### Define the URLs to scan -To specify the paths to scan, add a comma-separated list of the paths to the `DAST_PATHS` +URLs to scan can be specified by either of the following methods: + +- Use `DAST_PATHS_FILE` environment variable to specify the name of a file containing the paths. +- Use `DAST_PATHS` environment variable to list the paths. + +##### Use DAST_PATHS_FILE environment variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. + +To define the URLs to scan in a file, create a plain text file with one path per line. + +```txt +page1.html +/page2.html +category/shoes/page1.html +``` + +To scan the URLs in that file, set the environment variable `DAST_PATHS_FILE` to the path of that file. + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_PATHS_FILE: url_file.txt +``` + +By default, DAST scans do not clone the project repository. If the file is checked in to the project, instruct the DAST job to clone the project by setting GIT_STRATEGY to fetch. The file is expected to be in the `/zap/wrk` directory. + +```yaml +dast: + script: + - mkdir -p /zap/wrk + - cp url_file.txt /zap/wrk/url_file.txt + - /analyze -t $DAST_WEBSITE + variables: + GIT_STRATEGY: fetch + DAST_PATHS_FILE: url_file.txt +``` + +##### Use DAST_PATHS environment variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. + +To specify the paths to scan in an environment variable, add a comma-separated list of the paths to the `DAST_PATHS` environment variable. Note that you can only scan paths of a single host. ```yaml @@ -434,10 +484,13 @@ variables: DAST_PATHS=/page1.html,/category1/page1.html,/page3.html ``` -When using `DAST_PATHS`, note the following: +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_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, you should create multiple DAST jobs and split the paths over each job. + greater than this, use `DAST_PATHS_FILE`. #### Full Scan @@ -476,6 +529,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_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. | @@ -489,15 +543,16 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false` | -| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. | -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false` | -| `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` | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html` | -| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | +| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1.| +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `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_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` | ### DAST command-line options @@ -548,7 +603,7 @@ variables: ### Cloning the project's repository The DAST job does not require the project's repository to be present when running, so by default -[`GIT_STRATEGY`](../../../ci/yaml/README.md#git-strategy) is set to `none`. +[`GIT_STRATEGY`](../../../ci/runners/README.md#git-strategy) is set to `none`. ### Debugging DAST jobs @@ -713,10 +768,6 @@ To delete a scanner profile: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-project. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must start it manually. @@ -747,35 +798,6 @@ To run an on-demand DAST scan, you need: The on-demand DAST scan runs and the project's dashboard shows the results. -### Enable or disable On-demand Scans - -The On-demand DAST Scans feature is enabled by default. You can disable on-demand scans -instance-wide, or disable it for specific projects if you prefer. - -To run on-demand DAST scans, an administrator must enable the -`security_on_demand_scans_feature_flag` feature flag. - -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable or enable the feature flags. - -To disable On-demand DAST Scans: - -```ruby -# Instance-wide -Feature.disable(:security_on_demand_scans_feature_flag) -# or by project -Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) -``` - -To enable On-demand DAST Scans: - -```ruby -# Instance-wide -Feature.enable(:security_on_demand_scans_feature_flag) -# or by project -Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project ID>)) -``` - ## Reports The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png Binary files differdeleted file mode 100644 index 8eeadb34504..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png Binary files differdeleted file mode 100644 index 4687987b763..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png b/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png Binary files differnew file mode 100644 index 00000000000..78e324f43c4 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 1f730e5f205..ddd059707d4 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -32,7 +32,7 @@ Dependencies are displayed 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 | +| 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. | | License | Links to dependency's software licenses | Dependencies shown are initially sorted by the severity of their known vulnerabilities, if any. They @@ -44,6 +44,18 @@ If a dependency has known vulnerabilities, you can view them by clicking the arr dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description then appears below it. +### Dependency Paths + +The dependency list shows the path between a dependency and a top-level dependency it's connected +to, if any. There are many possible paths connecting a transient dependency to top-level +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/) + ## Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index b90bb37c60f..1b164c9cecd 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -53,7 +53,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae ## Supported languages and package managers GitLab relies on [`rules`](../../../ci/yaml/README.md#rules) to start relevant analyzers depending on the languages detected in the repository. -The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. +The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. The following languages and dependency managers are supported: @@ -71,11 +71,11 @@ The following languages and dependency managers are supported: Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. -| Package Managers | Languages | Supported files | Scan tools | -| ------------------- | --------- | --------------- | ------------ | +| Package Managers | Languages | Supported files | Scan tools | Issue | +| ------------------- | --------- | --------------- | ---------- | ----- | | [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#11756](https://gitlab.com/gitlab-org/gitlab/-/issues/11756) | | [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | -| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#249526](https://gitlab.com/gitlab-org/gitlab/-/issues/249526) | +| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#271345](https://gitlab.com/gitlab-org/gitlab/-/issues/271345) | ## Contribute your scanner @@ -201,7 +201,7 @@ Once a vulnerability is found, you can interact with it. Read more on how to Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation). +[solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). ## Security Dashboard @@ -356,9 +356,11 @@ 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. -- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/). - This is required because, in an offline environment, the Gemnasium analyzer can't fetch the latest - advisories from the online repository. +- 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 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. + - _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. diff --git a/doc/user/application_security/img/security_configuration_page_v13_2.png b/doc/user/application_security/img/security_configuration_page_v13_2.png Binary files differdeleted file mode 100644 index 016328948cc..00000000000 --- a/doc/user/application_security/img/security_configuration_page_v13_2.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..2dd44909dfe --- /dev/null +++ b/doc/user/application_security/img/security_widget_v13_6.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differnew file mode 100644 index 00000000000..05ca74c3d5c --- /dev/null +++ b/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png Binary files differnew file mode 100644 index 00000000000..a3034a7db04 --- /dev/null +++ b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differdeleted file mode 100644 index 63e9c1473b6..00000000000 --- a/doc/user/application_security/img/vulnerability_solution.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 413a9f894e2..30852d1bbcd 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,4 +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 type: reference, howto --- @@ -18,7 +21,7 @@ For an overview of application security with GitLab, see ## Quick start Get started quickly with Dependency Scanning, License Scanning, Static Application Security -Testing (SAST), and Secret Detection by adding the following to your `.gitlab-ci.yml`: +Testing (SAST), and Secret Detection by adding the following to your [`.gitlab-ci.yml`](../../ci/yaml/README.md): ```yaml include: @@ -67,12 +70,26 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | -| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | +| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | +| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | | [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | +### Use security scanning tools with Pipelines for Merge Requests + +The security scanning tools can all be added to pipelines with [templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Security). +See each tool for details on how to use include each template in your CI/CD configuration. + +By default, the application security jobs are configured to run for branch pipelines only. +To use them with [pipelines for merge requests](../../ci/merge_request_pipelines/index.md), +you may need to override the default `rules:` configuration to add: + +```yaml +rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" +``` + ## Security Scanning with Auto DevOps When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. @@ -93,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` (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). | | [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. | @@ -106,6 +123,24 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). +## Viewing security scan information in merge requests **(CORE)** + +> - [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. +> - 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:** +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. + + + ## Interacting with the vulnerabilities > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. @@ -119,7 +154,7 @@ information with several options: - [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../project/issues/confidential_issues.md). -- [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities, +- [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, a solution is provided for how to fix the vulnerability.  @@ -141,21 +176,21 @@ To view details of DAST vulnerabilities: 1. Click on the vulnerability's description. The following details are provided: - | Field | Description | -|:-----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Description | Description of the vulnerability. | -| 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 Headers | Headers of the request. | -| Response Status | Response status received from the application. | -| Response Headers | Headers of the response received from the application. | +| Field | Description | +|:-----------------|:------------------------------------------------------------------ | +| Description | Description of the vulnerability. | +| 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 Headers | Headers of the request. | +| Response Status | Response status received from the application. | +| Response Headers | Headers of the response received from the application. | | Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | -| Identifiers | Identifiers of the vulnerability. | -| Severity | Severity of the vulnerability. | -| Scanner Type | Type of vulnerability report. | -| Links | Links to further details of the detected vulnerability. | -| Solution | Details of a recommended solution to the vulnerability (optional). | +| Identifiers | Identifiers of the vulnerability. | +| Severity | Severity of the vulnerability. | +| Scanner Type | Type of vulnerability report. | +| Links | Links to further details of the detected vulnerability. | +| Solution | Details of a recommended solution to the vulnerability (optional). | #### Hide sensitive information in headers @@ -198,38 +233,60 @@ Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabili  -### Solutions for vulnerabilities (auto-remediation) +### Creating an issue for a vulnerability + +You can create an issue for a vulnerability by visiting the vulnerability's page and clicking +**Create issue**, which you can find in the **Related issues** section. + + + +This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the +vulnerability came from, and pre-populates it with some useful information taken from the vulnerability +report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on +it. + +Upon returning to the group security dashboard, the vulnerability now has an associated issue next +to the name. + + + +### Automatic remediation for vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. Some vulnerabilities can be fixed by applying the solution that GitLab -automatically generates. The following scanners are supported: +automatically generates. Although the feature name is Automatic Remediation, this feature is also commonly called Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: - [Dependency Scanning](dependency_scanning/index.md): Automatic Patch creation is only available for Node.js projects managed with `yarn`. - [Container Scanning](container_scanning/index.md) +When an automatic solution is available, the button in the header shows **Resolve with merge request**: + + + +Selecting the button creates a merge request with the solution. + #### Manually applying the suggested patch -Some vulnerabilities can be fixed by applying a patch that is automatically -generated by GitLab. To apply the fix: +To manually apply the patch that GitLab generated for a vulnerability: + +1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: + +  -1. Click the vulnerability. -1. Download and review the patch file `remediation.patch`. 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. - - #### Creating a merge request from a vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. In certain cases, GitLab allows you to create a merge request that automatically remediates the vulnerability. Any vulnerability that has a -[solution](#solutions-for-vulnerabilities-auto-remediation) can have a merge +[solution](#automatic-remediation-for-vulnerabilities) can have a merge request created to automatically solve the issue. If this action is available, the vulnerability page or modal contains a **Create merge request** button. @@ -237,25 +294,6 @@ Click this button to create a merge request to apply the solution onto the sourc  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by visiting the vulnerability's page and clicking -**Create issue**, which you can find in the **Related issues** section. - - - -This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and pre-populates it with some useful information taken from the vulnerability -report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on -it. CVE identifiers can be requested from GitLab by clicking the -[_CVE ID Request_ button](cve_id_request.md) that is enabled for maintainers of -public projects on GitLab.com - -Upon returning to the group security dashboard, the vulnerability now has an associated issue next -to the name. - - - ### Managing related issues for a vulnerability Issues can be linked to a vulnerability using the related issues block on the vulnerability page. @@ -320,7 +358,7 @@ appears:  -If at least one security scanner is enabled, you will be able to enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you will be able to enable the `License-Check` rule. +If at least one security scanner is enabled, you can enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you can enable the `License-Check` rule.  @@ -566,3 +604,36 @@ Additionally, we provide a dedicated project containing the versioned legacy tem This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). Instructions are available in the [legacy template project](https://gitlab.com/gitlab-org/auto-devops-v12-10). + +#### Vulnerabilities are found, but the job succeeds. How can I have a pipeline fail instead? + +This is the current default behavior, because the job's status indicates success or failure of the analyzer itself. +Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), +[Merge Request widget](sast/index.md) +or [Security Dashboard](security_dashboard/index.md). +There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. + +### Enable or disable the basic security widget **(CORE ONLY)** + +The basic security widget is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:core_security_mr_widget) +# For a single project +Feature.enable(:core_security_mr_widget, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:core_security_mr_widget) +# For a single project +Feature.disable(:core_security_mr_widget, Project.find(<project id>)) +``` diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 3a7c0148388..35582aa20ed 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -66,8 +66,7 @@ external links exposed in the UI. These links might not be accessible within an ### Automatic remediation for vulnerabilities -The [automatic remediation for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation) feature -(auto-remediation) is available for offline Dependency Scanning and Container Scanning, but may not work +The [automatic remediation for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. @@ -214,3 +213,28 @@ do ssh $GITLAB_HOST "sudo docker push ${registry}/analyzers/${i}:2" done ``` + +### Using GitLab Secure with AutoDevOps in an offline environment + +You can use GitLab AutoDevOps for Secure scans in an offline environment. However, you must first do +these steps: + +1. Load the container images into the local registry. GitLab Secure leverages analyzer container + images to do the various scans. These images must be available as part of running AutoDevOps. + Before running AutoDevOps, follow the [above steps](#using-the-official-gitlab-template) + to load those container images into the local container registry. + +1. Set the pipeline variable to ensure that AutoDevOps looks in the right place for those images. + The AutoDevOps templates leverage the `SECURE_ANALYZERS_PREFIX` variable to identify the location + of analyzer images. This variable is discussed above in [Using the secure bundle created](#using-the-secure-bundle-created). + Ensure that you set this variable to the correct value for where you loaded the analyzer images. + You could consider doing this with a pipeline variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) + the `.gitlab-ci.yml` file directly. + +Once these steps are complete, GitLab has local copies of the Secure analyzers and is set up to use +them instead of an Internet-hosted container image. This allows you to run Secure in AutoDevOps in +an offline environment. + +Note that these steps are specific to GitLab Secure with AutoDevOps. Using other stages with +AutoDevOps may require other steps covered in the +[Auto DevOps documentation](../../../topics/autodevops/). diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 6167c0445f9..4cbd4496dea 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -4,7 +4,10 @@ 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 --- -# SAST Analyzers **(ULTIMATE)** +# SAST Analyzers **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Core in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a @@ -33,7 +36,7 @@ SAST supports the following official analyzers: - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) -The analyzers are published as Docker images that SAST will use to launch +The analyzers are published as Docker images that SAST uses to launch dedicated containers for each analysis. SAST is pre-configured with a set of **default images** that are maintained by @@ -77,12 +80,12 @@ variables: SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" ``` -`bandit` runs first. When merging the reports, SAST will -remove the duplicates and will keep the `bandit` entries. +`bandit` runs first. When merging the reports, SAST +removes the duplicates and keeps the `bandit` entries. ### Disabling default analyzers -Setting `SAST_DEFAULT_ANALYZERS` to an empty string will disable all the official +Setting `SAST_DEFAULT_ANALYZERS` to an empty string disables all the official default analyzers. In `.gitlab-ci.yml` define: ```yaml @@ -121,7 +124,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | | --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | -| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | +| Severity | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | | Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | | File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -129,11 +132,11 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | | End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| External ID (e.g. CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| External ID (for example, CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Affected item (for example, class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | @@ -143,4 +146,4 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) - 𐄂 => 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`, and so on). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 9e4d4112ae8..49e194a9319 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -32,8 +32,8 @@ The results are sorted by the priority of the vulnerability: 1. Everything else A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish -for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST -job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, +for any reason, the security dashboard does not show SAST scanner output. For example, if the SAST +job finishes but the DAST job fails, the security dashboard does not show SAST results. On failure, the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). ## Use cases @@ -71,9 +71,9 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | -| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | | Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | -| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | | Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | | Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | @@ -84,7 +84,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | -| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | @@ -107,10 +107,11 @@ as shown in the following table: | [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | | [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -162,7 +163,7 @@ page: 1. Enter the custom SAST values. Custom values are stored in the `.gitlab-ci.yml` file. For variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. -1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](./analyzers.md) and enter custom analyzer values. +1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Click **Create Merge Request**. 1. Review and merge the merge request. @@ -205,15 +206,21 @@ spotbugs-sast: FAIL_NEVER: 1 ``` -### Custom rulesets +### Customize rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. -You can customize the default scanning rules provided with SAST's NodeJS-Scan and Gosec analyzers. -Customization allows you to exclude rules and modify the behavior of existing rules. +You can customize the default scanning rules provided by our SAST analyzers. + +Ruleset customization supports two capabilities: + +1. Disabling predefined rules +1. Modifying the default behavior of a given analyzer + +These capabilities can be used simultaneously. To customize the default scanning rules, create a file containing custom rules. These rules -are passed through to the analyzer's underlying scanner tool. +are passed through to the analyzer's underlying scanner tools. To create a custom ruleset: @@ -221,6 +228,25 @@ To create a custom ruleset: 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 disabled rules + belong to `eslint` and `sobelow` and have the corresponding identifiers `type` and `value`: + + ```toml + [eslint] + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "eslint_rule_id" + value = "security/detect-object-injection" + + [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: @@ -285,7 +311,7 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -#### Enabling Kubesec analyzer +### Enabling Kubesec analyzer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab Ultimate 12.6. @@ -300,7 +326,7 @@ variables: SCAN_KUBERNETES_MANIFESTS: "true" ``` -#### Pre-compilation +### Pre-compilation 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 @@ -398,7 +424,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` will use 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` will scan. 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. | @@ -426,7 +452,7 @@ to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. CAUTION: **Caution:** -Variables having names starting with these prefixes will **not** be propagated to the SAST Docker container and/or +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 @@ -642,7 +668,7 @@ security reports without requiring internet access. ### Configure certificate checking of packages If a SAST job invokes a package manager, you must configure its certificate verification. In an -offline environment, certificate verification with an external source isn't possible. Either use a +offline environment, certificate verification with an external source is not possible. Either use a self-signed certificate or disable certificate verification. Refer to the package manager's documentation for instructions. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index bb10e9d7315..025a37f684d 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -5,9 +5,10 @@ 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 --- -# Secret Detection **(ULTIMATE)** +# Secret Detection -> [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in 13.3. A recurring problem when developing applications is that developers may unintentionally commit secrets and credentials to their remote repositories. If other people have access to the source, @@ -30,6 +31,29 @@ GitLab displays identified secrets visibly in a few places: - Detecting unintentional commit of secrets like keys, passwords, and API tokens. - Performing a single or recurring scan of the full history of your repository for secrets. +## 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 Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks/gitleaks.toml) includes the following key types: + +- Cloud services: + - Amazon Web Services (AWS) + - Google Cloud Platform (GCP) +Encryption keys: + - PKCS8 + - RSA + - SSH + - PGP +- Social media platforms: + - Facebook API + - Twitter API +- Cloud SaaS vendors: + - GitHub API + - Slack Token + - Stripe API + - Generic API key strings starting with `api-` + ## Requirements To run Secret Detection jobs, by default, you need GitLab Runner with the @@ -59,7 +83,7 @@ as shown in the following table: | [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -102,6 +126,18 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. +### Post-processing + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/46390) 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. + +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). + ### Customizing settings The Secret Detection scan settings can be changed through [environment variables](#available-variables) @@ -142,7 +178,7 @@ Secret Detection can be customized by defining available variables: | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | 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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | -### Custom rulesets +### Custom rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png Binary files differdeleted file mode 100644 index 8fab4e39175..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png Binary files differnew file mode 100644 index 00000000000..6ccae80e80e --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png Binary files differdeleted file mode 100644 index 07b41b471d4..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 5fa8ebb80e0..1b038ef76a0 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -9,15 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: -- Security dashboards: An overview of the security status in your instance, groups, and projects. -- Vulnerability reports: Detailed lists of all vulnerabilities for the instance, group, project, or +- Security dashboards: An overview of the security status in your instance, [groups](#group-security-dashboard), and + [projects](#project-security-dashboard). +- [Vulnerability reports](#vulnerability-report): Detailed lists of all vulnerabilities for the instance, group, project, or pipeline. This is where you triage and manage vulnerabilities. -- Security Center: A dedicated area for vulnerability management at the instance level. This +- [Security Center](#instance-security-center): A dedicated area for vulnerability management at the instance level. This includes a security dashboard, vulnerability report, and settings. -You can also drill down into a vulnerability and get extra information. This includes the project it -comes from, any related file(s), and metadata that helps you analyze the risk it poses. You can also -dismiss a vulnerability or create an issue for it. +You can also drill down into a vulnerability and get extra information on the +[Vulnerability Page](../vulnerabilities/index.md). This view includes the project it +comes from, any related file(s), and metadata that helps you analyze the risk it poses. +You can also confirm, dismiss, or resolve a vulnerability, create an issue for it, +and in some cases, generate a merge request to fix the vulnerability. To benefit from these features, you must first configure one of the [security scanners](../index.md). @@ -30,7 +33,7 @@ The vulnerability report displays vulnerabilities detected by scanners such as: - [Dynamic Application Security Testing](../dast/index.md) - [Dependency Scanning](../dependency_scanning/index.md) - [Static Application Security Testing](../sast/index.md) -- And others! +- And [others](../index.md#security-scanning-tools)! ## Requirements @@ -60,43 +63,67 @@ job finishes but the DAST job fails, the security dashboard doesn't show SAST re the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). +You can filter the vulnerabilities list by selecting from the **Severity** and **Scanner** dropdowns. + ## Project Security Dashboard +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. + +At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. +Access it by navigating to **Security & Compliance > Security Dashboard**. Currently, we display historical +data up to 365 days. + + + +Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows +only the graph for vulnerabilities with **high** severity. + +### Vulnerability Report + > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. -At the project level, the Security Dashboard displays the vulnerabilities merged into your project's -[default branch](../../project/repository/branches/index.md#default-branch). Access it by navigating -to **Security & Compliance > Security Dashboard**. By default, the Security Dashboard displays all -detected and confirmed vulnerabilities. +The vulnerabilities that exist in your project's +[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to +**Security & Compliance > Vulnerability Report**. By default, the Vulnerability Report is filtered to +display all detected and confirmed vulnerabilities. -The Security Dashboard 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. +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 **Failed jobs** tab of the pipeline page. -The Security Dashboard next displays the total number of vulnerabilities by severity (for example, +The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) page to view more information about that vulnerability. - + You can filter the vulnerabilities by one or more of the following: -- Status -- Severity -- Scanner +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | + +You can filter the vulnerabilities list by selecting from the **Status**, **Severity**, and +**Scanner** dropdowns. In the **Scanner** dropdown, select individual scanners or scanner groups to +toggle those scanners. The **Scanner** dropdown includes both GitLab scanners, and in GitLab 13.6 +and later, custom scanners. You can also dismiss vulnerabilities in the table: 1. Select the checkbox for each vulnerability you want to dismiss. 1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. - + ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. -The group Security Dashboard gives an overview of the vulnerabilities in the default branches of the +The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** after selecting your group. By default, the Security Dashboard displays all detected and confirmed vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you @@ -111,20 +138,21 @@ enabled in a group. There is a timeline chart that shows how many open vulnerabilities your projects had at various points in time. You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get -more details about the open vulnerabilities at a specific time. +more details about the open vulnerabilities at a specific time. Aggregated data beyond 90 days can be accessed by querying our [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). This data is retained for 365 days. Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: -- F: One or more "critical" -- D: One or more "high" or "unknown" -- C: One or more "medium" -- B: One or more "low" -- A: Zero vulnerabilities +| Grade | Description | +| F | One or more "critical" | +| D | One or more "high" or "unknown" | +| C | One or more "medium" | +| B | One or more "low" | +| A | Zero vulnerabilities | Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed vulnerabilities are excluded. -Navigate to the group's [vulnerability report](#vulnerability-report) to view the vulnerabilities found. +Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. ## Instance Security Center @@ -232,10 +260,17 @@ into the default branch. You can filter which vulnerabilities the vulnerability report displays by: -- Status -- Severity -- Scanner -- Project +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | +| Project | Projects configured in the Security Center settings | + +You can filter the vulnerabilities list by selecting from the **Status**, **Severity**, and +**Scanner**, and **Project** dropdowns. In the **Scanner** dropdown, select individual scanners or +scanner groups to toggle those scanners. The **Scanner** dropdown includes both GitLab scanners, and +in GitLab 13.6 and later, custom scanners. Clicking any vulnerability in the table takes you to its [Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 391666a077e..f85d4f0140c 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Defend +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 --- diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png Binary files differdeleted file mode 100644 index b925c342a11..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ee3fd6c4dd4..95bb1ff1a67 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -11,10 +11,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w Each security vulnerability in a project's [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has an individual page which includes: -- Details of the vulnerability. +- Details for the vulnerability. - The status of the vulnerability within the project. - Available actions for the vulnerability. -- Issues related to the vulnerability. +- Any issues related to the vulnerability. On the vulnerability page, you can interact with the vulnerability in several different ways: @@ -25,22 +25,22 @@ several different ways: title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../../project/issues/confidential_issues.md). - [Link issues](#link-issues-to-the-vulnerability) - Link existing issues to vulnerability. -- [Solution](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, - a solution is provided for how to fix the vulnerability. +- [Automatic remediation](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, + a solution is provided for how to fix the vulnerability automatically. ## Changing vulnerability status You can switch the status of a vulnerability using the **Status** dropdown to one of the following values: -| Status | Description | -|-----------|-------------------------------------------------------------------| -| Detected | The default state for a newly discovered vulnerability | -| Confirmed | A user has seen this vulnerability and confirmed it to be real | -| Dismissed | A user has seen this vulnerability and dismissed it | -| Resolved | The vulnerability has been fixed and is no longer in the codebase | +| Status | Description | +|-----------|------------------------------------------------------------------------------------------------------------------| +| 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 | +| Resolved | The vulnerability has been fixed and is no longer valid | -A timeline shows you when the vulnerability status has changed, +A timeline shows you when the vulnerability status has changed and allows you to comment on a change. ## Creating an issue for a vulnerability @@ -48,7 +48,7 @@ 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 +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 issue page so you can edit, assign, or comment on the issue. @@ -61,4 +61,4 @@ that the resolution of one issue would resolve multiple vulnerabilities. ## Automatic remediation for vulnerabilities You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#solutions-for-vulnerabilities-auto-remediation). +generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#automatic-remediation-for-vulnerabilities). |
