Skip to content

Latest commit

 

History

History
256 lines (190 loc) · 10.9 KB

README.md

File metadata and controls

256 lines (190 loc) · 10.9 KB

API Pentesting Toolkit

tests Python License: MIT ruff checks: mypy

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.

HTML report dashboard

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.


Why this exists

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 confirmed when 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 suspected or inconclusive, with an explicit manual verification note.

The scripts

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/.

Controls coverage

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.

Requirements

  • Python 3.10+
  • Dependencies: httpx and PyYAML (plus pytest for the test suite)

Installation

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

Quick start

# 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.md

Every script supports --help.

Reproducible demo (offline, no network)

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.py

Example (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.

Run against a real target (Docker lab)

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.html

A 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:

Toolkit run against the live Docker lab

See lab/README.md for details. Local use only — the target is deliberately insecure.

Reports

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 .tex report (--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.

Running the tests

pytest

The 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.

Safe & authorised use

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.

Limitations

  • 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.

Contributing

See CONTRIBUTING.md.

Roadmap

See the roadmap at the bottom of docs/methodology.md.

References

License

MIT.