doc/user/application_security/api_fuzzing/_index.md
{{< details >}}
{{< /details >}}
Web API fuzz testing passes unexpected values to API operation parameters to cause unexpected behavior and errors in the backend. Use fuzz testing to discover bugs and potential vulnerabilities that other QA processes might miss.
You should use fuzz testing in addition to the other security scanners in GitLab Secure and your own test processes. If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow.
<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see Web API fuzzing - Advanced Security Testing.
Get started with API fuzzing by editing your CI/CD configuration.
Prerequisites:
A web API using one of the supported API types:
An API specification in one of the following formats:
An available GitLab Runner with the docker executor on Linux/amd64.
A deployed target application.
The fuzz stage is added to your CI/CD pipeline definition, after the deploy stage:
stages:
- build
- test
- deploy
- fuzz
To enable API fuzzing:
Use the Web API fuzzing configuration form.
The form lets you choose values for the most common API fuzzing options, and builds a YAML snippet that you can paste in your GitLab CI/CD configuration.
To view the output of a security scan:
You can also download the security scan results:
For more details, see the pipeline security report.
[!note] Findings are generated on feature branches. When they are merged into the default branch, they become vulnerabilities. This distinction is important when evaluating your security posture.
To get the most out of API fuzzing, follow these recommendations:
To run the latest versions of the analyzers, configure runners to use pull_policy: always.
By default, API fuzzing downloads all artifacts defined by previous jobs in the pipeline. If your
API fuzzing job does not rely on environment_url.txt to define the URL under test or any other
files created in previous jobs, you should not download artifacts.
To avoid downloading artifacts, extend the analyzer CI/CD job to specify no dependencies.
For example, for the API fuzzing analyzer, add the following to your .gitlab-ci.yml file:
apifuzzer_fuzz:
dependencies: []
API fuzzing requires a deployed application to be available to scan.
Depending on the complexity of the target application, there are a few options as to how to deploy and configure the API fuzzing template.
Review apps are the most involved method of deploying your API fuzzing target application. To assist in the process, GitLab created a review app deployment using Google Kubernetes Engine (GKE). This example can be found in the Review apps - GKE project, plus detailed instructions to configure review apps in DAST.
If your application uses Docker containers, you have another option for deploying and scanning with API fuzzing. After your Docker build job completes and your image is added to your container registry, you can use the image as a service.
By using service definitions in your .gitlab-ci.yml, you can scan services with the DAST analyzer.
When adding a services section to the job, the alias is used to define the hostname that can be used to access the service. In the following example, the alias: yourapp portion of the dast job definition means that the URL to the deployed application uses yourapp as the hostname: https://yourapp/.
stages:
- build
- fuzz
include:
- template: API-Fuzzing.gitlab-ci.yml
# Deploys the container to the GitLab container registry
deploy:
services:
- name: docker:dind
alias: dind
image: docker:20.10.16
stage: build
script:
- docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
- docker pull $CI_REGISTRY_IMAGE:latest || true
- docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
- docker push $CI_REGISTRY_IMAGE:latest
apifuzzer_fuzz:
services: # use services to link your app container to the dast job
- name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
alias: yourapp
variables:
FUZZAPI_TARGET_URL: https://yourapp
Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate
with each another. To allow communication between services, enable the FF_NETWORK_PER_BUILD feature flag.
variables:
FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network
services: # use services to link the container to the dast job
- name: mongo:latest
alias: mongo
- name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
alias: yourapp
Web API fuzzing runs in the fuzz stage of the CI/CD pipeline. To ensure API fuzzing scans the
latest code, your CI/CD pipeline should deploy changes to a test environment in one of the stages
preceding the fuzz stage.
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. 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.
You can run a web API fuzzing scan using the following methods:
To get support for your particular problem use the getting help channels.
The GitLab issue tracker on GitLab.com is the right place for bugs and feature proposals about API security and API fuzzing.
Use ~"Category:API Security" label when opening a new issue regarding API fuzzing to ensure it is quickly reviewed by the right people.
Search the issue tracker for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an emoji reaction or join the discussion.
When experiencing a behavior not working as expected, consider providing contextual information:
.gitlab-ci.yml job definition.gl-api-security-scanner.log.[!warning] Do not include sensitive information when you submit an issue. Remove credentials like passwords, tokens, and keys.