gqlhunter 0.3.0

GraphQL recon & analysis CLI — find endpoints, dump schema, flag risky fields.
_{detection-only · scope-aware · bug-bounty ready}

🌍 bess1lie.github.io · 🔍 apihunter · 🎯 bounthunt

📦 Installation

# From PyPI (recommended) — detection-only, scope-aware
pip install gqlhunter
gqlhunter --help

# Isolated with pipx (recommended for tools)
pipx install gqlhunter

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

⚡ 30-second start

pip install gqlhunter   # or pipx install gqlhunter
# 1. scope — allowlist for your target (never scan out-of-scope)
cat > scope.yaml <<'YAML'
targets: ["https://example.com"]
allowlist: ["example.com"]
YAML

# 2. discover + scan + risk in one go
gqlhunter discover https://example.com --scope scope.yaml
gqlhunter scan https://example.com/graphql --scope scope.yaml

# 3. report + dashboard
gqlhunter report --db gqlhunter_*.db --format html -o report.html
gqlhunter dashboard --db gqlhunter_*.db
# -> http://127.0.0.1:8080

Why now: 46k GraphQL issues found across 1500 APIs in 2024, 10% critical (Escape Tech). Introspection + batching + depth misconfigs are still the top 3.

✨ Features

🚀 Demo

discover + scan	report + dashboard
$ gqlhunter discover https://example.com --scope scope.yaml ╭────────── Discovered ──────────╮ │ https://example.com/graphql 200 │ │ https://example.com/graphiql 200 │ ╰──────────────────────────────╯ $ gqlhunter scan https://example.com/graphql --scope scope.yaml Introspection: enabled (HTTP 200) Stored 18 types, 8 queries, 3 mutations Risk findings: 2 high, 1 medium

📖 Commands

Full docs: docs/scope.md · docs/examples.md · docs/notifications.md

🏗️ Architecture

flowchart LR
    T[Target] --> D[Discovery 18 paths + POST]
    D --> I[Introspection]
    I --> P[Parser]
    P --> A[Risk IDOR+BOLA]
    P --> Q[Query Builder]
    P --> U[Auth Analyzer]
    A --> DB[(SQLite)]
    Q --> DB
    U --> DB
    DB --> R[Report HTML/MD]
    DB --> E[Export SARIF]
    DB --> V[Dashboard]
    DB --> N[Diff/Notify]

Stack: Python 3.11+ · Typer · httpx (+sse) · SQLite (WAL) · Jinja2 · Docker

🛡️ Philosophy

🗺️ Roadmap

❓ FAQ

Does it exploit? No. It discovers and classifies. Variant queries include # DO NOT AUTO-RUN warning.

Introspection disabled? Marked FILTERED/DISABLED. Next: Clairvoyance-lite via Did you mean ...? reconstruction.

Scope required? Yes. scope.yaml with targets/allowlist is mandatory for discover/scan/batch.

SARIF upload? gqlhunter.sarif → GitHub Code Scanning. Version synced from __version__.

🤝 Contributing

git clone https://github.com/bess1lie/gqlhunter.git
cd gqlhunter
pip install -e ".[dev]"
pytest -q  # 202 tests
ruff check gqlhunter/ && ruff format --check gqlhunter/
pip install gqlhunter  # try published package smoke test

See CONTRIBUTING.md if present, else open an issue.

📄 License

MIT — see LICENSE.

_{built in Almaty · bess1lie · detection-first security tooling}