gqlprobe 1.0.0

Fast GraphQL security scanner - schema-aware introspection, injection, DoS, CSRF, auth bypass, SARIF
Documentation

gqlprobe

crates.io docs.rs license CI status: stable

What it does

gqlprobe is a GraphQL security scanner that introspects your API first, builds a schema map, calibrates baseline behavior, then runs 14 targeted checks with evidence-backed findings and SARIF for GitHub/GitLab CI.

Most GraphQL scanners fire generic probes at user(id: "1") and hope something sticks. gqlprobe introspects the target first so every probe is schema-aware - reducing false positives and surfacing real issues.

ID Check What it finds
GQL-001 Introspection Production __schema / __type exposure
GQL-002 Query depth Missing depth limits (DoS)
GQL-003 Batching Unbounded operation batches
GQL-004 Field suggestions Schema leak via "Did you mean…" errors
GQL-005 Directive abuse @include / @skip amplification
GQL-006 Injection SQL / NoSQL / command injection via args
GQL-007 CSRF GET mutations, Content-Type bypass
GQL-008 Subscriptions Unauthenticated or unbounded subscriptions
GQL-009 Info disclosure Verbose errors, Playground/GraphiQL exposed
GQL-010 Auth bypass Sensitive fields / JWT tricks without auth
GQL-011 Alias abuse Alias amplification in one request
GQL-012 Permissions Auth directives vs actual access
GQL-013 IDOR / BOLA Schema-aware ID argument probing
GQL-014 Rate limit Burst probe for missing HTTP 429
gqlprobe --list-modules

Quick start

Install

# From crates.io (recommended)
cargo install gqlprobe

# From git (latest main)
cargo install --git https://github.com/santhreal/gqlprobe

# Docker
docker run --rm ghcr.io/santhreal/gqlprobe:latest https://api.example.com/graphql

# From source (Santh monorepo)
cd software/gqlprobe && cargo install --path .

Requires Rust 1.85+

Basic usage

# Human-readable report
gqlprobe https://api.example.com/graphql

# CI / code scanning (GitHub Advanced Security, GitLab SAST, etc.)
gqlprobe https://staging.example.com/graphql --output sarif > gqlprobe.sarif

# Authenticated staging API
gqlprobe https://staging.example.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  --output json > findings.json

# Fast smoke test (skip schema discovery)
gqlprobe https://api.example.com/graphql --skip-schema

# Only introspection + injection
gqlprobe https://api.example.com/graphql --modules GQL-001,GQL-006

Example output

⚠ Found 3 security issues:
  Critical: 1
  High: 2

Each finding includes severity, evidence, remediation, CWE tags, and module ID.

Configuration flags

Flag Description
-o, --output human (default), json, jsonl, sarif
-t, --timeout Global scan timeout (default 300s)
--module-timeout Per-module timeout (default 60s; 0 = disabled)
-c, --concurrency Parallel modules (default 5)
--modules Comma-separated module IDs
--skip-schema Skip introspection-based discovery
-H, --header Custom header (Authorization: Bearer …)
--proxy HTTP proxy (Burp, etc.)
--insecure Disable TLS verification (lab only)
-v / --debug Logging

CI/CD integration

name: GraphQL security
on:
  pull_request:
  schedule:
    - cron: "0 6 * * 1"

jobs:
  gqlprobe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install gqlprobe
        run: cargo install gqlprobe --locked
      - name: Scan staging GraphQL
        env:
          GRAPHQL_URL: ${{ secrets.STAGING_GRAPHQL_URL }}
          GRAPHQL_TOKEN: ${{ secrets.STAGING_GRAPHQL_TOKEN }}
        run: |
          gqlprobe "$GRAPHQL_URL" \
            -H "Authorization: Bearer $GRAPHQL_TOKEN" \
            --output sarif > gqlprobe.sarif
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: gqlprobe.sarif
          category: gqlprobe

Copy the workflow from .github/workflows/example-gqlprobe-scan.yml.

Library API

use gqlprobe::{Scanner, ScannerBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let scanner = ScannerBuilder::new()
        .target("https://api.example.com/graphql")
        .global_timeout(120)
        .modules(&["GQL-001", "GQL-006"])
        .build()?;

    let findings = scanner.scan().await?;
    for f in &findings {
        println!("[{:?}] {} - {}", f.severity(), f.title(), f.target());
    }
    Ok(())
}

Docs: docs.rs/gqlprobe

How it works

flowchart LR
  A[Target URL] --> B[Baseline capture]
  B --> C[Schema discovery]
  C --> D[14 modules concurrent]
  D --> E[Deduplicate + sort]
  E --> F[human / json / sarif]
  1. Baseline - Probes __typename and a bogus field to learn how the API rejects noise.
  2. Schema - Full introspection when allowed; extracts real fields and injectable arguments.
  3. Modules - Each check uses schema + baseline to avoid blind false positives.
  4. Output - Structured findings via secfinding; SARIF via secreport.

When to use / When not

Use gqlprobe when:

  • You need schema-aware GraphQL security scanning (not blind generic probes).
  • You want structured SARIF output for GitHub Advanced Security or GitLab SAST pipelines.
  • You are running authorized penetration tests or security reviews against GraphQL APIs.
  • You need a Rust library (AttackModule trait) to build custom security modules.
  • You want concurrent scanning with per-module and global timeouts enforced by default.

Do not use gqlprobe when:

  • You need a full DAST platform with session management, authenticated crawling, or active exploitation.
  • The target is not a GraphQL endpoint (use a purpose-built HTTP or REST scanner instead).
  • You do not have explicit permission to scan the target - authorized testing only.
  • You require real-time subscription protocol (WebSocket) testing; GQL-008 covers HTTP-based subscriptions only.

Compared to alternatives

Generic GraphQL scripts graphql-cop InQL gqlprobe
Schema awareness Blind field names Partial Yes (Burp plugin) Full introspection → targeted probes
False positives High Medium Medium Low (baseline calibration + parse-error filtering)
CI integration Ad-hoc JSON Limited Burp-dependent Native SARIF, JSON, JSONL
Speed Sequential Sequential Sequential 14 modules concurrent by default
Extensibility Copy-paste Limited Jython Rust library + AttackModule trait
Standalone binary No Python Burp plugin Yes (cargo install gqlprobe)

gqlprobe is designed for CI pipelines and programmatic use where structured output and low false-positive rates matter. It is not a replacement for a full manual assessment.

How it fits in Santh

gqlprobe is an open-source Santh Security tool that also functions as a standalone cargo install crate. Within the Santh monorepo it lives at software/gqlprobe.

  • Findings are emitted as secfinding::Finding values, which Santh's aggregation pipeline can consume directly alongside output from other scanners.
  • SARIF output feeds into GitHub Advanced Security code scanning when used in CI.
  • Library mode lets other Santh tools embed GraphQL checks by adding gqlprobe as a dependency and calling ScannerBuilder directly.
  • The crate is usable without any other Santh products - all dependencies are on crates.io.

Contributing

We welcome issues and PRs. See CONTRIBUTING.md and SECURITY.md.

Built with Rust, scanclient, and secfinding. Maintained by Santh Security - gqlprobe is open source and usable without any other Santh products.

License

Dual-licensed under MIT or Apache-2.0.