🛡️ Complete OWASP Modules Guide - APILeak¶

This guide covers all OWASP modules implemented in APILeak, from basic concepts to advanced usage examples.

📋 Table of Contents¶

Introduction to OWASP Modules
Available Modules
Basic Usage
Advanced Configuration
Practical Examples
Results Interpretation
Troubleshooting

🎯 Introduction¶

APILeak implements specialized modules for each category of the OWASP API Security Top 10 2023. Each module is designed to detect specific vulnerabilities through advanced automated testing techniques.

Why use OWASP modules?¶

Complete Coverage: Each module covers a specific OWASP Top 10 category
Specialized Testing: Specific techniques for each type of vulnerability
Automation: Automatic detection without manual intervention
Detailed Reports: Clear evidence and remediation recommendations

🧩 Available Modules¶

Module	OWASP Category	Description	Priority
`bola`	API1 - Broken Object Level Authorization	Broken Object Level Authorization (BOLA) detection	P0
`auth`	API2 - Broken Authentication	Broken Authentication detection	P0
`property`	API3 - Broken Object Property Level Authorization	Broken Object Property Level Authorization detection	P0
`resource`	API4 - Unrestricted Resource Consumption	Unrestricted Resource Consumption detection	P1
`function_auth`	API5 - Broken Function Level Authorization	Broken Function Level Authorization detection	P0
`business_flow`	API6 - Unrestricted Access to Sensitive Business Flows	Unrestricted Access to Sensitive Business Flows detection	P1
`ssrf`	API7 - Server-Side Request Forgery	Server-Side Request Forgery (SSRF) detection	P1
`security_misconfig`	API8 - Security Misconfiguration	Security Misconfiguration detection	P1
`inventory`	API9 - Improper Inventory Management	Improper Inventory Management detection	P2
`unsafe_consumption`	API10 - Unsafe Consumption of APIs	Unsafe Consumption of APIs detection	P2
`parameter_pollution`	API8* - HTTP Parameter Pollution	Duplicate-parameter handling across discovered endpoints + Burp/Caido capture replay	—
`spec_driven_testing`	API8* - Spec-Driven Testing	OpenAPI/Swagger contract-enforcement audit (enum/type/required)	—

* Not a strict Top 10 mapping — these two extend coverage beyond the Top 10 and are filed under API8 as the closest fit. See Parameter Pollution and Spec-Driven Testing.

Every module can run in isolation with apileaks owasp <key> --target URL, or as part of an orchestrated scan (all modules by default, or a subset via --modules). All twelve modules own module-specific CLI options — see the OWASP Command Reference for the full option tables.

Implementation Status¶

✅ Fully Implemented & Registered: all ten Top 10 modules (bola, auth, property, resource, function_auth, business_flow, ssrf, security_misconfig, inventory, unsafe_consumption) plus two additional modules (parameter_pollution, spec_driven_testing)

🚀 Basic Usage¶

Basic Command¶

# Run discovery + ALL registered OWASP modules (default)
python apileaks.py scan --target https://api.example.com

# Restrict to specific modules
python apileaks.py scan --target https://api.example.com --modules bola,auth,resource

# Run a single module in isolation (recommended for focused red-team runs)
python apileaks.py owasp bola --target https://api.example.com

Note: scan is the primary orchestrator and runs discovery plus every registered OWASP module by default; --modules a,b restricts the set. full and main are deprecated, hidden aliases of scan (they still work but emit a stderr notice). To run one module in isolation, prefer apileaks owasp <key> --target URL — for example full --modules bola becomes apileaks owasp bola.

Default Modules¶

By default, scan runs discovery plus all registered OWASP modules. To restrict the run, pass --modules:

--modules bola,auth,property,resource,function_auth

Module Syntax¶

--modules <module1>,<module2>,<module3>

