gqlprobe 1.0.0

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

## Design Goals

gqlprobe is a modular GraphQL security scanner built with the following design goals:

1. **Accuracy over speed** - Every finding is backed by an explicit test, not heuristics.
2. **False-positive discipline** - A finding is only emitted when the endpoint demonstrably behaves in an exploitable way.
3. **Library-first** - The CLI is a thin wrapper over a fully programmatic Rust API.
4. **Observability** - Structured logging via `tracing`, structured output via `secfinding`.
5. **Testability** - All HTTP interaction is abstracted behind `scanclient::ScanClient`, enabling mock-based unit tests.

## Module Architecture

```
src/
├── lib.rs          # Crate root: re-exports Scanner, ScannerBuilder, modules
├── main.rs         # CLI entry point (clap argument parsing, output formatting)
├── scanner.rs      # Scanner orchestrator + ScanConfig + ScannerBuilder
└── modules/
    ├── mod.rs      # Module declarations and documentation
    ├── introspection.rs        # GQL-001: Introspection detection
    ├── query_depth.rs          # GQL-002: Query depth DoS + circular fragments
    ├── batching.rs             # GQL-003: Batching abuse
    ├── field_suggestion.rs     # GQL-004: Field enumeration via suggestions
    ├── directive_abuse.rs      # GQL-005: Directive overloading
    ├── graphql_injection.rs    # GQL-006: SQL/NoSQL/Command injection
    ├── csrf.rs                 # GQL-007: Cross-Site Request Forgery
    ├── subscription_abuse.rs   # GQL-008: Subscription abuse
    ├── information_disclosure.rs # GQL-009: Information disclosure
    └── auth_bypass.rs          # GQL-010: Authentication bypass
```

### Core Traits

#### `AttackModule`

All detection modules implement this trait:

```rust
#[async_trait]
pub trait AttackModule: Send + Sync {
    fn id(&self) -> &'static str;           // e.g., "GQL-001"
    fn name(&self) -> &'static str;         // Human-readable name
    async fn detect(&self, client: &ScanClient, url: &str) -> Result<Vec<Finding>>;
}
```

The trait is object-safe and modules are stored as `Vec<Arc<dyn AttackModule>>` inside the `Scanner`.

#### `ScanClient`

Provided by the `scanclient` crate. Wraps `reqwest` with:

- Configurable timeouts (connect, request)
- TLS verification toggles
- Proxy support
- Custom header injection
- DNS resolution via `hickory-resolver`

### Finding Model

Findings are produced as `secfinding::Finding` values, which include:

- `title` - Human-readable issue name
- `severity` - `Critical` | `High` | `Medium` | `Low` | `Info`
- `kind` - Categorization tag
- `target` - Affected URL
- `detail` - Evidence / proof of exploitability
- `remediation` - Actionable fix guidance
- `tags` - Arbitrary labels for filtering
- `cwe_ids` - Mapped CWE identifiers

## Scanning Pipeline

```
┌─────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Target    │────▶│   Scanner    │────▶│  Module Registry │
│    URL      │     │  (builder)   │     │ (10 built-ins)   │
└─────────────┘     └──────────────┘     └──────────────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────┐
                    ▼                             ▼             ▼
             ┌─────────────┐              ┌─────────────┐ ┌─────────────┐
             │ GQL-001     │              │ GQL-002     │ │ GQL-003     │
             │Introspection│              │Query Depth  │ │ Batching    │
             └─────────────┘              └─────────────┘ └─────────────┘
                    │                             │             │
                    ▼                             ▼             ▼
             ┌─────────────┐              ┌─────────────┐ ┌─────────────┐
             │ GQL-004     │              │ GQL-005     │ │ GQL-006     │
             │Field Suggest│              │Directive    │ │ Injection   │
             └─────────────┘              └─────────────┘ └─────────────┘
                    │                             │             │
                    ▼                             ▼             ▼
             ┌─────────────┐              ┌─────────────┐ ┌─────────────┐
             │ GQL-007     │              │ GQL-008     │ │ GQL-009     │
             │ CSRF        │              │Subscription │ │ Info Disc   │
             └─────────────┘              └─────────────┘ └─────────────┘
                                                  │
                                                  ▼
                                           ┌─────────────┐
                                           │ GQL-010     │
                                           │ Auth Bypass │
                                           └─────────────┘
                                                  │
                                                  ▼
                                           ┌─────────────┐
                                           │ GQL-011     │
                                           │ Alias Abuse │
                                           └─────────────┘
                                                  │
                                                  ▼
                                           ┌─────────────┐
                                           │ GQL-012     │
                                           │ Permissions │
                                           └─────────────┘
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │  Deduplicate    │
                                         │  + Sort by      │
                                         │  Severity       │
                                         └─────────────────┘
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │  Vec<Finding>   │
                                         │  (output)       │
                                         └─────────────────┘
```

