OpenAPI/Swagger security analysis

What is OpenAPI/Swagger Security Analysis?

OpenAPI/Swagger security analysis focuses on vulnerabilities arising from exposed API documentation that reveals the complete API structure, endpoints, parameters, authentication methods, and internal architecture. While OpenAPI specifications are intended for development and integration, when exposed in production they provide attackers with a comprehensive roadmap for targeting APIs, including hidden endpoints, sensitive parameters, and security implementation details.

Vulnerable Scenario Example

Exposed Swagger documentation:

# Access: https://api.target.com/swagger.json
{
  "swagger": "2.0",
  "info": {
    "title": "Internal API",
    "version": "1.0.0"
  },
  "host": "internal-api.company.com",
  "basePath": "/api/v1",
  "paths": {
    "/admin/users": {
      "get": {
        "tags": ["admin"],
        "summary": "Get all users (admin only)",
        "parameters": [
          {
            "name": "debug",
            "in": "query",
            "description": "Enable debug mode",
            "type": "boolean"
          }
        ]
      }
    },
    "/internal/logs": {
      "get": {
        "tags": ["internal"],
        "summary": "Access system logs",
        "security": []
      }
    }
  }
}

Attack Result: The documentation reveals admin endpoints, internal services, debug parameters, and endpoints without authentication requirements, providing a complete attack map.

OpenAPI/Swagger Discovery Techniques

Common Documentation Endpoints

Standard Discovery Paths:

# Common OpenAPI/Swagger endpoints
curl https://api.target.com/swagger.json
curl https://api.target.com/swagger.yaml
curl https://api.target.com/openapi.json
curl https://api.target.com/openapi.yaml
curl https://api.target.com/api-docs
curl https://api.target.com/docs
curl https://api.target.com/api/docs
curl https://api.target.com/v1/swagger.json
curl https://api.target.com/v2/openapi.yaml

Interactive Documentation:

# Swagger UI endpoints
curl https://api.target.com/swagger-ui
curl https://api.target.com/swagger-ui.html
curl https://api.target.com/docs/swagger
curl https://api.target.com/api/swagger-ui
curl https://api.target.com/redoc
curl https://api.target.com/rapidoc

Alternative Locations:

# Less common but often exposed locations
curl https://api.target.com/.well-known/openapi.json
curl https://api.target.com/static/swagger.json
curl https://api.target.com/assets/api-docs.json
curl https://api.target.com/spec.json
curl https://api.target.com/schema.json

Automated Discovery Tools

Using ffuf for Discovery:

# Discover API documentation endpoints
ffuf -u https://api.target.com/FUZZ \
     -w swagger_wordlist.txt \
     -mc 200 \
     -fs 0

# Wordlist examples:
# swagger.json, openapi.json, api-docs
# docs, documentation, spec
# v1/swagger.json, v2/openapi.yaml
# swagger-ui, redoc, rapidoc

Burp Suite Discovery:

1. Configure Burp proxy
2. Browse target application
3. Use Content Discovery to find documentation:
   - swagger
   - openapi  
   - docs
   - api-docs
4. Check for exposed JSON/YAML files
5. Look for interactive documentation interfaces

OpenAPI Specification Analysis

Critical Information Extraction

Server and Host Information:

# Extract internal infrastructure details
servers:
  - url: https://internal-api.company.com/v1
    description: Internal API server
  - url: https://staging-api.company.com/v1  
    description: Staging environment
  - url: https://dev-api.company.com/v1
    description: Development server

host: internal.company.com
basePath: /api/v1

Security Scheme Analysis:

# Identify authentication mechanisms
securityDefinitions:
  apiKey:
    type: apiKey
    in: header
    name: X-API-Key
  basicAuth:
    type: basic
  oauth2:
    type: oauth2
    flow: implicit
    authorizationUrl: https://auth.company.com/oauth
    scopes:
      read: Read access
      write: Write access
      admin: Admin access

Sensitive Endpoint Discovery:

# Extract all endpoints from OpenAPI spec
curl -s https://api.target.com/swagger.json | jq -r '.paths | keys[]'

# Look for sensitive patterns
curl -s https://api.target.com/swagger.json | jq -r '.paths | keys[]' | grep -E '(admin|internal|debug|test|dev)'

# Extract endpoints without authentication
curl -s https://api.target.com/swagger.json | jq -r '
  .paths | to_entries[] | 
  select(.value | to_entries[] | .value.security == null or .value.security == []) | 
  .key'

Parameter and Schema Analysis

Sensitive Parameter Discovery:

