graphql-sentinel

Comprehensive GraphQL security scanner and runtime shield. Detect vulnerabilities in your GraphQL API and protect it at runtime with validation rules and rate limiting.

Quick Start

Scan any GraphQL endpoint for security vulnerabilities:

npx graphql-sentinel scan https://api.example.com/graphql

Installation

npm install graphql-sentinel graphql

Requirements

• Node.js >= 18.0.0
• graphql >= 16.0.0 (peer dependency)
• graphql-yoga >= 5.0.0 (optional, for Yoga plugin)
• @apollo/server >= 4.0.0 (optional, for Apollo plugin)
• TypeScript >= 5.0 (optional, for type definitions)

Fully written in TypeScript with complete type exports for all public APIs.

CLI Usage

Scan an endpoint

# Basic scan with terminal output
graphql-sentinel scan https://api.example.com/graphql

# JSON output
graphql-sentinel scan https://api.example.com/graphql --format json

# HTML report saved to file
graphql-sentinel scan https://api.example.com/graphql --format html --output report.html

# SARIF report for GitHub Security tab
graphql-sentinel scan https://api.example.com/graphql --format sarif --output report.sarif.json

# Security dashboard
graphql-sentinel scan https://api.example.com/graphql --format dashboard --output dashboard.html

# With custom headers
graphql-sentinel scan https://api.example.com/graphql -H "Authorization: Bearer token123"

# Run specific checks only
graphql-sentinel scan https://api.example.com/graphql --checks introspection,csrf,depth-limit,auth-bypass

# Custom timeout per check (in ms)
graphql-sentinel scan https://api.example.com/graphql --timeout 15000

The CLI exits with code 1 if any critical or high severity issues are found, making it suitable for CI/CD pipelines.

Start a security proxy

# Basic proxy with depth limiting
graphql-sentinel proxy https://upstream-api.example.com/graphql --max-depth 10

# Full shield configuration
graphql-sentinel proxy https://upstream-api.example.com/graphql \
  --port 4000 \
  --max-depth 10 \
  --max-complexity 1000 \
  --max-aliases 15 \
  --disable-introspection \
  --rate-limit-window 60000 \
  --rate-limit-max 100

# Forward auth headers to upstream
graphql-sentinel proxy https://upstream-api.example.com/graphql \
  -H "X-API-Key: secret"

Security Checks

Check	Severity	Description
introspection	Medium	Detects if introspection is enabled, exposing the full schema
depth-limit	High	Tests for absence of query depth limits (DoS vector)
batch-attack	Medium	Checks if batch queries are accepted (amplification attacks)
field-suggestion	Low	Detects field suggestions in error messages (schema enumeration)
alias-overloading	Medium	Tests if unlimited aliases are accepted (DoS vector)
csrf	High	Checks if queries are accepted via GET requests (CSRF risk)
auth-bypass	High	Tests for authorization bypass by sending unauthenticated requests

Authorization Bypass Detection

The auth-bypass check tests your endpoint for missing or improperly configured authorization:

1. Sends a request without any auth headers
2. Sends a request with an empty Authorization header
3. Sends a request with an invalid Bearer token
4. If auth headers are provided, compares authenticated vs unauthenticated responses

If any unauthenticated request returns data, it flags a potential bypass. Public APIs (no auth configured) are reported as info severity rather than failures.

Shield Middleware

Protect your GraphQL server at runtime with validation rules.

GraphQL Yoga

import { createYoga, createSchema } from 'graphql-yoga';
import { useSentinelShield } from 'graphql-sentinel';

const yoga = createYoga({
  schema: createSchema({ /* ... */ }),
  plugins: [
    useSentinelShield({
      maxDepth: 10,
      maxComplexity: 1000,
      maxAliases: 15,
      disableIntrospection: true,
      rateLimit: { window: 60000, max: 100 },
    }),
  ],
});

Apollo Server

import { ApolloServer } from '@apollo/server';
import { sentinelApolloPlugin } from 'graphql-sentinel';

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    sentinelApolloPlugin({
      maxDepth: 10,
      maxComplexity: 1000,
      disableIntrospection: true,
    }),
  ],
});

Express Middleware

import express from 'express';
import { GraphQLSchema } from 'graphql';
import { sentinelMiddleware } from 'graphql-sentinel';

const app = express();
app.use(express.json());

// Apply before your GraphQL middleware
app.use('/graphql', sentinelMiddleware(schema, {
  maxDepth: 10,
  maxAliases: 15,
  disableIntrospection: true,
}));

Field-Level Authorization

Enforce fine-grained authorization at the field level using GraphQL validation rules:

import { createShield, createFieldAuthRule } from 'graphql-sentinel';