Available modules: - bola - Broken Object Level Authorization (BOLA) detection (API1) - auth - Broken Authentication detection (API2) - property - Broken Object Property Level Authorization detection (API3) - resource - Unrestricted Resource Consumption detection (API4) - function_auth - Broken Function Level Authorization detection (API5) - business_flow - Unrestricted Access to Sensitive Business Flows detection (API6) - ssrf - Server-Side Request Forgery (SSRF) detection (API7) - security_misconfig - Security Misconfiguration detection (API8) - inventory - Improper Inventory Management detection (API9) - unsafe_consumption - Unsafe Consumption of APIs detection (API10) - parameter_pollution - HTTP Parameter Pollution detection (discovered endpoints + capture replay) - spec_driven_testing - OpenAPI/Swagger contract-enforcement audit

⚙️ Advanced Configuration¶

YAML Configuration File¶

# config/owasp_config.yaml
target:
  base_url: "https://api.example.com"
  timeout: 30

owasp_testing:
  enabled_modules: ["bola", "auth", "property", "resource", "function_auth"]

  # Module-specific configuration
  bola_testing:
    enabled: true
    id_patterns: ["sequential", "guid", "uuid"]
    test_contexts: ["anonymous", "user", "admin"]

  auth_testing:
    enabled: true
    jwt_testing: true
    weak_secrets_wordlist: "wordlists/jwt_secrets.txt"
    test_logout_invalidation: true

  property_testing:
    enabled: true
    sensitive_fields: ["password", "api_key", "secret", "ssn"]
    mass_assignment_fields: ["is_admin", "role", "permissions"]

  resource_testing:
    enabled: true
    burst_size: 100
    large_payload_sizes: [1048576, 10485760]  # 1MB, 10MB
    json_depth_limit: 1000

  function_auth_testing:
    enabled: true
    admin_endpoints: ["/admin", "/api/admin", "/management"]
    dangerous_methods: ["DELETE", "PUT", "PATCH"]

# Authentication for testing
authentication:
  contexts:
    - name: "anonymous"
      type: "bearer"
      token: ""
      privilege_level: 0
    - name: "user"
      type: "bearer"
      token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
      privilege_level: 1
    - name: "admin"
      type: "bearer"
      token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
      privilege_level: 3

rate_limiting:
  requests_per_second: 10
  adaptive: true
  respect_retry_after: true

Environment Variables¶

# Basic configuration
export APILEAK_TARGET="https://api.example.com"
export APILEAK_MODULES="bola,auth,resource"
export APILEAK_RATE_LIMIT="5"
export APILEAK_JWT_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

# Run with environment variables
python apileaks.py scan

📚 Practical Examples¶

1. 🔐 BOLA Testing (API1)¶

Detects unauthorized access to other users' objects, sequential ID enumeration, and horizontal privilege escalation.

# Basic read-only BOLA test
python apileaks.py owasp bola --target https://api.example.com

For the full command reference — including multi-user contexts (--auth-context), Safe Mode, and the advanced probes (--allow-write-bola, --bola-composite, --bola-id-leakage, --bola-verb-tampering, --bola-parameter-pollution, --bola-dry-run) — see BOLA Testing (API1).

2. 🔑 Authentication Testing (API2)¶

What does it detect? - Weak JWT algorithms (none, algorithm confusion) - Tokens that don't expire properly - Weak JWT secrets - Endpoints accessible without authentication

# Complete authentication test
python apileaks.py owasp auth --target https://api.example.com

# Test with specific JWT token
python apileaks.py owasp auth --target https://api.example.com \
  --jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U

# Test with custom JWT secrets wordlist
python apileaks.py scan --config config/auth_config.yaml --target https://api.example.com

Example configuration for auth testing:

owasp_testing:
  auth_testing:
    enabled: true
    jwt_testing: true
    weak_secrets_wordlist: "wordlists/custom_jwt_secrets.txt"
    test_logout_invalidation: true

3. 📊 Property Level Authorization (API3)¶

What does it detect? - Exposure of sensitive fields (passwords, API keys) - Mass assignment vulnerabilities - Undocumented fields in responses - Modifiable read-only properties

# Property level authorization test
python apileaks.py owasp property --target https://api.example.com

