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 -- probes 22 well-known paths (/openapi.json, /swagger.json, /v3/api-docs, /graphql, etc.), parses OpenAPI 2.0/3.0 & Swagger host+basePath.
• 🔐 Authentication Detection -- detects missing securitySchemes, auth_required without schemes, and unauthenticated sensitive paths (/admin, /user, …).
• 🛡️ Heuristic Security Scanning -- active (implemented):
  • Missing authentication schemes (HIGH)
  • Insecure http:// servers / missing securitySchemes (Headers)
  • Debug/admin endpoint exposure & verbose errors (Info Leak)
  • Roadmap (🚧): IDOR/BOLA, CORS, Rate Limit, Injection — stubs in get_experimental_registry()
• 📊 Multi‑format Reports -- HTML (XSS-escaped + CSP), Markdown, SARIF 2.1.0 for GitHub Code Scanning.
• 🗄️ Local SQLite Storage -- WAL + FK, parameterized, every scan stored with XDG ~/.local/share/apihunter/apihunter.db.
• ⚙️ Scope‑aware -- allow/deny/targets/excluded_extensions enforced on every request (docs/scope.md).
• 🧩 Extensible -- AnalyzerContext(target, scope, client) + AnalyzerRegistry for custom checks.

🛠️ 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 — profiles: safe (passive+light active, 10 req), balanced (20), aggressive (50)
apihunter scan https://api.example.com --scope scope.yaml --profile safe
apihunter scan https://api.example.com --scope scope.yaml --profile balanced  # default active: auth, IDOR, CORS
apihunter scan https://api.example.com --scope scope.yaml --profile aggressive --max-requests 50 --rate-limit 10

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

🎛️ Scan Profiles (1.2.0)

apihunter scan https://api.example.com --scope scope.yaml --profile safe
apihunter scan https://api.example.com --scope scope.yaml --profile balanced --timeout 15
apihunter scan https://api.example.com --scope scope.yaml --profile aggressive --max-requests 50

All profiles respect scope.yaml, 2MB limit, timeout, and allow_private=false by default.

🔄 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}