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/#designated-technical-writers
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.
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),
you can run fuzz tests as part your CI/CD workflow.
## Requirements
- One of the following web API types:
- REST API
- SOAP
- GraphQL
- Form bodies, JSON, or XML
- An OpenAPI definition, or HTTP Archive (HAR) of requests to test
## When fuzzing scans run
When using the `API-Fuzzing.gitlab-ci.yml` template, the `fuzz` job runs last, as shown here. To
ensure API fuzzing scans the latest code, your CI pipeline should deploy changes to a test
environment in one of the jobs preceding the `fuzz` job:
```yaml
stages:
-build
-test
-deploy
-fuzz
```
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 fuzzing scan. The only changes to the API should be from the fuzzing 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.
## Configuration
There are two ways to perform scans. See the configuration section for the one you wish to use:
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.
Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification:
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. Provide the location of the OpenAPI v2 specification. You can provide the specification as a file
or URL. Specify the location by adding the `FUZZAPI_OPENAPI` variable:
```yaml
include:
-template:API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_PROFILE:Quick-10
FUZZAPI_OPENAPI:test-api-specification.json
```
1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL`
variable:
```yaml
include:
-template:API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_PROFILE:Quick-10
FUZZAPI_OPENAPI:test-api-specification.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: **Danger:**
**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.
### 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 GitLab's API fuzzer, HAR
must contain records of calling the web API to test. The API fuzzer extracts all the requests and
uses them to perform testing.
You can use various tools to generate HAR files:
-[Fiddler](https://www.telerik.com/fiddler): Web debugging proxy
-[Insomnia Core](https://insomnia.rest/): API client
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 API fuzzing to use a HAR 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_HAR` variable and set it to the HAR file's location:
```yaml
include:
-template:API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_PROFILE:Quick-10
FUZZAPI_HAR:test-api-specification.json
```
1. Add the `FUZZAPI_TARGET_URL` variable and set it to the target API instance's base URL:
```yaml
include:
-template:API-Fuzzing.gitlab-ci.yml
variables:
FUZZAPI_PROFILE:Quick-10
FUZZAPI_HAR:test-api-specification.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: **Danger:**
**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.
### 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.
| `FUZZAPI_D_WORKER_PORTS` |Custom worker docker port options |
| `FUZZAPI_D_NETWORK` |Name of docker network, defaults to "testing-net"|
| `FUZZAPI_D_PRE_SCRIPT` |Pre script runs after docker login and docker network create, but before starting the scanning image container.|
| `FUZZAPI_D_POST_SCRIPT` |Post script runs after scanning image container is started. This is the place to start your target(s) and kick off scanning when using an advanced configuration.| -->
### 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
[authentication section](#authentication) includes examples of using overrides for that purpose.
Overrides uses a JSON document to define the headers and cookies:
```json
{
"headers":{
"header1":"value",
"header2":"value"
},
"cookies":{
"cookie1":"value",
"cookie2":"value"
}
}
```
Example usage for setting a single header:
```json
{
"headers":{
"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
}
}
```
Example usage for setting both a header and cookie:
```json
{
"headers":{
"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="
},
"cookies":{
"flags":"677"
}
}
```
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
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.
