A lightweight, CI/CD-integrated API fuzzing pipeline that uses property-based testing to automatically detect unhandled server exceptions (500 errors) before they reach production.
Developers often test the "happy path" of their APIs but neglect to test how their endpoints handle malformed or malicious data. This project solves that by automatically reading an application's OpenAPI specification and generating thousands of edge-case payloads (e.g., extremely large integers, null bytes, malformed strings) to attempt to crash the server.
If the API successfully catches the bad data and returns a 4xx error (like 422 Unprocessable Entity), the test passes. If the API logic breaks and throws a 500 Internal Server Error, the pipeline catches it, fails the build, and generates a security report.
- Target Backend: FastAPI (Python)
- Testing Engine: Pytest & Schemathesis
- Schema Protocol: OpenAPI 3.0
- CI/CD Automation: GitHub Actions
Language-Agnostic Core: While the mock target API in this repository is built with FastAPI, the fuzzing engine is entirely framework-agnostic. Because it targets the OpenAPI JSON specification, this exact testing pipeline can be pointed at APIs built in Node.js, Go, Java, or Ruby.
- Zero-Config CI/CD Integration: The fuzzing pipeline runs automatically on every push and pull request via GitHub Actions.
- Visual Security Reports: Results are piped directly into the GitHub UI using Step Summaries, providing developers with immediate feedback on which endpoints crashed without having to dig through raw terminal logs.
- In-Memory Testing: The fuzzer hooks directly into the ASGI/WSGI application object. This allows for lightning-fast test execution in memory without needing to orchestrate or stand up a live web server during the testing phase.
- Targeted Route Fuzzing: Developers can test the entire API suite or isolate specific endpoints using Pytest's test-node targeting through custom functions (e.g.,
pytest test_fuzzer.py::test_specific_route).
- Python 3.10+
Clone the repository and install the dependencies:
git clone [https://github.com/DavidOprea/Auto_API_Doc_And_Fuzzer.git](https://github.com/DavidOprea/Auto_API_Doc_And_Fuzzer.git)
cd Auto_API_Doc_And_Fuzzer
pip install -r requirements.txtTo run the property-based fuzzer against the entire FastAPI application:
pytest test_fuzzer.py -v --tb=lineTo target a specific route (configured in the test file):
pytest test_fuzzer.py::test_get_user_fuzz -v --tb=lineYou can easily replace the mock backend in the app/ folder with your own Python web application.
- Replace the contents of the
app/folder with your FastAPI project. - Ensure your main application object can be imported in
test_fuzzer.py(e.g.,from app.main import app). - Run the tests. Schemathesis will automatically detect your routes via FastAPI's native
/openapi.json.
- Replace the
app/folder with your Flask project. - Because Flask does not generate OpenAPI schemas natively, you must configure a library (like
flasggerorflask-smorest) to serve your schema, or provide a staticopenapi.jsonfile. - Open
test_fuzzer.pyand modify the loader to use WSGI:# Change this: schema = schemathesis.openapi.from_asgi("/openapi.json", app) # To this: schema = schemathesis.openapi.from_wsgi("/openapi.json", app)
This project utilizes GitHub Actions to enforce a strict quality gate. The workflow (.github/workflows/fuzzing_pipeline.yml) executes the following lifecycle on every push:
- Provisions an ephemeral Ubuntu runner.
- Installs Python and project dependencies.
- Executes the Schemathesis fuzzer against the in-memory application.
- Generates a markdown report of all failed endpoints.
- Publishes the report to the GitHub Actions dashboard.
- Fails the build if any 500 Internal Server Error responses are detected.
This project is licensed under the MIT License - see the LICENSE file for details.