# Extract all parameters
curl -s https://api.target.com/swagger.json | jq -r '
  .paths[][].parameters[]? | 
  select(.name | test("(admin|debug|internal|test|key|token|secret)"; "i")) | 
  .name'

# Hidden/undocumented parameters
curl -s https://api.target.com/swagger.json | jq -r '
  .paths[][].parameters[]? | 
  select(.description | test("(internal|hidden|deprecated)"; "i")) | 
  {name: .name, description: .description}'

Response Schema Analysis:

# Identify sensitive data in responses
curl -s https://api.target.com/swagger.json | jq -r '
  .definitions | to_entries[] | 
  select(.value.properties | has("password") or has("secret") or has("token")) | 
  .key'

# Extract example values that might contain real data
curl -s https://api.target.com/swagger.json | jq -r '
  .paths[][].responses[].examples | 
  select(. != null)'

Exploitation Techniques

Undocumented Endpoint Testing

Using Discovered Endpoints:

#!/bin/bash
# Extract and test all endpoints from Swagger

swagger_url="https://api.target.com/swagger.json"
base_url="https://api.target.com"

# Get all endpoints
endpoints=$(curl -s "$swagger_url" | jq -r '.paths | keys[]')

for endpoint in $endpoints; do
    echo "Testing: $endpoint"
    
    # Test without authentication
    curl -s -w "Status: %{http_code}\n" "$base_url$endpoint"
    
    # Test with different HTTP methods
    methods=$(curl -s "$swagger_url" | jq -r ".paths[\"$endpoint\"] | keys[]")
    
    for method in $methods; do
        echo "  $method $endpoint"
        curl -s -X "$method" -w "Status: %{http_code}\n" "$base_url$endpoint"
    done
    
    echo "---"
done

Admin Endpoint Exploitation:

# Endpoints discovered from Swagger
GET /api/v1/admin/users HTTP/1.1
Host: api.target.com

GET /api/v1/admin/debug?debug=true HTTP/1.1
Host: api.target.com

POST /api/v1/admin/execute HTTP/1.1
Host: api.target.com
Content-Type: application/json

{"command": "system_info"}

Parameter Injection and Manipulation

Using Swagger Parameter Definitions:

# Parameter discovered in Swagger: debug (boolean)
GET /api/v1/users?debug=true HTTP/1.1

# Try injection in documented parameters
GET /api/v1/search?query='; DROP TABLE users; -- HTTP/1.1

# Parameter pollution with documented params
GET /api/v1/transfer?amount=10&amount=1000 HTTP/1.1

Hidden Parameter Testing:

# Test parameters mentioned in Swagger but not documented as required
curl "https://api.target.com/api/v1/users?internal=true"
curl "https://api.target.com/api/v1/users?admin_mode=1"
curl "https://api.target.com/api/v1/users?debug_level=5"

Authentication Bypass Using Schema Info

Testing Documented Security Requirements:

# If Swagger shows endpoint without security requirement
"/public/data": {
  "get": {
    "security": []  # No authentication required
  }
}

# But endpoint might contain sensitive data
"/internal/config": {
  "get": {
    "security": []  # Misconfigured - should require auth
  }
}

Security Definition Exploitation:

# If Swagger documents weak authentication
# Example: API key in query parameter
GET /api/v1/users?api_key=weak_key HTTP/1.1

# Try common/default API keys from documentation
GET /api/v1/admin?api_key=admin HTTP/1.1
GET /api/v1/admin?api_key=test HTTP/1.1
GET /api/v1/admin?api_key=12345 HTTP/1.1

Automated Analysis Tools

Swagger/OpenAPI Security Scanners

Using swagger-codegen for Testing:

# Generate client code to understand API structure
swagger-codegen generate -i https://api.target.com/swagger.json -l python -o api_client

# Analyze generated code for:
# - All available endpoints
# - Required/optional parameters  
# - Authentication methods
# - Data models and schemas

Custom Python Analysis Script:

import requests
import json
from urllib.parse import urljoin

