APILeak User Guide¶

Complete guide for using APILeak to perform comprehensive API security testing with OWASP API Security Top 10 2023 coverage.

Table of Contents¶

Getting Started
Basic Usage
Advanced Features
OWASP Module Testing
Configuration Management
WAF Evasion Techniques
CI/CD Integration
Troubleshooting
Best Practices

Getting Started¶

Prerequisites¶

Python 3.11 or higher
Network access to target API
Valid authentication tokens (if testing authenticated endpoints)

Installation¶

# Clone the repository
git clone https://github.com/your-org/apileak.git
cd apileak

# Set up development environment
make setup-dev

# Activate virtual environment
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Verify installation
python apileaks.py --help

Quick Start¶

# Basic endpoint discovery
python apileaks.py dir --target https://api.example.com

# Parameter fuzzing
python apileaks.py par --target https://api.example.com

# Full security scan with OWASP modules
python apileaks.py scan --target https://api.example.com --modules bola,auth,property

Basic Usage¶

Command Structure¶

APILeak's main commands:

Directory Fuzzing (dir) - Discover hidden endpoints
Parameter Fuzzing (par) - Find hidden parameters
Security Scan (scan) - Primary orchestrator: runs discovery + all OWASP modules by default (or a subset via --modules a,b) and drives the CI gate
OWASP Module (owasp <key>) - Run exactly one OWASP module in isolation (red-team focus)

Deprecation. full and main are deprecated, hidden aliases of scan. They still forward to scan (emitting a one-line stderr notice) — migrate scripts to scan. A single-module alias invocation like full --modules bola becomes apileaks owasp bola.

Directory Fuzzing¶

Discover hidden API endpoints and administrative interfaces:

# Basic directory fuzzing
python apileaks.py dir --target https://api.example.com

# With custom wordlist
python apileaks.py dir \
  --target https://api.example.com \
  --wordlist wordlists/endpoints.txt

# With WAF evasion
python apileaks.py dir \
  --target https://api.example.com \
  --user-agent-random \
  --rate-limit 5

# Focus on specific status codes
python apileaks.py dir \
  --target https://api.example.com \
  --status-code 200,401,403 \
  --output endpoint_discovery

For the complete list of dir options (triage, scope, robustness, and batch-scan flags), see the CLI Reference.

Parameter Fuzzing¶

Discover hidden, undocumented, or debug parameters accepted by an API endpoint. The par command injects candidate parameter names and detects parameters that alter application behavior via reflection, new JSON fields, and response difference signals. See the full Parameter Fuzzing Guide for a detailed walkthrough.

# Basic: discover hidden parameters with the default wordlist
python apileaks.py par --target https://api.example.com

# With authentication
python apileaks.py par \
  --target https://api.example.com/users \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Control injection points via --methods
python apileaks.py par \
  --target https://api.example.com \
  --methods GET,POST,PUT \
  --wordlist wordlists/parameters.txt

# Hit confirmation to reduce false positives
python apileaks.py par \
  --target https://api.example.com/api/v1/search \
  --confirm-hits 3 \
  --max-requests 1000

# Request context: custom headers, cookie, and auth
python apileaks.py par \
  --target https://api.example.com/api/v1/profile \
  -H "X-API-Key: key123" \
  --cookie "session=abc" \
  --basic-auth admin:secret

Security Scan¶

Comprehensive security testing with OWASP modules. scan runs discovery and all registered OWASP modules by default:

# Basic scan (runs discovery + all OWASP modules by default)
python apileaks.py scan --target https://api.example.com

# With specific OWASP modules
python apileaks.py scan \
  --target https://api.example.com \
  --modules bola,auth,property \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# With configuration file
python apileaks.py scan \
  --config config/examples/rest_api_config.yaml \
  --target https://api.example.com

Advanced Features¶

Framework Detection¶

Automatically detect API frameworks and adapt testing strategies:

