run_api_security_scan
Run OWASP API Security Top 10 rule-based scans on OpenAPI 3.x specs to detect vulnerabilities with severity ratings and remediation guidance.
Instructions
v0.8.0: OWASP API Security Top 10 (2023) rule-based scanner. Loads an OpenAPI 3.x spec, walks each path × method, and dispatches v0.8's 5 in-scope rules — BOLA (API1), Broken Authentication (API2), Mass Assignment (API3, opt-in), Function-Level Authz (API5), Security Misconfiguration (API8). Returns a v0.8 security report block with per-finding rule_id, severity (critical/high/medium/low/info), endpoint, evidence dict, and remediation_hint.
Requires QA_API_SECURITY_CONSENT=true at the server level. Non-localhost hosts must be in QA_API_SECURITY_AUTHORIZED_DOMAINS (comma-separated). mass_assignment mutates server state — opt in by passing it in categories. Tier 1 fixture (examples/sample_vulnerable_api/) ships with the package for self-tests.
v0.9.4 — Pass plan_id (from qa_plan) to auto-verify the scan's findings against the plan's critical points in the same call. The response gains a plan_verification block (per-CP checklist + overall status). One-shot equivalent of qa_plan → run_api_security_scan → verify_plan.
Returns: {scan_id, spec_url, base_url, categories_run, rules_ran, ops_scanned, severity_threshold, findings[...], summary{total, by_severity}, findings_below_threshold_count, plan_verification (only when plan_id given)}.
Error shapes: consent_required / unauthorized_domain / spec_load_failed / no_base_url / unknown_categories / bad_severity_threshold.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spec_url | Yes | OpenAPI 3.x URL (http:// or https://) or local path (file:// or bare). YAML and JSON both accepted. | |
| auth | No | Auth config. `token` enables single-user rules (headers + broken_auth). Add `alt_user_token` to enable two-user rules (bola + function_authz). For BOLA: also provide `bola_test_ids: {user_a: [...], user_b: [...]}` listing the ids of objects each user owns. | |
| categories | No | Rules to run. Default: headers + broken_auth + bola + function_authz (mass_assignment excluded — it mutates server state, opt in explicitly). | |
| severity_threshold | No | Minimum severity to include in `findings`. Lower-severity findings counted in `findings_below_threshold_count`. | medium |
| base_url | No | Override spec's `servers[0].url`. Use when the spec is hosted separately from the API. | |
| timeout_s | No | Per-request timeout. Default 30s. | |
| plan_id | No | v0.9.4 — Optional. plan_id returned by qa_plan. When supplied, the scan auto-verifies its findings against the plan's critical points and adds a `plan_verification` block to the response (per-CP checklist + overall passed/incomplete/failed status). Only findings ABOVE severity_threshold are seen by the verifier — if a CP targets a low-severity finding, lower the threshold to 'low' or 'info' accordingly. |