class SwaggerSecurityAnalyzer:
    def __init__(self, swagger_url):
        self.swagger_url = swagger_url
        self.spec = None
        self.security_issues = []
        
    def load_specification(self):
        try:
            response = requests.get(self.swagger_url)
            self.spec = response.json()
            print(f"Loaded OpenAPI spec: {self.spec.get('info', {}).get('title', 'Unknown')}")
        except Exception as e:
            print(f"Error loading spec: {e}")
            return False
        return True
    
    def analyze_security_schemes(self):
        schemes = self.spec.get('securityDefinitions', {})
        if not schemes:
            schemes = self.spec.get('components', {}).get('securitySchemes', {})
        
        for name, scheme in schemes.items():
            if scheme.get('type') == 'apiKey':
                if scheme.get('in') == 'query':
                    self.security_issues.append({
                        'type': 'Weak Authentication',
                        'details': f'API key "{name}" in query parameter (logged in URLs)'
                    })
                    
            if scheme.get('type') == 'basic':
                self.security_issues.append({
                    'type': 'Basic Authentication',
                    'details': f'Basic auth scheme "{name}" (credentials in base64)'
                })
    
    def find_unsecured_endpoints(self):
        paths = self.spec.get('paths', {})
        
        for path, methods in paths.items():
            for method, details in methods.items():
                if method.upper() in ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']:
                    security = details.get('security', [])
                    
                    # Check if security is empty or undefined
                    if not security:
                        self.security_issues.append({
                            'type': 'Unsecured Endpoint',
                            'details': f'{method.upper()} {path} has no authentication requirements'
                        })
    
    def find_sensitive_endpoints(self):
        paths = self.spec.get('paths', {})
        sensitive_patterns = ['admin', 'internal', 'debug', 'test', 'dev', 'private']
        
        for path in paths.keys():
            for pattern in sensitive_patterns:
                if pattern in path.lower():
                    self.security_issues.append({
                        'type': 'Sensitive Endpoint Exposed',
                        'details': f'Endpoint {path} contains sensitive pattern "{pattern}"'
                    })
    
    def analyze_parameters(self):
        paths = self.spec.get('paths', {})
        sensitive_params = ['debug', 'admin', 'internal', 'key', 'token', 'secret']
        
        for path, methods in paths.items():
            for method, details in methods.items():
                parameters = details.get('parameters', [])
                
                for param in parameters:
                    param_name = param.get('name', '').lower()
                    for sensitive in sensitive_params:
                        if sensitive in param_name:
                            self.security_issues.append({
                                'type': 'Sensitive Parameter',
                                'details': f'{method.upper()} {path} has parameter "{param["name"]}"'
                            })
    
    def check_information_disclosure(self):
        # Check for internal server information
        if 'host' in self.spec:
            host = self.spec['host']
            if any(keyword in host.lower() for keyword in ['internal', 'dev', 'test', 'staging']):
                self.security_issues.append({
                    'type': 'Information Disclosure',
                    'details': f'Internal hostname exposed: {host}'
                })
        
        # Check servers array (OpenAPI 3.0)
        servers = self.spec.get('servers', [])
        for server in servers:
            url = server.get('url', '')
            if any(keyword in url.lower() for keyword in ['internal', 'dev', 'test', 'staging']):
                self.security_issues.append({
                    'type': 'Information Disclosure',
                    'details': f'Internal server URL exposed: {url}'
                })
    
    def generate_report(self):
        print(f"\n=== OpenAPI/Swagger Security Analysis Report ===")
        print(f"Specification URL: {self.swagger_url}")
        print(f"Total security issues found: {len(self.security_issues)}")
        
        issue_types = {}
        for issue in self.security_issues:
            issue_type = issue['type']
            if issue_type not in issue_types:
                issue_types[issue_type] = []
            issue_types[issue_type].append(issue['details'])
        
        for issue_type, details in issue_types.items():
            print(f"\n[!] {issue_type}:")
            for detail in details:
                print(f"    - {detail}")
    
    def run_analysis(self):
        if not self.load_specification():
            return
        
        self.analyze_security_schemes()
        self.find_unsecured_endpoints()
        self.find_sensitive_endpoints()
        self.analyze_parameters()
        self.check_information_disclosure()
        self.generate_report()

# Usage
analyzer = SwaggerSecurityAnalyzer('https://api.target.com/swagger.json')
analyzer.run_analysis()

Burp Suite Integration

Swagger Parser Extension:

1. Install Swagger Parser extension in Burp Suite
2. Load OpenAPI specification URL
3. Extension automatically:
   - Parses all endpoints
   - Generates test requests
   - Identifies parameters
   - Maps authentication requirements
4. Use generated requests in Scanner and Intruder

Manual Burp Testing:

1. Load Swagger JSON in browser
2. Copy specification to analysis tool
3. Extract all endpoints and parameters
4. Create Burp requests for each endpoint:
   - Test without authentication
   - Test with invalid authentication
   - Test parameter injection
   - Test method override
5. Use Intruder for systematic parameter fuzzing

Information Disclosure Analysis

Sensitive Data Extraction

Internal Infrastructure Discovery:

# Extract server information
curl -s https://api.target.com/swagger.json | jq -r '.host, .basePath'
curl -s https://api.target.com/swagger.json | jq -r '.servers[]?.url'