# Enable framework detection
python apileaks.py scan \
  --target https://api.example.com \
  --detect-framework \
  --framework-confidence 0.8

# Short flag version
python apileaks.py scan \
  --target https://api.example.com \
  --df \
  --framework-confidence 0.9

Supported Frameworks: - FastAPI - Express.js - Django REST Framework - Flask - Spring Boot - ASP.NET Core - Laravel - Ruby on Rails

API Version Discovery¶

Discover and test multiple API versions:

# Enable version fuzzing
python apileaks.py scan \
  --target https://api.example.com \
  --fuzz-versions \
  --version-patterns "/v1,/v2,/api/v1,/api/v2"

# Short flag version
python apileaks.py scan \
  --target https://api.example.com \
  --fv

# Combined framework and version detection
python apileaks.py scan \
  --target https://api.example.com \
  --df --fv \
  --output comprehensive_discovery

Status Code Filtering¶

Focus testing on specific response codes:

# Success responses only
python apileaks.py dir \
  --target https://api.example.com \
  --status-code 200-299

# Authentication-related responses
python apileaks.py par \
  --target https://api.example.com \
  --status-code 401,403

# Error analysis
python apileaks.py scan \
  --target https://api.example.com \
  --status-code 500-599 \
  --modules bola,auth

OWASP Module Testing¶

APILeak provides specialized modules for each OWASP API Security Top 10 category:

API1 - Broken Object Level Authorization (BOLA)¶

Test for unauthorized access to objects:

# BOLA testing only (single module in isolation)
python apileaks.py owasp bola \
  --target https://api.example.com \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# With multiple authentication contexts
python apileaks.py scan \
  --config config/examples/bola_testing_config.yaml \
  --target https://api.example.com

What BOLA Testing Covers: - Sequential ID enumeration - GUID/UUID enumeration - Cross-user object access - Privilege escalation detection - Anonymous access testing

API2 - Broken Authentication¶

Test authentication mechanisms and JWT security:

# Authentication testing (single module in isolation)
python apileaks.py owasp auth \
  --target https://api.example.com \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# JWT-specific testing
python apileaks.py scan \
  --config config/examples/auth_testing_config.yaml \
  --target https://api.example.com

What Authentication Testing Covers: - JWT algorithm confusion (RS256/HS256) - Weak JWT secrets - Token expiration validation - Logout token invalidation - Algorithm downgrade attacks

API3 - Broken Object Property Level Authorization¶

Test for excessive data exposure and mass assignment:

# Property-level authorization testing (single module in isolation)
python apileaks.py owasp property \
  --target https://api.example.com \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Comprehensive property testing
python apileaks.py scan \
  --config config/examples/property_testing_config.yaml \
  --target https://api.example.com

What Property Testing Covers: - Sensitive data exposure detection - Mass assignment vulnerabilities - Read-only field modification - Undocumented field discovery - PII leakage detection

API4 - Unrestricted Resource Consumption¶

Test for DoS vulnerabilities and rate limiting:

# Resource consumption testing (single module in isolation)
python apileaks.py owasp resource \
  --target https://api.example.com \
  --rate-limit 20  # Higher rate for resource testing

# Comprehensive resource testing
python apileaks.py scan \
  --config config/examples/resource_testing_example.yaml \
  --target https://api.example.com

What Resource Testing Covers: - Rate limiting detection - Large payload handling - JSON depth bomb testing - Array size limits - ReDoS pattern detection

API5 - Broken Function Level Authorization¶

Test for privilege escalation and admin access:

# Function-level authorization testing (single module in isolation)
python apileaks.py owasp function_auth \
  --target https://api.example.com \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Admin endpoint testing
python apileaks.py scan \
  --config config/examples/function_auth_testing_config.yaml \
  --target https://api.example.com

What Function Auth Testing Covers: - Admin endpoint discovery - HTTP method bypass testing - Parameter-based privilege escalation - Header-based bypass detection - Anonymous admin access

