APISCAN v3.0 is an OWASP API scanner designed to detect API vulnerabilities

AI-aware Swagger/OpenAPI HTML reports

APISCAN v3.0 AI-enhanced OWASP API Security Scanner.

APIscan is an API vulnerability scanner that proactively identifies security risks by testing against the OWASP API Security Top 10 (2023). It uses your OpenAPI/Swagger specification to generate realistic attack payloads and detect issues such as Broken Object Level Authorization (BOLA), Broken Authentication, Excessive Data Exposure, and other critical API vulnerabilities. APIscan supports OAuth 2.0, Bearer, mTLS, and API key authentication, generates realistic requests, runs scans in parallel, and offers optional AI-assisted review.

Star on GitHub What's new Version 3.0

What's new in v3.0

Generic Sanitizer

No customer hardcodes. Collapses duplicate path segments, normalizes /vN /vN.00, trims trailing slashes. Toggle with --no-sanitize and refine with --rewrite "pat=>rep".

Header Overrides

Universal header model: --flow token --token, --apikey --apikey-header, --extra-header, --headers-file. Spec examples/defaults are autoapplied too.

IDs & Samples

--ids-file to control path variables; fallback generator covers *id, code, uuid, email, date.

Better Planning

Improved requestBody sampling order and accurate JSON detection (application/json; charset=UTF-8).

Enhanced Verification

New --verify-plan option to test planned requests and --success-codes to define acceptable responses.

Adaptive Retry

--retry500 option for automatic retries on HTTP 5xx errors with field augmentation from error messages.

Quick Start

# 1) Install (Python 3.11+ recommended)
pip install -r requirements.txt

# 2) Run with a Swagger/OpenAPI file
python apiscan.py --url https://api.example.com \
  --swagger openapi.json --flow token --token <BEARER>

# Optional: export variables template
python apiscan.py --url https://api.example.com \
  --swagger openapi.json --export_vars vars_template.yml

Core Features

Comprehensive API Testing

Full OWASP API Security Top 10 (2023) coverage with 11 dedicated audit modules:

BOLA (Broken Object Level Authorization)
Broken Authentication
Property-level Authorization
Resource Consumption
Function-level Authorization
Business Logic Flows
SSRF
Security Misconfiguration
Inventory Management
Unsafe Consumption
AI-assisted Analysis

Authentication Support

Multiple authentication flows with flexible configuration:

Bearer Token (JWT)
OAuth2 Client Credentials
OAuth2 Authorization Code
Basic Authentication
NTLM Authentication
API Key in Headers
Client Certificate (mTLS)

Smart Request Planning

Advanced request generation from OpenAPI specs:

Automatic path parameter filling
Request body generation from schemas
Content-Type detection and handling
Multipart/form-data support
Dummy data generation for testing
Adaptive retry on 5xx errors

Advanced Reporting

Comprehensive reporting capabilities:

Individual HTML reports per vulnerability type
Combined master report
CSV export for planning and verification
Detailed logging with timestamps
Vulnerability summary with risk levels

Command Line Options

Basic Options

Authentication

Scan Options

Advanced

--url Base URL of the API to scan (required)

--swagger Path to Swagger/OpenAPI JSON file (required)

--threads Number of concurrent threads (default: 2)

--debug Enable debug output (verbose logging)

--insecure Disable TLS certificate validation

--flow Authentication flow: none, token, client, basic, ntlm, auth

--token Bearer token value (used with --flow token)

--apikey API key value (sent in header specified by --apikey-header)

--apikey-header Header name for API key (default: X-API-Key)

--client-cert Path to client certificate file (PEM, used for mTLS)

--client-key Path to private key file (PEM, used for mTLS)

--basic-auth Basic auth in the form user:password

--ntlm NTLM credentials in the form DOMAIN\user:password

--api1 to --api11 Run specific API security tests (default: all)

--plan-only Build all requests and write apiscan-plan.csv, do not send

--plan-then-scan First build full plan (CSV), then perform the scan

