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
 [, ]