zhongwei/gh-agentsecops-secopsagentkit

Fork 0

Files

Zhongwei Li ff1f4bd119 Initial commit

2025-11-29 17:51:02 +08:00

22 KiB

Raw Blame History

name, description, version, maintainer, category, tags, frameworks, dependencies, references

name

description

version

maintainer

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/TypeScript functions
assets/rule-templates/ - Reusable rule templates for common security patterns

Step 5: CI/CD Pipeline Integration

Integrate Spectral into continuous integration workflows:

GitHub Actions:

# .github/workflows/api-security-lint.yml
name: API Security Linting

on: [push, pull_request]

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli

      - name: Lint API Specifications
        run: |
          spectral lint api-specs/*.yaml \
            --ruleset .spectral.yaml \
            --format github-actions \
            --fail-severity error

      - name: Generate Report
        if: always()
        run: |
          spectral lint api-specs/*.yaml \
            --ruleset .spectral.yaml \
            --format json \
            --output spectral-report.json

      - name: Upload Report
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: spectral-security-report
          path: spectral-report.json

GitLab CI:

# .gitlab-ci.yml
api-security-lint:
  stage: test
  image: node:18
  script:
    - npm install -g @stoplight/spectral-cli
    - spectral lint api-specs/*.yaml --ruleset .spectral.yaml --fail-severity error
  artifacts:
    when: always
    reports:
      junit: spectral-report.xml

Docker-Based Pipeline:

# Run in CI/CD with Docker
docker run --rm \
  -v $(pwd):/work \
  stoplight/spectral lint /work/openapi.yaml \
  --ruleset /work/.spectral.yaml \
  --format json \
  --output /work/results.json

# Fail build on critical security issues
if jq -e '.[] | select(.severity == 0)' results.json > /dev/null; then
  echo "Critical security issues detected!"
  exit 1
fi

For complete CI/CD integration examples, see scripts/ci_integration_examples/.

Step 6: Results Analysis and Remediation

Analyze findings and provide security remediation:

# Parse Spectral JSON output for security report
python3 scripts/parse_spectral_results.py \
  --input spectral-report.json \
  --output security-report.html \
  --map-owasp \
  --severity-threshold error

# Generate remediation guidance
python3 scripts/generate_remediation.py \
  --input spectral-report.json \
  --output remediation-guide.md

Validation Workflow:

Review all error-level findings (critical security issues)
Verify each finding in API specification context
Map findings to OWASP API Security Top 10 categories
Prioritize by severity and exploitability
Apply fixes to API specifications
Re-lint to verify remediation
Document security decisions and exceptions

Feedback Loop Pattern:

# 1. Initial lint
spectral lint openapi.yaml --ruleset .spectral.yaml -o scan1.json

# 2. Apply security fixes to API specification

# 3. Re-lint to verify fixes
spectral lint openapi.yaml --ruleset .spectral.yaml -o scan2.json

# 4. Compare results
python3 scripts/compare_spectral_results.py scan1.json scan2.json

Advanced Patterns

Pattern 1: Multi-Specification Governance

Enforce consistent security standards across API portfolio:

# Scan all API specifications with organization ruleset
find api-specs/ -name "*.yaml" -o -name "*.json" | while read spec; do
  echo "Linting: $spec"
  spectral lint "$spec" \
    --ruleset .spectral-org-standards.yaml \
    --format json \
    --output "reports/$(basename $spec .yaml)-report.json"
done

# Aggregate findings across portfolio
python3 scripts/aggregate_api_findings.py \
  --input-dir reports/ \
  --output portfolio-security-report.html

Pattern 2: Progressive Severity Enforcement

Start with warnings and progressively enforce stricter rules:

# .spectral-phase1.yaml - Initial rollout (warnings only)
extends: ["spectral:oas"]
rules:
  servers-use-https: warn
  operation-security-defined: warn

# .spectral-phase2.yaml - Enforcement phase (errors)
extends: ["spectral:oas"]
rules:
  servers-use-https: error
  operation-security-defined: error

# Phase 1: Awareness (don't fail builds)
spectral lint openapi.yaml --ruleset .spectral-phase1.yaml

# Phase 2: Enforcement (fail on violations)
spectral lint openapi.yaml --ruleset .spectral-phase2.yaml --fail-severity error

Pattern 3: API Security Pre-Commit Validation

Prevent insecure API specifications from being committed:

# .git/hooks/pre-commit
#!/bin/bash

# Find staged API specification files
SPECS=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(yaml|yml|json)$' | grep -E '(openapi|swagger|api)')

if [ -n "$SPECS" ]; then
  echo "Validating API specifications..."
  for spec in $SPECS; do
    spectral lint "$spec" --ruleset .spectral.yaml --fail-severity error
    if [ $? -ne 0 ]; then
      echo "Security validation failed for $spec"
      exit 1
    fi
  done
fi

Pattern 4: Automated Security Review Comments

Generate security review comments for pull requests:

# Generate PR review comments from Spectral findings
spectral lint openapi.yaml \
  --ruleset .spectral.yaml \
  --format json | \
python3 scripts/generate_pr_comments.py \
  --file openapi.yaml \
  --severity error,warn \
  --output pr-comments.json

# Post to GitHub PR via gh CLI
gh pr comment $PR_NUMBER --body-file pr-comments.json

Custom Functions for Advanced Security Rules

Create custom JavaScript functions for complex security validation:

// spectral-functions/check-jwt-expiry.js
export default (targetVal, opts) => {
  // Validate JWT security scheme includes expiration
  if (targetVal.type === 'http' && targetVal.scheme === 'bearer') {
    if (!targetVal.bearerFormat || targetVal.bearerFormat !== 'JWT') {
      return [{
        message: 'Bearer authentication should specify JWT format'
      }];
    }
  }
  return [];
};

# .spectral.yaml with custom function
functions:
  - check-jwt-expiry
functionsDir: ./spectral-functions

rules:
  jwt-security-check:
    description: Validate JWT security configuration
    severity: error
    given: $.components.securitySchemes[*]
    then:
      function: check-jwt-expiry

For complete custom function development guide, see references/custom_functions.md.

Automation & Continuous Validation

Scheduled API Security Scanning

# Automated daily API specification scanning
./scripts/spectral_scheduler.sh \
  --schedule daily \
  --specs-dir api-specs/ \
  --ruleset .spectral-owasp.yaml \
  --output-dir scan-results/ \
  --alert-on error \
  --slack-webhook $SLACK_WEBHOOK

API Specification Monitoring

# Monitor API specifications for security regressions
./scripts/spectral_monitor.sh \
  --baseline baseline-scan.json \
  --current-scan latest-scan.json \
  --alert-on-new-findings \
  --email security-team@example.com

Security Considerations

Specification Security: API specifications may contain sensitive information (internal URLs, authentication schemes) - control access and sanitize before sharing
Rule Integrity: Protect ruleset files from unauthorized modification - store in version control with code review requirements
False Positives: Manually review findings before making security claims - context matters for API design decisions
Specification Versioning: Maintain version history of API specifications to track security improvements over time
Secrets in Specs: Never include actual credentials, API keys, or secrets in example values - use placeholder values only
Compliance Mapping: Document how Spectral rules map to compliance requirements (PCI-DSS, GDPR, HIPAA)
Governance Enforcement: Define exception process for legitimate rule violations with security team approval
Audit Logging: Log all Spectral scans, findings, and remediation actions for security auditing
Access Control: Restrict modification of security rulesets to designated API security team members
Continuous Validation: Re-validate API specifications whenever they change or when new security rules are added

Bundled Resources

Scripts (`scripts/`)

parse_spectral_results.py - Parse Spectral JSON output and generate security reports with OWASP mapping
generate_remediation.py - Generate remediation guidance based on Spectral findings
compare_spectral_results.py - Compare two Spectral scans to track remediation progress
aggregate_api_findings.py - Aggregate findings across multiple API specifications
spectral_ci.sh - CI/CD integration wrapper with exit code handling
spectral_scheduler.sh - Scheduled scanning with alerting
spectral_monitor.sh - Continuous monitoring with baseline comparison
generate_pr_comments.py - Convert Spectral findings to PR review comments

References (`references/`)

owasp_api_mappings.md - Complete OWASP API Security Top 10 rule mappings
custom_rules_guide.md - Custom rule authoring with examples
custom_functions.md - Creating custom JavaScript/TypeScript validation functions
ruleset_patterns.md - Reusable ruleset patterns for common security scenarios
api_security_checklist.md - API security validation checklist

Assets (`assets/`)

spectral-owasp.yaml - Comprehensive OWASP API Security Top 10 ruleset
spectral-org-template.yaml - Organization-wide API security standards template
github-actions-template.yml - Complete GitHub Actions workflow
gitlab-ci-template.yml - GitLab CI integration template
rule-templates/ - Reusable security rule templates

Common Patterns

Pattern 1: Security-First API Design Validation

Validate API specifications during design phase:

# Design phase validation (strict security rules)
spectral lint api-design.yaml \
  --ruleset .spectral-owasp.yaml \
  --fail-severity warn \
  --verbose

Pattern 2: API Specification Diff Analysis

Detect security regressions between API versions:

# Compare two API specification versions
spectral lint api-v2.yaml --ruleset .spectral.yaml -o v2-findings.json
spectral lint api-v1.yaml --ruleset .spectral.yaml -o v1-findings.json

python3 scripts/compare_spectral_results.py \
  --baseline v1-findings.json \
  --current v2-findings.json \
  --show-regressions

Pattern 3: Multi-Environment API Security

Different rulesets for development, staging, production:

# .spectral-dev.yaml (permissive)
extends: ["spectral:oas"]
rules:
  servers-use-https: warn

# .spectral-prod.yaml (strict)
extends: ["spectral:oas"]
rules:
  servers-use-https: error
  operation-security-defined: error

Integration Points

CI/CD: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure DevOps
API Gateways: Kong, Apigee, AWS API Gateway (validate specs before deployment)
IDE Integration: VS Code extension, JetBrains plugins for real-time validation
API Documentation: Stoplight Studio, Swagger UI, Redoc
Issue Tracking: Jira, GitHub Issues, Linear (automated ticket creation for findings)
API Governance: Backstage, API catalogs (enforce standards across portfolios)
Security Platforms: Defect Dojo, SIEM platforms (via JSON export)

Troubleshooting

Issue: Too Many False Positives

Solution:

Start with error severity only: spectral lint --fail-severity error
Progressively add rules and adjust severity levels
Use overrides section in ruleset to exclude specific paths
See references/ruleset_patterns.md for filtering strategies

Issue: Custom Rules Not Working

Solution:

Verify JSONPath expressions using online JSONPath testers
Check rule syntax with spectral lint --ruleset .spectral.yaml --verbose
Use --verbose flag to see which rules are being applied
Test rules in isolation before combining them

Issue: Performance Issues with Large Specifications

Solution:

Lint specific paths only: spectral lint api-spec.yaml --ignore-paths "components/examples"
Use --skip-rules to disable expensive rules temporarily
Split large specifications into smaller modules
Run Spectral in parallel for multiple specifications

Issue: CI/CD Integration Failing

Solution:

Check Node.js version compatibility (requires Node 14+)
Verify ruleset path is correct relative to specification file
Use --fail-severity to control when builds should fail
Review exit codes in scripts/spectral_ci.sh

22 KiB Raw Blame History

API Security with Spectral

Overview

Quick Start

Installation

Basic API Specification Linting

Quick Security Scan

Core Workflow

Workflow Checklist

Step 1: Ruleset Configuration

Step 2: Security-Focused API Linting

Step 3: OWASP API Security Validation

Step 4: Custom Security Rule Development

Step 5: CI/CD Pipeline Integration

Step 6: Results Analysis and Remediation

Advanced Patterns

Pattern 1: Multi-Specification Governance

Pattern 2: Progressive Severity Enforcement

Pattern 3: API Security Pre-Commit Validation

Pattern 4: Automated Security Review Comments

Custom Functions for Advanced Security Rules

Automation & Continuous Validation

Scheduled API Security Scanning

API Specification Monitoring

Security Considerations

Bundled Resources

Scripts (scripts/)

References (references/)

Assets (assets/)

Common Patterns

Pattern 1: Security-First API Design Validation

Pattern 2: API Specification Diff Analysis

Pattern 3: Multi-Environment API Security

Integration Points

Troubleshooting

Issue: Too Many False Positives

Issue: Custom Rules Not Working

Issue: Performance Issues with Large Specifications

Issue: CI/CD Integration Failing

References

22 KiB

Raw Blame History

Scripts (`scripts/`)

References (`references/`)

Assets (`assets/`)