diff options
Diffstat (limited to 'doc/user/application_security/api_fuzzing/index.md')
| -rw-r--r-- | doc/user/application_security/api_fuzzing/index.md | 165 |
1 files changed, 85 insertions, 80 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 674afcb29ee..49311ccc7cd 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -69,7 +69,7 @@ Examples of both configurations can be found here: The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing by using an OpenAPI specification to provide information about the target API to test. OpenAPI specifications -are provided as a filesystem resource or URL. +are provided as a file system resource or URL. Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: @@ -89,7 +89,7 @@ Follow these steps to configure API fuzzing in GitLab with an OpenAPI specificat 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, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -182,7 +182,7 @@ target API to test: 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, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -273,7 +273,7 @@ information about the target API to test: 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, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -335,16 +335,17 @@ provide a script that performs an authentication flow or calculates the token. #### HTTP Basic Authentication [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) -is an authentication method built into the HTTP protocol and used in-conjunction with +is an authentication method built in to the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -To use HTTP basic authentication, two variables are added to your `.gitlab-ci.yml` file: +To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab-ci.yml` file: - `FUZZAPI_HTTP_USERNAME`: The username for authentication. - `FUZZAPI_HTTP_PASSWORD`: The password for authentication. For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) (for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the -GitLab projects page at **Settings > CI/CD**, in the **Variables** section. +GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable +as the value for `FUZZAPI_HTTP_PASSWORD`: ```yaml include: @@ -356,7 +357,6 @@ variables: FUZZAPI_TARGET_URL: http://test-deployment/ FUZZAPI_HTTP_USERNAME: testuser FUZZAPI_HTTP_PASSWORD: $TEST_API_PASSWORD - ``` #### Bearer Tokens @@ -371,36 +371,39 @@ tokens with API fuzzing, you need one of the following: ##### Token doesn't expire -If the bearer token doesn't expire, you can provide it using the `FUZZAPI_OVERRIDES_ENV` variable. -The `FUZZAPI_OVERRIDES_ENV` content is a JSON snippet that provides headers and cookies that should -be added to outgoing HTTP requests made by API fuzzing. +If the bearer token doesn't expire, use the `FUZZAPI_OVERRIDES_ENV` variable to provide it. This +variable's content is a JSON snippet that provides headers and cookies to add to API fuzzing's +outgoing HTTP requests. -Create a CI/CD variable, for example `TEST_API_BEARERAUTH`, with the value -`{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can -create CI/CD variables from the GitLab projects page at **Settings > CI/CD** in the **Variables** -section. +Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: -Set `FUZZAPI_OVERRIDES_ENV` in your `.gitlab-ci.yml` file: +1. [Create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), + for example `TEST_API_BEARERAUTH`, with the value + `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You + can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the + **Variables** section. -```yaml -include: - - template: API-Fuzzing.gitlab-ci.yml +1. In your `.gitlab-ci.yml` file, set `FUZZAPI_OVERRIDES_ENV` to the variable you just created: -variables: - FUZZAPI_PROFILE: Quick-10 - FUZZAPI_OPENAPI: test-api-specification.json - FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH -``` + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml -To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and -the test API's application logs. + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH + ``` + +1. To validate that authentication is working, run an API fuzzing test and review the fuzzing logs + and the test API's application logs. -##### Token generated at test-runtime +##### Token generated at test runtime -If the bearer token must be generated, and the resulting token doesn't expire during testing, you -can provide to API fuzzing a file containing the token. This file can be generated by a prior stage -and job, or as part of the API fuzzing job. +If the bearer token must be generated and doesn't expire during testing, you can provide to API +fuzzing a file containing the token. A prior stage and job, or part of the API fuzzing job, can +generate this file. API fuzzing expects to receive a JSON file with the following structure: @@ -413,7 +416,7 @@ API fuzzing expects to receive a JSON file with the following structure: ``` This file can be generated by a prior stage and provided to API fuzzing through the -`FUZZAPI_OVERRIDES_FILE` variable. +`FUZZAPI_OVERRIDES_FILE` CI/CD variable. Set `FUZZAPI_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: @@ -448,11 +451,13 @@ The script must create a JSON file containing the bearer token in a specific for } ``` -You must provide three variables, each set for correct operation: +You must provide three CI/CD variables, each set for correct operation: -- `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. -- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. -- `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. +- `FUZZAPI_OVERRIDES_FILE`: JSON file the provided command generates. +- `FUZZAPI_OVERRIDES_CMD`: Command that generates the JSON file. +- `FUZZAPI_OVERRIDES_INTERVAL`: Interval (in seconds) to run command. + +For example: ```yaml include: @@ -472,35 +477,35 @@ the test API's application logs. ### Configuration files -To get started quickly, GitLab provides you with the configuration file +To get you started quickly, GitLab provides the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml). -This file has several testing profiles that perform various amounts of testing. The run time of each -increases as the numbers go up. To use a configuration file, add it to your repository's root as -`.gitlab-api-fuzzing.yml`. +This file has several testing profiles that perform various numbers of tests. The run time of each +profile increases as the test numbers go up. To use a configuration file, add it to your +repository's root as `.gitlab-api-fuzzing.yml`. -| Profile | Scan Type | +| Profile | Fuzz Tests (per parameter) | |:---------|:-----------| -|Quick-10 |Fuzzing 10 times per parameter | -|Medium-20 |Fuzzing 20 times per parameter | -|Medium-50 |Fuzzing 50 times per parameter | -|Long-100 |Fuzzing 100 times per parameter | - -### Available variables - -| Environment variable | Description | -|-----------------------------|--------------------| -| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | -| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | -|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | -|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | -| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | -|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | -|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | -|[`FUZZAPI_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. | -|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | +| Quick-10 | 10 | +| Medium-20 | 20 | +| Medium-50 | 50 | +| Long-100 | 100 | + +### Available CI/CD variables + +| CI/CD variable | Description | +|------------------------------------------------------|--------------------| +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | +|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | +|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | +|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`FUZZAPI_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. | +|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | |[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | |[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | @@ -518,11 +523,11 @@ increases as the numbers go up. To use a configuration file, add it to your repo ### Overrides -API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests -made. You can use this to inject semver headers, authentication, and so on. The +API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests. +You can use this to inject semantic version headers, authentication, and so on. The [authentication section](#authentication) includes examples of using overrides for that purpose. -Overrides uses a JSON document to define the headers and cookies: +Overrides use a JSON document to define the headers and cookies: ```json { @@ -537,7 +542,7 @@ Overrides uses a JSON document to define the headers and cookies: } ``` -Example usage for setting a single header: +Example of setting a single header: ```json { @@ -547,7 +552,7 @@ Example usage for setting a single header: } ``` -Example usage for setting both a header and cookie: +Example of setting both a header and cookie: ```json { @@ -560,14 +565,14 @@ Example usage for setting both a header and cookie: } ``` -You can provide this JSON document as a file or environment variable. You may also provide a command +You can provide this JSON document as a file or CI/CD variable. You may also provide a command to generate the JSON document. The command can run at intervals to support values that expire. #### Using a file -To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` environment variable is set. The path is relative to the job current working directory. +To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` CI/CD variable is set. The path is relative to the job current working directory. -Example `.gitlab-ci.yml`: +Here's an example `.gitlab-ci.yml`: ```yaml include: @@ -580,12 +585,12 @@ variables: FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json ``` -#### Using an environment variable +#### Using a CI/CD variable -To provide the overrides JSON as an environment variable, use the `FUZZAPI_OVERRIDES_ENV` variable. -This allows you to place the JSON as CI/CD variables that can be masked and protected. +To provide the overrides JSON as a CI/CD variable, use the `FUZZAPI_OVERRIDES_ENV` variable. +This allows you to place the JSON as variables that can be masked and protected. -In this example `.gitlab-ci.yml`, the JSON is provided directly: +In this example `.gitlab-ci.yml`, the `FUZZAPI_OVERRIDES_ENV` variable is set directly to the JSON: ```yaml include: @@ -598,8 +603,8 @@ variables: FUZZAPI_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}' ``` -In this example `.gitlab-ci.yml`, the CI/CD variable `SECRET_OVERRIDES` provides the JSON. This is a -[group or instance level environment variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-environment-variables): +In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-variables): ```yaml include: @@ -620,7 +625,7 @@ container that has Python 3 and Bash installed. If the Python script requires ad it must detect this and install the packages at runtime. The script creates the overrides JSON file as defined above. -You must provide three variables, each set for correct operation: +You must provide three CI/CD variables, each set for correct operation: - `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. - `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. @@ -689,9 +694,9 @@ for off. To turn header fuzzing on, change this setting to `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: +`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. To fuzz a header used by +your APIs, add an entry for it using the syntax `- Name: HeaderName`. For example, to fuzz a +custom header `X-Custom`, add `- Name: X-Custom`: ```yaml - Name: GeneralFuzzingCheck |