OpenAPI fuzzer
Black-box fuzzer that fuzzes APIs based on OpenAPI specification. All you need to do is to supply URL of the API and its specification. Find bugs for free!
Findings
The fuzzer has been used to find bugs in numerous software. Some of the well-known fuzzed software include1:
- Kubernetes
- Gitea
- Vault
The category of bugs differ, but some of the common are parsing bugs, invalid format bugs and querying non-existent entities. If you have found bugs with this fuzzer, please reach out to me. I would love to hear from you. Feel free to submit a PR and add your finding to the list above.
Building & installing
To build the fuzzer, you will need to have rust installed.
# Install from crates.io
cargo install openapi-fuzzer
# Or download the repo and build locally
git clone [email protected]:matusf/openapi-fuzzer.git
cd openapi-fuzzer
# Install to the $PATH
cargo install --path .
# Or build (add --releade to build optimized binary) inside the repo
cargo build
Usage
After installation you will have two binaries, openapi-fuzzer and openapi-fuzzer-resender. The openapi-fuzzer will fuzz the API according to the specification and report any findings. All findings will be located in a results directory in a JSON format. After you are done with fuzzing, you can use openapi-fuzzer-resender to resend payloads that triggered a bugs and examine the cause in depth.
Tips
- When the fuzzer receives an unexpected status code, it will report is as a finding. However, many APIs do not specify client error status codes in the specification. To minimize false positive findings ignore status codes that you are not interested in with
-iflag. It is adviced to fuzz it two stages. Firstly, run the fuzzer without-iflag for a minute. Then checkresultsfolder for the reported findings. If there are reports from status codes you do not care about, add them via-iflag and rerun the fuzzer. - Most APIs use some base prefix for endpoints like
/v1or/api, however, the specifications are sometimes writen without it. Do not forget to include the path prefix in the url. - You may add an extra header with
-Hflag. It may be useful when you would like to increase coverage by providing some sort of authorization.
$ openapi-fuzzer --help
Usage: openapi-fuzzer -s <spec> -u <url> [-i <ignore-status-code>] [-H <header>]
OpenAPI fuzzer
Options:
-s, --spec path to OpenAPI specification
-u, --url url of api to fuzz
-i, --ignore-status-code
status codes that will not be considered as finding
-H, --header additional header to send
--help display usage information
$ openapi-fuzzer -s spec.yaml -u http://127.0.0.1:8200/v1/ -i 404
Replaying findings
When you are done fuzzing you can replay the findings. All findings are stored in the results folder in path according to finding's endpoint and method. To resend the same payload to API, you simply run openapi-fuzzer-resender with path to the finding file as an argument. You can overwrite the headers with -H flag as well, which is useful for example, when the authorization token expired.
$ tree -L 3 results/
results/
├── sys-leases-renew
│ └── POST
│ └── 500
└── sys-seal
└── POST
└── 500
$ openapi-fuzzer-resender --help
Usage: openapi-fuzzer-resender <file> [-H <header>]
Resender of openapi-fuzzer results
Options:
-H, --header extra header
--help display usage information
$ openapi-fuzzer-resender results/sys-seal/POST/500/1b4e8a77.json
Response[status: 500, status_text: Internal Server Error, url: http://127.0.0.1:8200/v1/sys/seal]
{"errors":["1 error occurred: * missing client token"]}
Future plans
- Add script for minimization of the findings
Footnotes
-
not all found bugs are linked
↩
94 Sep 29, 2022
157 Oct 26, 2022
259 Dec 26, 2022
1.2k Dec 29, 2022
469 Dec 9, 2022
69 Dec 20, 2022
32 Dec 21, 2022
9 Nov 30, 2022
194 Oct 9, 2023
203 Nov 9, 2022
61 Dec 21, 2022
7 Sep 26, 2021
2k Jan 2, 2023
1 Apr 6, 2022
567 Dec 24, 2022
5 Mar 28, 2023
10 Nov 23, 2022
78 Jan 24, 2023
3 Jul 14, 2022