api-spectral

API Security with Spectral

Overview

Spectral is a flexible JSON/YAML linter from Stoplight that validates API specifications against security best practices and organizational standards. With built-in rulesets for OpenAPI v2/v3.x, AsyncAPI v2.x, and Arazzo v1.0, Spectral helps identify security vulnerabilities, design flaws, and compliance issues during the API design phase—before code is written. Custom rulesets enable enforcement of OWASP API Security Top 10 patterns, authentication standards, and data protection requirements across your entire API portfolio.

Quick Start

Installation

# Install via npm
npm install -g @stoplight/spectral-cli

# Or using Yarn
yarn global add @stoplight/spectral-cli

# Or using Docker
docker pull stoplight/spectral

# Verify installation
spectral --version

Basic API Specification Linting

# Lint OpenAPI specification with built-in rules
spectral lint openapi.yaml

# Lint with specific ruleset
spectral lint openapi.yaml --ruleset .spectral.yaml

# Output as JSON for CI/CD integration
spectral lint openapi.yaml --format json --output results.json

Quick Security Scan

# Create security-focused ruleset
echo 'extends: ["spectral:oas"]' > .spectral.yaml

# Lint API specification
spectral lint api-spec.yaml --ruleset .spectral.yaml

Core Workflow

Workflow Checklist

Progress: [ ] 1. Install Spectral and select appropriate base rulesets [ ] 2. Create or configure ruleset with security rules [ ] 3. Identify API specifications to validate (OpenAPI, AsyncAPI, Arazzo) [ ] 4. Run linting with appropriate severity thresholds [ ] 5. Review findings and categorize by security impact [ ] 6. Map findings to OWASP API Security Top 10 [ ] 7. Create custom rules for organization-specific security patterns [ ] 8. Integrate into CI/CD pipeline with failure thresholds [ ] 9. Generate reports with remediation guidance [ ] 10. Establish continuous validation process

Work through each step systematically. Check off completed items.

Step 1: Ruleset Configuration

Create a .spectral.yaml ruleset extending built-in security rules:

# .spectral.yaml - Basic security-focused ruleset
extends: ["spectral:oas", "spectral:asyncapi"]

rules:
  # Enforce HTTPS for all API endpoints
  oas3-valid-schema-example: true
  oas3-server-not-example.com: true

  # Authentication security
  operation-security-defined: error

  # Information disclosure prevention
  info-contact: warn
  info-description: warn

Built-in Rulesets:

• spectral:oas - OpenAPI v2/v3.x security and best practices
• spectral:asyncapi - AsyncAPI v2.x validation rules
• spectral:arazzo - Arazzo v1.0 workflow specifications

Ruleset Selection Best Practices:

• Start with built-in rulesets and progressively add custom rules
• Use error severity for critical security issues (authentication, HTTPS)
• Use warn for recommended practices and information disclosure risks
• Use info for style guide compliance and documentation completeness

For advanced ruleset patterns, see references/ruleset_patterns.md.

Step 2: Security-Focused API Linting

Run Spectral with security-specific validation:

# Comprehensive security scan
spectral lint openapi.yaml \
  --ruleset .spectral.yaml \
  --format stylish \
  --verbose

# Focus on error-level findings only (critical security issues)
spectral lint openapi.yaml \
  --ruleset .spectral.yaml \
  --fail-severity error

# Scan multiple specifications
spectral lint api-specs/*.yaml --ruleset .spectral.yaml

# Generate JSON report for further analysis
spectral lint openapi.yaml \
  --ruleset .spectral.yaml \
  --format json \
  --output security-findings.json

Output Formats:

• stylish - Human-readable terminal output (default)
• json - Machine-readable JSON for CI/CD integration
• junit - JUnit XML for test reporting platforms
• html - HTML report (requires additional plugins)
• github-actions - GitHub Actions annotations format

Step 3: OWASP API Security Validation

Validate API specifications against OWASP API Security Top 10:

# .spectral-owasp.yaml - OWASP API Security focused rules
extends: ["spectral:oas"]

rules:
  # API1:2023 - Broken Object Level Authorization
  operation-security-defined:
    severity: error
    message: "All operations must have security defined (OWASP API1)"

  # API2:2023 - Broken Authentication
  security-schemes-defined:
    severity: error
    message: "API must define security schemes (OWASP API2)"

  # API3:2023 - Broken Object Property Level Authorization
  no-additional-properties:
    severity: warn
    message: "Consider disabling additionalProperties to prevent data leakage (OWASP API3)"

  # API5:2023 - Broken Function Level Authorization
  operation-tag-defined:
    severity: warn
    message: "Operations should be tagged for authorization policy mapping (OWASP API5)"

  # API7:2023 - Server Side Request Forgery
  no-http-basic:
    severity: error
    message: "HTTP Basic auth transmits credentials in plain text (OWASP API7)"

  # API8:2023 - Security Misconfiguration
  servers-use-https:
    description: All server URLs must use HTTPS
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"
    message: "Server URL must use HTTPS (OWASP API8)"

  # API9:2023 - Improper Inventory Management
  api-version-required:
    severity: error
    given: $.info
    then:
      field: version
      function: truthy
    message: "API version must be specified (OWASP API9)"

Run OWASP-focused validation:

spectral lint openapi.yaml --ruleset .spectral-owasp.yaml

For complete OWASP API Security Top 10 rule mappings, see references/owasp_api_mappings.md.

Step 4: Custom Security Rule Development

Create organization-specific security rules using Spectral's rule engine:

# .spectral-custom.yaml
extends: ["spectral:oas"]

rules:
  # Require API key authentication
  require-api-key-auth:
    description: All APIs must support API key authentication
    severity: error
    given: $.components.securitySchemes[*]
    then:
      field: type
      function: enumeration
      functionOptions:
        values: [apiKey, oauth2, openIdConnect]
    message: "API must define apiKey, OAuth2, or OpenID Connect security"

  # Prevent PII in query parameters
  no-pii-in-query:
    description: Prevent PII exposure in URL query parameters
    severity: error
    given: $.paths[*][*].parameters[?(@.in == 'query')].name
    then:
      function: pattern
      functionOptions:
        notMatch: "(ssn|social.?security|credit.?card|password|secret|token)"
    message: "Query parameters must not contain PII identifiers"

  # Require rate limiting headers
  require-rate-limit-headers:
    description: API responses should include rate limit headers
    severity: warn
    given: $.paths[*][*].responses[*].headers
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            X-RateLimit-Limit: true
            X-RateLimit-Remaining: true
    message: "Consider adding rate limit headers for security"

  # Enforce consistent error responses
  error-response-format:
    description: Error responses must follow standard format
    severity: error
    given: $.paths[*][*].responses[?(@property >= 400)].content.application/json.schema
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: [error, message]
          properties:
            error:
              type: string
            message:
              type: string
    message: "Error responses must include 'error' and 'message' fields"

Custom Rule Development Resources:

• references/custom_rules_guide.md - Complete rule authoring guide with functions
• references/custom_functions.md - Creating custom JavaScript/TypeScrip