diff options
Diffstat (limited to 'doc/user/application_security/api_fuzzing/index.md')
| -rw-r--r-- | doc/user/application_security/api_fuzzing/index.md | 192 |
1 files changed, 185 insertions, 7 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 145422f8736..57c5f8bc1fa 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -8,9 +8,10 @@ type: reference, howto # Web API Fuzz Testing **(ULTIMATE)** You can add web API fuzzing to your [GitLab CI/CD](../../../ci/README.md) -pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. -API fuzzing performs fuzz testing of API operation parameters. -Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API backend. +pipelines. This helps you discover bugs and potential security issues that other QA processes may +miss. API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation +parameters to unexpected values in an effort to cause unexpected behavior and errors in the API +backend. We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), @@ -23,7 +24,10 @@ you can run fuzz tests as part your CI/CD workflow. - SOAP - GraphQL - Form bodies, JSON, or XML -- An OpenAPI definition, or HTTP Archive (HAR) of requests to test +- One of the following assets to provide APIs to test: + - OpenAPI v2 API definition + - HTTP Archive (HAR) of API requests to test + - Postman Collection v2.0 or v2.1 ## When fuzzing scans run @@ -48,15 +52,17 @@ changes, other pipelines, or other scanners) during a scan could cause inaccurat ## Configuration -There are two ways to perform scans. See the configuration section for the one you wish to use: +There are three ways to perform scans. See the configuration section for the one you wish to use: - [OpenAPI v2 specification](#openapi-specification) - [HTTP Archive (HAR)](#http-archive-har) +- [Postman Collection v2.0 or v2.1](#postman-collection) Examples of both configurations can be found here: - [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) +- [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) ### OpenAPI Specification @@ -133,7 +139,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Danger:** +DANGER: **Warning:** **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -224,7 +230,98 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Danger:** +DANGER: **Warning:** +**NEVER** run fuzz testing against a production server. Not only can it perform *any* function that +the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting +data. Only run fuzzing against a test server. + +### Postman Collection + +The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that +developers and testers use to call various types of APIs. The API definitions +[can be exported as a Postman Collection file](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-postman-data) +for use with API Fuzzing. When exporting, make sure to select a supported version of Postman +Collection: v2.0 or v2.1. + +When used with GitLab's API fuzzer, Postman Collections must contain definitions of the web API to +test with valid data. The API fuzzer extracts all the API definitions and uses them to perform +testing. + +DANGER: **Warning:** +Postman Collection files may contain sensitive information such as authentication tokens, API keys, +and session cookies. We recommend that you review the Postman Collection file contents before adding +them to a repository. + +Follow these steps to configure API fuzzing to use a Postman Collection file that provides +information about the target API to test: + +1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + ``` + +1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) + to your repository's root as `.gitlab-api-fuzzing.yml`. + +1. The [configuration file](#configuration-files) has several testing profiles defined with varying + amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this + profile completes quickly, allowing for easier configuration validation. + + Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + substituting `Quick-10` for the profile you choose: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + ``` + +1. Add the `FUZZAPI_POSTMAN_COLLECTION` variable and set it to the Postman Collection's location: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + ``` + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `FUZZAPI_TARGET_URL`: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + FUZZAPI_TARGET_URL: http://test-deployment/ + ``` + +This is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +DANGER: **Warning:** **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -398,6 +495,7 @@ increases as the numbers go up. To use a configuration file, add it to your repo | `FUZZAPI_REPORT` |Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | |[`FUZZAPI_OPENAPI`](#openapi-specification)|OpenAPI specification file or URL. | |[`FUZZAPI_HAR`](#http-archive-har)|HTTP Archive (HAR) file. | +|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection)|Postman Collection file. | |[`FUZZAPI_OVERRIDES_FILE`](#overrides) |Path to a JSON file containing overrides. | |[`FUZZAPI_OVERRIDES_ENV`](#overrides) |JSON string containing headers to override. | |[`FUZZAPI_OVERRIDES_CMD`](#overrides) |Overrides command. | @@ -540,6 +638,86 @@ variables: FUZZAPI_OVERRIDES_INTERVAL: 300 ``` +### Header Fuzzing + +Header fuzzing is disabled by default due to the high number of false positives that occur with many +technology stacks. When header fuzzing is enabled, you must specify a list of headers to include in +fuzzing. + +Each profile in the default configuration file has an entry for `GeneralFuzzingCheck`. This check +performs header fuzzing. Under the `Configuration` section, you must change the `HeaderFuzzing` and +`Headers` settings to enable header fuzzing. + +This snippet shows the `Quick-10` profile's default configuration with header fuzzing disabled: + +```yaml +- Name: Quick-10 + DefaultProfile: Empty + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: false + Headers: + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +`HeaderFuzzing` is a boolean that turns header fuzzing on and off. The default setting is `false` +for off. To turn header fuzzing on, change this setting to `true`: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: +``` + +`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. For example, to fuzz a +custom header `X-Custom` used by your APIs, add an entry for it using the syntax +`- Name: HeaderName`, substituting `HeaderName` with the header to fuzz: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom +``` + +You now have a configuration to fuzz the header `X-Custom`. Use the same notation to list additional +headers: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom + - Name: X-AnotherHeader +``` + +Repeat this configuration for each profile as needed. + ## Running your first scan When configured correctly, a CI/CD pipeline contains a `Fuzz` stage and a `apifuzzer_fuzz` job. The |