A progressive, authorization-aware toolkit of 14 Python scripts for testing the security of REST and GraphQL APIs, aligned with the OWASP API Security Top 10 (2023).
The scripts go from a simple non-destructive reconnaissance pass up to a modular, configurable audit orchestrator. They are designed for authorised testing only — labs, staging, and engagements where you have written permission — and they are built to be conservative: they separate what was observed from what is proven, and they refuse to run outside a declared scope.
This project is a personal, educational toolkit. It does not replace Burp Suite, OWASP ZAP, or a manual penetration test. Its value is targeted automation, reproducibility, and high-quality, reviewable reports.
The audit orchestrator produces reports in five formats — JSON, Markdown, an interactive HTML dashboard (above), a compilable LaTeX/PDF, and SARIF — in English or French.
Many API weaknesses cannot be proven by an automated client without taking risky actions. A lot of tools paper over this by flagging everything as a vulnerability. This toolkit takes the opposite stance:
- Every result carries three independent axes — severity, confidence, and
status (
informational/suspected/confirmed/inconclusive). - A finding is only
confirmedwhen the tool reproducibly demonstrated it within scope (e.g. a non-owner retrieved an owner's object and an owner-specific discriminator was present). - Everything else is
suspectedorinconclusive, with an explicit manual verification note.
Core ten — a progression from recon to an integrated orchestrator:
| # | Script | Level | Focus | OWASP (2023) |
|---|---|---|---|---|
| 01 | 01_api_recon.py |
Beginner | HTTP recon & inventory | API9 |
| 02 | 02_api_security_headers.py |
Beginner | Headers & misconfig | API8 |
| 03 | 03_api_auth_audit.py |
Intermediate | Authentication controls | API2 |
| 04 | 04_api_endpoint_inventory.py |
Intermediate | OpenAPI inventory | API9 |
| 05 | 05_api_input_validation.py |
Intermediate | Input validation & errors | API8 |
| 06 | 06_api_bola_audit.py |
Advanced | BOLA / IDOR | API1 |
| 07 | 07_api_authorization_audit.py |
Advanced | BFLA & BOPLA | API3, API5 |
| 08 | 08_api_rate_limit_audit.py |
Advanced | Rate limiting / resource use | API4 |
| 09 | 09_api_graphql_audit.py |
Advanced | GraphQL security | API4, API8 |
| 10 | 10_api_security_audit.py |
Expert | Integrated orchestrator | Multiple |
Bonus everyday scripts (added after the core ten):
| # | Script | Level | Focus | OWASP (2023) |
|---|---|---|---|---|
| 11 | 11_api_jwt_inspect.py |
Intermediate | Static JWT inspection (offline) | API2 |
| 12 | 12_api_cors_audit.py |
Intermediate | CORS misconfiguration | API8 |
| 13 | 13_api_data_leak_scan.py |
Intermediate | Secrets/PII leak scan | API3 |
| 14 | 14_api_exposure_scan.py |
Intermediate | Exposed specs / .env / actuators |
API9, API8 |
Each script has a dedicated guide in docs/scripts/.
| OWASP API (2023) | Covered by | Confidence it can reach |
|---|---|---|
| API1 — BOLA | 06, 10 | confirmed (with discriminator) |
| API2 — Broken Authentication | 03, 10 | suspected |
| API3 — BOPLA / data exposure | 07, 10, 13 | suspected/confirmed (leaked secret) |
| API4 — Unrestricted Resource Consumption | 08, 09, 10 | inconclusive/informational |
| API5 — BFLA | 07, 10 | suspected |
| API8 — Security Misconfiguration | 02, 05, 09, 10, 12, 14 | suspected/confirmed (CORS, exposure) |
| API9 — Improper Inventory Management | 01, 04, 10, 14 | informational/confirmed (exposure) |
JWT inspection (script 11) and CORS (script 12) also feed the orchestrator via the
jwt and cors categories.
API6, API7 and API10 are deliberately not automated here — they generally
require business-context or active exploitation that is unsafe to automate. See
docs/methodology.md for the rationale.
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate
pip install -e ".[dev]"The scripts also run without installation (they add src/ to the path), so
python scripts/01_api_recon.py --help works straight from a clone. After
pip install, a convenience command is also available:
apt audit --config configs/audit.example.yaml --json out/audit.json --sarif out/audit.sarif
apt jwt --token-env API_TOKEN_USER_A --expected-alg RS256
# Bilingual: write an English HTML report and a French copy (out/audit.fr.html)
apt audit --config configs/audit.example.yaml --html out/audit.html --lang both# 1. Non-destructive recon of an authorised target
python scripts/01_api_recon.py --base-url https://api.lab.local --allow-host api.lab.local -o recon.json
# 2. Inventory an OpenAPI document (no network needed)
python scripts/04_api_endpoint_inventory.py --openapi examples/sample_openapi.yaml -o inventory.json --csv inventory.csv
# 3. Full audit driven by a config file
export API_TOKEN_USER_A="..." # test account token, never a real user's
python scripts/10_api_security_audit.py --config configs/audit.example.yaml \
--json out/audit.json --markdown out/audit.mdEvery script supports --help.
The toolkit ships a bundled lab target (api_pentesting.demo.LabApp) that can
be run in a secure or an intentionally vulnerable posture, so you can see each
control fire without touching any real service:
python examples/run_demo.pyExample (vulnerable posture):
=== VULNERABLE lab target ===
summary: {"INFO": 5, "LOW": 10, "MEDIUM": 6, "HIGH": 3, "CRITICAL": 1}
[CRITICAL/confirmed] Broken Object Level Authorization: order #1 (user_a)
[HIGH/suspected] Protected route returned success without authentication
[HIGH/suspected] Low-privilege identity invoked privileged function: admin user listing
A representative report is saved at
examples/sample_results.json. It was produced
against the bundled lab target, not a real API.
For a demonstration over real HTTP (not an in-process mock), the repo ships an
intentionally vulnerable API in lab/. It is standard-library only and
bound to 127.0.0.1.
cd lab && docker compose up -d --build # http://127.0.0.1:8000 (or: python lab/vulnerable_api.py)
cd .. && apt audit --config lab/audit.lab.yaml --html out/lab_audit.htmlA full run produces ~36 findings, including confirmed BOLA (a non-owner reads
another user's order), JWT alg: none, CORS reflection with credentials, a leaked
AWS key and an exposed /.env:
See lab/README.md for details. Local use only — the target
is deliberately insecure.
Reports come from one reproducible envelope (audit id + UTC timestamp + tool version):
- JSON — machine-readable, for pipelines.
- Markdown — human-readable, with severity summary and remediation.
- HTML — a self-contained, filterable dashboard (
--html); no external assets. - LaTeX — a compilable
.texreport (--latex) for a polished PDF deliverable. - SARIF 2.1.0 — for GitHub code-scanning / CI ingestion (
--sarif). - Console — a quick ASCII summary.
Bilingual output. Markdown, HTML and LaTeX reports render in English or
French via --lang en|fr (JSON and SARIF are machine formats and stay neutral).
Finding titles/descriptions are authored in English by the checks; the report
chrome — headings, labels, severity/status vocabulary — is localised. Script 10
accepts --lang both to emit an English report and a .fr. copy side by side.
Rendered examples are committed:
sample_report.html /
sample_report.pdf (EN) and
sample_report_fr.html /
sample_report_fr.pdf (FR). Build a PDF with
pdflatex sample_report.tex (any standard TeX distribution).
See docs/findings-and-severity.md.
pytestThe suite is fully offline — it uses httpx.MockTransport and the bundled lab
target, and never depends on a public API. At the time of writing it contains 105
tests (unit + integration). CI also runs ruff (lint) and mypy (types) on
Python 3.10–3.12.
Read docs/authorization-and-scope.md and
SECURITY.md before pointing this at anything. In short:
- No targets are hard-coded; a host must be in an explicit allow-list.
- No secrets in Git — tokens come from environment variables.
- TLS verification is on by default.
- Requests, concurrency and duration are bounded; the run stops on instability.
- No brute force, no denial of service, no automated exploitation of third parties.
- It cannot prove most issues without manual follow-up — by design.
- It does not crawl or fuzz exhaustively.
- It does not cover API6/API7/API10 (business-flow abuse, SSRF, unsafe consumption).
- Findings require human triage; see each script's guide for false-positive notes.
See CONTRIBUTING.md.
See the roadmap at the bottom of docs/methodology.md.
- OWASP API Security Project — https://owasp.org/www-project-api-security/
- OWASP API Security Top 10 (2023) — https://owasp.org/API-Security/editions/2023/en/0x11-t10/
- OWASP Web Security Testing Guide — https://owasp.org/www-project-web-security-testing-guide/
- OWASP API Security Testing Framework — https://owasp.org/www-project-api-security-testing-framework/
- PortSwigger Web Security Academy — https://portswigger.net/web-security
MIT.

