# 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
| 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)
| `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
| `--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.