Scan Guide — Orchestrated OWASP Assessment¶

scan is APILeak's primary command. It runs endpoint discovery and then executes all twelve registered OWASP modules by default (the ten OWASP API Security Top 10 2023 categories plus parameter_pollution and spec_driven_testing), aggregating every finding through the unified reporting pipeline and driving the CI/CD severity gate.

Use owasp <key> to run a single module in isolation.

Table of Contents¶

• Overview
• Syntax
• Required Options
• Configuration
• Module Selection
• Discovery Control
• Advanced Discovery Features
• Authentication Options
• BOLA Module Options
• Auth Module Options
• Spec Import Options
• Multi-User Testing
• CI/CD Integration
• General Options
• Basic Examples
• Intermediate Examples
• Advanced Examples
• Exit Codes

Overview¶

A plain scan invocation:

1. Runs endpoint discovery against the target (same engine as dir)
2. Executes all twelve registered OWASP modules by default
3. Aggregates all findings into one report
4. Evaluates the CI/CD severity gate (when --ci-mode is set)

full and main are deprecated hidden aliases of scan. They still work but emit a one-line deprecation notice to stderr. Migrate scripts to scan.

Syntax¶

python apileaks.py scan [OPTIONS]

Required Options¶

--target is required unless you pass --config with a config file that contains the target URL.

Configuration¶

When --config is supplied and also --target, the CLI target wins over the config's base_url.

Module Selection¶

The APILEAK_MODULES environment variable is the fallback when --modules is not supplied. If neither is set, all twelve modules run.

Available module keys (in OWASP category order):

* Not a strict Top 10 mapping — see the OWASP Command Reference for details.

An unrecognized key aborts with a descriptive error before any module runs.

Discovery Control¶

These options tune the endpoint discovery phase that runs before the OWASP modules.

Depth precedence: explicit --depth > APILEAK_MAX_DEPTH env var > built-in default of 3.

--fuzz-versions vs the inventory module — when to use each¶

Both options use the same VersionFuzzer internally, but they do different things:

⚠️ Double execution: if you use --fuzz-versions and the inventory module is active (the default in scan), the VersionFuzzer runs twice against the same host — first in advanced_discovery, then in owasp_testing. The outputs are different but the HTTP requests are identical. To avoid duplicate requests, use one or the other: - inventory only (default in scan): full API9 analysis, no extra requests - --fuzz-versions without inventory: fast reconnaissance with INFO severity, no semantic classification — exclude inventory with --modules bola,auth,...

See the full dir vs scan vs inventory analysis.

Advanced Discovery Features¶

--enable-advanced is equivalent to enabling --detect-framework, --fuzz-versions, --enable-payload-encoding, --enable-waf-evasion, --enable-subdomain-discovery, and --enable-cors-analysis at once.

Authentication Options¶

--jwt and --basic-auth are mutually exclusive. --auth-context extends the authentication context list instead of replacing --jwt.

BOLA Module Options¶

These options are specific to the bola module and only take effect when bola is in the selected module set.

By default (without --allow-write-bola) the BOLA module only issues safe-method (read-only) probes.

Auth Module Options¶

These options are specific to the auth module. They only take effect when auth is in the selected module set.

JWT Module Tests (cryptographic key material)¶

Advanced Auth Options¶

Spec Import Options¶

Supply OpenAPI/Swagger or Postman specs so the OWASP modules test declared operations in addition to discovered endpoints. These same two options also feed the spec_driven_testing module's own contract-enforcement audit — see Spec-Driven Testing for what that module specifically checks (enum/type/required constraints), as distinct from this general spec-import plumbing.

A spec source that cannot be read or parsed aborts before any request is issued.

Multi-User Testing¶

A missing, unreadable, or unparseable --actor-profile or --unauthorized-assertions source aborts before any request is issued.

CI/CD Integration¶

Default gate. Without --fail-on, scan fails on high or critical findings. Use --fail-on critical to restore the old behavior.

Available severity levels: critical, high, medium, low

General Options¶

User-Agent options are mutually exclusive. Passing more than one aborts with an error before any request.

Basic Examples¶

1. Full scan — all modules

python apileaks.py scan --target https://api.example.com

2. Authenticated scan

python apileaks.py scan \
  --target https://api.example.com \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3. Restrict to specific modules

python apileaks.py scan \
  --target https://api.example.com \
  --modules bola,auth,property

4. From a config file

python apileaks.py scan \
  --config config/production.yaml \
  --target https://api.example.com

