diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 01:45:44 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 01:45:44 +0000 |
| commit | 85dc423f7090da0a52c73eb66faf22ddb20efff9 (patch) | |
| tree | 9160f299afd8c80c038f08e1545be119f5e3f1e1 /doc/user/application_security | |
| parent | 15c2c8c66dbe422588e5411eee7e68f1fa440bb8 (diff) | |
| download | gitlab-ce-85dc423f7090da0a52c73eb66faf22ddb20efff9.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-4-stable-ee
Diffstat (limited to 'doc/user/application_security')
46 files changed, 1426 insertions, 426 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md new file mode 100644 index 00000000000..ae22655e30b --- /dev/null +++ b/doc/user/application_security/api_fuzzing/index.md @@ -0,0 +1,739 @@ +--- +stage: Secure +group: Fuzz Testing +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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. + +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), +you can run fuzz tests as part your CI/CD workflow. + +## Requirements + +- One of the following web API types: + - REST API + - SOAP + - GraphQL + - Form bodies, JSON, or XML +- An OpenAPI definition, or HTTP Archive (HAR) of requests to test + +## When fuzzing scans run + +When using the `API-Fuzzing.gitlab-ci.yml` template, the `fuzz` job runs last, as shown here. To +ensure API fuzzing scans the latest code, your CI pipeline should deploy changes to a test +environment in one of the jobs preceding the `fuzz` job: + +```yaml +stages: + - build + - test + - deploy + - fuzz +``` + +Note that if your pipeline is configured to deploy to the same web server on each run, running a +pipeline while another is still running could cause a race condition in which one pipeline +overwrites the code from another. The API to scan should be excluded from changes for the duration +of a fuzzing scan. The only changes to the API should be from the fuzzing scanner. Be aware that +any changes made to the API (for example, by users, scheduled tasks, database changes, code +changes, other pipelines, or other scanners) during a scan could cause inaccurate results. + +## Configuration + +There are two 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) + +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) + +### OpenAPI Specification + +The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an +API description format for REST APIs. This section shows you how to configure API fuzzing by using +an OpenAPI specification to provide information about the target API to test. OpenAPI specifications +are provided as a filesystem resource or URL. + +Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: + +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. Provide the location of the OpenAPI v2 specification. You can provide the specification as a file + or URL. Specify the location by adding the `FUZZAPI_OPENAPI` variable: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.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_OPENAPI: test-api-specification.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: **Danger:** +**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. + +### HTTP Archive (HAR) + +The [HTTP Archive format (HAR)](http://www.softwareishard.com/blog/har-12-spec/) +is an archive file format for logging HTTP transactions. When used with GitLab's API fuzzer, HAR +must contain records of calling the web API to test. The API fuzzer extracts all the requests and +uses them to perform testing. + +You can use various tools to generate HAR files: + +- [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy +- [Insomnia Core](https://insomnia.rest/): API client +- [Chrome](https://www.google.com/chrome): Browser +- [Firefox](https://www.mozilla.org/en-US/firefox/): Browser + +DANGER: **Warning:** +HAR files may contain sensitive information such as authentication tokens, API keys, and session +cookies. We recommend that you review the HAR file contents before adding them to a repository. + +Follow these steps to configure API fuzzing to use a HAR 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_HAR` variable and set it to the HAR file's location: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_HAR: test-api-recording.har + ``` + +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_HAR: test-api-recording.har + 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: **Danger:** +**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. + +### Authentication + +Authentication is handled by providing the authentication token as a header or cookie. You can +provide a script that performs an authentication flow or calculates the token. + +#### HTTP Basic Authentication + +[HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) +is an authentication method built into the HTTP protocol and used in-conjunction with +[transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). +To use HTTP basic authentication, two variables are added to your `.gitlab-ci.yml` file: + +- `FUZZAPI_HTTP_USERNAME`: The username for authentication. +- `FUZZAPI_HTTP_PASSWORD`: The password for authentication. + +For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) +(for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the +GitLab projects page at **Settings > CI/CD**, in the **Variables** section. + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_HAR: test-api-recording.har + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_HTTP_USERNAME: testuser + FUZZAPI_HTTP_PASSWORD: $TEST_API_PASSWORD + +``` + +#### Bearer Tokens + +Bearer tokens are used by several different authentication mechanisms, including OAuth2 and JSON Web +Tokens (JWT). Bearer tokens are transmitted using the `Authorization` HTTP header. To use bearer +tokens with API fuzzing, you need one of the following: + +- A token that doesn't expire +- A way to generate a token that lasts the length of testing +- A Python script that API fuzzing can call to generate the token + +##### Token doesn't expire + +If the bearer token doesn't expire, you can provide it using the `FUZZAPI_OVERRIDES_ENV` variable. +The `FUZZAPI_OVERRIDES_ENV` content is a JSON snippet that provides headers and cookies that should +be added to outgoing HTTP requests made by API fuzzing. + +Create a CI/CD variable, for example `TEST_API_BEARERAUTH`, with the value +`{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can +create CI/CD variables from the GitLab projects page at **Settings > CI/CD** in the **Variables** +section. + +Set `FUZZAPI_OVERRIDES_ENV` in your `.gitlab-ci.yml` file: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH +``` + +To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and +the test API's application logs. + +##### Token generated at test-runtime + +If the bearer token must be generated, and the resulting token doesn't expire during testing, you +can provide to API fuzzing a file containing the token. This file can be generated by a prior stage +and job, or as part of the API fuzzing job. + +API fuzzing expects to receive a JSON file with the following structure: + +```json +{ + "headers" : { + "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +This file can be generated by a prior stage and provided to API fuzzing through the +`FUZZAPI_OVERRIDES_FILE` variable. + +Set `FUZZAPI_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json +``` + +To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and +the test API's application logs. + +##### Token has short expiration + +If the bearer token must be generated and expires prior to the scan's completion, you can provide a +program or script for the API fuzzer to execute on a provided interval. The provided script runs in +an Alpine Linux container that has Python 3 and Bash installed. If the Python script requires +additional packages, it must detect this and install the packages at runtime. + +The script must create a JSON file containing the bearer token in a specific format: + +```json +{ + "headers" : { + "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +You must provide three variables, each set for correct operation: + +- `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. +- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. +- `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_CMD: renew_token.py + FUZZAPI_OVERRIDES_INTERVAL: 300 +``` + +To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and +the test API's application logs. + +### Configuration files + +To get started quickly, GitLab provides you with 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). +This file has several testing profiles that perform various amounts of testing. The run time of each +increases as the numbers go up. To use a configuration file, add it to your repository's root as +`.gitlab-api-fuzzing.yml`. + +| Profile | Scan Type | +|:---------|:-----------| +|Quick-10 |Fuzzing 10 times per parameter | +|Medium-20 |Fuzzing 20 times per parameter | +|Medium-50 |Fuzzing 50 times per parameter | +|Long-100 |Fuzzing 100 times per parameter | + +### Available variables + +| Environment variable | Description | +|-----------------------------|--------------------| +| `FUZZAPI_VERSION` |Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` |Base URL of API testing target. | +|[`FUZZAPI_CONFIG`](#configuration-files)|API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | +|[`FUZZAPI_PROFILE`](#configuration-files)|Configuration profile to use during testing. Defaults to `Quick`. | +| `FUZZAPI_REPORT` |Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | +|[`FUZZAPI_OPENAPI`](#openapi-specification)|OpenAPI specification file or URL. | +|[`FUZZAPI_HAR`](#http-archive-har)|HTTP Archive (HAR) file. | +|[`FUZZAPI_OVERRIDES_FILE`](#overrides) |Path to a JSON file containing overrides. | +|[`FUZZAPI_OVERRIDES_ENV`](#overrides) |JSON string containing headers to override. | +|[`FUZZAPI_OVERRIDES_CMD`](#overrides) |Overrides command. | +|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) |How often to run overrides command in seconds. Defaults to `0` (once). | +|[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) |Username for HTTP authentication. | +|[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) |Password for HTTP authentication. | + +<!--|[`FUZZAPI_D_TARGET_IMAGE`](#target-container) |API target docker image | +|[`FUZZAPI_D_TARGET_ENV`](#target-container) |Docker environment options | +|[`FUZZAPI_D_TARGET_VOLUME`](#target-container)|Docker volume options | +|[`FUZZAPI_D_TARGET_PORTS`](#target-container) |Docker port options | +| `FUZZAPI_D_WORKER_IMAGE` |Custom worker docker image | +| `FUZZAPI_D_WORKER_ENV` |Custom worker docker environment options | +| `FUZZAPI_D_WORKER_VOLUME` |Custom worker docker volume options | +| `FUZZAPI_D_WORKER_PORTS` |Custom worker docker port options | +| `FUZZAPI_D_NETWORK` |Name of docker network, defaults to "testing-net"| +| `FUZZAPI_D_PRE_SCRIPT` |Pre script runs after docker login and docker network create, but before starting the scanning image container.| +| `FUZZAPI_D_POST_SCRIPT` |Post script runs after scanning image container is started. This is the place to start your target(s) and kick off scanning when using an advanced configuration.| --> + +### Overrides + +API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests +made. You can use this to inject semver headers, authentication, and so on. The +[authentication section](#authentication) includes examples of using overrides for that purpose. + +Overrides uses a JSON document to define the headers and cookies: + +```json +{ + "headers": { + "header1": "value", + "header2": "value" + }, + "cookies": { + "cookie1": "value", + "cookie2": "value" + } +} +``` + +Example usage for setting a single header: + +```json +{ + "headers": { + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +Example usage for setting both a header and cookie: + +```json +{ + "headers": { + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + }, + "cookies": { + "flags": "677" + } +} +``` + +You can provide this JSON document as a file or environment variable. You may also provide a command +to generate the JSON document. The command can run at intervals to support values that expire. + +#### Using a file + +To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` environment variable is set. The path is relative to the job current working directory. + +Example `.gitlab-ci.yml`: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json +``` + +#### Using an environment variable + +To provide the overrides JSON as an environment variable, use the `FUZZAPI_OVERRIDES_ENV` variable. +This allows you to place the JSON as CI/CD variables that can be masked and protected. + +In this example `.gitlab-ci.yml`, the JSON is provided directly: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}' +``` + +In this example `.gitlab-ci.yml`, the CI/CD variable `SECRET_OVERRIDES` provides the JSON. This is a +[group or instance level environment variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-environment-variables): + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: $SECRET_OVERRIDES +``` + +#### Using a command + +If the value must be generated or regenerated on expiration, you can provide a program or script for +the API fuzzer to execute on a specified interval. The provided script runs in an Alpine Linux +container that has Python 3 and Bash installed. If the Python script requires additional packages, +it must detect this and install the packages at runtime. The script creates the overrides JSON file +as defined above. + +You must provide three variables, each set for correct operation: + +- `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. +- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. +- `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_CMD: renew_token.py + FUZZAPI_OVERRIDES_INTERVAL: 300 +``` + +## Running your first scan + +When configured correctly, a CI/CD pipeline contains a `Fuzz` stage and a `apifuzzer_fuzz` job. The +job only fails when an invalid configuration is provided. During normal operation, the job always +succeeds even if faults are identified during fuzz testing. + +Faults are displayed on the **Tests** pipeline tab with the suite name **API-Fuzzing**. The **Name** +field on the **Tests** page includes the fuzz-tested operation and parameter. The **Trace** field +contains a writeup of the identified fault. This writeup contains information on what the fuzzer +tested and how it detected something wrong. + +To prevent an excessive number of reported faults, the API fuzzing scanner limits the number of +faults it reports to one per parameter. + +### Fault Writeup + +The faults that API fuzzing finds aren't associated with a specific vulnerability type. They require +investigation to determine what type of issue they are and if they should be fixed. See +[handling false positives](#handling-false-positives) for information about configuration changes +you can make to limit the number of false positives reported. + +This table contains a description of fields in an API fuzzing fault writeup. + +| Writeup Item | Description | +|:-------------|:------------| +| Operation | The operation tested. | +| Parameter | The field modified. This can be a path segment, header, query string, or body element. | +| Endpoint | The endpoint being tested. | +| Check | Check module producing the test. Checks can be turned on and off. | +| Assert | Assert module that detected a failure. Assertions can be configured and turned on and off. | +| CWE | Fuzzing faults always have the same CWE. | +| OWASP | Fuzzing faults always have the same OWASP ID. | +| Exploitability | Fuzzing faults always have an `unknown` exploitability. | +| Impact | Fuzzing faults always have an `unknown` risk impact. | +| Description | Verbose description of what the check did. Includes the original parameter value and the modified (mutated) value. | +| Detection | Why a failure was detected and reported. This is related to the Assert that was used. | +| Original Request | The original, unmodified HTTP request. Useful when reviewing the actual request to see what changes were made. | +| Actual Request | The request that produced the failure. This request has been modified in some way by the Check logic. | +| Actual Response | The response to the actual request. | +| Recorded Request | An unmodified request. | +| Recorded Response | The response to the unmodified request. You can compare this with the actual request when triaging this fault. | + +## Handling False Positives + +False positives can be handled in two ways: + +- Turn off the Check producing the false positive. This prevents the check from generating any + faults. Example checks are the JSON Fuzzing Check, and Form Body Fuzzing Check. +- Fuzzing checks have several methods of detecting when a fault is identified, called _Asserts_. + Asserts can also be turned off and configured. For example, the API fuzzer by default uses HTTP + status codes to help identify when something is a real issue. If an API returns a 500 error during + testing, this creates a fault. This isn't always desired, as some frameworks return 500 errors + often. + +### Turn off a Check + +Checks perform testing of a specific type and can be turned on and off for specific configuration +profiles. The provided [configuration files](#configuration-files) define several profiles that you +can use. The profile definition in the configuration file lists all the checks that are active +during a scan. To turn off a specific check, simply remove it from the profile definition in the +configuration file. The profiles are defined in the `Profiles` section of the configuration file. + +Example profile definition: + +```yaml +Profiles: + - Name: Quick-10 + DefaultProfile: Quick + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +To turn off the General Fuzzing Check you can remove these lines: + +```yaml +- Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +This results in the following YAML: + +```yaml +- Name: Quick-10 + DefaultProfile: Quick + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +### Turn off an Assertion for a Check + +Assertions detect faults in tests produced by checks. Many checks support multiple Assertions such +as Log Analysis, Response Analysis, and Status Code. When a fault is found, the Assertion used is +provided. To identify which Assertions are on by default, see the Checks default configuration in +the configuration file. The section is called `Checks`. + +This example shows the FormBody Fuzzing Check: + +```yaml +Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 30 + UnicodeFuzzing: true + Assertions: + - Name: LogAnalysisAssertion + - Name: ResponseAnalysisAssertion + - Name: StatusCodeAssertion +``` + +Here you can see three Assertions are on by default. A common source of false positives is +`StatusCodeAssertion`. To turn it off, modify its configuration in the `Profiles` section. This +example provides only the other two Assertions (`LogAnalysisAssertion`, +`ResponseAnalysisAssertion`). This prevents `FormBodyFuzzingCheck` from using `StatusCodeAssertion`: + +```yaml +Profiles: + - Name: Quick-10 + DefaultProfile: Quick + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + Assertions: + - Name: LogAnalysisAssertion + - Name: ResponseAnalysisAssertion + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlInjectionCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +<!-- +### Target Container + +The API Fuzzing template supports launching a docker container containing an API target using docker-in-docker. + +TODO +--> + +## Glossary + +- Assert: Assertions are detection modules used by checks to trigger a fault. Many assertions have + configurations. A check can use multiple Assertions. For example, Log Analysis, Response Analysis, + and Status Code are common Assertions used together by checks. Checks with multiple Assertions + allow them to be turned on and off. +- Check: Performs a specific type of test, or performed a check for a type of vulnerability. For + example, the JSON Fuzzing Check performs fuzz testing of JSON payloads. The API fuzzer is + comprised of several checks. Checks can be turned on and off in a profile. +- Fault: During fuzzing, a failure identified by an Assert is called a fault. Faults are + investigated to determine if they are a security vulnerability, a non-security issue, or a false + positive. Faults don't have a known vulnerability type until they are investigated. Example + vulnerability types are SQL Injection and Denial of Service. +- Profile: A configuration file has one or more testing profiles, or sub-configurations. You may + have a profile for feature branches and another with extra testing for a main branch. diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 1195d07d7b7..a6ad701360e 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -7,23 +7,41 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Security Configuration **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. +> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. -The Security Configuration page displays the configuration state of each security feature in the -current project. The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) -to determine each feature's configuration state. If a job with the expected security report artifact -exists in the pipeline, the feature is considered enabled. +The Security Configuration page displays the configuration state of each security control in the +current project. -You can only enable SAST from the Security Configuration page. Documentation links are included for -the other features. For details about configuring SAST, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +To view a project's security configuration, go to the project's home page, +then in the left sidebar go to **Security & Compliance > Configuration**. + +For each security control the page displays: + +- **Status** - Status of the security control: enabled, not enabled, or available. +- **Manage** - A management option or a link to the documentation. + +## Status + +The status of each security control is determined by the project's latest default branch +[CI pipeline](../../../ci/pipelines/index.md). +If a job with the expected security report artifact exists in the pipeline, the feature's status is +_enabled_. + +For SAST, click **View history** to see the `.gitlab-ci.yml` file’s history. NOTE: **Note:** If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), all security features are configured by default. -## View Security Configuration +## Manage -To view a project's security configuration: +You can configure the following security controls: -1. Go to the project's home page. -1. In the left sidebar, go to **Security & Configuration** > **Configuration**. +- Auto DevOps + - Click **Enable Auto DevOps** to enable it for the current project. For more details, see [Auto DevOps](../../../topics/autodevops/index.md). +- SAST + - Click either **Enable** or **Configure** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +- DAST Profiles + - Click **Manage** to manage the available DAST profiles used for on-demand scans. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 6b7086ddc71..880e5a3875a 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -26,7 +26,7 @@ To integrate security scanners other than Clair and Klar into GitLab, see You can enable container scanning by doing one of the following: - [Include the CI job](#configuration) in your existing `.gitlab-ci.yml` file. -- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning-ultimate) +- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning) provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab compares the found vulnerabilities between the source and target branches, and shows the @@ -40,12 +40,12 @@ information directly in the merge request. ## Requirements -To enable Container Scanning in your pipeline, you need the following: +To enable container scanning in your pipeline, you need the following: -- [GitLab Runner](https://docs.gitlab.com/runner/) with the [Docker](https://docs.gitlab.com/runner/executors/docker.html) - or [Kubernetes](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -- Docker `18.09.03` or higher installed on the same computer as the Runner. If you're using the - shared Runners on GitLab.com, then this is already the case. +- [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) + or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. +- Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the + shared runners on GitLab.com, then this is already the case. - [Build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use the following [predefined environment variables](../../../ci/variables/predefined_variables.md): @@ -72,7 +72,7 @@ To enable Container Scanning in your pipeline, you need the following: ## Configuration -How you enable Container Scanning depends on your GitLab version: +How you enable container scanning depends on your GitLab version: - GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) 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) @@ -91,16 +91,16 @@ include: The included template: - Creates a `container_scanning` job in your CI/CD pipeline. -- Pulls the built Docker image from your project's [Container Registry](../../packages/container_registry/index.md) +- Pulls the built Docker image from your project's [container registry](../../packages/container_registry/index.md) (see [requirements](#requirements)) and scans it for possible vulnerabilities. GitLab saves the results as a -[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning-ultimate) +[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning) that you can download and analyze later. When downloading, you always receive the most-recent artifact. -The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the Container -Registry, and scans the containers: +The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container +registry, and scans the containers: ```yaml variables: @@ -127,7 +127,7 @@ include: - template: Container-Scanning.gitlab-ci.yml ``` -### Customizing the Container Scanning settings +### Customizing the container scanning settings There may be cases where you want to customize how GitLab scans your containers. For example, you may want to enable more verbose output from Clair or Klar, access a Docker registry that requires @@ -136,7 +136,7 @@ parameter in your `.gitlab-ci.yml` to set [environment variables](#available-var The environment variables you set in your `.gitlab-ci.yml` overwrite those in `Container-Scanning.gitlab-ci.yml`. -This example [includes](../../../ci/yaml/README.md#include) the Container Scanning template and +This example [includes](../../../ci/yaml/README.md#include) the container scanning template and enables verbose output from Clair by setting the `CLAIR_OUTPUT` environment variable to `High`: ```yaml @@ -153,30 +153,30 @@ variables: #### Available variables -Container Scanning can be [configured](#customizing-the-container-scanning-settings) -using environment variables. - -| Environment Variable | Default | Description | -| -------------------- | ----------- | ------- | -| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | -| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | -| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | -| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | -| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | -| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | -| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | -| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | -| `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. | -| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database 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. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | -| `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. | -| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | -| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | -| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | -| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | -| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | - -### Overriding the Container Scanning template +You can [configure](#customizing-the-container-scanning-settings) container +scanning by using the following environment variables: + +| Environment Variable | Default | Description | +| ------------------------------ | ------------- | ----------- | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | +| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database 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. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | +| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | +| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | +| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | +| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | +| `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. | +| `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. | +| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | +| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | +| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | +| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | +| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | + +### Overriding the container scanning template If you want to override the job definition (for example, to change properties like `variables`), you must declare a `container_scanning` job after the template inclusion, and then @@ -201,35 +201,35 @@ instead. To allowlist specific vulnerabilities, follow these steps: 1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in - [overriding the Container Scanning template](#overriding-the-container-scanning-template). + [overriding the container scanning template](#overriding-the-container-scanning-template). 1. Define the allowlisted vulnerabilities in a YAML file named `vulnerability-allowlist.yml`. This must use the format described in the [allowlist example file](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/raw/master/testdata/vulnerability-allowlist.yml). 1. Add the `vulnerability-allowlist.yml` file to your project's Git repository. -### Running Container Scanning in an offline environment +### Running container scanning in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for the Container Scanning job to +to external resources through the internet, some adjustments are required for the container scanning job to successfully run. For more information, see [Offline environments](../offline_deployments/index.md). -#### Requirements for offline Container Scanning +#### Requirements for offline container Scanning -To use Container Scanning in an offline environment, you need: +To use container scanning in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- To configure a local Docker Container Registry with copies of the Container Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [Container Scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry). +- To configure a local Docker container registry with copies of the container scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [container scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry). NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. -#### Make GitLab Container Scanning analyzer images available inside your Docker registry +#### Make GitLab container scanning analyzer images available inside your Docker registry -For Container Scanning, import the following default images from `registry.gitlab.com` into your +For container scanning, import the following default images from `registry.gitlab.com` into your [local Docker container registry](../../packages/container_registry/index.md): ```plaintext @@ -249,7 +249,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -#### Set Container Scanning CI job variables to use local Container Scanner analyzers +#### Set container scanning CI job variables to use local container scanner analyzers 1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry: @@ -267,10 +267,10 @@ For details on saving and transporting Docker images as a file, see Docker's doc self-signed certificate, then you must set `DOCKER_INSECURE: "true"` in the above `container_scanning` section of your `.gitlab-ci.yml`. -#### Automating Container Scanning vulnerability database updates with a pipeline +#### Automating container scanning vulnerability database updates with a pipeline It can be worthwhile to set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to -automatically build a new version of the vulnerabilities database on a preset schedule. Automating +build a new version of the vulnerabilities database on a preset schedule. Automating this with a pipeline means you won't have to do it manually each time. You can use the following `.gitlab-yml.ci` as a template: @@ -293,9 +293,9 @@ build_latest_vulnerabilities: The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. -## Running the standalone Container Scanning Tool +## Running the standalone container scanning tool -It's possible to run the [GitLab Container Scanning Tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar) +It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar) against a Docker container without needing to run it within the context of a CI job. To scan an image directly, follow these steps: @@ -329,10 +329,10 @@ The results are stored in `gl-container-scanning-report.json`. ## Reports JSON format -The Container Scanning tool emits a JSON report file. For more information, see the +The container scanning tool emits a JSON report file. For more information, see the [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json). -Here's an example Container Scanning report: +Here's an example container scanning report: ```json-doc { @@ -401,7 +401,7 @@ For more information about the vulnerabilities database update, check the ## Interacting with the vulnerabilities -Once a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). ## Solutions for vulnerabilities (auto-remediation) @@ -413,7 +413,7 @@ the [`DOCKERFILE_PATH`](#available-variables) environment variable. To ensure th has access to this file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/yaml/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. +[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). @@ -421,8 +421,8 @@ Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vu ### `docker: Error response from daemon: failed to copy xattrs` -When the GitLab Runner uses the Docker executor and NFS is used -(for example, `/var/lib/docker` is on an NFS mount), Container Scanning might fail with +When the runner uses the `docker` executor and NFS is used +(for example, `/var/lib/docker` is on an NFS mount), container scanning might fail with an error like the following: ```plaintext @@ -430,6 +430,6 @@ docker: Error response from daemon: failed to copy xattrs: failed to set xattr " ``` This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt"). -To prevent the error, ensure the Docker version that the Runner is using is +To prevent the error, ensure the Docker version that the runner is using is `18.09.03` or higher. For more information, see [issue #10241](https://gitlab.com/gitlab-org/gitlab/-/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 1672e9fbb25..dff71cb9445 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -25,9 +25,11 @@ Docker image with the fuzz engine to run your app. | Language | Fuzzing Engine | Example | |----------|----------------|---------| -| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/c-cpp-fuzzing-example) | -| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) | -| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | | +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | +| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | +| 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) | ## Configuration diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md new file mode 100644 index 00000000000..94cacf2882f --- /dev/null +++ b/doc/user/application_security/cve_id_request.md @@ -0,0 +1,69 @@ +--- +type: tutorial +stage: Secure +group: Vulnerability Research +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# CVE ID Requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. + +As part of [GitLab's role as a CVE Numbering Authority](https://about.gitlab.com/security/cve) +([CNA](https://cve.mitre.org/cve/cna.html)), you may request +[CVE](https://cve.mitre.org/index.html) identifiers from GitLab to track +vulnerabilities found within your project. + +## Overview + +CVE identifiers track specific vulnerabilities within projects. Having a CVE assigned to a +vulnerability in your project helps your users stay secure and informed. For example, +[dependency scanning tools](../application_security/dependency_scanning/index.md) +can detect when vulnerable versions of your project are used as a dependency. + +## Conditions + +If the following conditions are met, a **Request CVE ID** button appears in your issue sidebar: + +- The project is hosted in GitLab.com. +- The project is public. +- You are a maintainer of the project. +- The issue is confidential. + +## Submitting a CVE ID Request + +Clicking the **Request CVE ID** button in the issue sidebar takes you to the new issue page for +[GitLab's CVE project](https://gitlab.com/gitlab-org/cves). + + + +Creating the confidential issue starts the CVE request process. + + + +You are required to fill in the issue description, which includes: + +- A description of the vulnerability +- The project's vendor and name +- Impacted versions +- Fixed versions +- The vulnerability type (a [CWE](https://cwe.mitre.org/data/index.html) identifier) +- A [CVSS v3 vector](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) + +## CVE Assignment + +GitLab triages your submitted CVE ID request and communicates with you throughout the CVE validation +and assignment process. + + + +Once a CVE identifier is assigned, you may use and reference it as you see fit. + +Details of the vulnerability submitted in the CVE ID request are published according to your +schedule. It's common to request a CVE for an unpatched vulnerability, reference the assigned CVE +identifier in release notes, and later publish the vulnerability's details after the fix is +released. + +Separate communications notify you when different stages of the publication process are complete. + + diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index b2020d48d38..73a8e727389 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -26,7 +26,7 @@ If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your runn for known vulnerabilities using Dynamic Application Security Testing (DAST). You can take advantage of DAST by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using -[Auto DAST](../../../topics/autodevops/stages.md#auto-dast-ultimate), +[Auto DAST](../../../topics/autodevops/stages.md#auto-dast), provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the DAST report, compares the found vulnerabilities between the source and target @@ -106,7 +106,7 @@ The included template creates a `dast` job in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate) +[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations we always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) @@ -177,13 +177,13 @@ include: variables: DAST_WEBSITE: https://example.com DAST_AUTH_URL: https://example.com/sign-in - DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form - DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form - DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between + DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form + DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate) +[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. @@ -206,6 +206,9 @@ variables: DAST_FULL_SCAN_ENABLED: "true" ``` +NOTE: **Note:** +If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). + #### Domain validation The DAST job can be run anywhere, which means you can accidentally hit live web servers @@ -364,7 +367,7 @@ dast: DAST_API_SPECIFICATION: api-specification.yml ``` -#### Full scan +#### Full API scan API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` environment variable. Domain validation is not supported for full API scans. @@ -395,7 +398,11 @@ variables: DAST_API_HOST_OVERRIDE: api-test.host.com ``` -Note that `DAST_API_HOST_OVERRIDE` is only applied to specifications imported by URL. +NOTE: **Note:** +Using a host override is ONLY supported when importing the API +specification from a URL. It does not work and will be ignored when importing +the specification from a file. This is due to a limitation in the ZAP OpenAPI +extension. #### Authentication using headers @@ -412,6 +419,31 @@ variables: DAST_REQUEST_HEADERS: "Authorization: Bearer my.token" ``` +### URL scan + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +A URL scan allows you to specify which parts of a website are scanned by DAST. + +#### Define the URLs to scan + +To specify the paths to be scanned, add a comma-separated list of the paths to the `DAST_PATHS` environment variable. Note that you can only scan paths of a single host. + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_PATHS=/page1.html,/category1/page1.html,/page3.html +``` + +NOTE: **Note:** +`DAST_AUTH_EXCLUDE_URLS` are ignored when `DAST_PATHS` is set. + +#### Full Scan + +To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` environment variable. + ### Customizing the DAST settings CAUTION: **Deprecation:** @@ -451,12 +483,12 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | | `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | | `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_AUTH_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. | +| `DAST_AUTH_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | | `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | -| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. 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 supressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `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. | @@ -465,6 +497,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `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_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` | @@ -484,8 +517,8 @@ dast: ``` You must then overwrite the `script` command to pass in the appropriate -argument. For example, passive scanning can be delayed using option `-D`. The following -configuration delays passive scanning by five minutes: +argument. For example, vulnerability definitions in alpha can be included with +`-a`. The following configuration includes those definitions: ```yaml include: @@ -494,7 +527,7 @@ include: dast: script: - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -D 300 -t $DAST_WEBSITE + - /analyze -a -t $DAST_WEBSITE ``` ### Custom ZAProxy configuration @@ -559,8 +592,8 @@ To use DAST in an offline environment, you need: NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. @@ -600,110 +633,171 @@ security reports without requiring internet access. Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. -## On-Demand Scans +## Site 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). +A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is +required for an on-demand DAST scan. -You can run a passive DAST scan against a target website, outside the DevOps lifecycle. These scans -are always associated with the default branch of your project and the results are available in the -project dashboard. +A site profile contains the following: -### Site profile +- **Profile name**: A name you assign to the site to be scanned. +- **Target URL**: The URL that DAST runs against. -An on-demand scan requires a site profile, which includes a profile name and target URL. The profile -name allows you to describe the site to be scanned. The target URL specifies the URL against which -the DAST scan is run. +### Create a site profile -### Run an on-demand scan +To create a site profile: -NOTE: **Note:** -You must have permission to run an on-demand DAST scan against a protected branch. -The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **New Profile > Site Profile**. +1. Type in a unique **Profile name** and **Target URL** then click **Save profile**. -Running an on-demand scan requires an existing site profile. If a site profile for the target URL -doesn't exist, first [create a site profile](#create-a-site-profile). An on-demand DAST scan has -a fixed timeout of 60 seconds. +### Edit a site profile -- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. -- Click **Create new DAST scan**. -- Select a site profile from the profiles dropdown. -- Click **Run scan**. +To edit an existing site profile: -#### Create a site profile +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **Edit** in the row of the profile to edit. +1. Edit the **Profile name** and **Target URL**, then click **Save profile**. -- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. -- Click **Create new DAST scan**. -- Click **New Site Profile**. -- Type in a unique **Profile name** and **Target URL** then click **Save profile**. +### Delete a site profile -#### Delete a site profile +To delete an existing site profile: -- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. -- Click **Create new DAST scan**. -- Click **Delete** in the matching site profile's row. +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **{remove}** in the row of the profile to delete. -### Enable or disable On-demand Scans and site profiles +## Scanner profile -On-demand Scans with site profiles is enabled by default. You can disable On-demand Scans -instance-wide, or disable it for specific projects if you prefer. DAST site profiles are not -available if the On-demand Scans feature is disabled. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. +> - [Deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Enabled on GitLab.com. +> - Can be enabled or disabled per-project. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can [disable this feature](#enable-or-disable-dast-scanner-profiles). -Use of On-demand Scans with site profiles requires **both** the following feature flags enabled: +A scanner profile defines the scanner settings used to run an on-demand scan: -- security_on_demand_scans_feature_flag -- security_on_demand_scans_site_profiles_feature_flag +- **Profile name:** A name you give the scanner profile. For example, "Spider_15". +- **Spider timeout:** The maximum number of minutes allowed for the spider to traverse the site. +- **Target timeout:** The maximum number of seconds DAST waits for the site to be available before + starting the scan. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable or enable the feature flags. +### Create a scanner profile + +To create a scanner profile: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **New Profile > Scanner Profile**. +1. Enter a unique **Profile name**, the desired **Spider timeout**, and the **Target timeout**. +1. Click **Save profile**. + +### Edit a scanner profile + +To edit a scanner profile: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **Edit** in the scanner profile's row. -#### Enable or disable On-demand Scans +### Delete a scanner profile -To disable On-demand Scans: +To delete a scanner profile: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **{remove}** in the scanner profile's row. + +### Enable or disable DAST scanner profiles + +The scanner profile feature is ready for production use. It's deployed behind a feature flag that +is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can opt to disable it. + +To disable it: ```ruby # Instance-wide -Feature.disable(:security_on_demand_scans_feature_flag) +Feature.disable(:security_on_demand_scans_scanner_profiles) # or by project -Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +Feature.disable(:security_on_demand_scans_scanner_profiles, Project.find(<project id>)) ``` -To enable On-demand Scans: +To enable it: ```ruby # Instance-wide -Feature.enable(:security_on_demand_scans_feature_flag) +Feature.enable(:security_on_demand_scans_scanner_profiles) # or by project -Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +Feature.enable(:security_on_demand_scans_scanner_profiles, Project.find(<project ID>)) ``` -#### Enable or disable site profiles +## On-demand scans + +> - [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. + +An on-demand DAST scan: + +- Uses settings in the site profile and scanner profile you select when you run the scan, + instead of those in the `.gitlab-ci.yml` file. +- Is associated with your project's default branch. + +### Run an on-demand DAST scan + +NOTE: **Note:** +You must have permission to run an on-demand DAST scan against a protected branch. +The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +To run an on-demand DAST scan, you need: + +- A [scanner profile](#create-a-scanner-profile). +- A [site profile](#create-a-site-profile). + +1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. +1. Click **Create new DAST scan**. +1. In **Scanner settings**, select a scanner profile from the dropdown. +1. In **Site profiles**, select a site profile from the dropdown. +1. Click **Run scan**. + +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. -The Site Profiles feature is enabled instance-wide by default. You can disable it instance-wide, or disable it -for specific projects if you prefer. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable or enable the feature flag. +can disable or enable the feature flags. -To disable Site Profiles: +To disable On-demand DAST Scans: ```ruby # Instance-wide -Feature.disable(:security_on_demand_scans_site_profiles_feature_flag) +Feature.disable(:security_on_demand_scans_feature_flag) # or by project -Feature.disable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) +Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) ``` -To enable Site Profiles: +To enable On-demand DAST Scans: ```ruby # Instance-wide -Feature.enable(:security_on_demand_scans_site_profiles_feature_flag) +Feature.enable(:security_on_demand_scans_feature_flag) # or by project -Feature.enable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) +Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project ID>)) ``` ## Reports @@ -825,6 +919,10 @@ variables: Here, DAST is being allocated 3072 MB. Change the number after `-Xmx` to the required memory amount. +### DAST job exceeding the job timeout + +If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index d41f9441464..40189235e64 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -90,32 +90,7 @@ That's needed when one totally relies on [custom analyzers](#custom-analyzers). ## Custom analyzers -### Custom analyzers with Docker-in-Docker - -When Docker-in-Docker for Dependency Scanning is enabled, -you can provide your own analyzers as a comma-separated list of Docker images. -Here's how to add `analyzers/nuget` and `analyzers/perl` to the default images. -In `.gitlab-ci.yml` define: - -```yaml -include: - template: Dependency-Scanning.gitlab-ci.yml - -variables: - DS_ANALYZER_IMAGES: "my-docker-registry/analyzers/nuget,amy-docker-registry/analyzers/perl" -``` - -The values must be the full path to the container registry images, -like what you would feed to the `docker pull` command. - -NOTE: **Note:** -This configuration doesn't benefit from the integrated detection step. Dependency -Scanning has to fetch and spawn each Docker image to establish whether the -custom analyzer can scan the source code. - -### Custom analyzers without Docker-in-Docker - -When Docker-in-Docker for Dependency Scanning is disabled, you can provide your own analyzers by +You can provide your own analyzers by defining CI jobs in your CI configuration. For consistency, you should suffix your custom Dependency Scanning jobs with `-dependency_scanning`. Here's how to add a scanning job that's based on the Docker image `my-docker-registry/analyzers/nuget` and generates a Dependency Scanning report diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 6b14f93735b..5cce336d04c 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -20,7 +20,7 @@ vulnerabilities using Dependency Scanning. All dependencies are scanned, including the transitive dependencies (also known as nested dependencies). You can take advantage of Dependency Scanning by either [including the Dependency Scanning template](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using -the [Auto Dependency Scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning-ultimate) +the [Auto Dependency Scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the Dependency Scanning report, compares the found vulnerabilities @@ -43,14 +43,12 @@ The results are sorted by the severity of the vulnerability: To run Dependency Scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -If you're using the shared Runners on GitLab.com, this is enabled by default. +If you're using the shared runners on GitLab.com, this is enabled by default. CAUTION: **Caution:** -If you use your own Runners, make sure your installed version of Docker +If you use your own runners, make sure your installed version of Docker is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. -Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for Dependency Scanning](#enabling-docker-in-docker). - ## 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. @@ -61,6 +59,7 @@ The following languages and dependency managers are supported: | Language (package managers) | Supported files | Scan tool(s) | |----------------------------- | --------------- | ------------ | | C# .NET ([NuGet](https://www.nuget.org/) 4.9+) | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| C/C++ ([Conan](https://conan.io/)) | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | Java ([Gradle](https://gradle.org/), [Maven](https://maven.apache.org/)) | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | | Go ([Golang](https://golang.org/)) | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | @@ -99,7 +98,7 @@ include: The included template creates Dependency Scanning jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate) +[Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest Dependency Scanning artifact available. @@ -153,24 +152,10 @@ The following variables allow configuration of global dependency scanning settin | --------------------------------------- |------------ | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `DS_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | -| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. | +| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"` | | `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info` | -#### Configuring Docker-in-Docker orchestrator - -The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker). - -| Environment variable | Default | Description | -| --------------------------------------- | ----------- | ----------- | -| `DS_ANALYZER_IMAGES` | | Comma-separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). | -| `DS_ANALYZER_IMAGE_TAG` | | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `DS_PULL_ANALYZER_IMAGES` | | Pull the images from the Docker registry (set to `0` to disable). | -| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `300ms`, `1.5h`, or `2h45m`. | -| `DS_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling an analyzer's image. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `300ms`, `1.5h`, or `2h45m`. | -| `DS_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `300ms`, `1.5h`, or `2h45m`. | - #### Configuring specific analyzers used by Dependency Scanning The following variables are used for configuring specific analyzers (used for a specific language/framework). @@ -205,27 +190,6 @@ 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 Docker-in-Docker - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12487) in GitLab Ultimate 12.5. - -If needed, you can enable Docker-in-Docker to restore the Dependency Scanning behavior that existed -prior to GitLab 13.0. Follow these steps to do so: - -1. Configure GitLab Runner with Docker-in-Docker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). -1. Set the `DS_DISABLE_DIND` variable to `false`: - - ```yaml - include: - - template: Dependency-Scanning.gitlab-ci.yml - - variables: - DS_DISABLE_DIND: "false" - ``` - -This creates a single `dependency_scanning` job in your CI/CD pipeline instead of multiple -`<analyzer-name>-dependency_scanning` jobs. - ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to @@ -388,7 +352,6 @@ jobs to run successfully. For more information, see [Offline environments](../of Here are the requirements for using Dependency Scanning in an offline environment: -- Keep Docker-In-Docker disabled (default). - 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/). @@ -399,8 +362,8 @@ Here are the requirements for using Dependency Scanning in an offline environmen NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. @@ -443,7 +406,6 @@ include: variables: SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers" GEMNASIUM_DB_REMOTE_URL: "gitlab.example.com/gemnasium-db.git" - GIT_SSL_NO_VERIFY: "true" ``` See explanations of the variables above in the [configuration section](#configuration). diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png Binary files differdeleted file mode 100644 index cb8911b14b1..00000000000 --- a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png Binary files differnew file mode 100644 index 00000000000..8e7bcf09428 --- /dev/null +++ b/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png diff --git a/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png b/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png Binary files differnew file mode 100644 index 00000000000..b792fbc9af1 --- /dev/null +++ b/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png diff --git a/doc/user/application_security/img/create_issue_with_list_hover.png b/doc/user/application_security/img/create_issue_with_list_hover.png Binary files differdeleted file mode 100644 index 4c38862e68f..00000000000 --- a/doc/user/application_security/img/create_issue_with_list_hover.png +++ /dev/null diff --git a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png Binary files differnew file mode 100644 index 00000000000..a914c2996f7 --- /dev/null +++ b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png diff --git a/doc/user/application_security/img/cve_id_request_button.png b/doc/user/application_security/img/cve_id_request_button.png Binary files differnew file mode 100644 index 00000000000..15707ba9eb2 --- /dev/null +++ b/doc/user/application_security/img/cve_id_request_button.png diff --git a/doc/user/application_security/img/cve_request_communication.png b/doc/user/application_security/img/cve_request_communication.png Binary files differnew file mode 100644 index 00000000000..0766b371c11 --- /dev/null +++ b/doc/user/application_security/img/cve_request_communication.png diff --git a/doc/user/application_security/img/cve_request_communication_publication.png b/doc/user/application_security/img/cve_request_communication_publication.png Binary files differnew file mode 100644 index 00000000000..9e34c217e13 --- /dev/null +++ b/doc/user/application_security/img/cve_request_communication_publication.png diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png Binary files differdeleted file mode 100644 index 19d47712f9e..00000000000 --- a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png Binary files differnew file mode 100644 index 00000000000..db698995469 --- /dev/null +++ b/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png diff --git a/doc/user/application_security/img/new_cve_request_issue.png b/doc/user/application_security/img/new_cve_request_issue.png Binary files differnew file mode 100644 index 00000000000..a342c73992e --- /dev/null +++ b/doc/user/application_security/img/new_cve_request_issue.png diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png Binary files differnew file mode 100644 index 00000000000..f497b0fbc4e --- /dev/null +++ b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png Binary files differnew file mode 100644 index 00000000000..fc847b578f5 --- /dev/null +++ b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png diff --git a/doc/user/application_security/img/vulnerability-check_v13_0.png b/doc/user/application_security/img/vulnerability-check_v13_0.png Binary files differdeleted file mode 100644 index 9f0bd0f759b..00000000000 --- a/doc/user/application_security/img/vulnerability-check_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability-check_v13_4.png b/doc/user/application_security/img/vulnerability-check_v13_4.png Binary files differnew file mode 100644 index 00000000000..e0b53059b45 --- /dev/null +++ b/doc/user/application_security/img/vulnerability-check_v13_4.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index c003b512808..d509176f2b2 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -67,6 +67,7 @@ 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. | | [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. | @@ -76,12 +77,12 @@ GitLab uses the following tools to scan and report known vulnerabilities found i When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. -- [Auto SAST](../../topics/autodevops/stages.md#auto-sast-ultimate) -- [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection-ultimate) -- [Auto DAST](../../topics/autodevops/stages.md#auto-dast-ultimate) -- [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning-ultimate) -- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance-ultimate) -- [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning-ultimate) +- [Auto SAST](../../topics/autodevops/stages.md#auto-sast) +- [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) +- [Auto DAST](../../topics/autodevops/stages.md#auto-dast) +- [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning) +- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance) +- [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning) While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customizing-gitlab-ciyml). @@ -121,7 +122,7 @@ information with several options: - [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities, a solution is provided for how to fix the vulnerability. - + ### View details of a DAST vulnerability @@ -165,7 +166,8 @@ reports. You can specify the list of all headers to be masked. For details, see ### Dismissing a vulnerability -To dismiss a vulnerability, you must set its status to Dismissed. Follow these steps to do so: +To dismiss a vulnerability, you must set its status to Dismissed. This dismisses the vulnerability +for the entire project. Follow these steps to do so: 1. Select the vulnerability in the Security Dashboard. 1. Select **Dismissed** from the **Status** selector menu at the top-right. @@ -181,7 +183,7 @@ vulnerability's status to Dismissed, a text box appears for you to add a comment dismissal. Once added, you can edit or delete it. This allows you to add and update context for a vulnerability as you learn more over time. - + #### Dismissing multiple vulnerabilities @@ -196,22 +198,6 @@ Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabili  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by selecting the **Create issue** -button from within the vulnerability modal, or by using the action buttons to the right of -a vulnerability row in the group security dashboard. - -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. - - - ### Solutions for vulnerabilities (auto-remediation) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. @@ -246,10 +232,29 @@ vulnerability. Any vulnerability that has a [solution](#solutions-for-vulnerabilities-auto-remediation) can have a merge request created to automatically solve the issue. -If this action is available, the vulnerability modal contains a **Create merge request** button. +If this action is available, the vulnerability page or modal contains a **Create merge request** button. Click this button to create a merge request to apply the solution onto the source branch. - + + +### 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 @@ -307,15 +312,29 @@ rating. ### Enabling Security Approvals within a project -To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#adding--editing-a-default-approval-rule) -must be created with the case-sensitive name `Vulnerability-Check`. This approval group must be set -with the number of approvals required greater than zero. You must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) to manage approval rules. +To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#adding--editing-a-default-approval-rule) +must be created. A [security scanner job](#security-scanning-tools) must be enabled for +`Vulnerability-Check`, and a [license scanning](../compliance/license_compliance/index.md#configuration) +job must be enabled for `License-Check`. When the proper jobs aren't configured, the following +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. + + + +For this approval group, you must set the number of approvals required to greater than zero. You +must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) +to manage approval rules. + +Follow these steps to enable `Vulnerability-Check`: 1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -1. Click **Add approval rule**, or **Edit**. - - Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). +1. Click **Enable**, or **Edit**. +1. Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). - + Once this group is added to your project, the approval rule is enabled for all merge requests. @@ -332,32 +351,14 @@ An approval is optional when the security report: - Contains no new vulnerabilities when compared to the target branch. - Contains only new vulnerabilities of `low` or `medium` severity. -## Enabling License Approvals within a project +### Enabling License Approvals within a project > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -`License-Check` is an approval rule you can enable to allow an individual or group to approve a -merge request that contains a `denied` license. - -You can enable `License-Check` one of two ways: - -- Create a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) - with the case-sensitive name `License-Check`. -- Create an approval group in the [project policies section for License Compliance](../compliance/license_compliance/index.md#policies). - You must set this approval group's number of approvals required to greater than zero. Once you - enable this group in your project, the approval rule is enabled for all merge requests. - -Any code changes cause the approvals required to reset. - -An approval is required when a license report: - -- Contains a dependency that includes a software license that is `denied`. -- Is not generated during pipeline execution. - -An approval is optional when a license report: - -- Contains no software license violations. -- Contains only new licenses that are `allowed` or unknown. +`License-Check` is a [security approval rule](#enabling-security-approvals-within-a-project) +you can enable to allow an individual or group to approve a merge request that contains a `denied` +license. For instructions on enabling this rule, see +[Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). ## Working in an offline environment diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index a5cf93f9448..3a7c0148388 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -64,10 +64,10 @@ Once a vulnerability is found, you can interact with it. Read more on how to Please note that in some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. -### Suggested Solutions for vulnerabilities +### Automatic remediation for vulnerabilities -The [suggested solutions](../index.md#solutions-for-vulnerabilities-auto-remediation) feature -(auto-remediation) is available for Dependency Scanning and Container Scanning, but may not work +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 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. @@ -96,7 +96,7 @@ above. You can find more information at each of the pages below: To use many GitLab features, including [security scans](../index.md#working-in-an-offline-environment) -and [Auto DevOps](../../../topics/autodevops/index.md), the GitLab Runner must be able to fetch the +and [Auto DevOps](../../../topics/autodevops/index.md), the runner must be able to fetch the relevant Docker images. The process for making these images available without direct access to the public internet @@ -124,7 +124,7 @@ The pipeline downloads the Docker images needed for the Security Scanners and sa [job artifacts](../../../ci/pipelines/job_artifacts.md) or pushes them to the [Container Registry](../../packages/container_registry/index.md) of the project where the pipeline is executed. These archives can be transferred to another location and [loaded](https://docs.docker.com/engine/reference/commandline/load/) in a Docker daemon. -This method requires a GitLab Runner with access to both `gitlab.com` (including +This method requires a runner with access to both `gitlab.com` (including `registry.gitlab.com`) and the local offline instance. This runner must run in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) to be able to use the `docker` command inside the jobs. This runner can be installed in a DMZ or on diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 214044ad783..727f077aa09 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -28,7 +28,6 @@ SAST supports the following official analyzers: - [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) (NodeJsScan) - [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit) - [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only)) -- [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) (Secrets (Gitleaks & TruffleHog secret detectors)) - [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) - [`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)) @@ -97,32 +96,7 @@ That's needed when one totally relies on [custom analyzers](#custom-analyzers). ## Custom Analyzers -### Custom analyzers with Docker-in-Docker - -When Docker-in-Docker for SAST is enabled, -you can provide your own analyzers as a comma-separated list of Docker images. -Here's how to add `analyzers/csharp` and `analyzers/perl` to the default images: -In `.gitlab-ci.yml` define: - -```yaml -include: - - template: SAST.gitlab-ci.yml - -variables: - SAST_ANALYZER_IMAGES: "my-docker-registry/analyzers/csharp,amy-docker-registry/analyzers/perl" -``` - -The values must be the full path to the container registry images, -like what you would feed to the `docker pull` command. - -NOTE: **Note:** -This configuration doesn't benefit from the integrated detection step. -SAST has to fetch and spawn each Docker image to establish whether the -custom analyzer can scan the source code. - -### Custom analyzers without Docker-in-Docker - -When Docker-in-Docker for SAST is disabled, you can provide your own analyzers by +You can provide your own analyzers by defining CI jobs in your CI configuration. For consistency, you should suffix your custom SAST jobs with `-sast`. Here's how to add a scanning job that's based on the Docker image `my-docker-registry/analyzers/csharp` and generates a SAST report @@ -146,7 +120,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | | --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | -| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | +| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | | Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | | File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -159,7 +133,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | +| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | | Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fd331020719..a4fc3c9e638 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -43,29 +43,28 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j ## Requirements -To run SAST jobs, by default, you need a GitLab Runner with the +To run SAST jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -If you're using the shared Runners on GitLab.com, this is enabled by default. - -Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for SAST](#enabling-docker-in-docker-ultimate). +If you're using the shared runners on GitLab.com, this is enabled by default. CAUTION: **Caution:** Our SAST jobs require a Linux container type. Windows containers are not yet supported. CAUTION: **Caution:** -If you use your own Runners, make sure the Docker version installed +If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks -The following table shows which languages, package managers and frameworks are supported and which tools are used. +GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. + +You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). | Language (package managers) / framework | Scan tool | Introduced in GitLab Version | |--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11., [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | @@ -94,9 +93,6 @@ All open source (OSS) analyzers have been moved to the GitLab Core tier. Progres tracked in the corresponding [epic](https://gitlab.com/groups/gitlab-org/-/epics/2098). -Please note that support for [Docker-in-Docker](#enabling-docker-in-docker-ultimate) -will not be extended to the GitLab Core tier. - #### Summary of features per tier Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), @@ -108,8 +104,9 @@ as shown in the following table: | [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}** | -| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities-ultimate) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](#security-dashboard-ultimate) | **{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}** | ## Contribute your scanner @@ -119,7 +116,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To configure SAST for a project you can: -- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) provided by +- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast) provided by [Auto DevOps](../../../topics/autodevops/index.md). - [Configure SAST manually](#configure-sast-manually). - [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). @@ -135,30 +132,31 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml ``` The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast-ultimate) +[SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. -### Configure SAST in the UI +### Configure SAST in the UI **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab Ultimate 13.4. -For a project that does not have a `.gitlab-ci.yml` file, you can enable SAST with a basic -configuration using the **SAST Configuration** page: +You can enable and configure SAST with a basic configuration using the **SAST Configuration** +page: -1. From the project's home page, go to **Security & Configuration** > **Configuration** in the +1. From the project's home page, go to **Security & Compliance** > **Configuration** in the left sidebar. -1. Click **Enable via Merge Request** on the Static Application Security Testing (SAST) row. -1. Enter the appropriate SAST details into the fields on the page. See [Available variables](#available-variables) - for a description of these variables. -1. Click **Create Merge Request**. +1. If the project does not have a `gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. +1. Enter the custom SAST values, then click **Create Merge Request**. + + 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. Review and merge the merge request. ### Customizing the SAST settings @@ -215,25 +213,6 @@ 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 Docker-in-Docker **(ULTIMATE)** - -If needed, you can enable Docker-in-Docker to restore the SAST behavior that existed prior to GitLab -13.0. Follow these steps to do so: - -1. Configure a GitLab Runner with Docker-in-Docker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). -1. Set the variable `SAST_DISABLE_DIND` set to `false`: - - ```yaml - include: - - template: SAST.gitlab-ci.yml - - variables: - SAST_DISABLE_DIND: "false" - ``` - -This creates a single `sast` job in your CI/CD pipeline instead of multiple `<analyzer-name>-sast` -jobs. - #### Enabling Kubesec analyzer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab Ultimate 12.6. @@ -265,8 +244,8 @@ analyzer and compilation will be skipped: image: maven:3.6-jdk-8-alpine stages: - - build - - test + - build + - test include: - template: SAST.gitlab-ci.yml @@ -327,7 +306,6 @@ The following are Docker image-related variables. | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | | `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker-ultimate). This variable is `true` by default. | #### Vulnerability filters @@ -340,23 +318,7 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | | `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | -| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | | `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | -| `SAST_GITLEAKS_COMMIT_FROM` | | The commit a Gitleaks scan starts at. | -| `SAST_GITLEAKS_COMMIT_TO` | | The commit a Gitleaks scan ends at. | -| `SAST_GITLEAKS_HISTORIC_SCAN` | `false` | Flag to enable a historic Gitleaks scan. | - -#### Docker-in-Docker orchestrator - -The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker-ultimate). - -| Environment variable | Default value | Description | -|------------------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_ANALYZER_IMAGES` | | Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | -| `SAST_PULL_ANALYZER_IMAGES` | 1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | -| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | #### Analyzer settings @@ -514,15 +476,14 @@ run successfully. For more information, see [Offline environments](../offline_de To use SAST in an offline environment, you need: -- To keep Docker-In-Docker disabled (default). -- A GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Configure certificate checking of packages (optional). NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. @@ -543,7 +504,6 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/kubesec:2 registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2 registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2 registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:2 registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2 registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2 registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2 @@ -563,13 +523,13 @@ For details on saving and transporting Docker images as a file, see Docker's doc Add the following configuration to your `.gitlab-ci.yml` file. You must replace `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: - ```yaml +```yaml include: - template: SAST.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" - ``` +``` The SAST job should now use local copies of the SAST analyzers to scan your code and generate security reports without requiring internet access. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 7daf2f3308b..f3e411cdc16 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -37,13 +37,13 @@ GitLab displays identified secrets visibly in a few places: To run Secret Detection jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -If you're using the shared Runners on GitLab.com, this is enabled by default. +If you're using the shared runners on GitLab.com, this is enabled by default. CAUTION: **Caution:** Our Secret Detection jobs currently expect a Linux container type. Windows containers are not yet supported. CAUTION: **Caution:** -If you use your own Runners, make sure the Docker version installed +If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ### Making Secret Detection available to all GitLab tiers @@ -83,7 +83,7 @@ variable. For example, `https://username:$password@example.com/path/to/repo` won detected, whereas `https://username:password@example.com/path/to/repo` would be detected. NOTE: **Note:** -You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection-ultimate) +You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) provided by [Auto DevOps](../../../topics/autodevops/index.md). To enable Secret Detection for GitLab 13.1 and later, you must include the `Secret-Detection.gitlab-ci.yml` template that’s provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined in that template. @@ -99,7 +99,7 @@ The included template creates Secret Detection jobs in your CI/CD pipeline and s your project's source code for secrets. The results are saved as a -[Secret Detection report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssecret_detection-ultimate) +[Secret Detection report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssecret_detection) that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png Binary files differdeleted file mode 100644 index 7b9a48b8738..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png Binary files differnew file mode 100644 index 00000000000..67a7bb5f368 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png Binary files differnew file mode 100644 index 00000000000..3c618090be8 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_0.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_0.png Binary files differdeleted file mode 100644 index 77e75551bd9..00000000000 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png Binary files differnew file mode 100644 index 00000000000..9ade24be16f --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png Binary files differnew file mode 100644 index 00000000000..d010adcc90c --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png Binary files differdeleted file mode 100644 index 75b5ad1d885..00000000000 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png Binary files differdeleted file mode 100644 index 591a08f4d7a..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png Binary files differnew file mode 100644 index 00000000000..c89179e739d --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif b/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif Binary files differdeleted file mode 100644 index 29e7168b6ea..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png Binary files differnew file mode 100644 index 00000000000..34c64f830ba --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png Binary files differdeleted file mode 100644 index 2b792727a99..00000000000 --- a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png Binary files differnew file mode 100644 index 00000000000..eb91cfc47ad --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b8fcc513cb1..51d9b4f45cd 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -35,7 +35,7 @@ To use the instance, group, project, or pipeline security dashboard: the [supported reports](#supported-reports). 1. The configured jobs must use the [new `reports` syntax](../../../ci/pipelines/job_artifacts.md#artifactsreports). 1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. - If you're using the shared Runners on GitLab.com, this is already the case. + If you're using the shared runners on GitLab.com, this is already the case. ## Pipeline Security @@ -43,13 +43,11 @@ To use the instance, group, project, or pipeline security dashboard: At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against. - + Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. - - NOTE: **Note:** A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. @@ -63,11 +61,13 @@ to **Security & Compliance > Security Dashboard**. By default, the Security Dash detected and confirmed vulnerabilities. The Security Dashboard first displays the total number of vulnerabilities by severity (for example, -Critical, High, Medium, Low). Below this, a table displays each vulnerability's status, severity, +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: + + +You can filter the vulnerabilities by one or more of the following: - Status - Severity @@ -122,24 +122,28 @@ branches of all the projects you configure to display on the dashboard. It inclu [group Security Dashboard's](#group-security-dashboard) features. + + You can access the Instance Security Dashboard from the menu bar at the top of the page. Under **More**, select **Security**.  +The dashboard is empty before you add projects to it. + + + ### Adding projects to the dashboard To add projects to the dashboard: -1. Click the **Edit dashboard** button on the Instance Security Dashboard page. +1. Click **Settings** in the left navigation bar or click the **Add projects** button. 1. Search for and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -Once added, the Security Dashboard displays the vulnerabilities found in your chosen projects' +After you add projects, the Security Dashboard displays the vulnerabilities found in those projects' default branches. - - ## Export vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. @@ -150,6 +154,8 @@ is built, the CSV report downloads to your local machine. The report contains al vulnerabilities for the projects defined in the **Security Dashboard**, as filters don't apply to the export function. + + NOTE: **Note:** It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Do not close the page until the download finishes. @@ -190,7 +196,7 @@ to configure daily security scans. Each dashboard's vulnerability list contains vulnerabilities from the latest scans that were merged into the default branch. - + You can filter which vulnerabilities the Security Dashboard displays by: @@ -208,7 +214,7 @@ To create an issue associated with the vulnerability, click the **Create Issue** Once you create the issue, the vulnerability list contains a link to the issue and an icon whose color indicates the issue's status (green for open issues, blue for closed issues). - + <!-- ## Troubleshooting diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md new file mode 100644 index 00000000000..8006a49ba35 --- /dev/null +++ b/doc/user/application_security/terminology/index.md @@ -0,0 +1,171 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: reference +--- + +# Secure and Defend terminology + +This terminology list for GitLab Secure and Defend aims to: + +- Promote a ubiquitous language for discussing application security. +- Improve the effectiveness of communication regarding GitLab's application security features. +- Get new contributors up to speed faster. + +NOTE: **Note:** +This document defines application security terms in the specific context of GitLab's Secure and +Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend. + +## Terms + +### Analyzer + +Software that performs a scan. The scan analyzes an attack surface for vulnerabilities and produces +a report containing findings. Reports adhere to the [Secure report format](#secure-report-format). + +Analyzers integrate into GitLab using a CI job. The report produced by the analyzer is published as +an artifact once the job is complete. GitLab ingests this report, allowing users to visualize and +manage found vulnerabilities. For more information, see [Security Scanner Integration](../../../development/integrations/secure.md). + +Many GitLab analyzers follow a standard approach using Docker to run a wrapped scanner. For example, +the Docker image `bandit-sast` is an analyzer that wraps the scanner `Bandit`. You can optionally +use the [Common library](https://gitlab.com/gitlab-org/security-products/analyzers/common) +to assist in building an Analyzer. + +### Attack surface + +The different places in an application that are vulnerable to attack. Secure products discover and +search the attack surface during scans. Each product defines the attack surface differently. For +example, SAST uses files and line numbers, and DAST uses URLs. + +### CVE + +Common Vulnerabilities and Exposures (CVE®) is a list of common identifiers for publicly known +cybersecurity vulnerabilities. The list is managed by the [Mitre Corporation](https://cve.mitre.org/). + +### CVSS + +The Common Vulnerability Scoring System (CVSS) is a free and open industry standard for assessing +the severity of computer system security vulnerabilities. + +### CWE + +Common Weakness Enumeration (CWE™) is a community-developed list of common software and hardware +weakness types that have security ramifications. Weaknesses are flaws, faults, bugs, +vulnerabilities, or other errors in software or hardware implementation, code, design, or +architecture. If left unaddressed, weaknesses could result in systems, networks, or hardware being +vulnerable to attack. The CWE List and associated classification taxonomy serve as a language that +you can use to identify and describe these weaknesses in terms of CWEs. + +### Duplicate finding + +A legitimate finding that is reported multiple times. This can occur when different scanners +discover the same finding, or when a single scan inadvertently reports the same finding more than +once. + +### False positive + +A finding that doesn't exist but is incorrectly reported as existing. + +### Feedback + +Feedback the user provides about a finding. Types of feedback include dismissal, creating an issue, +or creating a merge request. + +### Finding + +An asset that has the potential to be vulnerable, identified within a project by an analyzer. Assets +include but are not restricted to source code, binary packages, containers, dependencies, networks, +applications, and infrastructure. + +### Insignificant finding + +A legitimate finding that a particular customer doesn't care about. + +### Location fingerprint + +A finding's location fingerprint is a text value that's unique for each location on the attack +surface. Each Secure product defines this according to its type of attack surface. For example, SAST +incorporates file path and line number. + +### Pipeline Security tab + +A page that displays findings discovered in the associated CI pipeline. + +### Primary identifier + +A finding's primary identifier is a value unique to that finding. The external type and external ID +of the finding's [first identifier](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/v2.4.0-rc1/dist/sast-report-format.json#L228) +combine to create the value. + +Examples of primary identifiers include ZAP's `PluginID`, or `CVE` for Klar. Note that the +identifier must be stable. Subsequent scans must return the same value for the same finding, even if +the location has slightly changed. + +### Report finding + +A [finding](#finding) that only exists in a report produced by an analyzer, and is yet to be +persisted to the database. The report finding becomes a [vulnerability finding](#vulnerability-finding) +once it's imported into the database. + +### Scan type (report type) + +The type of scan. This must be one of the following: + +- `container_scanning` +- `dependency_scanning` +- `dast` +- `sast` + +### Scanner + +Software that can scan for vulnerabilities. The resulting scan report is typically not in the +[Secure report format](#secure-report-format). Examples include ESLint, Klar, and ZAP. + +### Secure product + +A group of features related to a specific area of application security with first-class support by +GitLab. Products include Container Scanning, Dependency Scanning, Dynamic Application Security +Testing (DAST), Secret Detection, Static Application Security Testing (SAST), and Fuzz Testing. Each +of these products typically include one or more analyzers. + +### Secure report format + +A standard report format that Secure products comply with when creating JSON reports. The format is described by a +[JSON schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas). + +### Security Dashboard + +Provides an overview of all the vulnerabilities for a project, group, or GitLab instance. +Vulnerabilities are only created from findings discovered on the project's default branch. + +### Vendor + +The party maintaining an analyzer. As such, a vendor is responsible for integrating a scanner into +GitLab and keeping it compatible as they evolve. A vendor isn't necessarily the author or maintainer +of the scanner, as in the case of using an open core or OSS project as a base solution of an +offering. For scanners included as part of a GitLab distribution or GitLab subscription, the vendor +is listed as GitLab. + +### Vulnerability + +A flaw that has a negative impact on the security of its environment. Vulnerabilities describe the +error or weakness, and don't describe where the error is located (see [finding](#finding)). +Each vulnerability maps to a unique finding. + +### Vulnerability finding + +When a [report finding](#report-finding) is stored to the database, it becomes a vulnerability +[finding](#finding). + +### Vulnerability tracking + +Deals with the responsibility of matching findings across scans so that a finding's life cycle can +be understood. Engineers and security teams use this information to decide whether to merge code +changes, and to see unresolved findings and when they were introduced. Vulnerabilities are tracked +by comparing the location fingerprint, primary identifier, and report type. + +### Vulnerability occurrence + +Deprecated, see [finding](#finding). diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index c916cdbfe7c..5414800b290 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -66,7 +66,7 @@ global: enabled: true metrics: enabled: - - 'flow:sourceContext=namespace;destinationContext=namespace' + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` The **Container Network Policy** section displays the following information @@ -88,8 +88,9 @@ investigate it for potential threats by The **Threat Monitoring** page's **Policy** tab displays deployed network policies for all available environments. You can check a -network policy's `yaml` manifest and toggle the policy's enforcement -status. This section has the following prerequisites: +network policy's `yaml` manifest, toggle the policy's enforcement +status, and create and edit deployed policies. This section has the +following prerequisites: - Your project contains at least one [environment](../../../ci/environments/index.md) - You've [installed Cilium](../../clusters/applications.md#install-cilium-using-gitlab-cicd) @@ -124,3 +125,47 @@ Disabled network policies have the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect any pods. The policy itself is still deployed to the corresponding deployment namespace. + +### Container Network Policy editor + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +The policy editor allows you to create, edit, and delete policies. To +create a new policy click the **New policy** button located in the +**Policy** tab's header. To edit an existing policy, click**Edit +policy** in the selected policy drawer. + +NOTE: **Note:** +The policy editor only supports the +[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular +Kubernetes +[NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) +resources aren't supported. + +The policy editor has two modes: + +- The visual _Rule_ mode allows you to construct and preview policy + rules using rule blocks and related controls. +- YAML mode allows you to enter a policy definition in `.yaml` format + and is aimed at expert users and cases that the Rule mode doesn't + support. + +You can use both modes interchangeably and switch between them at any +time. If a YAML resource is incorrect, Rule mode is automatically +disabled. You must use YAML mode to fix your policy before Rule mode +is available again. + +Rule mode supports the following rule types: + +- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). +- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). +- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only + the `toCIDR` block without `except` is supported. +- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). +- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) + can be added to all other rules. + +Once your policy is complete, save it by pressing the **Save policy** +button at the bottom of the editor. Existing policies can also be +removed from the editor interface by clicking the **Delete policy** +button at the bottom of the editor. diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png Binary files differdeleted file mode 100644 index 30a7195e1ab..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ffec4bf336d..ff383fdf553 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -9,10 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -Each security vulnerability in the [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has its own standalone -page. +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. +- The status of the vulnerability within the project. +- Available actions for the vulnerability. On the vulnerability page, you can interact with the vulnerability in several different ways: @@ -22,7 +23,7 @@ several different ways: - [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](#automatic-remediation-solutions-for-vulnerabilities) - For some vulnerabilities, +- [Solution](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, a solution is provided for how to fix the vulnerability. ## Changing vulnerability status @@ -46,28 +47,7 @@ project the vulnerability came from, and pre-populates it with useful informatio 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. -## Automatic remediation solutions for vulnerabilities +## Automatic remediation for vulnerabilities You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. GitLab supports the following scanners: - -- [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 will show "Resolve with merge request": - - - -Selecting the button will create a merge request with the automatic solution. - -### Manually applying a suggested patch - -To manually apply the patch that was generated by GitLab for a vulnerability, select the dropdown arrow on the "Resolve -with merge request" button, then select the "Download patch to resolve" option: - - - -This will change the button text to "Download patch to resolve". Click on it to download the patch: - - +generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#solutions-for-vulnerabilities-auto-remediation). |