const shield = createShield({
  maxDepth: 10,
  fieldAuth: {
    rules: {
      'Query.users': { requireAuth: true, roles: ['admin'] },
      'Query.user': { requireAuth: true, permissions: ['read:users'] },
      'Mutation.deleteUser': { requireAuth: true, roles: ['admin'] },
      'User.email': { requireAuth: true },
    },
    extractContext: (context) => {
      // Extract user info from your GraphQL context
      const user = (context as any)?.user;
      if (!user) return null;
      return {
        authenticated: true,
        roles: user.roles || [],
        permissions: user.permissions || [],
      };
    },
  },
});

// Use with graphql's validate()
const errors = validate(schema, parse(query), shield.validationRules);

The createFieldAuthRule can also be used standalone:

import { createFieldAuthRule } from 'graphql-sentinel';

const rule = createFieldAuthRule({
  rules: {
    'Query.sensitiveData': { requireAuth: true, roles: ['admin'] },
  },
  extractContext: (ctx) => /* ... */,
});

// Add to your validation rules array
const errors = validate(schema, document, [rule]);

Proxy Mode

Run graphql-sentinel as a standalone reverse proxy that enforces security rules before forwarding requests to your upstream GraphQL server:

import { createProxyServer, startProxy } from 'graphql-sentinel';

// Quick start
await startProxy({
  target: 'https://upstream-api.example.com/graphql',
  port: 4000,
  shield: {
    maxDepth: 10,
    maxComplexity: 1000,
    maxAliases: 15,
    disableIntrospection: true,
    rateLimit: { window: 60000, max: 100 },
  },
  headers: { 'X-API-Key': 'upstream-key' },
});

// Or get the raw http.Server for custom configuration
const server = createProxyServer({
  target: 'https://upstream-api.example.com/graphql',
  port: 4000,
  shield: { maxDepth: 10 },
});
server.listen(4000);

The proxy:

• Parses and validates all incoming GraphQL queries against shield rules
• Blocks queries that exceed depth, complexity, or alias limits
• Blocks introspection queries when configured
• Enforces rate limiting per client IP
• Forwards valid queries to the upstream server
• Handles CORS headers automatically
• Returns 400 for blocked queries with detailed error messages
• Returns 429 for rate-limited requests

Report Formats

Terminal

ANSI-colored output for terminal/CLI usage.

JSON

Machine-readable JSON output of the full scan report.

HTML

Self-contained HTML report with styled results.

SARIF (Static Analysis Results Interchange Format)

SARIF 2.1.0 compliant output for integration with GitHub's Security tab:

graphql-sentinel scan https://api.example.com/graphql --format sarif --output results.sarif

Upload to GitHub Security tab:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Dashboard

A rich, interactive security dashboard with:

• Security posture score (0-100) weighted by severity
• Executive summary suitable for management reporting
• Category breakdown (Authorization, DoS, Information Disclosure)
• Expandable check details with remediation guidance
• Vulnerability timeline tracking when multiple reports are provided
• localStorage persistence for building history across browser sessions
• Dark theme with professional styling, fully self-contained (no external dependencies)

graphql-sentinel scan https://api.example.com/graphql --format dashboard --output dashboard.html

Programmatic usage with multiple reports for timeline tracking:

import { generateDashboard, runScan } from 'graphql-sentinel';

const reports = [previousReport, currentReport];
const html = generateDashboard(reports, { title: 'My API Security Dashboard' });

GitHub Action

Use graphql-sentinel as a reusable GitHub Action in your CI/CD pipelines:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: mstuart/graphql-sentinel/.github/actions/scan@main
        with:
          endpoint: 'https://api.example.com/graphql'
          format: 'sarif'
          fail-on-severity: 'high'
          headers: |
            Authorization: Bearer ${{ secrets.API_TOKEN }}

Action Inputs

Input	Required	Default	Description
endpoint	Yes	-	GraphQL endpoint URL to scan
format	No	terminal	Output format (terminal, json, html, sarif)
checks	No	all	Comma-separated list of checks to run
fail-on-severity	No	high	Minimum severity to fail the build
headers	No	-	Headers, one per line ("Key: Value")
timeout	No	10000	Timeout per check in milliseconds

Action Outputs

Output	Description
report	Path to the generated report file
passed	Whether the scan passed (true/false)

The action automatically uploads the report as a build artifact named sentinel-security-report.

Programmatic API

Scanner

import { runScan } from 'graphql-sentinel';

const report = await runScan({
  endpoint: 'https://api.example.com/graphql',
  headers: { Authorization: 'Bearer token' },
  checks: ['introspection', 'depth-limit', 'csrf', 'auth-bypass'],
  timeout: 10000,
});

console.log(`Found ${report.summary.failed} issues`);

Shield (Standalone)

import { createShield } from 'graphql-sentinel';
import { validate, parse } from 'graphql';

const shield = createShield({
  maxDepth: 10,
  maxComplexity: 1000,
  maxAliases: 15,
  disableIntrospection: true,
  rateLimit: { window: 60000, max: 100 },
});