--verify-plan After planning, actually send each planned request and expect success

--success-codes Comma list of codes or ranges, e.g., 200-299,302 (default: 200-299)

--dummy Use dummy data for request bodies and parameters

--export_vars Export variables template YAML if .yml/.yaml else JSON

--proxy Optional proxy URL, e.g. http://127.0.0.1:8080

--ids-file JSON file mapping path parameter names to concrete values

--rewrite Regex=>replacement rewrite applied to each URL (can be repeated)

--no-sanitize Disable built-in URL normalization; only apply explicit --rewrite rules

--retry500 Adaptive retries on HTTP 5xx for POST/PUT/PATCH (default: 1)

--no-retry-500 Disable adaptive 5xx retries

--normalize-version Normalize version segments in URLs like /v2.00/ -> /v2.0/

Usage Examples & Recipes

Basic Scan with Bearer Token

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --flow token --token "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --threads 5

API Key Authentication

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --apikey "your-api-key-here" --apikey-header "X-API-Key" \
  --api1 --api2 --api5  # Test only specific vulnerabilities

OAuth2 Client Credentials

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --flow client \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --token-url "https://auth.example.com/oauth/token" \
  --scope "api.read api.write"

Planning Phase Only

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --flow token --token "<JWT>" \
  --plan-only

Generates apiscan-plan.csv with all planned requests without executing them.

Verification with Custom Success Codes

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --flow token --token "<JWT>" \
  --verify-plan --success-codes "200-299,304"

Tests all planned requests and expects success codes in 200-299 range or 304.

Using ID Mapping File

# ids.json content:
{
  "userId": "12345",
  "orderId": "67890", 
  "vehicleId": "abc123",
  "postId": "post-001"
}

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --ids-file ids.json \
  --flow token --token "<JWT>"

URL Rewriting for Path Normalization

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --rewrite "/v2(?!\.)=>/v2.00" \
  --rewrite "/alpha/beta/alpha=>/alpha/beta" \
  --no-sanitize \
  --flow token --token "<JWT>"

Through Proxy with Debug Output

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --proxy http://127.0.0.1:8080 \
  --insecure \
  --debug \
  --flow token --token "<JWT>"

Dummy Mode for Testing

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --dummy \
  --flow token --token "<JWT>" \
  --verify-plan

Uses generated dummy data for all request bodies and parameters.

Custom Headers from File

# headers.json content:
{
  "X-Custom-Header": "custom-value",
  "X-Tenant-ID": "tenant-123",
  "X-Request-ID": "req-456"
}

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --headers-file headers.json \
  --flow token --token "<JWT>"

AI-Assisted Analysis

# Set environment variables first
export LLM_PROVIDER=openai_compat
export LLM_MODEL=gpt-4o-mini
export LLM_API_KEY=sk-...

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --flow token --token "<JWT>" \
  --api11  # Run AI-assisted analysis

Adaptive Retry on Server Errors

python apiscan.py --url https://api.example.com \
  --swagger openapi.json \
  --flow token --token "<JWT>" \
  --retry500 3  # Retry up to 3 times on 5xx errors

Comprehensive Enterprise Scan

python apiscan.py --url https://api.company.com \
  --swagger enterprise-api.json \
  --flow token --token "<JWT>" \
  --threads 10 \
  --proxy http://corporate-proxy:8080 \
  --ids-file prod-ids.json \
  --headers-file prod-headers.json \
  --rewrite "/v1/=>/v1.00/" \
  --retry500 3 \
  --verify-plan \
  --success-codes "200-299,302,304"

Scan Workflow

APISCAN Execution Flow

Initialization: Parse arguments, set up logging, create output directory
Authentication: Configure session with specified auth flow
API Reachability: Check if target API is accessible
Swagger Processing: Load and parse OpenAPI specification
Planning Phase: Generate request plan from endpoints (optional)
Verification Phase: Test planned requests (optional)
Security Audits: Execute selected API security tests (API1-API11)
Reporting: Generate HTML reports and combined summary