# With custom sensitive fields
python apileaks.py scan --config config/property_config.yaml --target https://api.example.com

Custom configuration:

owasp_testing:
  property_testing:
    enabled: true
    sensitive_fields: 
      - "password"
      - "api_key" 
      - "secret"
      - "ssn"
      - "credit_card"
      - "bank_account"
    mass_assignment_fields:
      - "is_admin"
      - "role"
      - "permissions"
      - "user_id"
      - "account_type"

4. ⚡ Resource Consumption (API4)¶

What does it detect? - Missing rate limiting - Large payload acceptance - Deeply nested JSON - ReDoS vulnerabilities - Complex query processing

# Basic resource consumption test
python apileaks.py owasp resource --target https://api.example.com

# Test with custom burst
python apileaks.py owasp resource --target https://api.example.com \
  --rate-limit 20

# Test with advanced configuration
python apileaks.py scan --config config/resource_config.yaml --target https://api.example.com

Advanced configuration:

owasp_testing:
  resource_testing:
    enabled: true
    burst_size: 150                    # Requests for rate limiting test
    large_payload_sizes: [1048576, 10485760, 104857600]  # 1MB, 10MB, 100MB
    json_depth_limit: 1500             # JSON depth

5. 🛡️ Function Level Authorization (API5)¶

What does it detect? - Unauthorized access to administrative functions - HTTP method bypass - Parameter and header bypass - Vertical privilege escalation

# Function level authorization test
python apileaks.py owasp function_auth --target https://api.example.com

# With custom administrative endpoints
python apileaks.py scan --config config/function_auth_config.yaml --target https://api.example.com

Custom configuration:

owasp_testing:
  function_auth_testing:
    enabled: true
    admin_endpoints: 
      - "/admin"
      - "/api/admin" 
      - "/management"
      - "/dashboard"
      - "/api/v1/admin"
    dangerous_methods: ["DELETE", "PUT", "PATCH", "POST"]

🎯 Real-World Use Case Examples¶

Case 1: E-commerce API¶

# Complete testing for e-commerce API
python apileaks.py scan --target https://api.shop.example.com \
  --modules bola,auth,property,resource \
  --jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... \
  --rate-limit 5 \
  --output ecommerce_security_test

Case 2: Banking API (High Security)¶

# Testing with very low rate limiting for critical APIs
python apileaks.py scan --target https://api.bank.example.com \
  --modules bola,auth,property,function_auth \
  --rate-limit 1 \
  --jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... \
  --log-level INFO \
  --output banking_security_audit

# Testing focused on BOLA and property level auth
python apileaks.py scan --target https://api.social.example.com \
  --modules bola,property,resource \
  --jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... \
  --rate-limit 10 \
  --output social_media_test

Case 4: CI/CD Testing¶

#!/bin/bash
# ci_security_test.sh

export APILEAK_TARGET="https://staging-api.example.com"
export APILEAK_MODULES="bola,auth,property"
export APILEAK_JWT_TOKEN="${CI_JWT_TOKEN}"
export APILEAK_RATE_LIMIT="3"

python apileaks.py scan \
  --jwt "${APILEAK_JWT_TOKEN}" \
  --ci-mode \
  --fail-on high \
  --no-banner

# scan exits with:
#   0 = no findings at or above --fail-on threshold
#   1 = high severity findings found
#   2 = critical findings found
EXIT=$?
if [ $EXIT -eq 2 ]; then
    echo "❌ Critical vulnerabilities found! Failing CI/CD pipeline."
    exit 1
elif [ $EXIT -eq 1 ]; then
    echo "⚠️ High severity vulnerabilities found. Review required."
    exit 1
else
    echo "✅ No findings above threshold."
    exit 0
fi

📊 Results Interpretation¶

Severity Levels¶

Severity	Description	Required Action
CRITICAL	Vulnerabilities allowing immediate unauthorized access	Immediate fix
HIGH	Significant vulnerabilities requiring urgent attention	Fix within 24-48h
MEDIUM	Moderate vulnerabilities that should be fixed	Fix within 1-2 weeks
LOW	Minor security issues	Fix in next cycle
INFO	Information about configuration or discovered endpoints	Optional review

