apihunter

Professional REST API security testing CLI -- OpenAPI discovery, authentication auditing, heuristic scanning, and comprehensive reporting.

Why apihunter • Features • Architecture • Quick Start • Configuration • Roadmap • Contributing

🚀 Demo

# Discover OpenAPI endpoints
$ apihunter discover https://api.example.com
╭──────────────────── Discovered Endpoints ─────────────────────╮
│ URL                              │ Method │ Auth      │ Status │
├──────────────────────────────────┼────────┼───────────┼────────┤
│ https://api.example.com/v1/users │ GET    │ JWT       │ 200    │
│ https://api.example.com/v1/users │ POST   │ JWT       │ 201    │
│ https://api.example.com/v1/login │ POST   │ None      │ 200    │
│ https://api.example.com/v1/admin │ GET    │ JWT+RBAC  │ 403    │
╰──────────────────────────────────┴────────┴───────────┴────────╯

# Run security scan
$ apihunter scan https://api.example.com
[INFO] Starting scan on 4 endpoints...
[INFO] Testing authentication: 2 endpoints require JWT
[INFO] Testing authorization (IDOR)...
[!] 🔴 CRITICAL: IDOR vulnerability on /v1/users/{id} (GET)
[!] 🟠 HIGH: Missing rate limiting on /v1/login
[!] 🟡 MEDIUM: Verbose error message on /v1/debug
[✓] 🟢 Scan completed in 12.3s

# Generate HTML report
$ apihunter report <run_id> --format html
[✓] 🟢 Report saved to report_<run_id>.html

🧐 Why apihunter?

✨ Features

• 🔎 OpenAPI / Swagger Discovery -- automatically finds and parses OpenAPI 2.0/3.0, Swagger UI, and GraphQL introspection endpoints.
• 🔐 Authentication Detection -- detects JWT, OAuth2, Basic Auth, API keys, and missing authentication.
• 🛡️ Heuristic Security Scanning -- checks for:
  • Insecure Direct Object References (IDOR)
  • CORS misconfigurations
  • SQL/NoSQL injection points (detection only)
  • Rate limiting absence
  • Information disclosure (verbose errors, stack traces)
• 📊 Multi‑format Reports -- HTML (interactive dashboard), Markdown (for docs), SARIF (for GitHub Code Scanning).
• 🗄️ Local SQLite Storage -- every scan is stored, enabling historical comparison and audit trails.
• ⚙️ Scope‑aware -- respect scope.yaml to focus on specific domains, paths, and exclude third‑party endpoints.
• 🧩 Extensible -- plugin‑based architecture to add custom checks or providers.

🛠️ Tech Stack

• Language: Python 3.11+
• CLI: Typer
• Terminal output: Rich
• HTTP client: HTTPX
• Storage: SQLite
• Reports: Jinja2
• Config: PyYAML

🏗️ Architecture

graph TD
    A[CLI Entry] --> B{Command}
    B -->|discover| C[Discover Provider]
    B -->|scan| D[Scan Engine]
    B -->|report| E[Report Generator]
    B -->|db| F[Database Manager]
    
    C --> G[OpenAPI Parser]
    C --> H[GraphQL Introspection]
    C --> I[Common Patterns]
    
    D --> J[Heuristic Modules]
    J --> K[IDOR Checker]
    J --> L[CORS Checker]
    J --> M[Auth Checker]
    J --> N[Injection Detector]
    
    D --> F
    D --> O[Results]
    O --> E
    E --> P[HTML Report]
    E --> Q[Markdown Report]
    E --> R[SARIF Report]
    
    F --> S[SQLite Storage]
    S --> O
    
    style A fill:#58a6ff,stroke:#1f6feb,color:#fff
    style C fill:#3fb950,stroke:#2ea043
    style D fill:#d29922,stroke:#9e6a03
    style E fill:#f0883e,stroke:#d97a00
    style F fill:#f85149,stroke:#da3633

• Discovery Engine: Injects providers to probe target surfaces.
• Scanner Engine: Executes specialized analyzers against discovered endpoints.
• Core: Manages the database, HTTP client, and scope.

📦 Installation

# From PyPI (recommended) — detection-only, no payloads
pip install apihunter-bess1lie
# CLI stays `apihunter`
apihunter --help

# Isolated with pipx (recommended for tools)
pipx install apihunter-bess1lie

# From source (latest dev)
git clone https://github.com/bess1lie/apihunter.git
cd apihunter
pip install -e .

⚡ Quick Start

Basic usage (scope-aware)

# 0. Create scope.yaml — every request gated by allowlist
cat > scope.yaml <<'YAML'
allow: ["api.example.com"]
targets: ["https://api.example.com"]
YAML

# 1. Discover endpoints
apihunter discover https://api.example.com --scope scope.yaml

# 2. Scan (heuristics: auth — detection only; IDOR/CORS/injection are 🚧)
apihunter scan https://api.example.com --scope scope.yaml

# 3. Report + SARIF for GitHub Code Scanning
apihunter report <run_id> --format html -o report.html
apihunter report <run_id> --format sarif -o apihunter.sarif

# Verify install
apihunter --help && apihunter version

Requires scope.yaml — out-of-scope requests are blocked. See scope.example.yaml and docs/scope.md.

⚙️ Configuration

Create a scope.yaml file to define your testing boundaries (see docs/scope.md):

allow:
  - "api.example.com"
  - "*.example.com"
deny:
  - "cdn.example.com"
targets:
  - "https://api.example.com"
excluded_extensions:
  - png
  - css
  - js

All keys optional; empty = fail-closed. allow supports *. wildcards, bare domain matches subdomains.

🔄 Comparison with alternatives

🗺️ Roadmap

🤝 Contributing

Pull requests are welcome. For major changes, open an issue first to discuss what you would like to change.

🛡️ Security

If you find a vulnerability, please report it privately to bess1iework@gmail.com — see SECURITY.md.

PyPI name: pip install apihunter-bess1lie (import apihunter, CLI apihunter). The short name apihunter is reserved for a future 1.x alias.

📄 License

Distributed under the MIT License. See LICENSE for more information.

🌐 More Tools

• bounthunt - Bug bounty reconnaissance and automation.
• gqlhunter - GraphQL security testing and introspection.

_{detection-first · scope-aware · bess1lie.github.io · contact}