APIGhost

Automated Broken Object Level Authorization (BOLA/IDOR) detection for REST APIs.

---

Traditional DAST scanners test endpoints in isolation — they fire a GET request, see a 403, and move on. They are architecturally incapable of detecting BOLA because BOLA requires a stateful, multi-step test:

1. User A creates a resource → gets an object ID
2. User B (a different account) tries to access that same object ID
3. If User B succeeds, that's BOLA

APIGhost automates this entirely. It builds the cross-user chain automatically, fills every request field with schema-valid values so input validation doesn't block the test before the authorization check, and scores each finding with four independent signals to minimize false positives.

How it works

flowchart:

OpenAPI / HAR / Burp XML / Crawler
        ↓
  Chain Builder  ←── Layer 1: path parameter matching
        ↓         ←── Layer 2: JSON schema field matching
  Value Resolution Engine (Spec → Heuristics → Live prefetch)
        ↓
  Stateful Executor
    User A: POST /orders → {orderId: 4821}
    User A: GET  /orders/4821 → baseline response
    User B: GET  /orders/4821 → attacker response   ← the actual test
    User A: DELETE /orders/4821 → teardown
        ↓
  Verdict Engine (4 signals → confidence score 0.0–1.0)
        ↓
  Report: JSON / HTML / Markdown / SARIF

Quickstart

Install

pip install git+https://github.com/Arul-AGC/APIGhost.git

Windows users: double-click run.bat for an interactive menu with no terminal knowledge required.

Scan with an OpenAPI spec

apighost scan https://api.example.com \
  --spec openapi.json \
  --token-a "UserA_JWT" \
  --token-b "UserB_JWT" \
  --output report.html \
  --format html

Scan without a spec (crawler mode)

# Step 1: discover and map the API
apighost crawl https://api.example.com wordlists/common_endpoints.txt \
  --token "UserA_JWT" \
  --output spec.json

# Step 2: scan with the inferred spec
apighost scan https://api.example.com \
  --spec spec.json \
  --token-a "UserA_JWT" \
  --token-b "UserB_JWT"

Preview chains before sending any requests

apighost scan https://api.example.com --spec openapi.json \
  --token-a "..." --token-b "..." \
  --dry-run

CI/CD integration

# Exit code: 0 = secure, 1 = BOLA found, 2 = error
apighost scan $API_URL --spec spec.json \
  --token-a $TOKEN_A --token-b $TOKEN_B \
  --output results.sarif --format sarif

Authentication modes

Mode	Flag	Example
Bearer token (default)	--auth-mode bearer	Authorization: Bearer <token>
API key header	--auth-mode api_key --auth-header X-API-Key	X-API-Key: <token>
Cookie	--auth-mode cookie --auth-header session	Cookie: session=<token>
HTTP Basic	--auth-mode basic	Authorization: Basic <base64>
Custom header	--auth-mode custom --auth-header X-Auth-Token	X-Auth-Token: <token>

Token refresh for long scans:

apighost scan ... --refresh-cmd "python get_new_token.py"

What it detects

OWASP API Top 10 (2023)	Supported
API1: Broken Object Level Authorization (BOLA/IDOR)	✅ READ, UPDATE, DELETE chains
API3: Broken Object Property Level Authorization (Mass Assignment)	✅
API3: Excessive Data Exposure	✅
API5: Broken Function Level Authorization (BFLA)	✅
API4: Unrestricted Resource Consumption (rate limiting)	✅ bypass testing
API8: Security Misconfiguration (injection)	✅ SSTI / SQLi fuzzing

Reports

APIGhost generates four report formats from the same scan:

--format json    # Machine-readable, CI/CD friendly
--format html    # Self-contained, browser-viewable
--format md      # Markdown (for GitHub issues or wikis)
--format sarif   # SARIF 2.1.0 (GitHub Code Scanning, VS Code)

Replication (Research)

To reproduce the evaluation results from our ISSTA 2027 tool paper:

# 1. Clone this repo
git clone https://github.com/Arul-AGC/APIGhost.git
cd APIGhost

# 2. Spin up the three intentionally vulnerable testbeds
docker compose -f testbed/docker-compose.yml up -d

# 3. Wait ~30s for services, then run the evaluation
python testbed/run_evaluation.py

# 4. Run statistical significance tests
python stats/significance_tests.py

All raw per-chain detection logs are in testbed/results/. Expected runtime: under 30 minutes on an 8-core / 16 GB machine.

Architecture & Documentation

• Architecture & Engine Details
• Vulnerability Coverage & Bypass Techniques
• Contributing Guidelines
• Changelog

Disclaimer

APIGhost is intended for authorized security testing only.
Always obtain explicit written permission from the target system's owner before scanning.
The authors are not responsible for misuse.

License

MIT — see LICENSE.

Citation

If you use APIGhost in academic work, please cite:

@software{apighost2026,
  author    = {Arul Guru Chandiran P R, and Arun A, and Kapil M, and Kishore R},
  title     = {{APIGhost}: Automated BOLA Detection via Dual-Layer Cross-User Chain Resolution},
  year      = {2026},
  url       = {https://github.com/Arul-AGC/APIGhost},
  version   = {0.1.0}
}