diff options
Diffstat (limited to 'doc/user/application_security/api_fuzzing/index.md')
| -rw-r--r-- | doc/user/application_security/api_fuzzing/index.md | 95 |
1 files changed, 57 insertions, 38 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index b65e5cd703a..49311ccc7cd 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -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 @@ -337,8 +337,7 @@ provide a script that performs an authentication flow or calculates the token. [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 [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). - -To use HTTP basic authentication, add these two variables 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. @@ -358,7 +357,6 @@ variables: FUZZAPI_TARGET_URL: http://test-deployment/ FUZZAPI_HTTP_USERNAME: testuser FUZZAPI_HTTP_PASSWORD: $TEST_API_PASSWORD - ``` #### Bearer Tokens @@ -417,8 +415,10 @@ API fuzzing expects to receive a JSON file with the following structure: } ``` -You can provide this file to API fuzzing through the `FUZZAPI_OVERRIDES_FILE` variable, in your -`.gitlab-ci.yml` file: +This file can be generated by a prior stage and provided to API fuzzing through the +`FUZZAPI_OVERRIDES_FILE` CI/CD variable. + +Set `FUZZAPI_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: ```yaml include: @@ -451,7 +451,7 @@ 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`: JSON file the provided command generates. - `FUZZAPI_OVERRIDES_CMD`: Command that generates the JSON file. @@ -490,24 +490,24 @@ repository's root as `.gitlab-api-fuzzing.yml`. | Medium-50 | 50 | | Long-100 | 100 | -### 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). | -| [`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | -| [`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | +### 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. | <!--|[`FUZZAPI_D_TARGET_IMAGE`](#target-container) |API target docker image | |[`FUZZAPI_D_TARGET_ENV`](#target-container) |Docker environment options | @@ -565,13 +565,12 @@ Example of 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 override JSON as a file, set the `FUZZAPI_OVERRIDES_FILE` environment variable to the -file. The file path is relative to the job's 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. Here's an example `.gitlab-ci.yml`: @@ -586,10 +585,10 @@ variables: FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json ``` -#### Using an environment variable +#### Using a CI/CD variable -To provide the override JSON as an environment variable, set the `FUZZAPI_OVERRIDES_ENV` variable to -the JSON. You can also 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 `FUZZAPI_OVERRIDES_ENV` variable is set directly to the JSON: @@ -604,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-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: @@ -621,9 +620,29 @@ variables: #### Using a command If the value must be generated or regenerated on expiration, you can provide a program or script for -the API fuzzer to execute on a specified interval. To do this, follow the instructions in the -section [Token has short expiration](#token-has-short-expiration), -which uses the same three variables. The script creates the overrides JSON file as defined. +the API fuzzer to execute on a specified interval. The provided script runs in an Alpine Linux +container that has Python 3 and Bash installed. If the Python script requires additional packages, +it must detect this and install the packages at runtime. The script creates the overrides JSON file +as defined above. + +You must provide three 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. + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_CMD: renew_token.py + FUZZAPI_OVERRIDES_INTERVAL: 300 +``` ### Header Fuzzing |