Finding Categories by Module¶

BOLA Module (API1)¶

BOLA_ANONYMOUS_ACCESS (CRITICAL)
BOLA_HORIZONTAL_ESCALATION (CRITICAL)
BOLA_ID_ENUMERATION (HIGH)
BOLA_OBJECT_ACCESS (HIGH)

Auth Module (API2)¶

AUTH_BYPASS (CRITICAL)
WEAK_JWT_ALGORITHM (HIGH)
TOKEN_NOT_EXPIRED (HIGH)
WEAK_JWT_SECRET (HIGH)

Property Module (API3)¶

SENSITIVE_DATA_EXPOSURE (CRITICAL)
MASS_ASSIGNMENT (HIGH)
READONLY_PROPERTY_MODIFICATION (HIGH)
UNDOCUMENTED_FIELD (MEDIUM)

Resource Module (API4)¶

MISSING_RATE_LIMITING (MEDIUM)
LARGE_PAYLOAD_ACCEPTED (MEDIUM)

Function Auth Module (API5)¶

BFLA_ANONYMOUS_ADMIN_ACCESS (CRITICAL)
BFLA_LOW_PRIV_ACCESS (CRITICAL)
BFLA_ADMIN_ENDPOINT_EXPOSED (MEDIUM)
BFLA_VERB_TAMPERING (HIGH)
BFLA_METHOD_OVERRIDE (HIGH)
BFLA_MASS_ASSIGNMENT_ROLE (CRITICAL)
BFLA_VERSION_DOWNGRADE (HIGH)

Example Report¶

{
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "target": "https://api.example.com",
  "timestamp": "2024-01-08T10:30:00Z",
  "summary": {
    "total_findings": 15,
    "critical": 3,
    "high": 5,
    "medium": 4,
    "low": 2,
    "info": 1
  },
  "owasp_coverage": {
    "tested_categories": 5,
    "total_categories": 10,
    "coverage_percentage": 50.0
  },
  "findings": [
    {
      "id": "finding-001",
      "category": "BOLA_ANONYMOUS_ACCESS",
      "owasp_category": "API1",
      "severity": "CRITICAL",
      "endpoint": "https://api.example.com/users/123",
      "method": "GET",
      "evidence": "Object 123 accessible without authentication. Status: 200, Size: 245 bytes",
      "recommendation": "Implement proper authentication checks for object access."
    }
  ]
}

🔧 Troubleshooting¶

Common Issues¶

1. Server Rate Limiting¶

Error: Too many requests (429)

Solution:

# Reduce rate limit
python apileaks.py scan --target https://api.example.com --rate-limit 1

# Use adaptive mode (default)
python apileaks.py owasp bola --target https://api.example.com

2. Connection Timeouts¶

Error: Connection timeout

Solution:

target:
  timeout: 60  # Increase timeout to 60 seconds

3. Invalid JWT Token¶

Warning: JWT token validation failed

Solution:

# Verify JWT token
python apileaks.py jwt decode eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

# Generate new token
python apileaks.py jwt encode '{"sub":"user123","role":"user"}' --secret mysecret

4. Wordlists Not Found¶

Error: Wordlist file not found

Solution:

# Verify wordlists exist
ls -la wordlists/

# Use custom wordlists
python apileaks.py scan --config config/custom_wordlists.yaml --target https://api.example.com

Debug Logs¶

# Enable detailed logging
python apileaks.py owasp bola --target https://api.example.com \
  --log-level DEBUG \
  --log-file debug.log

Network Configuration¶

# For APIs behind proxies or with custom SSL
target:
  verify_ssl: false  # Only for testing, not in production
  timeout: 30

rate_limiting:
  adaptive: true
  respect_retry_after: true

📈 Best Practices¶

1. Module Selection¶

Public APIs: Use all modules (bola,auth,property,resource,function_auth)
Internal APIs: Focus on bola,property,function_auth
High Traffic APIs: Use resource,auth with low rate limiting

