gqlprobe 1.0.0

Fast GraphQL security scanner - schema-aware introspection, injection, DoS, CSRF, auth bypass, SARIF
Documentation
//! Endpoint baseline calibration to reduce false positives.

use anyhow::Result;
use scanclient::reqwest::header::CONTENT_TYPE;
use scanclient::ScanClient;
use serde_json::{json, Value};
use tracing::debug;

/// Observed behavior of the target before active security tests.
#[derive(Debug, Clone, Default)]
pub struct EndpointBaseline {
    /// `{ __typename }` returned HTTP 200 with non-null `data`.
    pub typename_accessible: bool,
    /// A deliberately invalid field returns GraphQL `errors` (typical hardened API).
    pub rejects_unknown_fields: bool,
    /// Lowercased error messages from the unknown-field probe.
    pub unknown_field_errors: Vec<String>,
    /// Whether the endpoint appears to be fully public (no auth gate on `__typename`).
    pub appears_public: bool,
}

/// Capture baseline responses used to calibrate later modules.
pub async fn capture(client: &ScanClient, url: &str) -> Result<EndpointBaseline> {
    let mut baseline = EndpointBaseline::default();

    debug!("Capturing endpoint baseline for {}", url);

    if let Ok(resp) = post_query(client, url, "{ __typename }").await {
        if let Ok(text) = resp.body_text() {
            if resp.status().is_success() {
                if let Ok(json) = serde_json::from_str::<Value>(text) {
                    baseline.typename_accessible = json
                        .pointer("/data/__typename")
                        .and_then(|v| v.as_str())
                        .is_some();
                    baseline.appears_public =
                        baseline.typename_accessible && !has_auth_errors(&json);
                }
            }
        }
    }

    if let Ok(resp) = post_query(
        client,
        url,
        "query Baseline { __gqlprobe_nonexistent_field_xyz } { id }",
    )
    .await
    {
        if let Ok(text) = resp.body_text() {
            if let Ok(json) = serde_json::from_str::<Value>(text) {
                if let Some(errors) = json.get("errors").and_then(|e| e.as_array()) {
                    baseline.rejects_unknown_fields = !errors.is_empty();
                    for err in errors {
                        if let Some(msg) = err.get("message").and_then(|m| m.as_str()) {
                            baseline.unknown_field_errors.push(msg.to_lowercase());
                        }
                    }
                }
            }
        }
    }

    Ok(baseline)
}

/// Returns true when a GraphQL response contains meaningful data for `field_name`.
pub fn has_meaningful_field_data(json: &Value, field_name: &str) -> bool {
    let Some(value) = json.pointer(&format!("/data/{field_name}")) else {
        return false;
    };
    if value.is_null() {
        return false;
    }
    match value {
        Value::Object(map) => !map.is_empty(),
        Value::Array(arr) => !arr.is_empty(),
        Value::String(s) => !s.is_empty(),
        Value::Number(_) | Value::Bool(_) => true,
        _ => false,
    }
}

/// Returns true when GraphQL errors indicate an auth failure.
pub fn has_auth_errors(json: &Value) -> bool {
    let Some(errors) = json.get("errors").and_then(|e| e.as_array()) else {
        return false;
    };
    errors.iter().any(|e| {
        let msg = e
            .get("message")
            .and_then(|m| m.as_str())
            .unwrap_or("")
            .to_lowercase();
        msg.contains("unauthorized")
            || msg.contains("unauthenticated")
            || msg.contains("forbidden")
            || msg.contains("not authorized")
            || msg.contains("authentication")
    })
}

/// Returns true when errors look like "field does not exist" rather than auth bypass.
pub fn is_unknown_field_error(errors: &[String]) -> bool {
    errors.iter().any(|msg| {
        msg.contains("cannot query field")
            || msg.contains("did you mean")
            || msg.contains("unknown field")
            || msg.contains("field undefined")
            || msg.contains("is not defined")
    })
}

async fn post_query(
    client: &ScanClient,
    url: &str,
    query: &str,
) -> Result<scanclient::ScanResponse> {
    let body = json!({ "query": query });
    let request = client
        .request(scanclient::reqwest::Method::POST, url)
        .header(CONTENT_TYPE, "application/json")
        .body(body.to_string());
    client.execute(request).await.map_err(Into::into)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn meaningful_field_data_requires_non_empty_object() {
        let json: Value = serde_json::from_str(r#"{"data":{"users":[{"id":"1"}]}}"#).unwrap();
        assert!(has_meaningful_field_data(&json, "users"));
        let empty: Value = serde_json::from_str(r#"{"data":{"users":{}}}"#).unwrap();
        assert!(!has_meaningful_field_data(&empty, "users"));
    }
}