Multiple Module Testing¶

Run multiple OWASP modules together:

# Core P0 modules
python apileaks.py scan \
  --target https://api.example.com \
  --modules bola,auth,property,function_auth \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# All available modules (scan runs every module by default, so a plain scan is enough)
python apileaks.py scan \
  --target https://api.example.com \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Configuration Management¶

Configuration File Structure¶

APILeak uses YAML configuration files for complex testing scenarios:

# Basic configuration structure
target:
  base_url: "https://api.example.com"
  timeout: 15
  verify_ssl: true

authentication:
  contexts:
    - name: "user"
      type: "bearer"
      token: "your-jwt-token"
      privilege_level: 1

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

rate_limiting:
  requests_per_second: 10
  adaptive: true

reporting:
  formats: ["json", "html"]
  output_dir: "reports"

Using Configuration Files¶

# Use configuration file
python apileaks.py scan \
  --config config/examples/rest_api_config.yaml \
  --target https://api.example.com

# Override configuration with CLI arguments
python apileaks.py scan \
  --config config/examples/rest_api_config.yaml \
  --target https://api.example.com \
  --rate-limit 5 \
  --modules bola,auth

Environment Variables¶

Override configuration with environment variables:

# Set environment variables
export APILEAK_TARGET_URL="https://api.example.com"
export APILEAK_AUTH_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
export APILEAK_RATE_LIMIT="5"

# Run with environment variables
python apileaks.py scan --config config/examples/ci_cd_config.yaml

WAF Evasion Techniques¶

APILeak provides multiple strategies for bypassing Web Application Firewalls:

User Agent Rotation¶

# Random user agent from built-in list
python apileaks.py dir \
  --target https://api.example.com \
  --user-agent-random

# Custom user agent
python apileaks.py par \
  --target https://api.example.com \
  --user-agent-custom "Mozilla/5.0 (compatible; Googlebot/2.1)"

# User agent rotation from file
python apileaks.py scan \
  --target https://api.example.com \
  --user-agent-file wordlists/user_agents.txt \
  --modules bola,auth

Rate Limiting for WAF Bypass¶

# Conservative rate limiting
python apileaks.py scan \
  --target https://api.example.com \
  --rate-limit 1 \
  --user-agent-random \
  --modules bola,auth

# Adaptive rate limiting
python apileaks.py scan \
  --config config/examples/waf_protected_api_config.yaml \
  --target https://api.example.com

Configuration-Based WAF Evasion¶

# WAF evasion in configuration
fuzzing:
  headers:
    user_agent_rotation: true
    user_agent_list:
      - "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
      - "curl/8.4.0"
      - "Postman/10.20.0"

rate_limiting:
  requests_per_second: 1
  jitter: true
  jitter_factor: 0.3

CI/CD Integration¶

Basic CI/CD Usage¶

# CI/CD friendly command
python apileaks.py scan \
  --target "${API_ENDPOINT}" \
  --jwt "${JWT_TOKEN}" \
  --modules bola,auth,property \
  --output ci_security_scan \
  --no-banner

# With exit code handling
python apileaks.py scan \
  --config config/examples/ci_cd_config.yaml \
  --target "${API_ENDPOINT}" || exit 1

GitHub Actions Example¶

name: API Security Scan
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install -r requirements.txt

      - name: Run APILeak Security Scan
        env:
          API_ENDPOINT: ${{ secrets.API_ENDPOINT }}
          JWT_TOKEN: ${{ secrets.JWT_TOKEN }}
        run: |
          python apileaks.py scan \
            --target "${API_ENDPOINT}" \
            --jwt "${JWT_TOKEN}" \
            --modules bola,auth,property \
            --output github_actions_scan \
            --no-banner

      - name: Upload Security Reports
        uses: actions/upload-artifact@v3
        with:
          name: security-reports
          path: reports/

GitLab CI Example¶

stages:
  - security

