graphinder is a Python reconnaissance tool that maps every GraphQL endpoint exposed across a domain's subdomains, built for authorized bug bounty and assessment workflows.
| Tool | Escape-Technologies/graphinder — fast GraphQL endpoint finder combining subdomain enumeration, script analysis, and directory brute forcing |
| Category | Reconnaissance / attack surface mapping |
| Primary Use | Enumerating GraphQL endpoints across a target domain's subdomains during authorized bug bounty and pentest scoping |
| Safe Use | Run only against assets you own or have explicit written authorization to test, such as bug bounty programs with defined scope or internal labs |
| Telemetry Note | Generates high volumes of HTTP requests (script fetches plus directory brute forcing), which will register in WAF logs, rate limiters, and anomaly detection as scanning behavior; results are written to a local results.json |
graphinder, maintained by Escape-Technologies, addresses a specific and increasingly common gap in web reconnaissance: locating every GraphQL endpoint hidden across an organization's subdomain footprint. GraphQL APIs frequently expose far more query surface than their REST counterparts — introspection, verbose error messages, and forgotten staging deployments — which is precisely why attackers and authorized testers alike hunt for them. Rather than manually grepping JavaScript bundles or guessing directory paths, graphinder automates the full pipeline: it enumerates subdomains, fetches and analyzes the scripts loaded by the browser, brute forces common directories on discovered hosts, and validates candidates. The project is written in Python, ships on PyPI, and carries an MIT license with roughly 228 stars, which is healthy traction for a niche recon utility.
A scan in graphinder is composed of a few discrete phases, and the README is refreshingly explicit about what each one does. You point the tool at a root domain with -d or --domain, and it takes over from there. The script analysis phase, toggled with -s/--script, crawls the JavaScript assets loaded by pages under the target domain and searches them for GraphQL references — a technique that catches endpoints never advertised in any sitemap or documentation. The brute forcing phase, -b/--bruteforce, probes well-known directory paths on all discovered URLs to surface endpoints that the script analysis missed entirely, such as API gateways sitting on hosts with no front-end at all.
What elevates graphinder above a simple fetch-and-grep script is the validation layer. The README includes a section titled "How do you make sure this is a valid graphql endpoint?" accompanied by a detector diagram, which tells you the tool does not merely pattern-match strings like /graphql in source code. It actively verifies that a candidate URL actually speaks GraphQL before reporting it. This matters operationally because raw string matching on JavaScript produces enormous false-positive rates — dead endpoints, string constants, commented-out code — and a validated endpoint list is what distinguishes a usable recon deliverable from noise an analyst has to triage by hand.
The --precision flag, enabled by default, is the knob controlling this rigor. The README notes that precision mode is slower but more accurate, which is an honest trade-off statement that experienced operators will appreciate. When scanning a large enterprise scope where time matters more than certainty, disabling precision can cast a wider net; when you need a clean, high-confidence endpoint inventory before moving into deeper GraphQL testing, leaving it enabled is the right call. The fact that the developers made precision the default tells you something about their priorities — they optimized for correct results rather than impressive-looking scan speed.
Installation is deliberately frictionless, with two supported paths. The PyPI route is the simplest: pip install graphinder (or python3 -m pip install graphinder for a pinned interpreter), after which the graphinder command is available. For container-minded teams, escapetech/graphinder is published on Docker Hub: docker pull escapetech/graphinder followed by docker run -it --rm escapetech/graphinder -d example.com runs a scan with no local Python environment to manage. The README thoughtfully shows how to extract the results.json output from a named container with docker cp, since the --rm pattern would otherwise discard your results with the container.
Bulk workflows are covered through the -f/--file option, which accepts a domains.txt list rather than a single -d target, and the concurrency model scales with your network. The -w/--max-workers <int> flag caps the number of concurrent workers across multiple domains, and the README offers practical advice: if you experience networking bottlenecks or irregularities, reduce your workers; the better your network, the more workers you can sustain. This is a tool whose authors have clearly run it against real, large-scale scopes and hit real infrastructure limits, and the guidance reflects that experience rather than theoretical speculation.
The remaining flags round out a sensible operational feature set. -r/--reduce limits the maximum number of subdomains scanned per domain, useful when a wildcard-laden target resolves thousands of hosts and you need to bound scan time. -o/--output-file <FILE_PATH> writes structured results to disk instead of only printing them, making graphinder composable with downstream tooling in a pipeline. -v/--verbose gives per-request visibility for debugging, and --no-bruteforce and --no-script let you surgically disable either discovery phase when one is unnecessary — for example, skipping brute force on a scope where it would violate program rules.
One flag deserves particular attention from a tradecraft perspective: -wb/--webhook_url, which sends results to a Discord webhook. This is a monitoring-oriented feature, suggesting the intended workflow is continuous or scheduled scanning of a bug bounty scope rather than one-off enumeration. Set it up against a program you are authorized to test, run it on a cron, and get notified when a new GraphQL endpoint appears in the attack surface. That shift from point-in-time recon to continuous surface monitoring is where tools like this deliver the most value to authorized researchers.
For development setups, the repository uses poetry for dependency management, with an ./install-dev.sh script handling the bootstrap and poetry shell dropping you into the virtual environment. The project's CI pipeline runs on GitHub Actions with a published badge, and codecov integration tracks test coverage — both signals that graphinder is actively engineered rather than a dumped proof-of-concept. The contribution policy asks for tests to be updated alongside changes, which is a good indicator of maintained quality for anyone considering extending the tool.
From a defensive standpoint, graphinder is equally useful run inwards. Blue teams and asset owners can point it at their own domains to answer an uncomfortable question: how many GraphQL endpoints exist in our attack surface that we forgot about? Shadow APIs, deprecated staging environments, and third-party dashboards embedding GraphQL clients all surface in a graphinder scan, and the results.json output gives you a concrete inventory to reconcile against your API registry. Because the script analysis phase mirrors exactly what an attacker would do — read your shipped JavaScript — endpoints it finds are endpoints an adversary will find too.
Operationally, be aware of the footprint this tool leaves. Subdomain enumeration plus browser script fetching plus directory brute forcing is a noisy combination by design, and any competent WAF, rate limiter, or network monitoring stack will register it as scanning behavior. On authorized engagements this is fine and often expected, but it also means defenders can detect graphinder-style reconnaissance through volume anomalies, novel-path 404 spikes, and bursts of asset fetches from a single source. Disabling the brute force phase with --no-bruteforce reduces the noise profile considerably if your rules of engagement demand stealthier handling.
In summary, graphinder occupies a well-defined niche in the recon toolchain: it is a validated, parallelized GraphQL endpoint discovery engine that chains subdomain enumeration, script analysis, and directory guessing into a single pass. The precision-mode validation, bounded concurrency, file-based output, and webhook notification support make it suitable both for one-time authorized assessments and for continuous bug bounty surface monitoring. For professionals working within explicitly authorized scope, it is a solid addition to the reconnaissance stage of any web engagement — and for defenders, a mirror to run against their own estates before someone else does.
Escape-Technologies/graphinder.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.