Merge branch '345950-document-openapi-relaxed-validation' into 'master'

Document OPENAPI_RELAXED_VALIDATION in API Fuzz and DAST API

See merge request gitlab-org/gitlab!77030

doc/user/application_security/api_fuzzing/index.md

@@ -572,6 +572,7 @@ profile increases as the number of tests increases.
 |[`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_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_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. |
@@ -1293,6 +1294,41 @@ The API Fuzzing template supports launching a docker container containing an API
 TODO
 -->
 
+### Use OpenAPI with an invalid schema
+
+There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors.
+
+#### Edit a non-compliant OpenAPI file
+
+To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include:
+
+| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x |
+| -- | -- | -- | -- |
+| [Swagger Editor](https://editor.swagger.io/) | [X] YAML, JSON | [X] YAML, JSON | [ ] YAML, JSON |
+| [Stoplight Studio](https://stoplight.io/studio/) | [X] YAML, JSON | [X] YAML, JSON | [X] YAML, JSON |
+
+If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using.
+
+#### Enable OpenAPI relaxed validation
+
+Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema.
+
+API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION` to any value, for example:
+
+```yaml
+   stages:
+     - fuzz
+
+   include:
+     - template: API-Fuzzing.gitlab-ci.yml
+
+   variables:
+     FUZZAPI_PROFILE: Quick-10
+     FUZZAPI_TARGET_URL: http://test-deployment/
+     FUZZAPI_OPENAPI: test-api-specification.json
+     FUZZAPI_OPENAPI_RELAXED_VALIDATION: On
+```
+
 ## 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/).

doc/user/application_security/dast_api/index.md

@@ -637,6 +637,7 @@ can be added, removed, and modified by creating a custom configuration.
 |[`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_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_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. |
@@ -1209,6 +1210,41 @@ deploy-test-target:
       - environment_url.txt
 ```
 
+### Use OpenAPI with an invalid schema
+
+There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `DAST_API_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors.
+
+#### Edit a non-compliant OpenAPI file
+
+To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include:
+
+| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x |
+| -- | -- | -- | -- |
+| [Swagger Editor](https://editor.swagger.io/) | [X] YAML, JSON | [X] YAML, JSON | [ ] YAML, JSON |
+| [Stoplight Studio](https://stoplight.io/studio/) | [X] YAML, JSON | [X] YAML, JSON | [X] YAML, JSON |
+
+If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using.
+
+#### Enable OpenAPI relaxed validation
+
+Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema.
+
+API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `DAST_API_OPENAPI_RELAXED_VALIDATION` to any value, for example:
+
+```yaml
+   stages:
+     - dast
+
+   include:
+     - template: DAST-API.gitlab-ci.yml
+
+   variables:
+     DAST_API_PROFILE: Quick
+     DAST_API_TARGET_URL: http://test-deployment/
+     DAST_API_OPENAPI: test-api-specification.json
+     DAST_API_OPENAPI_RELAXED_VALIDATION: On
+```
+
 ## 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/).