1. **Initialization** - `ScannerBuilder` collects target URL, timeouts, concurrency, and HTTP config.
2. **Client creation** - `ScanClient` is built with the provided `HttpConfig` and a `TokioResolver`.
3. **Baseline capture** - `baseline::capture()` probes `__typename` and an invalid field to calibrate false-positive thresholds.
4. **Schema discovery** - `schema::discover()` runs introspection (unless skipped) to build a `SchemaGraph` for targeted tests.
5. **Module dispatch** - Each module runs inside a `tokio::spawn` task, limited by a `Semaphore` (`max_concurrency`).
6. **Per-module timeout** - Each task is wrapped in `tokio::time::timeout(module_timeout_secs)`.
7. **Global timeout** - A polling loop collects finished tasks; when the global deadline is reached, remaining tasks are aborted and partial findings are returned.
6. **Aggregation** - Results are collected, deduplicated by `(title, target)`, and sorted by severity descending.
7. **Output** - Findings are returned to the caller (CLI formats them as human/JSON/JSONL).

### Concurrency Model

- Modules run concurrently with a configurable semaphore (default: 5 concurrent modules).
- Each module has a per-request timeout (default 10s via `HttpConfig`) and a per-module timeout (default 60s).
- The entire scan has a global timeout (default 300s).
- If a module times out or panics, it produces zero findings; the scan continues.

## Finding Taxonomy

| ID | Module | Issue | Severity | Confidence |
|----|--------|-------|----------|------------|
| GQL-001 | introspection | Introspection enabled in production | High | Confirmed |
| GQL-002 | query_depth | No query depth limit / deep recursion | High | Confirmed |
| GQL-003 | batching | Batch queries accepted without limits | Medium | Confirmed |
| GQL-004 | field_suggestion | Field enumeration via suggestion leaks | Medium | Likely |
| GQL-005 | directive_abuse | Directive overloading or custom directive abuse | Medium / Low | Confirmed |
| GQL-006 | graphql_injection | SQL/NoSQL/Command injection via GraphQL arguments | Critical | Likely |
| GQL-007 | csrf | Cross-Site Request Forgery (GET-based or Content-Type bypass) | High / Medium | Confirmed |
| GQL-008 | subscription_abuse | Subscriptions enabled without auth or rate limits | High / Medium / Low | Likely |
| GQL-009 | information_disclosure | Verbose errors, debug endpoints, or exposed Playground/GraphiQL | High / Medium | Confirmed |
| GQL-010 | auth_bypass | Missing authentication on sensitive operations or JWT bypass | Critical / High / Low | Likely |
| GQL-011 | alias_abuse | Alias abuse enables query cost bypass or field duplication | Medium | Confirmed |
| GQL-012 | permissions | Auth-required fields accessible without credentials | Critical / Medium | Likely |

Severity is determined by exploitability and data exposure potential. Confidence reflects how definitively the test proves the issue.

## Configuration Options

### `ScanConfig` (library)

| Field | Default | Description |
|-------|---------|-------------|
| `global_timeout_secs` | `300` | Maximum duration for the entire scan |
| `module_timeout_secs` | `60` | Maximum duration for any single module |
| `max_concurrency` | `5` | Number of modules that may run in parallel |
| `http_config.timeout_secs` | `10` | Per-request HTTP timeout |
| `http_config.tls_verify` | `true` | Require valid TLS certificates |
| `http_config.proxy` | `None` | HTTP/HTTPS proxy URL |
| `http_config.custom_headers` | `{}` | Additional HTTP headers |

### CLI flags

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--output` | `-o` | `human` | Output format: `human`, `json`, `jsonl` |
| `--timeout` | `-t` | `300` | Global scan timeout (seconds) |
| `--module-timeout` | | `60` | Per-module timeout (seconds) |
| `--concurrency` | `-c` | `5` | Maximum concurrent modules |
| `--http-timeout` | | `10` | HTTP request timeout (seconds) |
| `--insecure` | | `false` | Disable TLS certificate verification |
| `--header` | `-H` | `[]` | Custom header (`Key: Value`) |
| `--proxy` | `-p` | `None` | Proxy URL |
| `--verbose` | `-v` | `false` | Enable info-level logging |
| `--debug` | | `false` | Enable debug-level logging |

## Extending with New Modules

### 1. Implement the `AttackModule` trait

Create a new file in `src/modules/`:

```rust
// src/modules/my_attack.rs
use anyhow::Result;
use scanclient::ScanClient;
use secfinding::{Finding, Severity};

pub async fn test(client: &ScanClient, url: &str) -> Result<Vec<Finding>> {
    let mut findings = Vec::new();

    // Detection logic here
    // Use client.query() or client.query_json()

    Ok(findings)
}
```

### 2. Register the module

Add it to the scanner's module list in `src/scanner.rs`:

```rust
// In src/modules/attack.rs:
module_impl!(
    MyAttackModule,
    "GQL-013",
    "My Attack",
    my_attack::test_with_context
);
```

Also add it to `default_registry()`:

```rust
Arc::new(MyAttackModule),
```

### 3. Add tests

Add adversarial and positive tests in `tests/break_it.rs` and module-level unit tests in the new file.

### Design constraints for new modules

- **No `unwrap()` / `expect()`** in production code. Use `?` or propagate `Result`.
- **Every finding must include evidence** - raw response excerpts, status codes, or computed metrics.
- **Respect timeouts** - Do not perform unbounded work; the `ScanClient` timeout is the upper bound.
- **Idempotent** - A module should be safe to run multiple times against the same target.