diff options
Diffstat (limited to 'doc/user/application_security')
22 files changed, 1290 insertions, 413 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 5413c28912a..ed94686b7a3 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -91,20 +91,25 @@ The API fuzzing configuration form helps you create or modify your project's API configuration. The form lets you choose values for the most common API fuzzing options and builds a YAML snippet that you can paste in your GitLab CI/CD configuration. -#### Configure Web API fuzzing with the configuration form +#### Configure Web API fuzzing in the UI To generate an API Fuzzing configuration snippet: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. -1. In the **API Fuzzing** row, select **Configure**. -1. Complete the form as needed. Read below for more information on available configuration options. +1. In the **API Fuzzing** row, select **Enable API Fuzzing**. +1. Complete the fields. For details see [Available CI/CD variables](#available-cicd-variables). 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you've selected in the form. -1. Choose one of the following actions: - 1. To copy the snippet to your clipboard and be redirected to your project's `.gitlab-ci.yml` file, - where you can paste the YAML configuration, select **Copy code and open `.gitlab-ci.yml` file**. - 1. To copy the snippet to your clipboard and close the modal, select **Copy code only**. +1. Do one of the following: + 1. To copy the snippet to your clipboard, select **Copy code only**. + 1. To add the snippet to your project's `.gitlab-ci.yml` file, select + **Copy code and open `.gitlab-ci.yml` file**. The Pipeline Editor opens. + 1. Paste the snippet into the `.gitlab-ci.yml` file. + 1. Select the **Lint** tab to confirm the edited `.gitlab-ci.yml` file is valid. + 1. Select the **Edit** tab, then select **Commit changes**. + +When the snippet is committed to the `.gitlab-ci.yml` file, pipelines include an API Fuzzing job. ### OpenAPI Specification @@ -112,6 +117,7 @@ To generate an API Fuzzing configuration snippet: > - Support for OpenAPI Specification using YAML format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. > - Support for OpenAPI Specification v3.1 was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.2. > - Support to generate media type `application/xml` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.8. +> - Support to select media types was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. 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 using an OpenAPI Specification to provide information about the target API to test. @@ -125,6 +131,25 @@ the body generation is limited to these body types: - `application/json` - `application/xml` +### OpenAPI and media types + +A media type (formerly known as MIME type) is an identifier for file formats and format contents transmitted. A OpenAPI document lets you specify that a given operation can accept different media types, hence a given request can send data using different file content. As for example, a `PUT /user` operation to update user data could accept data in either XML (media type `application/xml`) or JSON (media type `application/json`) format. +OpenAPI 2.x lets you specify the accepted media types globally or per operation, and OpenAPI 3.x lets you specify the accepted media types per operation. API Fuzzing checks the listed media types and tries to produce sample data for each supported media type. + +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), the default behavior is to select one of the supported media types to use. The first supported media type is chosen from the list. This behavior is configurable. +- In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, `application/json` and `application/xml`), tests are performed using JSON, and then the same tests using XML. + +Testing the same operation (for example, `POST /user`) using different media types (for example, `application/json` and `application/xml`) is not always desirable. +For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. + +The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing will try to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type. + +Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. + +Multiple media types in `FUZZAPI_OPENAPI_MEDIA_TYPES` must separated by a colon (`:`). For example, to limit request generation to the media types `application/x-www-form-urlencoded` and `multipart/form-data`, set the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` to `application/x-www-form-urlencoded:multipart/form-data`. Only supported media types in this list are included when creating requests, though unsupported media types are always skipped. A media type text may contain different sections. For example, `application/vnd.api+json; charset=UTF-8` is a compound of `type "/" [tree "."] subtype ["+" suffix]* [";" parameter]`. Parameters are not taken into account when filtering media types on request generation. + +The environment variables `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` and `FUZZAPI_OPENAPI_MEDIA_TYPES` allow you to decide how to handle media types. These settings are mutually exclusive. If both are enabled, API Fuzzing reports an error. + #### Configure Web API fuzzing with an OpenAPI Specification To configure API fuzzing in GitLab with an OpenAPI Specification: @@ -345,8 +370,8 @@ By default, the API fuzzer uses the Postman file to resolve Postman variable val is set in a GitLab CI/CD variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`, then the JSON file takes precedence to get Postman variable values. -Although Postman can export environment variables into a JSON file, the format is not compatible -with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. +WARNING: +Although Postman can export environment variables into a JSON file, the format is not compatible with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: @@ -561,13 +586,19 @@ profile increases as the number of tests increases. | CI/CD variable | Description | |-------------------------------------------------------------|-------------| | `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | -| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `1`. | +| `FUZZAPI_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | | `FUZZAPI_TARGET_URL` | Base URL of API testing target. | | `FUZZAPI_CONFIG` | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/276395) in GitLab 13.12, replaced with default `.gitlab/gitlab-api-fuzzing-config.yml`. API Fuzzing configuration file. | |[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | |[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | +|[`FUZZAPI_EXCLUDE_URLS`](#exclude-urls) | Exclude API URL from testing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. | +|[`FUZZAPI_EXCLUDE_PARAMETER_ENV`](#exclude-parameters) | JSON string containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | +|[`FUZZAPI_EXCLUDE_PARAMETER_FILE`](#exclude-parameters) | Path to a JSON file containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | |[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`FUZZAPI_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | +|[`FUZZAPI_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. | @@ -891,7 +922,7 @@ def get_auth_response(): # In our example, access token is retrieved from a given endpoint try: - # Performs a http request, response sample: + # Performs a http request, response sample: # { "Token" : "b5638ae7-6e77-4585-b035-7d9de2e3f6b3" } response = get_auth_response() @@ -921,7 +952,7 @@ except Exception as e: logging.error(f'Error, unknown error while retrieving access token. Error message: {e}') raise -# computes object that holds overrides file content. +# computes object that holds overrides file content. # It uses data fetched from request overrides_data = { "headers": { @@ -1036,6 +1067,294 @@ variables: FUZZAPI_EXCLUDE_PATHS=/auth*;/v1/* ``` +### Exclude parameters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. + +While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters you can use one of the following variables: `FUZZAPI_EXCLUDE_PARAMETER_ENV` or `FUZZAPI_EXCLUDE_PARAMETER_FILE`. + +The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre script using `FUZZAPI_PRE_SCRIPT`. + +#### Exclude parameters using a JSON document + +The JSON document contains a JSON object which uses specific properties to identify which parameter should be excluded. +You can provide the following properties to exclude specific parameters during the scanning process: + +- `headers`: Use this property to exclude specific headers. The property's value is an array of header names to be excluded. Names are case-insensitive. +- `cookies`: Use this property's value to exclude specific cookies. The property's value is an array of cookie names to be excluded. Names are case-sensitive. +- `query`: Use this property to exclude specific fields from the query string. The property's value is an array of field names from the query string to be excluded. Names are case-sensitive. +- `body-form`: Use this property to exclude specific fields from a request that uses the media type `application/x-www-form-urlencoded`. The property's value is an array of the field names from the body to be excluded. Names are case-sensitive. +- `body-json`: Use this property to exclude specific JSON nodes from a request that uses the media type `application/json`. The property's value is an array, each entry of the array is a [JSON Path](https://goessner.net/articles/JsonPath/) expression. +- `body-xml`: Use this property to exclude specific XML nodes from a request that uses media type `application/xml`. The property's value is an array, each entry of the array is a [XPath v2](https://www.w3.org/TR/xpath20/) expression. + +The following JSON document is an example of the expected structure to exclude parameters. + +```json +{ + "headers": [ + "header1", + "header2" + ], + "cookies": [ + "cookie1", + "cookie2" + ], + "query": [ + "query-string1", + "query-string2" + ], + "body-form": [ + "form-param1", + "form-param2" + ], + "body-json": [ + "json-path-expression-1", + "json-path-expression-2" + ], + "body-xml" : [ + "xpath-expression-1", + "xpath-expression-2" + ] +} +``` + +#### Examples + +##### Excluding a single header + +To exclude the header `Upgrade-Insecure-Requests`, set the `header` property's value to an array with the header name: `[ "Upgrade-Insecure-Requests" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Upgrade-Insecure-Requests" ] +} +``` + +Header names are case-insensitive, thus the header name `UPGRADE-INSECURE-REQUESTS` is equivalent to `Upgrade-Insecure-Requests`. + +##### Excluding both a header and two cookies + +To exclude the header `Authorization` and the cookies `PHPSESSID` and `csrftoken`, set the `headers` property's value to an array with header name `[ "Authorization" ]` and the `cookies` property's value to an array with the cookies' names `[ "PHPSESSID", "csrftoken" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Authorization" ], + "cookies": [ "PHPSESSID", "csrftoken" ] +} +``` + +##### Excluding a `body-form` parameter + +To exclude the `password` field in a request that uses `application/x-www-form-urlencoded`, set the `body-form` property's value to an array with the field name `[ "password" ]`. For instance, the JSON document looks like this: + +```json +{ + "body-form": [ "password" ] +} +``` + +The exclude parameters uses `body-form` when the request uses a content type `application/x-www-form-urlencoded`. + +##### Excluding a specific JSON nodes using JSON Path + +To exclude the `schema` property in the root object, set the `body-json` property's value to an array with the JSON Path expression `[ "$.schema" ]`. + +The JSON Path expression uses special syntax to identify JSON nodes: `$` refers to the root of the JSON document, `.` refers to the current object (in our case the root object), and the text `schema` refers to a property name. Thus, the JSON path expression `$.schema` refers to a property `schema` in the root object. +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.schema" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path, characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding multiple JSON nodes using JSON Path + +To exclude the property `password` on each entry of an array of `users` at the root level, set the `body-json` property's value to an array with the JSON Path expression `[ "$.users[*].paswword" ]`. + +The JSON Path expression starts with `$` to refer to the root node and uses `.` to refer to the current node. Then, it uses `users` to refer to a property and the characters `[` and `]` to enclose the index in the array you want to use, instead of providing a number as an index you use `*` to specify any index. After the index reference, we find `.` which now refers to any given selected index in the array, preceded by a property name `password`. + +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.users[*].paswword" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding an XML attribute + +To exclude an attribute named `isEnabled` located in the root element `credentials`, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/@isEnabled" ]`. + +The XPath expression `/credentials/@isEnabled`, starts with `/` to indicate the root of the XML document, then it is followed by the word `credentials` which indicates the name of the element to match. It uses a `/` to refer to a node of the previous XML element, and the character `@` to indicate that the name `isEnable` is an attribute. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/@isEnabled" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be an [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions, characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML element's text + +To exclude the text of the `username` element contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username/text()" ]`. + +In the XPath expression `/credentials/username/text()`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. Last part has a `/` that refers to the current element, and uses a XPath function called `text()` which identifies the text of the current element. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username/text()" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML element + +To exclude the element `username` contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username" ]`. + +In the XPath expression `/credentials/username`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML node with namespaces + +To exclude a XML element `login` which is defined in namespace `s`, and contained in `credentials` root node, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/s:login" ]`. + +In the XPath expression `/credentials/s:login`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `s:login`. Notice that name contains the character `:`, this character separates the namespace from the node name. + +The namespace name should have been defined in the XML document which is part of the body request. You may check the namespace in the specification document HAR, OpenAPI, or Postman Collection file. + +```json +{ + "body-xml": [ + "/credentials/s:login" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +#### Using a JSON string + +To provide the exclusion JSON document set the variable `FUZZAPI_EXCLUDE_PARAMETER_ENV` with the JSON string. In the following example, the `.gitlab-ci.yml`, the `FUZZAPI_EXCLUDE_PARAMETER_ENV` variable is set to a JSON string: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_EXCLUDE_PARAMETER_ENV: '{ "headers": [ "Upgrade-Insecure-Requests" ] }' +``` + +#### Using a file + +To provide the exclusion JSON document, set the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE` with the JSON file path. The file path is relative to the job current working directory. In the following example `.gitlab-ci.yml` file, the `FUZZAPI_EXCLUDE_PARAMETER_FILE` variable is set to a JSON file path: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_EXCLUDE_PARAMETER_FILE: api-fuzzing-exclude-parameters.json +``` + +The `api-fuzzing-exclude-parameters.json` is a JSON document that follows the structure of [exclude parameters document](#exclude-parameters-using-a-json-document). + +### Exclude URLS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. + +As an alternative to excluding by paths, you can filter by any other component in the URL by using the `FUZZAPI_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry such as `.*` excludes all URLs because it is a regular expression that matches everything. + +In your job output you can check if any URLs matched any provided regular expression from `FUZZAPI_EXCLUDE_URLS`. Matching operations are listed in the **Excluded Operations** section. Operations listed in the **Excluded Operations** should not be listed in the **Tested Operations** section. For example the following portion of a job output: + +```plaintext +2021-05-27 21:51:08 [INF] API Security: --[ Tested Operations ]------------------------- +2021-05-27 21:51:08 [INF] API Security: 201 POST http://target:7777/api/users CREATED +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +2021-05-27 21:51:08 [INF] API Security: --[ Excluded Operations ]----------------------- +2021-05-27 21:51:08 [INF] API Security: GET http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: POST http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +``` + +NOTE: +Each value in `FUZZAPI_EXCLUDE_URLS` is a regular expression. Characters such as `.` , `*` and `$` among many others have special meanings in [regular expressions](https://en.wikipedia.org/wiki/Regular_expression#Standards). + +#### Examples + +##### Excluding a URL and child resources + +The following example excludes the URL `http://target/api/auth` and its child resources. + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: http://target/api/auth +``` + +##### Excluding two URLs and allow their child resources + +To exclude the URLs `http://target/api/buy` and `http://target/api/sell` but allowing to scan their child resources, for instance: `http://target/api/buy/toy` or `http://target/api/sell/chair`. You could use the value `http://target/api/buy/$,http://target/api/sell/$`. This value is using two regular expressions, each of them separated by a `,` character. Hence, it contains `http://target/api/buy$` and `http://target/api/sell$`. In each regular expression, the trailing `$` character points out where the matching URL should end. + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$ +``` + +##### Excluding two URLs and their child resources + +In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell +``` + +##### Excluding URL using regular expressions + +In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: https://target/api/v.*/user/create$ +``` + ### Header Fuzzing Header fuzzing is disabled by default due to the high number of false positives that occur with many @@ -1495,6 +1814,19 @@ API Security can still try to consume an OpenAPI document that does not fully co FUZZAPI_OPENAPI_RELAXED_VALIDATION: On ``` +### No operation in the OpenAPI document is consuming any supported media type + +API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. + +**Error message** + +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), `Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.` + +**Solution** + +1. Review the supported media types in the [OpenAPI Specification](#openapi-specification) section. +1. Edit your OpenAPI document, allowing at least a given operation to accept any of the supported media types. Alternatively, a supported media type could be set in the OpenAPI document level and get applied to all operations. This step may require changes in your application to ensure the supported media type is accepted by the application. + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index f2d6cef669d..64566e458ee 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -186,7 +186,7 @@ The `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` CI/CD variable controls whether the findings related to programming languages. The languages supported depend on the [scanner used](#change-scanners): -- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/language/). +- [Trivy](https://aquasecurity.github.io/trivy/latest/docs/vulnerability/detection/language/). - [Grype](https://github.com/anchore/grype#features). By default, the report only includes packages managed by the Operating System (OS) package manager @@ -222,6 +222,7 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | +| `CS_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | | `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | | `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | @@ -236,22 +237,29 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u Support depends on the scanner: - [Grype](https://github.com/anchore/grype#grype) -- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/os/) (Default). +- [Trivy](https://aquasecurity.github.io/trivy/latest/docs/vulnerability/detection/os/) (Default). -#### UBI-based images +#### FIPS-enabled images > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5775) in GitLab 14.1. -GitLab also offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) -versions of the container-scanning images. You can therefore replace standard images with UBI-based -images. To configure the images, set the `CS_ANALYZER_IMAGE` variable to the standard tag plus the -`-ubi` extension. +GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the container-scanning images. You can therefore replace standard images with FIPS-enabled +images. To configure the images, set the `CS_IMAGE_SUFFIX` to `-fips` or modify the `CS_ANALYZER_IMAGE` variable to the +standard tag plus the `-fips` extension. | Scanner name | `CS_ANALYZER_IMAGE` | | --------------- | ------------------- | -| Default (Trivy) | `registry.gitlab.com/security-products/container-scanning:4-ubi` | -| Grype | `registry.gitlab.com/security-products/container-scanning/grype:4-ubi` | -| Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:4-ubi` | +| Default (Trivy) | `registry.gitlab.com/security-products/container-scanning:4-fips` | +| Grype | `registry.gitlab.com/security-products/container-scanning/grype:4-fips` | +| Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:4-fips` | + +NOTE: +Prior to GitLab 15.0, the `-ubi` image extension is also available. GitLab 15.0 and later only +support `-fips`. + +Starting with GitLab 14.10, `-fips` is automatically added to `CS_ANALYZER_IMAGE` when FIPS mode is +enabled in the GitLab instance. ### Enable Container Scanning through an automatic merge request @@ -753,7 +761,7 @@ The images include the latest advisory database available for their respective s scanner includes data from multiple sources: - [Grype](https://github.com/anchore/grype#grypes-database). -- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/data-source/). +- [Trivy](https://aquasecurity.github.io/trivy/latest/docs/vulnerability/detection/data-source/). Database update information for other analyzers is available in the [maintenance table](../index.md#vulnerability-scanner-maintenance). diff --git a/doc/user/application_security/dast/checks/598.2.md b/doc/user/application_security/dast/checks/598.2.md new file mode 100644 index 00000000000..f6c6787128d --- /dev/null +++ b/doc/user/application_security/dast/checks/598.2.md @@ -0,0 +1,30 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Use of GET request method with sensitive query strings (password) + +## Description + +The user's password was identified in the request URL. Passwords should never be sent in GET +requests as they maybe captured by proxy systems, stored in browser history, or stored in +log files. If an attacker were to get access to these logs or logging systems, they would +be able to gain access to the target account. + +## Remediation + +Passwords should never be sent in GET requests. When authenticating users or requesting users +reset their passwords, always use POST requests to transmit sensitive data. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 598.2 | true | 598 | Passive | Medium | + +## Links + +- [OWASP](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) +- [CWE](https://cwe.mitre.org/data/definitions/598.html) diff --git a/doc/user/application_security/dast/checks/598.3.md b/doc/user/application_security/dast/checks/598.3.md new file mode 100644 index 00000000000..fa6fdf43e1c --- /dev/null +++ b/doc/user/application_security/dast/checks/598.3.md @@ -0,0 +1,31 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Use of GET request method with sensitive query strings (Authorization header details) + +## Description + +The authorization header value was identified in the request URL. These headers typically contain +usernames and passwords or JWT tokens. These values should never be sent in GET requests as they +maybe captured by proxy systems, stored in browser history, or stored in log files. If an attacker +were to get access to these logs or logging systems, they would be able to gain access to the +target account. + +## Remediation + +Authorization header details should never be sent in GET requests. When transmitting sensitive information +such as JWT tokens, always use POST requests or headers to transmit the sensitive data. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 598.3 | true | 598 | Passive | Medium | + +## Links + +- [OWASP](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) +- [CWE](https://cwe.mitre.org/data/definitions/598.html) diff --git a/doc/user/application_security/dast/checks/829.1.md b/doc/user/application_security/dast/checks/829.1.md new file mode 100644 index 00000000000..ca3d99c2bc9 --- /dev/null +++ b/doc/user/application_security/dast/checks/829.1.md @@ -0,0 +1,48 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Inclusion of Functionality from Untrusted Control Sphere + +## Description + +JavaScript or CSS source files are included from third party domains without +[Sub-Resource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). +If an attacker were to compromise the sites hosting these third party resources, they could inject malicious +script or CSS data in an attempt to compromise users of your application. However, if SRI was applied and an +attacker attempted to modify the contents of the script, the browser would not load the script and your +applications users would be protected from the malicious alterations. + +## Remediation + +All identified resources should be sourced from the same domain as the target application. If this is not +possible, it is strongly recommended that all `script` tags that implement `src` values, or `link` tags +that implement the `href` values include Sub-Resource Integrity. To generate SRI integrity values the +[srihash](https://www.srihash.org/) tool can be used, or by running one of the following commands: + +- `cat FILENAME.js | openssl dgst -sha384 -binary | openssl base64 -A` +- `shasum -b -a 384 FILENAME.js | awk '{ print $1 }' | xxd -r -p | base64` + +The output of these tools must be added as additional attributes, in particular: `integrity` and either +`crossorigin=anonymous` or `crossorigin=use-credentials`. +An example of a valid SRI protected script tag can be found below: + +```html +<script src="https://example.com/example-framework.js" + integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC" + crossorigin="anonymous"></script> +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 829.1 | true | 829 | Passive | Low | + +## Links + +- [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html#subresource-integrity) +- [CWE](https://cwe.mitre.org/data/definitions/829.html) +- [MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) diff --git a/doc/user/application_security/dast/checks/829.2.md b/doc/user/application_security/dast/checks/829.2.md new file mode 100644 index 00000000000..e6fada117f8 --- /dev/null +++ b/doc/user/application_security/dast/checks/829.2.md @@ -0,0 +1,47 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Invalid Sub-Resource Integrity values detected + +## Description + +JavaScript or CSS source files were found to contain invalid +[Sub-Resource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) +`integrity` values or a missing `crossorigin` value. These scripts or links should be investigated to +ensure they have not been maliciously altered. If in doubt, contact the owner of the scripts or replace +them with known good versions. + +## Remediation + +All identified resources should be sourced from the same domain as the target application. If this is not +possible, it is strongly recommended that all `script` tags that implement `src` values, or `link` tags +that implement the `href` values include Sub-Resource Integrity. To generate SRI integrity values the +[srihash](https://www.srihash.org/) tool can be used, or by running one of the following commands: + +- `cat FILENAME.js | openssl dgst -sha384 -binary | openssl base64 -A` +- `shasum -b -a 384 FILENAME.js | awk '{ print $1 }' | xxd -r -p | base64` + +The output of these tools must be added as additional attributes, in particular: `integrity` and either +`crossorigin=anonymous` or `crossorigin=use-credentials`. +An example of a valid SRI protected script tag can be found below: + +```html +<script src="https://example.com/example-framework.js" + integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC" + crossorigin="anonymous"></script> +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 829.2 | true | 829 | Passive | Medium | + +## Links + +- [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html#subresource-integrity) +- [CWE](https://cwe.mitre.org/data/definitions/829.html) +- [MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 435bc28c4aa..764e3c4a839 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -20,5 +20,9 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [200.1](200.1.md) | Exposure of sensitive information to an unauthorized actor (private IP address) | Low | Passive | | [548.1](548.1.md) | Exposure of information through directory listing | Low | Passive | | [598.1](598.1.md) | Use of GET request method with sensitive query strings (session ID) | Medium | Passive | +| [598.2](598.2.md) | Use of GET request method with sensitive query strings (password) | Medium | Passive | +| [598.3](598.3.md) | Use of GET request method with sensitive query strings (Authorization header details) | Medium | Passive | | [614.1](614.1.md) | Sensitive cookie without Secure attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | +| [829.1](829.1.md) | Inclusion of Functionality from Untrusted Control Sphere | Low | Passive | +| [829.2](829.2.md) | Invalid Sub-Resource Integrity values detected | Medium | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index fd6c39ffbf1..ee57803dfc7 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -278,7 +278,8 @@ page. You can enable or configure DAST settings using the UI. The generated settings are formatted so they can be conveniently pasted into the `.gitlab-ci.yml` file. -1. From the project's home page, go to **Security & Compliance > Configuration**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Enable DAST** or **Configure DAST**. 1. Select the desired **Scanner profile**, or select **Create scanner profile** and save a @@ -288,12 +289,14 @@ can be conveniently pasted into the `.gitlab-ci.yml` file. 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you selected. 1. Do one of the following: - 1. Select **Copy code only** to copy the snippet to your clipboard. - 1. Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard. The - CI/CD Editor then opens. + 1. To copy the snippet to your clipboard, select **Copy code only**. + 1. To add the snippet to your project's `.gitlab-ci.yml` file, select + **Copy code and open `.gitlab-ci.yml` file**. The Pipeline Editor opens. 1. Paste the snippet into the `.gitlab-ci.yml` file. 1. Select the **Lint** tab to confirm the edited `.gitlab-ci.yml` file is valid. - 1. Select **Commit changes**. + 1. Select the **Edit** tab, then select **Commit changes**. + +When the snippet is committed to the `.gitlab-ci.yml` file, pipelines include a DAST job. #### Crawling web applications dependent on JavaScript @@ -1053,7 +1056,7 @@ To run an on-demand scan either at a scheduled date or frequency, read 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. -1. Select **New DAST scan**. +1. Select **New scan**. 1. Complete the **Scan name** and **Description** fields. 1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown. 1. In **Scanner profile**, select a scanner profile from the dropdown. @@ -1088,7 +1091,7 @@ To schedule a scan: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > On-demand Scans**. -1. Select **New DAST scan**. +1. Select **New scan**. 1. Complete the **Scan name** and **Description** text boxes. 1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. 1. In the **Scanner profile** section, from the dropdown list, select a scanner profile. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 839833d9d98..a4908204b60 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -7,73 +7,65 @@ type: reference, howto # DAST API **(ULTIMATE)** -You can add dynamic application security testing of web APIs to your [GitLab CI/CD](../../../ci/index.md) pipelines. -This helps you discover bugs and potential security issues that other QA processes may miss. +You can add dynamic application security testing (DAST) of web APIs to your +[GitLab CI/CD](../../../ci/index.md) pipelines. This helps you discover bugs and potential security +issues that other QA processes may miss. We recommend that you use DAST API testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run DAST API tests as part your CI/CD workflow. -## Requirements - -- One of the following web API types: - - REST API - - SOAP - - GraphQL - - Form bodies, JSON, or XML -- One of the following assets to provide APIs to test: - - OpenAPI v2 or v3 API definition - - Postman Collection v2.0 or v2.1 - - HTTP Archive (HAR) of API requests to test +WARNING: +Do not run DAST API 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 DAST API against a test server. -## When DAST API scans run +You can run DAST API scanning against the following web API types: -When using the `DAST-API.gitlab-ci.yml` template, the defined jobs use the `dast` stage by default. To enable your `.gitlab-ci.yml` file must include the `dast` stage in your `stages` definition. To ensure DAST API scans the latest code, your CI pipeline should deploy changes to a test environment in a stage before the `dast` stage: +- REST API +- SOAP +- GraphQL +- Form bodies, JSON, or XML -```yaml -stages: - - build - - test - - deploy - - dast -``` +## When DAST API scans run -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 DAST API scan. The only changes to the API should be from the DAST API 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. +DAST API scanning runs in the `dast` stage by default. To ensure DAST API scanning examines the latest +code, ensure your CI/CD pipeline deploys changes to a test environment in a stage before the `dast` +stage. -## Enable DAST API scanning +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 be scanned should be excluded from changes for the duration of a +DAST API scan. The only changes to the API should be from the DAST API scanner. 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. -There are three ways to perform scans. See the configuration section for the one you wish to use: +## Example DAST API scanning configurations -- [OpenAPI v2 or v3 specification](#openapi-specification) -- [HTTP Archive (HAR)](#http-archive-har) -- [Postman Collection v2.0 or v2.1](#postman-collection) +The following projects demonstrate DAST API scanning: -Examples of various configurations can be found here: - -- [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/openapi-example) +- [Example OpenAPI v2 Specification project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/openapi-example) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/har-example) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/postman-example) - [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/graphql-example) - [Example SOAP project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/soap-example) -WARNING: -GitLab 14.0 will require that you place DAST API configuration files (for example, -`gitlab-dast-api-config.yml`) in your repository's `.gitlab` directory instead of your -repository's root. You can continue using your existing configuration files as they are, but -starting in GitLab 14.0, GitLab will not check your repository's root for configuration files. +## Targeting API for DAST scanning + +You can specify the API you want to scan by using: + +- [OpenAPI v2 or v3 Specification](#openapi-specification) +- [HTTP Archive (HAR)](#http-archive-har) +- [Postman Collection v2.0 or v2.1](#postman-collection) ### OpenAPI Specification > - Support for OpenAPI Specification using YAML format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. > - Support to generate media type `application/xml` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.8. +> - Support to media types was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. 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 using an OpenAPI Specification to provide information about the target API to test. +This section shows you how to configure DAST API scanning using an OpenAPI Specification to provide information about the target API to test. OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported. DAST API uses an OpenAPI document to generate the request body. When a request body is required, @@ -84,52 +76,40 @@ the body generation is limited to these body types: - `application/json` - `application/xml` -Follow these steps to configure DAST API in GitLab with an OpenAPI specification: +### OpenAPI and media types -1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) - that's provided as part of your GitLab installation. Add the following to your - `.gitlab-ci.yml` file: +A media type (formerly known as MIME type) is an identifier for file formats and format contents transmitted. A OpenAPI document lets you specify that a given operation can accept different media types, hence a given request can send data using different file content. As for example, a `PUT /user` operation to update user data could accept data in either XML (media type `application/xml`) or JSON (media type `application/json`) format. +OpenAPI 2.x lets you specify the accepted media types globally or per operation, and OpenAPI 3.x lets you specify the accepted media types per operation. DAST API will check the listed media types, and try to produce sample data for each supported media type. - ```yaml - stages: - - dast +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), the default behavior is to select one of the supported media types to use. The first supported media type is chosen from the list. This behavior is configurable. +- In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, `application/json` and `application/xml`), testing are performed using JSON, and then the same tests using XML. - include: - - template: DAST-API.gitlab-ci.yml - ``` +Testing the same operation (for example, `POST /user`) using different media types (for example, `application/json` and `application/xml`) is not always desirable. +For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicated vulnerabilities related to the request body depending on the target app. -1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. - Testing with this profile completes faster, allowing for easier configuration validation. +The environment variable `DAST_API_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environment variable `DAST_API_OPENAPI_ALL_MEDIA_TYPES` is set to any value, DAST API tries to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type. - Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick` for the profile you choose: +Alternatively, the variable `DAST_API_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `DAST_API_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. - ```yaml - stages: - - dast +Multiple media types in `DAST_API_OPENAPI_MEDIA_TYPES` are separated by a colon (`:`). For example, to limit request generation to the media types `application/x-www-form-urlencoded` and `multipart/form-data`, set the environment variable `DAST_API_OPENAPI_MEDIA_TYPES` to `application/x-www-form-urlencoded:multipart/form-data`. Only supported media types in this list are included when creating requests, though non-supported media types are always skipped. A media type text may contain different sections. For example, `application/vnd.api+json; charset=UTF-8`, is a compound of `type "/" [tree "."] subtype ["+" suffix]* [";" parameter]`. Parameters are not taken into account when performing the filtering media types on request generation. - include: - - template: DAST-API.gitlab-ci.yml +The environment variables `DAST_API_OPENAPI_ALL_MEDIA_TYPES` and `DAST_API_OPENAPI_MEDIA_TYPES` allow you to decide how to handle media types. These settings are mutually exclusive. If both are enabled, DAST API reports an error. - variables: - DAST_API_PROFILE: Quick - ``` +#### Configure DAST API with an OpenAPI Specification -1. Provide the location of the OpenAPI specification. You can provide the specification as a file - or URL. Specify the location by adding the `DAST_API_OPENAPI` variable: +To configure DAST API scanning with an OpenAPI specification: - ```yaml - stages: - - dast +To configure DAST API scanning with an OpenAPI Specification: - include: - - template: DAST-API.gitlab-ci.yml +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) in your `.gitlab-ci.yml` file. - variables: - DAST_API_PROFILE: Quick - DAST_API_OPENAPI: test-api-specification.json - ``` +1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. + Testing with this profile completes faster, allowing for easier configuration validation. + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. + +1. Provide the location of the OpenAPI Specification as either a file or URL. + Specify the location by adding the `DAST_API_OPENAPI` variable. 1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. @@ -140,20 +120,20 @@ Follow these steps to configure DAST API in GitLab with an OpenAPI specification 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 `DAST_API_TARGET_URL`: +Complete example configuration of using an OpenAPI Specification: - ```yaml - stages: - - dast +```yaml +stages: + - dast - include: - - template: DAST-API.gitlab-ci.yml +include: + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_PROFILE: Quick - DAST_API_OPENAPI: test-api-specification.json - DAST_API_TARGET_URL: http://test-deployment/ - ``` +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ +``` This is a minimal configuration for DAST API. From here you can: @@ -161,14 +141,12 @@ This is a minimal configuration for DAST API. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run DAST API 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 DAST API scanning 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 the GitLab DAST API scanner, HAR must contain records of calling the web API to test. The DAST API scanner extracts all the requests and -uses them to perform testing. +The [HTTP Archive format (HAR)](../api_fuzzing/create_har_files.md) is an archive file format for +logging HTTP transactions. When used with the GitLab DAST API scanner, the HAR file must contain +records of calling the web API to test. The DAST API scanner extracts all of the requests and uses them +to perform testing. You can use various tools to generate HAR files: @@ -182,53 +160,20 @@ 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 DAST API to use a HAR file that provides information about the -target API to test: +#### DAST API scanning with a HAR file -1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) - that's provided as part of your GitLab installation. To do so, add the following to your - `.gitlab-ci.yml` file: +To configure DAST API to use a HAR file that provides information about the target API to test: - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - ``` +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) in your `.gitlab-ci.yml` file. 1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. Testing with this profile completes faster, allowing for easier configuration validation. - Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick` for the profile you choose: - - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - ``` + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. 1. Provide the location of the HAR file. You can provide the location as a file path - or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable: - - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - DAST_API_HAR: test-api-recording.har - ``` + or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable. 1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. @@ -239,20 +184,20 @@ target API to test: 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 `DAST_API_TARGET_URL`: +Complete example configuration of using an HAR file: - ```yaml - stages: - - dast +```yaml +stages: + - dast - include: - - template: DAST-API.gitlab-ci.yml +include: + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_PROFILE: Quick - DAST_API_HAR: test-api-recording.har - DAST_API_TARGET_URL: http://test-deployment/ - ``` +variables: + DAST_API_PROFILE: Quick + DAST_API_HAR: test-api-recording.har + DAST_API_TARGET_URL: http://test-deployment/ +``` This is a minimal configuration for DAST API. From here you can: @@ -260,11 +205,6 @@ This is a minimal configuration for DAST API. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run DAST API 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 DAST API against a test server. - ### Postman Collection The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that @@ -282,52 +222,20 @@ Postman Collection files may contain sensitive information such as authenticatio and session cookies. We recommend that you review the Postman Collection file contents before adding them to a repository. -Follow these steps to configure DAST API to use a Postman Collection file that provides -information about the target API to test: - -1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) - that's provided as part of your GitLab installation. To do so, add the following to your - `.gitlab-ci.yml` file: +#### DAST API scanning with a Postman Collection file - ```yaml - stages: - - dast +To configure DAST API to use a Postman Collection file that provides information about the target +API to test: - include: - - template: DAST-API.gitlab-ci.yml - ``` +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). 1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. Testing with this profile completes faster, allowing for easier configuration validation. - Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick` for the profile you choose: + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - ``` - -1. Provide the location of the Postman Collection file. You can provide the location as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: - - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json - ``` +1. Provide the location of the Postman Collection file as either a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable. 1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. @@ -338,20 +246,20 @@ information about the target API to test: 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 `DAST_API_TARGET_URL`: +Complete example configuration of using a Postman collection: - ```yaml - stages: - - dast +```yaml +stages: + - dast - include: - - template: DAST-API.gitlab-ci.yml +include: + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_PROFILE: Quick - DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json - DAST_API_TARGET_URL: http://test-deployment/ - ``` +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json + DAST_API_TARGET_URL: http://test-deployment/ +``` This is a minimal configuration for DAST API. From here you can: @@ -359,12 +267,7 @@ This is a minimal configuration for DAST API. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run DAST API 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 DAST API against a test server. - -#### Postman variables +##### Postman variables Postman allows the developer to define placeholders that can be used in different parts of the requests. These placeholders are called variables, as explained in [Using variables](https://learning.postman.com/docs/sending-requests/variables/). @@ -388,11 +291,11 @@ Postman file. For example, Postman does not export environment-scoped variables file. By default, the DAST API scanner uses the Postman file to resolve Postman variable values. If a JSON file -is set in a GitLab CI environment variable `DAST_API_POSTMAN_COLLECTION_VARIABLES`, then the JSON +is set in a GitLab CI/CD environment variable `DAST_API_POSTMAN_COLLECTION_VARIABLES`, then the JSON file takes precedence to get Postman variable values. -Although Postman can export environment variables into a JSON file, the format is not compatible -with the JSON expected by `DAST_API_POSTMAN_COLLECTION_VARIABLES`. +WARNING: +Although Postman can export environment variables into a JSON file, the format is not compatible with the JSON expected by `DAST_API_POSTMAN_COLLECTION_VARIABLES`. Here is an example of using `DAST_API_POSTMAN_COLLECTION_VARIABLES`: @@ -421,12 +324,12 @@ values. For example: } ``` -### Authentication +## 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 [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) is an authentication method built in to the HTTP protocol and used in conjunction with @@ -456,23 +359,23 @@ variables: DAST_API_HTTP_PASSWORD: $TEST_API_PASSWORD ``` -#### Bearer Tokens +### 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 (JWT). Bearer tokens are transmitted using the `Authorization` HTTP header. To use Bearer tokens with DAST API, 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 DAST API can call to generate the token +- A token that doesn't expire. +- A way to generate a token that lasts the length of testing. +- A Python script that DAST API can call to generate the token. -##### Token doesn't expire +#### Token doesn't expire -If the bearer token doesn't expire, use the `DAST_API_OVERRIDES_ENV` variable to provide it. This +If the Bearer token doesn't expire, use the `DAST_API_OVERRIDES_ENV` variable to provide it. This variable's content is a JSON snippet that provides headers and cookies to add to DAST API's outgoing HTTP requests. -Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: +Follow these steps to provide the Bearer token with `DAST_API_OVERRIDES_ENV`: 1. [Create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables), for example `TEST_API_BEARERAUTH`, with the value @@ -502,9 +405,9 @@ Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: 1. To validate that authentication is working, run an DAST API test and review the job logs and the test API's application logs. -##### Token generated at test runtime +#### Token generated at test runtime -If the bearer token must be generated and doesn't expire during testing, you can provide to DAST API a file containing the token. A prior stage and job, or part of the DAST API job, can +If the Bearer token must be generated and doesn't expire during testing, you can provide DAST API a file that has the token. A prior stage and job, or part of the DAST API job, can generate this file. DAST API expects to receive a JSON file with the following structure: @@ -539,14 +442,14 @@ variables: To validate that authentication is working, run an DAST API test and review the job logs and the test API's application logs. -##### Token has short expiration +#### Token has short expiration -If the bearer token must be generated and expires prior to the scan's completion, you can provide a +If the Bearer token must be generated and expires prior to the scan's completion, you can provide a program or script for the DAST API scanner 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: +The script must create a JSON file containing the Bearer token in a specific format: ```json { @@ -582,7 +485,7 @@ variables: To validate that authentication is working, run an DAST API test and review the job logs and the test API's application logs. See the [overrides section](#overrides) for more information about override commands. -### Configuration files +## Configuration files To get you started quickly, GitLab provides the configuration file [`gitlab-dast-api-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/dast/-/blob/master/config/gitlab-dast-api-config.yml). @@ -590,12 +493,12 @@ This file has several testing profiles that perform various numbers of tests. Th profile increases as the test numbers go up. To use a configuration file, add it to your repository's root as `.gitlab/gitlab-dast-api-config.yml`. -#### Profiles +### Profiles The following profiles are pre-defined in the default configuration file. Profiles can be added, removed, and modified by creating a custom configuration. -##### Quick +#### Quick - Application Information Check - Cleartext Authentication Check @@ -610,7 +513,7 @@ can be added, removed, and modified by creating a custom configuration. - Token Check - XML Injection Check -##### Full +#### Full - Application Information Check - Cleartext AuthenticationCheck @@ -630,17 +533,24 @@ can be added, removed, and modified by creating a custom configuration. - Token Check - XML Injection Check -### Available CI/CD variables +## Available CI/CD variables | CI/CD variable | Description | |------------------------------------------------------|--------------------| -| `DAST_API_VERSION` | Specify DAST API container version. Defaults to `latest`. | +| `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | +| `DAST_API_VERSION` | Specify DAST API container version. Defaults to `1`. | +| `DAST_API_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | |[`DAST_API_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | +|[`DAST_API_EXCLUDE_URLS`](#exclude-urls) | Exclude API URL from testing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. | +|[`DAST_API_EXCLUDE_PARAMETER_ENV`](#exclude-parameters) | JSON string containing excluded parameters. | +|[`DAST_API_EXCLUDE_PARAMETER_FILE`](#exclude-parameters) | Path to a JSON file containing excluded parameters. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`DAST_API_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | +|[`DAST_API_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | @@ -656,7 +566,7 @@ can be added, removed, and modified by creating a custom configuration. |`DAST_API_SERVICE_START_TIMEOUT` | How long to wait for target API to become available in seconds. Default is 300 seconds. | |`DAST_API_TIMEOUT` | How long to wait for API responses in seconds. Default is 30 seconds. | -### Overrides +## Overrides DAST API provides a method to add or override specific items in your request, for example: @@ -814,7 +724,7 @@ It is changed to: 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 +### Using a file To provide the overrides JSON as a file, the `DAST_API_OVERRIDES_FILE` CI/CD variable is set. The path is relative to the job current working directory. @@ -834,7 +744,7 @@ variables: DAST_API_OVERRIDES_FILE: dast-api-overrides.json ``` -#### Using a CI/CD variable +### Using a CI/CD variable To provide the overrides JSON as a CI/CD variable, use the `DAST_API_OVERRIDES_ENV` variable. This allows you to place the JSON as variables that can be masked and protected. @@ -872,7 +782,7 @@ variables: DAST_API_OVERRIDES_ENV: $SECRET_OVERRIDES ``` -#### Using a command +### Using a command If the value must be generated or regenerated on expiration, you can provide a program or script for the DAST API scanner to execute on a specified interval. The provided command runs in an Alpine Linux @@ -914,7 +824,7 @@ variables: DAST_API_OVERRIDES_INTERVAL: 300 ``` -#### Debugging overrides +### Debugging overrides > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. @@ -965,10 +875,10 @@ def get_auth_response(): # In our example, access token is retrieved from a given endpoint try: - # Performs a http request, response sample: + # Performs a http request, response sample: # { "Token" : "b5638ae7-6e77-4585-b035-7d9de2e3f6b3" } response = get_auth_response() - + # Check that the request is successful. may raise `requests.exceptions.HTTPError` response.raise_for_status() @@ -995,7 +905,7 @@ except Exception as e: logging.error(f'Error, unknown error while retrieving access token. Error message: {e}') raise -# computes object that holds overrides file content. +# computes object that holds overrides file content. # It uses data fetched from request overrides_data = { "headers": { @@ -1070,7 +980,7 @@ variables: In the previous sample, you could use the script `user-pre-scan-set-up.sh` to also install new runtimes or applications that later on you could use in our overrides command. -### Exclude Paths +## Exclude Paths > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. @@ -1088,7 +998,7 @@ To verify the paths are excluded, review the `Tested Operations` and `Excluded O 2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ ``` -#### Examples +### Examples This example excludes the `/auth` resource. This does not exclude child resources (`/auth/child`). @@ -1111,6 +1021,294 @@ variables: DAST_API_EXCLUDE_PATHS=/auth*;/v1/* ``` +### Exclude parameters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. + +While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters, you can set one of the following variables: `DAST_API_EXCLUDE_PARAMETER_ENV` or `DAST_API_EXCLUDE_PARAMETER_FILE`. + +The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre script using `DAST_API_PRE_SCRIPT`. + +#### Exclude parameters using a JSON document + +The JSON document contains a JSON object, this object uses specific properties to identify which parameter should be excluded. +You can provide the following properties to exclude specific parameters during the scanning process: + +- `headers`: Use this property to exclude specific headers. The property's value is an array of header names to be excluded. Names are case-insensitive. +- `cookies`: Use this property's value to exclude specific cookies. The property's value is an array of cookie names to be excluded. Names are case-sensitive. +- `query`: Use this property to exclude specific fields from the query string. The property's value is an array of field names from the query string to be excluded. Names are case-sensitive. +- `body-form`: Use this property to exclude specific fields from a request that uses the media type `application/x-www-form-urlencoded`. The property's value is an array of the field names from the body to be excluded. Names are case-sensitive. +- `body-json`: Use this property to exclude specific JSON nodes from a request that uses the media type `application/json`. The property's value is an array, each entry of the array is a [JSON Path](https://goessner.net/articles/JsonPath/) expression. +- `body-xml`: Use this property to exclude specific XML nodes from a request that uses media type `application/xml`. The property's value is an array, each entry of the array is a [XPath v2](https://www.w3.org/TR/xpath20/) expression. + +Thus, the following JSON document is an example of the expected structure to exclude parameters. + +```json +{ + "headers": [ + "header1", + "header2" + ], + "cookies": [ + "cookie1", + "cookie2" + ], + "query": [ + "query-string1", + "query-string2" + ], + "body-form": [ + "form-param1", + "form-param2" + ], + "body-json": [ + "json-path-expression-1", + "json-path-expression-2" + ], + "body-xml" : [ + "xpath-expression-1", + "xpath-expression-2" + ] +} +``` + +#### Examples + +##### Excluding a single header + +To exclude the header `Upgrade-Insecure-Requests`, set the `header` property's value to an array with the header name: `[ "Upgrade-Insecure-Requests" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Upgrade-Insecure-Requests" ] +} +``` + +Header names are case-insensitive, so the header name `UPGRADE-INSECURE-REQUESTS` is equivalent to `Upgrade-Insecure-Requests`. + +##### Excluding both a header and two cookies + +To exclude the header `Authorization`, and the cookies `PHPSESSID` and `csrftoken`, set the `headers` property's value to an array with header name `[ "Authorization" ]` and the `cookies` property's value to an array with the cookies' names `[ "PHPSESSID", "csrftoken" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Authorization" ], + "cookies": [ "PHPSESSID", "csrftoken" ] +} +``` + +##### Excluding a `body-form` parameter + +To exclude the `password` field in a request that uses `application/x-www-form-urlencoded`, set the `body-form` property's value to an array with the field name `[ "password" ]`. For instance, the JSON document looks like this: + +```json +{ + "body-form": [ "password" ] +} +``` + +The exclude parameters uses `body-form` when the request uses a content type `application/x-www-form-urlencoded`. + +##### Excluding a specific JSON nodes using JSON Path + +To exclude the `schema` property in the root object, set the `body-json` property's value to an array with the JSON Path expression `[ "$.schema" ]`. + +The JSON Path expression uses special syntax to identify JSON nodes: `$` refers to the root of the JSON document, `.` refers to the current object (in our case the root object), and the text `schema` refers to a property name. Thus, the JSON path expression `$.schema` refers to a property `schema` in the root object. +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.schema" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding multiple JSON nodes using JSON Path + +To exclude the property `password` on each entry of an array of `users` at the root level, set the `body-json` property's value to an array with the JSON Path expression `[ "$.users[*].paswword" ]`. + +The JSON Path expression starts with `$` to refer to the root node and uses `.` to refer to the current node. Then, it uses `users` to refer to a property and the characters `[` and `]` to enclose the index in the array you want to use, instead of providing a number as an index you use `*` to specify any index. After the index reference, we find `.` which now refers to any given selected index in the array, preceded by a property name `password`. + +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.users[*].paswword" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding a XML attribute + +To exclude an attribute named `isEnabled` located in the root element `credentials`, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/@isEnabled" ]`. + +The XPath expression `/credentials/@isEnabled`, starts with `/` to indicate the root of the XML document, then it is followed by the word `credentials` which indicates the name of the element to match. It uses a `/` to refer to a node of the previous XML element, and the character `@` to indicate that the name `isEnable` is an attribute. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/@isEnabled" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding a XML text's element + +To exclude the text of the `username` element contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username/text()" ]`. + +In the XPath expression `/credentials/username/text()`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. Last part has a `/` that refers to the current element, and uses a XPath function called `text()` which identifies the text of the current element. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username/text()" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML element + +To exclude the element `username` contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username" ]`. + +In the XPath expression `/credentials/username`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML node with namespaces + +To exclude anXML element `login` which is defined in namespace `s`, and contained in `credentials` root node, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/s:login" ]`. + +In the XPath expression `/credentials/s:login`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `s:login`. Notice that name contains the character `:`, this character separates the namespace from the node name. + +The namespace name should have been defined in the XML document which is part of the body request. You may check the namespace in the specification document HAR, OpenAPI, or Postman Collection file. + +```json +{ + "body-xml": [ + "/credentials/s:login" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be an [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath, expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +#### Using a JSON string + +To provide the exclusion JSON document set the variable `DAST_API_EXCLUDE_PARAMETER_ENV` with the JSON string. In the following example, the `.gitlab-ci.yml`, the `DAST_API_EXCLUDE_PARAMETER_ENV` variable is set to a JSON string: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_EXCLUDE_PARAMETER_ENV: '{ "headers": [ "Upgrade-Insecure-Requests" ] }' +``` + +#### Using a file + +To provide the exclusion JSON document set the variable `DAST_API_EXCLUDE_PARAMETER_FILE` with the JSON file path. The file path is relative to the job current working directory. In the following example `.gitlab-ci.yml` content, the `DAST_API_EXCLUDE_PARAMETER_FILE` variable is set to a JSON file path: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_EXCLUDE_PARAMETER_FILE: dast-api-exclude-parameters.json +``` + +The `dast-api-exclude-parameters.json` is a JSON document that follows the structure of [exclude parameters document](#exclude-parameters-using-a-json-document). + +### Exclude URLS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. + +As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` will exclude all URLs because it is a regular expression that matches everything. + +In your job output you can check if any URLs matched any provided regular expression from `DAST_API_EXCLUDE_URLS`. Matching operations are listed in the **Excluded Operations** section. Operations listed in the **Excluded Operations** should not be listed in the **Tested Operations** section. For example the following portion of a job output: + +```plaintext +2021-05-27 21:51:08 [INF] API Security: --[ Tested Operations ]------------------------- +2021-05-27 21:51:08 [INF] API Security: 201 POST http://target:7777/api/users CREATED +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +2021-05-27 21:51:08 [INF] API Security: --[ Excluded Operations ]----------------------- +2021-05-27 21:51:08 [INF] API Security: GET http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: POST http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +``` + +NOTE: +Each value in `DAST_API_EXCLUDE_URLS` is a regular expression. Characters such as `.` , `*` and `$` among many others have special meanings in [regular expressions](https://en.wikipedia.org/wiki/Regular_expression#Standards). + +#### Examples + +##### Excluding a URL and child resources + +The following example excludes the URL `http://target/api/auth` and its child resources. + +```yaml +variables: + DAST_API_EXCLUDE_URLS: http://target/api/auth +``` + +##### Excluding two URLs and allow their child resources + +To exclude the URLs `http://target/api/buy` and `http://target/api/sell` but allowing to scan their child resources, for instance: `http://target/api/buy/toy` or `http://target/api/sell/chair`. You could use the value `http://target/api/buy/$,http://target/api/sell/$`. This value is using two regular expressions, each of them separated by a `,` character. Hence, it contains `http://target/api/buy$` and `http://target/api/sell$`. In each regular expression, the trailing `$` character points out where the matching URL should end. + +```yaml +variables: + DAST_API_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$ +``` + +##### Excluding two URLs and their child resources + +In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: + +```yaml +variables: + DAST_API_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell +``` + +##### Excluding URL using regular expressions + +In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. + +```yaml +variables: + DAST_API_EXCLUDE_URLS: https://target/api/v.*/user/create$ +``` + ## Running your first scan When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During normal operation, the job always succeeds even if vulnerabilities are identified during testing. @@ -1165,7 +1363,7 @@ pipelines. For more information, see the [Security Dashboard documentation](../s Once a vulnerability is found, you can interact with it. Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). -## Handling False Positives +### Handling False Positives False positives can be handled in several ways: @@ -1177,7 +1375,7 @@ False positives can be handled in several ways: - Turn off the Check producing the false positive. This prevents the check from generating any vulnerabilities. Example checks are the SQL Injection Check, and JSON Hijacking Check. -### Turn off a Check +#### 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 @@ -1235,7 +1433,7 @@ This results in the following YAML: - Name: XmlInjectionCheck ``` -### Turn off an Assertion for a Check +#### Turn off an Assertion for a Check Assertions detect vulnerabilities in tests produced by checks. Many checks support multiple Assertions such as Log Analysis, Response Analysis, and Status Code. When a vulnerability 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`. @@ -1419,6 +1617,19 @@ API Security can still try to consume an OpenAPI document that does not fully co DAST_API_OPENAPI_RELAXED_VALIDATION: On ``` +### No operation in the OpenAPI document is consuming any supported media type + +API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. + +**Error message** + +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), `Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.` + +**Solution** + +1. Review supported media types in the [OpenAPI Specification](#openapi-specification) section. +1. Edit your OpenAPI document, allowing at least a given operation to accept any of the supported media types. Alternatively, a supported media type could be set in the OpenAPI document level and get applied to all operations. This step may require changes in your application to ensure the supported media type is accepted by the application. + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a4a7e6703ab..924e3838d91 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -321,13 +321,13 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Package Manager | Supported File Format Versions | Tested Versions | | ------ | ------ | ------ | -| Bundler | N/A | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| Composer | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/tests/php-composer/-/blob/master/composer.lock) | -| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/c-conan/-/blob/master/conan.lock) | -| Go | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/tests/go-modules/-/blob/master/go.mod) | -| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/tests/csharp-nuget-dotnetcore/-/blob/master/src/web.api/packages.lock.json#L2) | -| npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/master/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/lockfile-v2-FREEZE/package-lock.json#L4) | -| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/js-yarn/-/blob/master/yarn.lock) | +| Bundler | N/A | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/main/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| Composer | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/main/composer.lock) | +| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/main/conan.lock) | +| Go | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/main/go.sum) | +| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/main/src/web.api/packages.lock.json#L2) | +| npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/main/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4) | +| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/main/yarn.lock#L2) | #### Obtaining dependency information by running a package manager to generate a parsable file @@ -339,19 +339,19 @@ To support the following package managers, the GitLab analyzers proceed in two s | Package Manager | Pre-installed Versions | Tested Versions | | ------ | ------ | ------ | | Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L330), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L339), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L348), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L357), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L366), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L384) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L289-297)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3), [7.3](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-7-3/gradle/wrapper/gradle-wrapper.properties#L3), [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L299-317)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup> | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | -| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | -| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-4">4</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | +| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L443-447), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L449-453), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L455-459), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L461-465), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L467-471), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L473-477), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L479-483) | +| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L319-323), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L286-288)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L331-335), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L300-302)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup> | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L224-247) | +| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L77-91) | +| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L168-191)<sup><b><a href="#exported-dependency-information-notes-4">4</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L143-166) | <!-- markdownlint-disable MD044 --> <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> - The pre-installed version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a>. + The pre-installed and tested version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a>. </p> </li> <li> @@ -508,19 +508,18 @@ always take the latest dependency scanning artifact available. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/282533) in GitLab 14.1. > - [Feature flag sec_dependency_scanning_ui_enable removed](https://gitlab.com/gitlab-org/gitlab/-/issues/326005) in GitLab 14.2. -To enable Dependency Scanning in a project, you can create a merge request -from the Security Configuration page. +To enable Dependency Scanning in a project, you can create a merge request: -1. In the project where you want to enable Dependency Scanning, navigate to - **Security & Compliance > Configuration**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dependency Scanning** row, select **Configure with a merge request**. +1. Review and merge the merge request to enable Dependency Scanning. -This automatically creates a merge request with the changes necessary to enable Dependency Scanning -that you can review and merge to complete the configuration. +Pipelines now include a dependency scanning job. ### Customizing the dependency scanning settings -The dependency scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the +The Dependency Scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. For example: @@ -580,6 +579,7 @@ The following variables allow configuration of global dependency scanning settin | `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_DEFAULT_ANALYZERS` | ([**DEPRECATED - use `DS_EXCLUDED_ANALYZERS` instead**](https://gitlab.com/gitlab-org/gitlab/-/issues/287691)) Override the names of the official default images. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | +| `DS_IMAGE_SUFFIX` | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info`. | @@ -660,6 +660,40 @@ you can use the `MAVEN_CLI_OPTS` CI/CD variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repositories). +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10. + +GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the Gemnasium images. You can therefore replace standard images with FIPS-enabled images. + +To use FIPS-enabled images, set the `DS_IMAGE_SUFFIX` to `-fips`, +and set `DS_EXCLUDED_ANALYZERS` to `bundler-audit, retire.js` +to exclude the analyzers that don't support FIPS. + +```yaml +variables: + DS_IMAGE_SUFFIX: "-fips" + DS_EXCLUDED_ANALYZERS: "bundler-audit, retire.js" +``` + +If you want to execute `bundler-audit` or `retire.js` in your project pipeline, you can override the +Gemnasium scanning jobs, and set `DS_IMAGE_SUFFIX` to `-fips` only for those jobs. + +```yaml +gemnasium-dependency_scanning: + variables: + DS_IMAGE_SUFFIX: "-fips" + +gemnasium-maven-dependency_scanning: + variables: + DS_IMAGE_SUFFIX: "-fips" + +gemnasium-python-dependency_scanning: + variables: + DS_IMAGE_SUFFIX: "-fips" +``` + ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to @@ -890,7 +924,7 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s ## Contributing to the vulnerability database You can search the [`gemnasium-db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project -to find a vulnerability in the Gemnasium database. +to find a vulnerability in the GitLab Advisory Database. You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). ## Running dependency scanning in an offline environment @@ -1237,3 +1271,24 @@ analyzers, edit your `gitlab-ci.yml` file and either: For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to `"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"`. + +### Dependency Scanning of setuptools project fails with `use_2to3 is invalid` error + +Support for [2to3](https://docs.python.org/3/library/2to3.html) +was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) +in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` +version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on +`lib2to3` will fail with this message: + +```plaintext +error in <dependency name> setup command: use_2to3 is invalid +``` + +To work around this error, downgrade the analyzer's version of `setuptools` (e.g. `v57.5.0`): + +```yaml +gemnasium-python-dependency_scanning: + before_script: + - pip install setuptools==57.5.0 + image: registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python:2-python-3.9 +``` diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index b72f54b4493..35968a6361f 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -41,9 +41,31 @@ GitLab IaC scanning supports a variety of IaC configuration files. Our IaC secur | Google Deployment Manager | [KICS](https://kics.io/) | 14.5 | | Kubernetes | [KICS](https://kics.io/) | 14.5 | | OpenAPI | [KICS](https://kics.io/) | 14.5 | -| Terraform | [KICS](https://kics.io/) | 14.5 | +| Terraform <sup>2</sup> | [KICS](https://kics.io/) | 14.5 | 1. IaC scanning can analyze Azure Resource Manager templates in JSON format. If you write templates in the [Bicep](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview) language, you must use [the bicep CLI](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli) to convert your Bicep files into JSON before GitLab IaC scanning can analyze them. +1. Terraform modules in a custom registry are not scanned for vulnerabilities. You can follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/357004) for the proposed feature. + +### Supported distributions + +GitLab scanners are provided with a base alpine image for size and maintainability. + +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. + +GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the images. You can therefore replace standard images with FIPS-enabled +images. To configure the images, set the `SAST_IMAGE_SUFFIX` to `-fips` or modify the +standard tag plus the `-fips` extension. + +```yaml +variables: + SAST_IMAGE_SUFFIX: '-fips' + +include: + - template: Security/SAST-IaC.latest.gitlab-ci.yml +``` ### Making IaC analyzers available to all GitLab tiers @@ -54,13 +76,13 @@ All open source (OSS) analyzers are available with the GitLab Free tier. Future Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | -|:---------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure IaC Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in merge request | **{dotted-circle}** | **{check-circle}** | -| [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free & Premium | In Ultimate | +|:----------------------------------------------------------------|:--------------------|:-------------------| +| [Configure IaC scanner](#configuration) | **{check-circle}** | **{check-circle}** | +| Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -92,15 +114,14 @@ that you can download and analyze. ### Enable IaC Scanning via an automatic merge request -To enable IaC Scanning in a project, you can create a merge request -from the Security Configuration page: +To enable IaC Scanning in a project, you can create a merge request: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. +1. Review and merge the merge request to enable IaC Scanning. -This automatically creates a merge request with the changes necessary to enable IaC Scanning -that you can review and merge to complete the configuration. +Pipelines now include an IaC job. ## Reports JSON format diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index ff548f1d29f..3a6aa8e3485 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -52,7 +52,7 @@ The following vulnerability scanners and their databases are regularly updated: | Secure scanning tool | Vulnerabilities database updates | |:----------------------------------------------------------------|:---------------------------------| | [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. For more details, see [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database-update). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Security Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | @@ -218,7 +218,7 @@ security issues: WARNING: This feature is in its end-of-life process. It is [deprecated](../../update/deprecations.md#vulnerability-check) -for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new +in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new [Security Approval Policies](policies/scan-result-policies.md). To prevent a merge request introducing a security vulnerability in a project, enable the @@ -381,6 +381,12 @@ Learn more on overriding security jobs: All the security scanning tools define their stage, so this error can occur with all of them. +## Self managed installation options + +For self managed installations, you can choose to run most of the GitLab security scanners even when [not connected to the internet](offline_deployments/index.md). + +Self managed installations can also run the security scanners on a GitLab Runner [running inside OpenShift](../../install/openshift_and_gitlab/index.md). + ## Security report validation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. @@ -474,6 +480,7 @@ GitLab provides two methods of accomplishing this, each with advantages and disa - [Compliance framework pipelines](../project/settings/#compliance-pipeline-configuration) are recommended when: + - Scan execution enforcement is required for SAST or Secret Detection scans that use custom rulesets. - Scan execution enforcement is required for SAST IaC, Dependency Scanning, License Compliance, API Fuzzing, or Coverage-guided Fuzzing. - Scan execution enforcement is required for scanners external to GitLab. @@ -482,9 +489,18 @@ GitLab provides two methods of accomplishing this, each with advantages and disa - [Scan execution policies](policies/scan-execution-policies.md) are recommended when: - - Scan execution enforcement is required for DAST, SAST, Secret Detection, or Container Scanning. + - Scan execution enforcement is required for DAST. + - Scan execution enforcement is required for Container Scanning with project-specific variable + customizations. To accomplish this, users must create a separate security policy per project. - Scans are required to run on a regular, scheduled cadence. +- Either solution can be used equally well when: + + - Scan execution enforcement is required for SAST or Secret Detection when custom rulesets are not + used. + - Scan execution enforcement is required for Container Scanning with no project-specific variable + customizations. + Additional details about the differences between the two solutions are outlined below: | | Compliance Framework Pipelines | Scan Execution Policies | diff --git a/doc/user/application_security/policies/img/association_diagram.png b/doc/user/application_security/policies/img/association_diagram.png Binary files differnew file mode 100644 index 00000000000..d082e297c68 --- /dev/null +++ b/doc/user/application_security/policies/img/association_diagram.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 8a39220da35..81d24104340 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -21,6 +21,56 @@ GitLab supports the following security policies: - [Scan Result Policy](scan-result-policies.md) - [Container Network Policy](#container-network-policy) (DEPRECATED) +## Security policy project + +All security policies are stored as YAML in a separate security policy project that gets linked to +the development project. This association can be a one-to-many relationship, allowing one security +policy project to apply to multiple development projects. Linked projects are not required to be in +the same group as the development projects to which they are linked. + + + +Although it is possible to have one project linked to itself and to serve as both the development +project and the security policy project, this is not recommended. Keeping the security policy +project separate from the development project allows for complete separation of duties between +security/compliance teams and development teams. + +All security policies are stored in the `.gitlab/security-policies/policy.yml` YAML file inside the +linked security policy project. The format for this YAML is specific to the type of policy that is +stored there. Examples and schema information are available for the following policy types: + +- [Scan execution policy](scan-execution-policies.md#example-security-policies-project) +- [Scan result policy](scan-result-policies.md#example-security-scan-result-policies-project) + +Policies created in this project are applied through a background job that runs once every 10 +minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. + +### Managing the linked security policy project + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select, edit, and unlink a security policy project. + +As a project owner, take the following steps to create or edit an association between your current +project and a project that you would like to designate as the security policy project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Select **Edit Policy Project**, and search for and select the + project you would like to link from the dropdown menu. +1. Select **Save**. + +To unlink a security policy project, follow the same steps but instead select the trash can icon in +the modal. + + + +### Viewing the linked security policy project + +All users who have access to the project policy page and are not project owners will instead view a +button linking out to the associated security policy project. If no security policy project has been +associated then the linking button does not appear. + ## Policy management The Policies page displays deployed @@ -57,6 +107,7 @@ You can use the policy editor to create, edit, and delete policies: 1. On the top bar, select **Menu > Projects** and find your group. 1. On the left sidebar, select **Security & Compliance > Policies**. - To create a new policy, select **New policy** which is located in the **Policies** page's header. + You can then select which type of policy to create. - To edit an existing policy, select **Edit policy** in the selected policy drawer. The policy editor has two modes: @@ -78,44 +129,12 @@ by the Rule mode, Rule mode is automatically disabled. If the YAML is incorrect, you must use YAML mode to fix your policy before Rule mode is available again. -## Security Policies project - -NOTE: -We recommend using the [Security Policies project](#security-policies-project) -exclusively for managing policies for the project. Do not add your application's source code to such -projects. - -The Security Policies feature is a repository to store policies. All security policies are stored in -the `.gitlab/security-policies/policy.yml` YAML file. The format for this YAML is specific to the type of policy that is being stored there. Examples and schema information are available for the following policy types: - -- [Scan execution policy](scan-execution-policies.md#example-security-policies-project) -- [Scan result policy](scan-result-policies.md#example-security-scan-result-policies-project) - -Policies created in this project are applied through a background job that runs once every 10 -minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. - -## Security Policy project selection - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. - -When the Security Policy project is created and policies are created within that repository, you -must create an association between that project and the project you want to apply policies to: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Policies**. -1. Select **Edit Policy Project**, and search for and select the - project you would like to link from the dropdown menu. -1. Select **Save**. - -  - -### Unlink Security Policy projects - -Project owners can unlink Security Policy projects from development projects. To do this, follow -the steps described in [Security Policy project selection](#security-policy-project-selection), -but select the trash can icon in the modal. +When you finish creating or editing your policy, save and apply it by selecting the +**Configure with a merge request** button and then merging the resulting merge request. When you +press this button, the policy YAML is validated and any resulting errors are displayed. +Additionally, if you are a project owner and a security policy project has not been previously +associated with this project, then a new project is created and associated automatically at the same +time that the first policy merge request is created. ## Scan execution policies @@ -132,7 +151,7 @@ See [Scan result policies](scan-result-policies.md). WARNING: Container Network Policy is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. The **Container Network Policy** section provides packet flow metrics for diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index c3778ac97de..7e8e60768b9 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -132,8 +132,8 @@ Note the following: ## Example security policies project -You can use this example in a `.gitlab/security-policies/policy.yml`, as described in -[Security policies project](index.md#security-policies-project). +You can use this example in a `.gitlab/security-policies/policy.yml` file stored in a +[security policy project](index.md#security-policy-project): ```yaml --- diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 8215316bcab..d2cce207bfd 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -65,7 +65,7 @@ This rule enforces the defined actions based on the information provided. | `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | | `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. The `newly_detected` state considers all newly detected vulnerabilities regardless of their status or dismissal. The other states consider findings that match the selected state and already exist in the default branch. | ## `require_approval` action type @@ -90,8 +90,8 @@ Requirements and limitations: ## Example security scan result policies project -You can use this example in a `.gitlab/security-policies/policy.yml`, as described in -[Security policies project](index.md#security-policies-project): +You can use this example in a `.gitlab/security-policies/policy.yml` file stored in a +[security policy project](index.md#security-policy-project): ```yaml --- diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index d3a79410eea..8f006f258b6 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -81,6 +81,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Go | [Semgrep](https://semgrep.dev) | 14.4 | | Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | | Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | +| Java (any build system) | [Semgrep](https://semgrep.dev) | 14.10 | | Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | | Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | @@ -132,6 +133,30 @@ The following analyzers have multi-project support: Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). +### Supported distributions + +The default scanner images are build off a base Alpine image for size and maintainability. + +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. + +GitLab offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the images that are FIPS-enabled. To use the FIPS-enabled images, you can either: + +- Set the `SAST_IMAGE_SUFFIX` to `-fips`. +- Add the `-fips` extension to the default image name. + +For example: + +```yaml +variables: + SAST_IMAGE_SUFFIX: '-fips' + +include: + - template: Security/SAST.gitlab-ci.yml +``` + ### Making SAST analyzers available to all GitLab tiers All open source (OSS) analyzers have been moved to the GitLab Free tier as of GitLab 13.3. @@ -141,17 +166,17 @@ All open source (OSS) analyzers have been moved to the GitLab Free tier as of Gi Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | -|:---------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | -| [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | -| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | -| [False Positive Detection](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free & Premium | In Ultimate | +|:----------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | +| Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | +| [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -190,28 +215,28 @@ always take the latest SAST artifact available. ### Configure SAST in the UI You can enable and configure SAST in the UI, either with default settings, or with customizations. -Use the method that best meets your needs. +The method you can use depends on your GitLab license tier. -- [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings) -- [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations) +- [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings). +- [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations). **(ULTIMATE)** ### Configure SAST in the UI with default settings > [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + To enable and configure SAST with default settings: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance** > **Configuration**. -1. In the SAST section, select `Enable via MR`. -1. Review the draft MR that enables SAST with the default recommended settings in the - `.gitlab-ci.yml` file. -1. Merge the MR to enable SAST. You should see SAST jobs run in that MR's pipeline. +1. In the SAST section, select **Configure with a merge request**. +1. Review and merge the merge request to enable SAST. -NOTE: -The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal -configuration file. If you have a complex GitLab configuration file it may not be parsed -successfully, and an error may occur. +Pipelines now include a SAST job. ### Configure SAST in the UI with customizations **(ULTIMATE)** @@ -219,27 +244,28 @@ successfully, and an error may occur. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab 13.4. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab 13.5. +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + To enable and configure SAST with customizations: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. -1. If the project does not have a `.gitlab-ci.yml` file, select **Enable** in the Static Application - Security Testing (SAST) row, otherwise select **Configure**. +1. If the project does not have a `.gitlab-ci.yml` file, select **Enable SAST** in the Static + Application Security Testing (SAST) row, otherwise select **Configure SAST**. 1. Enter the custom SAST values. Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST - Configuration page, their values are left unchanged. Default values are inherited from the GitLab - SAST template. + Configuration page, their values are inherited from the GitLab SAST template. 1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Select **Create Merge Request**. 1. Review and merge the merge request. -NOTE: -The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal -configuration file. If you have a complex GitLab configuration file it may not be parsed -successfully, and an error may occur. +Pipelines now include a SAST job. ### Overriding SAST jobs @@ -399,7 +425,7 @@ and `value` of identifiers and then overridden: ``` If a vulnerability is found with a type `CWE` with a value of `703` then -the vulnerability severity is overwritten to `Critical`. +the vulnerability severity is overwritten to `Critical`. #### Synthesize a custom configuration @@ -523,7 +549,7 @@ Several passthrouh types generate a configuration for the target analyzer: the configuration. - If there is a filename collision between files in both repositories, files from the `sast` repository overwrite files from the `myrules` repository, - as `sast-rules` has higher precedence. + as `sast-rules` has higher precedence. - The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The full path is `/sgrules/insecure.yml`. - The `url` entry fetches a configuration made available through a URL and @@ -831,6 +857,7 @@ The following are Docker image-related CI/CD variables. | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SAST_EXCLUDED_ANALYZERS` | Names of default images that should never run. Read more about [customizing analyzers](analyzers.md). | | `SAST_ANALYZER_IMAGE_TAG` | Override the default version of analyzer image. Read more about [pinning the analyzer image version](#pinning-to-minor-image-version). | +| `SAST_IMAGE_SUFFIX` | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355518) in GitLab 14.10. | #### Vulnerability filters @@ -936,7 +963,7 @@ To use SAST in an offline environment, you need: - A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Configure certificate checking of packages (optional). -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull_policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -990,7 +1017,7 @@ Support for custom certificate authorities was introduced in the following versi | `phpcs-security-audit` | [v2.8.2](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit/-/releases/v2.8.2) | | `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | | `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | -| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/releases/v0.0.1) | +| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/releases/v0.0.1) | | `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | | `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 582497eb465..0a18e7d5f45 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -60,13 +60,14 @@ as shown in the following table: | Capability | In Free & Premium | In Ultimate | |:----------------------------------------------------------------|:--------------------|:-------------------| -| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in merge request | **{dotted-circle}** | **{check-circle}** | +| [Configure Secret Detection scanner](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize Secret Detection settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | +| Download [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | +| See new findings in the merge request widget | **{dotted-circle}** | **{check-circle}** | | View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** | **{check-circle}** | -| [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Configuration @@ -107,25 +108,48 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. +### Supported distributions + +The default scanner images are build off a base Alpine image for size and maintainability. + +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. + +GitLab offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the images that are FIPS-enabled. To use the FIPS-enabled images, you can either: + +- Set the `SAST_IMAGE_SUFFIX` to `-fips`. +- Add the `-fips` extension to the default image name. + +For example: + +```yaml +variables: + SECRET_DETECTION_IMAGE_SUFFIX: '-fips' + +include: + - template: Security/Secret-Detection.gitlab-ci.yml +``` + ### Enable Secret Detection via an automatic merge request > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, deployed behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1. -To enable Secret Detection in a project, you can create a merge request -from the Security Configuration page. +NOTE: +This method works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration +file. If you have a complex GitLab configuration file it may not be parsed successfully, and an +error may occur. -1. In the project where you want to enable Secret Detection, go to - **Security & Compliance > Configuration**. -1. In the **Secret Detection** row, select **Configure with a merge request**. +To enable Secret Detection in a project, you can create a merge request: -This automatically creates a merge request with the changes necessary to enable Secret Detection -that you can review and merge to complete the configuration. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **Secret Detection** row, select **Configure with a merge request**. +1. Review and merge the merge request to enable Secret Detection. -NOTE: -The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal -configuration file. If you have a complex GitLab configuration file it may not be parsed -successfully, and an error may occur. +Pipelines now include a Secret Detection job. ### Customizing settings @@ -176,6 +200,7 @@ Secret Detection can be customized by defining available CI/CD variables: | `SECRET_DETECTION_COMMITS` | - | The list of commits that Gitleaks should scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. | | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | +| `SECRET_DETECTION_IMAGE_SUFFIX` | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355519) in GitLab 14.10. | ### Custom rulesets **(ULTIMATE)** diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index a0cfd6d9d77..488ec336646 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -52,6 +52,9 @@ To view vulnerabilities in a pipeline: 1. From the list, select the pipeline you want to check for vulnerabilities. 1. Select the **Security** tab. +**Scan details** shows vulnerabilities introduced by the merge request, in addition to existing vulnerabilities +from the latest successful pipeline in your project's default branch. + A pipeline consists of multiple jobs, such as SAST and DAST scans. If a job fails to finish, the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, @@ -66,7 +69,8 @@ To view the total number of vulnerabilities per scan: 1. Select the **Status** of a branch. 1. Select the **Security** tab. -**Scan details** show the total number of vulnerabilities found per scan in the pipeline. +**Scan details** shows vulnerabilities introduced by the merge request, in addition to existing vulnerabilities +from the latest successful pipeline in your project's default branch. ### Download security scan outputs diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 390882d4326..9b8dd2825ea 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Threat Monitoring is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. The **Threat Monitoring** page provides alerts and metrics diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 0b27760b4bb..18b99e06299 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -28,7 +28,7 @@ On the vulnerability's page, you can: - [Create an issue](#create-an-issue-for-a-vulnerability). - [Link issues to the vulnerability](#linked-issues). - [Resolve a vulnerability](#resolve-a-vulnerability) if a solution is - available. + available. - [View security training specific to the detected vulnerability](#view-security-training-for-a-vulnerability). ## Vulnerability status values diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index eb59c289700..a9cef15e3e8 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -222,12 +222,8 @@ To undo this action, select a different status from the same menu. ## Manually add a vulnerability finding -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. - -FLAG: -This feature is not enabled by default. To make it available, ask an administrator to -[enable the feature flag](../../feature_flags.md) named `new_vulnerability_form`. -On GitLab.com, this feature is not yet available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353796) in GitLab 14.10. To add a new vulnerability finding from your project level Vulnerability Report page: @@ -236,7 +232,7 @@ To add a new vulnerability finding from your project level Vulnerability Report 1. Click on **Submit Vulnerability**. 1. Complete the fields and submit the form. -You will be brought to the newly created vulnerability's detail page. Manually created records appear in the +You will be brought to the newly created vulnerability's detail page. Manually created records appear in the Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. ## Operational vulnerabilities |
