The main goal of this repository is to provide examples of how to use REST API Fuzzing tools for automatically testing cloud services through their REST APIs and finding security and reliability bugs in these services.
Maintaining high-quality APIs is expensive. It's difficult to write unit/integration tests that cover all edge-cases corner-cases and find all security vulnerabilities. These APIs are consantly evolving, imply an increased attack surface and thus increasing demand for testing to keep up.
Also, working with legacy systems without proper test raise in an increased need to provide coverage in order to reduce the cost of development.
Rest API Fuzzers are able to find the following classes of bugs:
- API Specification
- Input validation
- Data leaks
- Resource leaks
- Security vulnerabilities
- Regression
Below you can find examples of REST API Fuzzers. Each tool is capable of automatically testing your APIs based on Swagger/OpenApi specification.
| Tool | Description |
|---|---|
| ZAP | Primary, ZAP is web app scanner. ZAP can test REST and SOAP APIs. Developed by OWASP community. |
| RESTler | Stateful API Fuzzer. Resources created by earlier requests are consumed by subsequent requests. Developed by Microsoft. |
| Dredd | Ability to build test similar to unit-test using hooks. Hooks allows us to setup context and clean-up after a tests execution |
| Schemathesis | Supports REST and GraphQL |
| GitLab API Fuzzer | Build-in API fuzzer. The fuzzer is avaiable in GitLab Ultimate |
This repository contains 2 examples of API Fuzzer usage:
- ZAP
- RESTler
I decided to use spring-petclinic-rest for testing. Spring-petclinic-rest is a clone of very popular Spring Pet Clinic Demo Project. This app provides REST API and exposes Swagger/OpenAPI specification.
The app is available on DockerHub. Running the app under tests:
docker run -p 9966:9966 springcommunity/spring-petclinic-restRest API definition: http://localhost:9966/petclinic
API docs: http://localhost:9966/petclinic/v2/api-docs
ZAP is used for API security testing. Zed Attack Proxy (ZAP) is a free, open-source penetration testing tool. At its core, ZAP is what is known as a “man-in-the-middle proxy.” For this use case, ZAP is run in headless mode with additional add-ons. During the test, ZAP:
- Imports the Rest API definition
- Scans the API
- Reports issues
This example runs default Scan Policy tuned for APIs:
# run the app under tests
docker run --rm -d -p 9966:9966 --name petclinic-rest springcommunity/spring-petclinic-rest
#start fuzzing in debug mode
docker run --rm --link petclinic-rest -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-weekly zap-api-scan.py -t http://petclinic-rest:9966/petclinic/v2/api-docs -f openapi -r api_zap_report.html -d
#cleanup after fuzzing
docker rm -f petclinic-restAll start-up parameters are well documented on ZAP webpage.
The test takes a few minutes, depends on your scan policy.
After successful scan, you can find report api_zap_report.html in your working directory.
ZAP Report contains list of issues. For each issue, ZAP provides exact details and a solution.
RESTler is a stateful REST API fuzzing tool for automatically testing. For a given OpenAPI/Swagger specification, RESTler analyzes its entire specification and then generates and executes tests that exercise the service through its REST API.
RESTler provides a docker image but the official docker image is not very convenient for simple usage.
This example uses simplified RESTler docker image.
Before you start fuzzing, you have to clone repository restler-fuzzer-getting-started and build docker image according to README.
Running Rest API fuzzing:
cd ./restler
# run the app under tests
docker run -d --rm -p 9966:9966 --name petclinic-rest springcommunity/spring-petclinic-rest
#start fuzzing
docker run --rm --link petclinic-rest -v $(pwd):/fuzzer:rw wkoszolko/restler-fuzzer-getting-started fuzz --compilation_config=config.json --settings=engine_settings.json --no_ssl=true
#cleanup after fuzzing
docker rm -f petclinic-restRESTler has multiple variants of fuzzing:
- smoke tests
- fuzz-lean
- fuzzing
The example runs all tree types of test. After successful scan, you can find tests results and logs in ./restler directory.
List of aggregated results:
- restler/Test/ResponseBuckets/errorBuckets.json
- restler/Test/ResponseBuckets/runSummary.json
- restler/FuzzLean/ResponseBuckets/errorBuckets.json
- restler/FuzzLean/ResponseBuckets/runSummary.json
- restler/Fuzz/ResponseBuckets/errorBuckets.json
- restler/Fuzz/ResponseBuckets/runSummary.json
ZAP and RESTler fuzzers are able to find multiple API issues. Most of the problems are related to API design and the quality of the implementation.
Fuzzing spring-petclinic-rest finds the following issues:
- Low quality of API documentation: lack of examples in API docs leads to lower coverage.
- API design issues: using database entities as API input parameters. If the client sets id filed, the API crashes because the id field is set by an identity column.
- Security vulnerabilities e.g improper error handling: error response often provides useful information to an attacker (stack trace, name of libraries, and frameworks).