api_security_scan:
  stage: security
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - python apileaks.py scan
        --target "${API_ENDPOINT}"
        --jwt "${JWT_TOKEN}"
        --modules bola,auth,property
        --output gitlab_ci_scan
        --no-banner
  artifacts:
    reports:
      junit: reports/*.xml
    paths:
      - reports/
  variables:
    API_ENDPOINT: "https://api.staging.example.com"
  only:
    - merge_requests
    - main

Troubleshooting¶

Common Issues and Solutions¶

Rate Limiting (429 Responses)¶

# Reduce request rate
python apileaks.py dir \
  --target https://api.example.com \
  --rate-limit 1 \
  --user-agent-random

# Use adaptive rate limiting
python apileaks.py scan \
  --target https://api.example.com \
  --rate-limit 5 \
  --modules bola \
  --config config/examples/waf_protected_api_config.yaml

WAF Blocking Requests¶

# Use legitimate user agents
python apileaks.py par \
  --target https://api.example.com \
  --user-agent-custom "Mozilla/5.0 (compatible; Googlebot/2.1)"

# Conservative testing
python apileaks.py scan \
  --target https://api.example.com \
  --rate-limit 2 \
  --user-agent-file wordlists/legitimate_agents.txt \
  --modules bola

SSL Certificate Issues¶

# Disable SSL verification (not recommended for production)
python apileaks.py scan \
  --target https://api.example.com \
  --no-verify-ssl

# Or in configuration:
target:
  verify_ssl: false

Authentication Issues¶

# Test with different authentication methods
python apileaks.py scan \
  --target https://api.example.com \
  --header "X-API-Key: your-api-key"

# Use configuration file for complex auth
python apileaks.py scan \
  --config config/examples/auth_testing_config.yaml \
  --target https://api.example.com

Debug Mode¶

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

# JSON structured logging
python apileaks.py scan \
  --target https://api.example.com \
  --json-logs \
  --log-file structured.log

Best Practices¶

Security Testing Guidelines¶

Start Conservative

# Begin with low rate limits
python apileaks.py dir --target https://api.example.com --rate-limit 2

Use Legitimate User Agents

# Avoid suspicious user agents
python apileaks.py scan --target https://api.example.com --user-agent-random

Test with Proper Authorization

# Always use valid tokens when available
python apileaks.py scan \
  --target https://api.example.com \
  --jwt "valid-jwt-token" \
  --modules bola,auth

Performance Optimization¶

Use Status Code Filtering

# Focus on relevant responses
python apileaks.py dir \
  --target https://api.example.com \
  --status-code 200,401,403

Optimize Wordlists

# Use targeted wordlists
python apileaks.py par \
  --target https://api.example.com \
  --wordlist wordlists/api_parameters.txt

Configure Appropriate Timeouts

target:
  timeout: 30  # Adjust based on API response times

Reporting Best Practices¶

Use Multiple Formats

python apileaks.py scan \
  --target https://api.example.com \
  --output comprehensive_scan
# Generates: .json, .html, .xml, .txt

Structured Output for Automation

python apileaks.py scan \
  --target https://api.example.com \
  --json-logs \
  --output automation_scan

Include Context in Filenames

python apileaks.py scan \
  --target https://api.example.com \
  --output "production_api_$(date +%Y%m%d)"

Ethical Testing Guidelines¶

Obtain Proper Authorization
Always get written permission before testing
Respect scope limitations
Follow responsible disclosure practices
Respect Rate Limits
Start with conservative settings
Monitor for 429 responses
Use adaptive rate limiting
Avoid Destructive Testing
Don't test DELETE operations on production data
Avoid large payload testing on production systems
Use test environments when possible
Document Your Testing
Keep detailed logs of testing activities
Document any issues discovered
Provide clear remediation guidance

For more detailed information, see: - Configuration Guide - OWASP Modules Guide - CI/CD Integration Guide - Troubleshooting Guide