# Find internal domains and IPs
curl -s https://api.target.com/swagger.json | jq -r '
  .paths[][].servers[]?.url // empty,
  .host // empty' | 
  grep -E "(internal|dev|test|staging|10\.|192\.168\.|172\.)"

API Version and Technology Stack:

# Extract version information
curl -s https://api.target.com/swagger.json | jq -r '.info.version'

# Look for technology indicators in descriptions
curl -s https://api.target.com/swagger.json | jq -r '
  .info.description,
  .paths[][].description // empty' | 
  grep -i -E "(node|python|java|.net|php|ruby|spring|django|express)"

Contact and Documentation URLs:

# Extract contact information and external URLs
curl -s https://api.target.com/swagger.json | jq -r '
  .info.contact.email // empty,
  .info.contact.url // empty,
  .externalDocs.url // empty'

Business Logic Discovery

Endpoint Relationship Mapping:

# Identify CRUD operations and data flow
curl -s https://api.target.com/swagger.json | jq -r '
  .paths | to_entries[] |
  {path: .key, methods: (.value | keys)}'

# Find potential privilege escalation paths
curl -s https://api.target.com/swagger.json | jq -r '
  .paths | to_entries[] |
  select(.key | contains("admin") or contains("role") or contains("permission")) |
  {path: .key, methods: (.value | keys)}'

Testing Methodology

Systematic OpenAPI Testing

Postman Collection Generation:

1. Import OpenAPI specification into Postman

2. Postman automatically generates:

   • Collection with all endpoints

   • Environment variables for base URL

   • Example requests with parameters

3. Customize collection for security testing:

   • Remove authentication headers

   • Add malicious payloads to parameters

   • Test different HTTP methods

4. Use Collection Runner for automated testing

Security Testing Checklist

Discovery Phase:

• Find OpenAPI/Swagger documentation

• Download and analyze specification

• Extract all endpoints and parameters

• Identify authentication requirements

Analysis Phase:

• Check for unsecured endpoints

• Analyze security scheme implementations

• Find sensitive parameters and data

• Look for internal infrastructure exposure

Testing Phase:

• Test all discovered endpoints

• Attempt authentication bypass

• Test parameter injection

• Check for admin/debug functionality

• Verify actual vs. documented security

OpenAPI-Specific Attack Patterns

Documentation vs. Reality Testing:

# Test if documented authentication is actually enforced
# Swagger says auth required, but test without auth
swagger_endpoints=$(curl -s https://api.target.com/swagger.json | jq -r '.paths | keys[]')

for endpoint in $swagger_endpoints; do
    echo "Testing $endpoint without authentication:"
    curl -s -w "%{http_code}" "https://api.target.com$endpoint"
    echo
done

Parameter Discovery and Testing:

# Extract and test all documented parameters
import requests
import json

def test_swagger_parameters(swagger_url, base_url):
    spec = requests.get(swagger_url).json()
    
    for path, methods in spec.get('paths', {}).items():
        for method, details in methods.items():
            if method.upper() in ['GET', 'POST', 'PUT', 'DELETE']:
                parameters = details.get('parameters', [])
                
                print(f"Testing {method.upper()} {path}")
                
                # Test each parameter
                for param in parameters:
                    param_name = param['name']
                    param_location = param.get('in', 'query')
                    
                    # Test with injection payloads
                    test_payloads = [
                        "'; DROP TABLE users; --",
                        "<script>alert('xss')</script>",
                        "../../../etc/passwd",
                        "true",
                        "admin"
                    ]
                    
                    for payload in test_payloads:
                        if param_location == 'query':
                            test_url = f"{base_url}{path}?{param_name}={payload}"
                            response = requests.get(test_url)
                            print(f"  {param_name}={payload}: {response.status_code}")

test_swagger_parameters('https://api.target.com/swagger.json', 'https://api.target.com')

Business Impact Assessment

Critical Findings Prioritization

High-Risk Exposures:

# Priority 1: Admin endpoints without authentication
curl -s https://api.target.com/swagger.json | jq -r '
  .paths | to_entries[] |
  select(.key | contains("admin")) |
  select(.value | to_entries[] | .value.security == null or .value.security == []) |
  "HIGH: " + .key + " (admin endpoint, no auth required)"'

# Priority 2: Internal/debug endpoints
curl -s https://api.target.com/swagger.json | jq -r '
  .paths | to_entries[] |
  select(.key | test("(internal|debug|test)"; "i")) |
  "MEDIUM: " + .key + " (internal endpoint exposed)"'

# Priority 3: Sensitive data in examples
curl -s https://api.target.com/swagger.json | jq -r '
  .paths[][].responses[].examples | 
  select(. != null) |
  "LOW: Example data found in responses"'