2. Rate Limiting¶

Production APIs: --rate-limit 1-5
Staging APIs: --rate-limit 5-10
Development APIs: --rate-limit 10-20

3. Authentication¶

Use multiple authentication contexts when possible
Include tokens with different privilege levels
Test with both valid and invalid tokens

4. CI/CD Integration¶

# Script for CI/CD
python apileaks.py scan \
  --target "${API_ENDPOINT}" \
  --jwt "${JWT_TOKEN}" \
  --modules bola,auth,property \
  --rate-limit 3 \
  --output "security-scan-${BUILD_NUMBER}" \
  --ci-mode \
  --fail-on high \
  --no-banner

# Exit codes:
# 0 = no findings at or above --fail-on threshold
# 1 = high severity findings found (default gate)
# 2 = critical findings found

5. Reporting¶

Use descriptive names for outputs
Generate multiple formats (JSON for automation, HTML for humans)
Archive reports with timestamps

🚀 All Modules Available¶

All ten OWASP API Security Top 10 2023 modules are fully implemented and registered, plus two additional modules (parameter_pollution, spec_driven_testing). See the OWASP Coverage for a detailed breakdown of what each module detects.

Future Features¶

Machine Learning: Intelligent pattern detection
Custom Rules: Industry-specific custom rules
Integration APIs: APIs for SIEM/SOAR integration
Real-time Monitoring: Continuous API monitoring

📞 Support¶

Additional Documentation¶

Quick Reference - Basic commands and examples
Scan Guide - Complete scan command reference
OWASP Command Reference - Complete owasp <module> reference
CI/CD Integration - Configuration for automated pipelines
Troubleshooting Guide - Common problem solutions
Example Configurations - Ready-to-use examples

Available Example Configurations¶

BOLA Testing - API1: Broken Object Level Authorization
Auth Testing - API2: Broken Authentication
Property Testing - API3: Broken Object Property Level Authorization
Resource Testing - API4: Unrestricted Resource Consumption
Function Auth Testing - API5: Broken Function Level Authorization

Report Issues¶

Troubleshooting: First check the Troubleshooting Guide
GitHub Issues: APILeak Issues
Documentation: APILeak Docs

This documentation covers APILeak version 0.3.0. For updates, check the project releases.

🛡️ Complete OWASP Modules Guide - APILeak¶

📋 Table of Contents¶

🎯 Introduction¶

Why use OWASP modules?¶

🧩 Available Modules¶

Implementation Status¶

🚀 Basic Usage¶

Basic Command¶

Default Modules¶

Module Syntax¶

⚙️ Advanced Configuration¶

YAML Configuration File¶

Environment Variables¶

📚 Practical Examples¶

1. 🔐 BOLA Testing (API1)¶

2. 🔑 Authentication Testing (API2)¶

3. 📊 Property Level Authorization (API3)¶

4. ⚡ Resource Consumption (API4)¶

5. 🛡️ Function Level Authorization (API5)¶

🎯 Real-World Use Case Examples¶

Case 1: E-commerce API¶

Case 2: Banking API (High Security)¶

Case 3: Social Media API¶

Case 4: CI/CD Testing¶

📊 Results Interpretation¶

Severity Levels¶

Finding Categories by Module¶

BOLA Module (API1)¶

Auth Module (API2)¶

Property Module (API3)¶

Resource Module (API4)¶

Function Auth Module (API5)¶

Example Report¶

🔧 Troubleshooting¶

Common Issues¶

1. Server Rate Limiting¶

2. Connection Timeouts¶

3. Invalid JWT Token¶

4. Wordlists Not Found¶

Debug Logs¶

Network Configuration¶

📈 Best Practices¶

1. Module Selection¶

2. Rate Limiting¶

3. Authentication¶

4. CI/CD Integration¶

5. Reporting¶

🚀 All Modules Available¶

Future Features¶

📞 Support¶

Additional Documentation¶

Available Example Configurations¶

Report Issues¶