Supported OWASP API Security Risks

API1: Broken Object Level Authorization

Tests for inadequate access controls on object endpoints using ID manipulation and privilege escalation attempts.

API2: Broken Authentication

Assesses authentication mechanisms for weaknesses like credential stuffing, weak tokens, and flawed session management.

API3: Broken Object Property Level Authorization

Checks if users can access or modify object properties they shouldn't have permissions for.

API4: Unrestricted Resource Consumption

Tests for resource exhaustion attacks through large payloads, deep nesting, or excessive requests.

API5: Broken Function Level Authorization

Verifies proper authorization checks for sensitive functions and administrative endpoints.

API6: Unrestricted Access to Sensitive Business Flows

Assesses business logic vulnerabilities that could be exploited to manipulate workflows.

API7: Server Side Request Forgery (SSRF)

Tests for SSRF vulnerabilities where the API makes requests to internal or external resources.

API8: Security Misconfiguration

Checks for security misconfigurations like verbose errors, insecure defaults, or missing security headers.

API9: Improper Inventory Management

Assesses API inventory exposure including outdated versions, exposed debug endpoints, and deprecated APIs.

API10: Unsafe Consumption of APIs

Tests for vulnerabilities when consuming third-party APIs, including data validation and trust boundaries.

API11: AI-Assisted Security Analysis

Uses AI to identify complex security patterns and business logic flaws that traditional scanners might miss.

Troubleshooting

Connection Issues

Symptoms: Timeouts, connection refused, SSL errors
Solutions: Check network connectivity, verify URL, use --insecure for self-signed certs, configure proxy with --proxy

Authentication Failures

Symptoms: 401 Unauthorized, 403 Forbidden responses
Solutions: Verify token validity, check auth flow configuration, ensure proper headers with --headers-file or --extra-header

Path/Endpoint Issues

Symptoms: 404 Not Found, wrong endpoints being called
Solutions: Use --no-sanitize to disable URL normalization, add --rewrite rules for path corrections, verify Swagger file accuracy

Request Body Problems

Symptoms: 400 Bad Request, 422 Unprocessable Entity
Solutions: Use --dummy for generated data, check request body schemas in Swagger, use --export_vars to create template

Performance Issues

Symptoms: Slow scanning, timeouts
Solutions: Reduce --threads, use --apiX flags to run specific tests only

AI Analysis Failures

Symptoms: API11 errors, LLM connection issues
Solutions: Verify LLM environment variables (LLM_PROVIDER, LLM_MODEL, LLM_API_KEY), check API quotas, ensure network access to LLM provider

Output & Reporting

HTML Reports

Individual vulnerability reports (api_*_report.html) and combined master report with detailed findings, risk levels, and remediation guidance.

CSV Files

apiscan-plan.csv (planned requests) and apiscan-verify.csv (verification results) for further analysis or integration with other tools.

Log Files

Detailed execution logs in the log/ directory with timestamps, request/response data, and error information for debugging.

Console Output

Real-time progress with colored status indicators, vulnerability counts, and summary statistics upon completion.

Prerequisite: You need an OpenAPI/Swagger file

APISCAN works from an OpenAPI/Swagger specification to plan and verify calls.
If you already have a Swagger/OpenAPI file (e.g., openapi.json or swagger.yaml), you can use it directly with --swagger.

If you only have a Postman collection, convert it first:

Export your Postman collection (*.postman_collection.json).
Convert it to OpenAPI/Swagger using the open-source converter: https://github.com/perrym/postman-to-swagger.
Use the converted file with APISCAN via --swagger.

Example conversion flow

# Convert Postman -> Swagger/OpenAPI (see repo for options)
python postman-to-swagger.py --input ./MyCollection.postman_collection.json --output ./openapi.json

# Then run APISCAN using the converted spec
python apiscan.py --url https://api.example.com --swagger ./openapi.json --plan-only --verify-plan

Links

Repository: perrym/apiscanner

Medium: APISCAN a practical approach

Contact: pamsniffer@gmail.com