// Use validation rules with graphql's validate()
const errors = validate(schema, parse(query), shield.validationRules);

// Use rate limiter
if (shield.rateLimiter) {
  const { allowed, remaining } = shield.rateLimiter.check(clientIp, queryCost);
  if (!allowed) {
    throw new Error('Rate limit exceeded');
  }
}

Report Generation

import { runScan, generateReport, generateDashboard, generateSarifReport } from 'graphql-sentinel';

const report = await runScan({ endpoint: 'https://api.example.com/graphql' });

// Terminal output with ANSI colors
console.log(generateReport(report, 'terminal'));

// JSON
const json = generateReport(report, 'json');

// Self-contained HTML
const html = generateReport(report, 'html');

// SARIF for GitHub Security tab
const sarif = generateReport(report, 'sarif');

// Dashboard with timeline tracking
const dashboard = generateDashboard([report], { title: 'Security Dashboard' });

Configuration Reference

ScannerConfig

Option	Type	Default	Description
endpoint	string	required	GraphQL endpoint URL
headers	Record<string, string>	undefined	Custom HTTP headers
checks	string[]	all checks	List of check names to run
timeout	number	10000	Timeout per check in milliseconds

ShieldConfig

Option	Type	Default	Description
maxDepth	number	undefined	Maximum query nesting depth
maxComplexity	number	undefined	Maximum query complexity score
maxAliases	number	undefined	Maximum number of aliases per query
disableIntrospection	boolean	false	Block introspection queries
costLimit	number	undefined	Maximum query cost
rateLimit.window	number	undefined	Rate limit window in milliseconds
rateLimit.max	number	undefined	Maximum cost per window
fieldAuth	FieldAuthConfig	undefined	Field-level authorization rules

ProxyConfig

Option	Type	Default	Description
target	string	required	Upstream GraphQL endpoint URL
port	number	4000	Proxy listening port
shield	ShieldConfig	required	Shield configuration
headers	Record<string, string>	undefined	Headers to forward to upstream
cors	boolean	true	Enable CORS headers

FieldAuthConfig

Option	Type	Description
rules	Record<string, FieldAuthRule>	Map of TypeName.fieldName to auth rules
extractContext	(context) => UserContext | null	Function to extract user context

FieldAuthRule

Option	Type	Description
requireAuth	boolean	Whether authentication is required
roles	string[]	Required roles (any match grants access)
permissions	string[]	Required permissions (any match grants access)

Comparison with graphql-armor

graphql-armor is an excellent runtime-only shield. graphql-sentinel provides a broader security toolkit:

Feature	graphql-sentinel	graphql-armor
Runtime shield (depth, complexity, aliases)	Yes	Yes
Security scanner (7 automated checks)	Yes	No
CLI for CI/CD pipelines	Yes	No
SARIF reports for GitHub Security tab	Yes	No
Interactive security dashboard	Yes	No
Reverse proxy mode	Yes	No
Reusable GitHub Action	Yes	No
Field-level authorization	Yes	No
Express middleware	Yes	No

Choose graphql-armor if you only need runtime protection. Choose graphql-sentinel if you also want scanning, reporting, CI integration, or proxy deployment.

API Reference

Scanner

• runScan(config: ScannerConfig): Promise<ScanReport> - Run security checks against an endpoint

Shield

• createShield(config: ShieldConfig): Shield - Create shield with validation rules and rate limiter
• createDepthLimitRule(maxDepth?: number) - Create depth limit validation rule
• createComplexityRule(config?: ComplexityConfig) - Create complexity validation rule
• createAliasLimitRule(maxAliases?: number) - Create alias limit validation rule
• createIntrospectionControlRule() - Create introspection blocking rule
• createRateLimiter(config: RateLimitConfig) - Create sliding window rate limiter
• createFieldAuthRule(config: FieldAuthConfig) - Create field-level authorization rule

Proxy

• createProxyServer(config: ProxyConfig): http.Server - Create proxy server instance
• startProxy(config: ProxyConfig): Promise<http.Server> - Create and start proxy server

Plugins

• useSentinelShield(config?: ShieldConfig) - GraphQL Yoga plugin
• sentinelApolloPlugin(config?: ShieldConfig) - Apollo Server plugin
• sentinelMiddleware(schema, config?: ShieldConfig) - Express middleware

Reporter

• generateReport(report: ScanReport, format: 'json' | 'terminal' | 'html' | 'sarif' | 'dashboard'): string - Generate formatted report
• generateSarifReport(report: ScanReport): string - Generate SARIF 2.1.0 report
• generateDashboard(reports: ScanReport[], config?): string - Generate security dashboard
• calculatePostureScore(results: ScanResult[]): number - Calculate security posture score (0-100)

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Run tests (npm test)
4. Commit your changes (git commit -am 'feat: add my feature')
5. Push to the branch (git push origin feature/my-feature)
6. Open a Pull Request

License

MIT