<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: analyzing-openapi-spec-vulnerabilities
description: >-
  Analyze OpenAPI/Swagger specifications for security misconfigurations including
  missing authentication, overly permissive schemas, undocumented endpoints,
  sensitive data in parameters, and insecure default values.
domain: cybersecurity
subdomain: api-security
tags:
  - openapi
  - swagger
  - api-security
  - schema-validation
  - api-documentation
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1190", "T1592"]
  owasp-api: ["API8", "API9"]
  tools: ["curl", "spectral", "openapi-generator", "nuclei", "schemathesis"]
---

# Analyzing OpenAPI Spec Vulnerabilities

## Overview

OpenAPI/Swagger specifications document API structure and can reveal security
weaknesses: missing security schemes, overly broad input schemas, endpoints
without authentication, sensitive data in query parameters, and deprecated
but active endpoints. Spec analysis is a high-value pre-assessment activity.

## Prerequisites

- Tools: ["curl", "spectral", "openapi-generator", "nuclei", "schemathesis"]
- Access to OpenAPI/Swagger specification (URL or file)
- Authorized testing engagement with written scope

## Key Concepts

- **Security schemes**: Global and per-endpoint authentication definitions
- **Schema validation**: Input/output constraints on request/response bodies
- **Undocumented endpoints**: Endpoints in production not in the spec
- **Deprecated endpoints**: Still active but no longer maintained/patched
- **Sensitive data exposure**: PII in query params (logged by proxies)

## Workflow

### Step 1: Specification Discovery

```bash
# Common OpenAPI spec locations
SPEC_URLS=(
  "/swagger.json"
  "/openapi.json"
  "/api-docs"
  "/api/swagger.json"
  "/api/openapi.json"
  "/v1/swagger.json"
  "/v2/api-docs"
  "/swagger/v1/swagger.json"
  "/.well-known/openapi.yaml"
  "/api/docs"
  "/docs/api.json"
)

for PATH in "${SPEC_URLS[@]}"; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://target.com$PATH")
  [ "$STATUS" = "200" ] && echo "[FOUND] $PATH"
done

# Download and parse specification
curl -s https://target.com/openapi.json | jq '.info, .servers' > spec_info.json
curl -s https://target.com/openapi.json | jq '.paths | keys[]' > endpoints.txt
```

### Step 2: Security Scheme Analysis

```bash
# Check global security definitions
curl -s https://target.com/openapi.json | \
  jq '.securityDefinitions // .components.securitySchemes'

# Find endpoints without security requirements
curl -s https://target.com/openapi.json | \
  jq '.paths | to_entries[] | select(.value | to_entries[] |
      select(.value.security == null or .value.security == [])) |
      "\(.key) — no security defined"'

# Check for API key in query parameter (insecure — logged)
curl -s https://target.com/openapi.json | \
  jq '.components.securitySchemes | to_entries[] |
      select(.value.in == "query") | "\(.key): API key in query string"'
```

### Step 3: Schema Validation Audit

```bash
# Run Spectral linting
spectral lint openapi.json --ruleset spectral-security.yaml

# Custom security ruleset for Spectral
cat > spectral-security.yaml << 'EOF'
extends: [[spectral:oas, recommended]]
rules:
  operation-security-defined:
    description: Every operation must have security defined
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: security
      function: truthy
  no-api-key-in-query:
    description: API keys should not be in query parameters
    given: "$.components.securitySchemes[*]"
    then:
      field: in
      function: pattern
      functionOptions:
        notMatch: query
  request-body-schema:
    description: Request bodies must have schema validation
    given: "$.paths[*][post,put,patch].requestBody.content[*]"
    then:
      field: schema
      function: truthy
EOF

spectral lint openapi.json --ruleset spectral-security.yaml
```

### Step 4: Sensitive Data in Parameters

```bash
# Find sensitive data in query parameters (visible in logs/URLs)
curl -s https://target.com/openapi.json | \
  jq '.paths | to_entries[] | .value | to_entries[] |
      .value.parameters[]? |
      select(.in == "query" and
        (.name | test("password|token|secret|key|ssn|credit"; "i"))) |
      "\(.name) in query — sensitive data exposure"'

# Find endpoints returning sensitive fields
curl -s https://target.com/openapi.json | \
  jq '.paths | to_entries[] | .value | to_entries[] |
      select(.value.responses["200"].content) |
      .value.responses["200"].content | to_entries[] |
      .value.schema.properties? // {} | keys[] |
      select(test("password|secret|ssn|credit_card|token"; "i"))' 2>/dev/null
```

### Step 5: Automated Spec-Based Testing

```bash
# Schemathesis — property-based testing from OpenAPI spec
schemathesis run https://target.com/openapi.json \
  --checks all \
  --hypothesis-max-examples 100 \
  --base-url https://target.com \
  --auth "$TOKEN" --auth-type bearer

# Generate test cases from spec
openapi-generator-cli generate \
  -i openapi.json -g python -o /tmp/api-client

# Nuclei with OpenAPI spec
nuclei -u https://target.com -t http/exposures/apis/ -severity high,critical

# Compare spec endpoints vs live endpoints
comm -23 <(sort endpoints_from_spec.txt) <(sort endpoints_live.txt) \
  > undocumented_endpoints.txt
```

### Step 6: Deprecated Endpoint Analysis

```bash
# Find deprecated endpoints still in spec
curl -s https://target.com/openapi.json | \
  jq '.paths | to_entries[] | .value | to_entries[] |
      select(.value.deprecated == true) |
      "\(.key) — deprecated but documented"'

# Test if deprecated endpoints are still active
while IFS= read -r endpoint; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    -H "Authorization: Bearer $TOKEN" \
    "https://target.com$endpoint")
  [ "$STATUS" != "404" ] && echo "[ACTIVE] $endpoint: HTTP $STATUS"
done < deprecated_endpoints.txt
```

## Detection Opportunities

| Signal | Source | Description |
|--------|--------|-------------|
| Spec file access | WAF | Requests to swagger.json/openapi.json |
| Undocumented endpoint access | API gateway | Requests to non-spec endpoints |
| Deprecated endpoint usage | App logs | Traffic to deprecated routes |
| Schema validation failures | API gateway | Requests failing input validation |

```yaml
title: OpenAPI Specification Access Detected
id: f2a3b4c5-d6e7-8901-f012-234567890123
status: experimental
description: Detects access to OpenAPI/Swagger specification files from external sources
logsource:
  category: webserver
detection:
  selection:
    cs-uri-stem:
      - '/swagger.json'
      - '/openapi.json'
      - '/api-docs'
      - '/swagger/v1/swagger.json'
      - '/.well-known/openapi.yaml'
  external:
    c-ip|cidr:
      - '!10.0.0.0/8'
      - '!172.16.0.0/12'
      - '!192.168.0.0/16'
  condition: selection and external
falsepositives:
  - API consumers accessing documentation for integration
level: low
tags:
  - attack.t1592
  - attack.reconnaissance
```

## Verification

- [ ] OpenAPI spec discovered and analyzed
- [ ] Security schemes audited for completeness
- [ ] Endpoints without authentication identified
- [ ] Sensitive data in query parameters flagged
- [ ] Schema validation strictness assessed
- [ ] Deprecated but active endpoints identified

## References

- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [Spectral API Linter](https://github.com/stoplightio/spectral)
- [Schemathesis](https://github.com/schemathesis/schemathesis)
