/api-spectral

name: api-spectral
description: >
  API specification linting and security validation using Stoplight's Spectral with support for
  OpenAPI, AsyncAPI, and Arazzo specifications. Validates API definitions against security best
  practices, OWASP API Security Top 10, and custom organizational standards. Use when: (1) Validating
  OpenAPI/AsyncAPI specifications for security issues and design flaws, (2) Enforcing API design
  standards and governance policies across API portfolios, (3) Creating custom security rules for
  API specifications in CI/CD pipelines, (4) Detecting authentication, authorization, and data
  exposure issues in API definitions, (5) Ensuring API specifications comply with organizational
  security standards and regulatory requirements.
version: 0.1.0
maintainer: SirAppSec
category: appsec
tags: [api-security, openapi, asyncapi, linting, spectral, api-governance, owasp-api, specification-validation]
frameworks: [OWASP]
dependencies:
  tools: [node, npm]
  optional: [docker, git]
references:
  - https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview
  - https://github.com/stoplightio/spectral
  - https://owasp.org/API-Security/editions/2023/en/0x11-t10/

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 Autho