5. Adjust rate limit

python apileaks.py scan \
  --target https://api.example.com \
  --rate-limit 3

Intermediate Examples¶

1. Framework detection and version fuzzing

python apileaks.py scan \
  --target https://api.example.com \
  --detect-framework \
  --fuzz-versions \
  --framework-confidence 0.8

2. Recursion control

python apileaks.py scan \
  --target https://api.example.com \
  --depth 5 \
  --max-requests 5000 \
  --concurrency 100

3. Resilience tuning

python apileaks.py scan \
  --target https://api.example.com \
  --timeout 30 \
  --retries 5 \
  -x json,php

4. WAF evasion

python apileaks.py scan \
  --target https://api.example.com \
  --user-agent-random \
  --rate-limit 2

5. Route through a proxy

python apileaks.py scan \
  --target https://api.example.com \
  --modules bola,auth,ssrf \
  --proxy http://127.0.0.1:8080

6. Structured logging to file

python apileaks.py scan \
  --target https://api.example.com \
  --log-level INFO \
  --log-file scan.log \
  --json-logs

7. Multi-user BOLA testing

python apileaks.py scan \
  --target https://api.example.com \
  --modules bola \
  --auth-context alice:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZSJ9.sig:1 \
  --auth-context bob:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJib2IifQ.sig:1

8. Spec-driven scan with OpenAPI

python apileaks.py scan \
  --target https://api.example.com \
  --openapi openapi.yaml \
  --modules bola,auth,property

Advanced Examples¶

1. Enable all advanced discovery features

python apileaks.py scan \
  --target https://api.example.com \
  --enable-advanced \
  --user-agent-random \
  --output advanced-scan

2. Non-destructive scan (safe mode)

python apileaks.py scan \
  --target https://api.example.com \
  --safe-mode \
  --modules bola,auth,security_misconfig

3. CI/CD gate with SARIF output

python apileaks.py scan \
  --target https://api.example.com \
  --ci-mode \
  --fail-on high \
  --sarif \
  --no-banner

4. Baseline-gated CI/CD (only new findings fail the pipeline)

python apileaks.py scan \
  --target https://api.example.com \
  --ci-mode \
  --fail-on medium \
  --baseline reports/previous-scan.json

5. Full CI/CD: non-destructive + baseline + SARIF

python apileaks.py scan \
  --target https://api.example.com \
  --ci-mode \
  --fail-on high \
  --safe-mode \
  --sarif \
  --baseline reports/baseline.json \
  --no-banner

6. Auth module with real key material

python apileaks.py scan \
  --target https://api.example.com \
  --modules auth \
  --public-key ./idp_public.pem \
  --signing-secret 's3cr3t'

7. Auth module with JWKS endpoint

python apileaks.py scan \
  --target https://api.example.com \
  --modules auth \
  --jwks-url https://idp.example.com/.well-known/jwks.json

8. BOLA with destructive probes enabled

python apileaks.py scan \
  --target https://api.example.com \
  --modules bola \
  --allow-write-bola \
  --bola-destructive-methods PATCH,PUT,DELETE \
  --bola-composite \
  --bola-verb-tampering \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

9. Deep discovery + full orchestrated scan

python apileaks.py scan \
  --target https://api.example.com \
  --detect-framework \
  --fuzz-versions \
  --depth 5 \
  --max-requests 8000 \
  --concurrency 100 \
  -x json,php \
  --timeout 30 \
  --retries 5 \
  --output deep-scan

10. MFA bypass and OAuth abuse testing

python apileaks.py scan \
  --target https://api.example.com \
  --modules auth \
  --jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --mfa-provisional-token tok_provisional_abc123 \
  --mfa-protected-endpoint https://api.example.com/dashboard \
  --oauth-authorize-url https://auth.example.com/authorize \
  --oauth-attacker-redirect https://attacker.example.com/cb

11. Multi-user with actor profiles and unauthorized assertions

python apileaks.py scan \
  --target https://api.example.com \
  --modules bola,function_auth \
  --auth-context alice:eyJ...:1 \
  --auth-context admin:eyJ...:3 \
  --actor-profile profiles/actors.yaml \
  --unauthorized-assertions assertions/forbidden.yaml

Exit Codes¶

These exit codes are deterministic and documented for CI/CD consumption. The gate is only evaluated when --ci-mode is set; outside CI mode the exit code is always 0 on a clean run.

See also: OWASP Command Reference · OWASP Modules Guide · CLI Reference · CI/CD Integration