Graphql Introspection in Fastapi with Cockroachdb

GraphQL introspection in a FastAPI application that uses CockroachDB can expose sensitive schema details that aid reconnaissance for attackers. Introspection is a core GraphQL feature that allows clients to query the schema structure, types, and queries available. When enabled in production, introspection can reveal field names, argument types, and relationships that map closely to database models and access patterns in CockroachDB.

In a FastAPI implementation, GraphQL endpoints are often backed by SQLAlchemy models that map to CockroachDB tables. If introspection is not restricted, an attacker can use queries like { __schema { queryType { fields { name } } } } to enumerate operations that interact with the database. This can expose data structures such as user tables, tenant identifiers, or sensitive attributes that map to columns in CockroachDB.

Because CockroachDB is a distributed SQL database, schema information such as table and column names is directly reflected in the GraphQL types. Without input validation and schema hardening, introspection can lead to information disclosure that facilitates further attacks, such as IDOR or BOLA, by clarifying resource naming conventions stored in CockroachDB.

When combined with unauthenticated or improperly authenticated GraphQL endpoints, introspection becomes a low-effort reconnaissance tool. Attackers can correlate schema findings with known CVEs for CockroachDB or exploit patterns in FastAPI route handling to infer backend behavior. This is particularly risky when the GraphQL schema mirrors database relations one-to-one, as it simplifies mapping introspection results to potential data exfiltration paths.

middleBrick detects GraphQL introspection exposure as part of its Input Validation and LLM/AI Security checks, highlighting the risk when introspection is allowed without controls. The scanner correlates findings with the OpenAPI spec and runtime behavior, ensuring that schema exposure risks are surfaced alongside other findings. This helps teams understand how introspection interacts with CockroachDB-backed services in FastAPI deployments.

To secure a FastAPI GraphQL endpoint backed by CockroachDB, disable introspection in production and apply strict input validation. Below are concrete code examples that demonstrate how to implement these controls while preserving development utility.

1. Disable introspection in production

Configure your GraphQL view to disable introspection when the application is not in a development environment. This prevents schema discovery via queries while keeping introspection available locally.

from starlette.applications import Starlette
from starlette.routing import Mount
from graphql_server.fastapi import GraphQLApp
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
import os

# CockroachDB connection string
DATABASE_URL = os.getenv("COCKROACHDB_URL", "postgresql://root@localhost:26257/defaultdb?sslmode=disable")

engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

def get_graphql_app(disable_introspection: bool = True):
    return GraphQLApp(
        schema=schema,  # your GraphQL schema
        debug=not disable_introspection,
        introspection=not disable_introspection,
    )

app = Starlette(
    routes=[
        Mount("/graphql", app=get_graphql_app(disable_introspection=True)),
    ]
)

2. Validate and limit query complexity

Use query complexity analysis to restrict overly broad introspection-like queries even when introspection is technically enabled for certain roles. This adds a layer of protection specific to data exposure risks from CockroachDB-backed queries.

from graphql import graphql_sync
from graphql.validation import ValidationRule

def validate_query(document, context_value):
    # Implement complexity rules that limit depth and fields
    errors = []
    for definition in document.definitions:
        if definition.__class__.__name__ == 'OperationDefinition':
            # Example: restrict queries touching sensitive CockroachDB tables
            fields = extract_fields(definition)
            if any('users' in field.name.value for field in fields):
                errors.append('Querying users table is restricted')
    return errors

# In your FastAPI resolver, apply validation before execution
async def resolve_field_with_validation(root, info):
    validation_errors = validate_query(info.document, info.context)
    if validation_errors:
        raise ValueError('Invalid query: ' + '; '.join(validation_errors))
    # proceed with CockroachDB session logic

3. Use CockroachDB-specific session controls

Ensure database sessions and transactions are scoped correctly to avoid leaking schema information through error messages or verbose logs that could aid an attacker.

from sqlalchemy.exc import SQLAlchemyError

async def safe_db_call(statement, params):
    session = SessionLocal()
    try:
        result = session.execute(statement, params)
        session.commit()
        return result
    except SQLAlchemyError as e:
        # Avoid exposing CockroachDB internal details
        raise RuntimeError('Database operation failed') from None
    finally:
        session.close()

# Example usage in a resolver
async def get_user_by_id(root, info, user_id: int):
    stmt = select(users).where(users.c.id == user_id)
    return await safe_db_call(stmt, {})

4. Environment-aware schema loading

Load a trimmed schema for production while keeping a full schema for development. This ensures introspection is harmless in CI/CD while protecting production metadata tied to CockroachDB.

from graphql import build_schema

def load_schema(env: str):
    if env == 'production':
        with open('schema_limited.graphql') as f:
            return build_schema(f.read())
    else:
        with open('schema_full.graphql') as f:
            return build_schema(f.read())

schema = load_schema(os.getenv('ENV', 'development'))

These remediation steps help reduce the attack surface introduced by GraphQL introspection when using FastAPI with CockroachDB. By combining schema restrictions, input validation, and environment-aware configurations, you limit the exposure of database structure without sacrificing developer tooling.

middleBrick can validate these configurations by scanning your GraphQL endpoint and checking whether introspection is exposed in production contexts. The scanner correlates findings with the OpenAPI spec and flags high-risk patterns, helping you verify that remediation aligns with secure design principles for CockroachDB-backed services.