Metadata-Version: 2.4
Name: vamp-api-probe
Version: 1.0
Summary: REST API security DAST scanner: BOLA, BFLA, mass assignment, rate limiting and OWASP API Top 10
Author-email: VampSecure Studios <contact@vampsecurestudios.com>
License: AGPL-3.0-only
Project-URL: Homepage, https://github.com/Vampsecure-Labs/vamp-api-probe
Project-URL: Repository, https://github.com/Vampsecure-Labs/vamp-api-probe
Keywords: security,pentest,api,rest,owasp,bola,bfla,mass-assignment,vampsecure,dast
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.7.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: pyyaml>=6.0

<!-- © VampSecure Studios — VampSecure Labs Security Research Division -->
<h1 align="center">vamp-api-probe</h1>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.9%2B-blue?logo=python&logoColor=white" alt="Python 3.9+"/>
  <img src="https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey" alt="Platform"/>
  <img src="https://img.shields.io/badge/license-AGPL--3.0-green" alt="License AGPL-3.0"/>
  <img src="https://img.shields.io/badge/VampSecure-Labs-magenta" alt="VampSecure Labs"/>
</p>

## Overview

`vamp-api-probe` is a DAST (Dynamic Application Security Testing) scanner for modern REST APIs, aligned with the OWASP API Security Top 10 2023. It probes live API endpoints for broken object-level authorization (BOLA), broken function-level authorization (BFLA), mass assignment vulnerabilities, absent rate limiting, authentication weaknesses, exposed administrative endpoints, security header misconfigurations, and legacy version exposure. It can operate against a bare base URL with automatic endpoint discovery or drive its test suite from an OpenAPI/Swagger specification for complete endpoint coverage.

## Features

- **API1 — BOLA** (Broken Object Level Authorization): enumerates numeric path parameters (±1, ±10, ±100, and common IDs), compares authenticated vs unauthenticated responses to detect cross-user data leakage (CRITICAL/HIGH)
- **API2 — BFLA** (Broken Function Level Authorization): probes every endpoint without Authorization header and tests privileged HTTP methods (DELETE, PUT, PATCH) for missing access control (CRITICAL/HIGH)
- **API3 — Mass Assignment**: injects admin-escalation fields (`isAdmin`, `role`, `is_superuser`, `verified`, `balance`, `credits`) in POST/PUT/PATCH bodies and checks whether the API accepts them (CRITICAL)
- **API4 — Rate Limiting**: fires a configurable burst of requests against the same endpoint and flags absence of HTTP 429 responses (HIGH)
- **API5 — Broken Authentication**: tests manipulated JWT tokens (single-character mutation) and expired JWT detection to identify missing token validation (CRITICAL)
- **API6 — Sensitive Business Flows**: detects administrative and debug endpoints (`/admin`, `/internal`, `/debug`, `/actuator`, `/metrics`, `/env`, `/_debug`) accessible without authentication (HIGH)
- **API8 — Security Misconfiguration**: audits response headers (`X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security`, `Content-Security-Policy`) and checks for stack trace exposure via malformed input (MEDIUM)
- **API9 — Improper Inventory Management**: probes legacy API versions (e.g. `/v1/` when target is `/v2/`) for unretired endpoints (MEDIUM)
- OpenAPI/Swagger spec ingestion (YAML or JSON) for automatic endpoint and schema discovery
- Fallback endpoint discovery against common REST paths when no spec is provided
- Bearer token support for authenticated test passes
- Configurable per-request timeout and rate-limit burst size
- Export to Console (Rich), JSON, and HTML (dark-theme)
- VSL unified client report (HTML + optional PDF via fpdf2)

## Requirements

- Python 3.9 or later
- `rich >= 13.7.0`
- `aiohttp >= 3.8.0`
- `pyyaml >= 6.0`
- Optional: `fpdf2 >= 2.7` for `--report-pdf`

## Installation

```bash
pip install vamp-api-probe
# o con Homebrew:
brew install vampsecure-labs/labs/vamp-api-probe
```

```bash
git clone https://github.com/Vampsecure-Labs/vamp-api-probe.git
cd vamp-api-probe
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## Usage

```
vamp-api-probe scan --help
```

```
usage: vamp-api-probe scan --url URL
                            [--spec OPENAPI_FILE]
                            [--token BEARER_TOKEN]
                            [--no-auth-tests]
                            [--timeout SECONDS]
                            [--rate-limit-burst N]
                            [--json FILE] [--html FILE]
                            [--client CLIENT] [--engagement ENGAGEMENT]
                            [--auditor AUDITOR] [--report-scope SCOPE]
                            [--report-html FILE] [--report-pdf FILE]

vamp-api-probe — REST API DAST Scanner (VampSecure Labs)
```

## Examples

```bash
# Scan a public API with automatic endpoint discovery
vamp-api-probe scan --url https://api.ejemplo.com/v1

# Scan with an OpenAPI spec for full endpoint coverage
vamp-api-probe scan --url https://api.ejemplo.com/v1 --spec openapi.yaml

# Authenticated scan with a Bearer token
vamp-api-probe scan --url https://api.ejemplo.com/v1 --token eyJhbGciOiJIUzI1NiJ9...

# Skip tests that require a second user account
vamp-api-probe scan --url https://api.ejemplo.com/v1 --no-auth-tests

# Custom timeout and rate-limit burst
vamp-api-probe scan --url https://api.ejemplo.com/v1 --timeout 15 --rate-limit-burst 30

# Export findings to JSON and dark-theme HTML
vamp-api-probe scan --url https://api.ejemplo.com/v1 --json results.json --html report.html

# Generate client-ready engagement report (HTML + PDF)
vamp-api-probe scan --url https://api.ejemplo.com/v1 \
    --client "Acme Corp" --engagement "API Security Assessment Q4 2026" \
    --auditor "J. Smith" --report-html client_report.html --report-pdf client_report.pdf
```

## CLI Reference

| Flag | Default | Description |
|------|---------|-------------|
| `--url URL` | (required) | Base URL of the API under test |
| `--spec FILE` | — | OpenAPI/Swagger YAML or JSON spec for endpoint discovery |
| `--token TOKEN` | — | Bearer token for authenticated requests |
| `--no-auth-tests` | off | Skip tests that require a second-user context |
| `--timeout N` | 10 | Per-request timeout in seconds |
| `--rate-limit-burst N` | 20 | Number of rapid requests for rate-limit test |
| `--json FILE` | — | Export results to JSON |
| `--html FILE` | — | Export dark-theme HTML report |
| `--client TEXT` | — | Client name for VSL engagement report |
| `--engagement TEXT` | — | Engagement title for VSL engagement report |
| `--auditor TEXT` | — | Auditor name for VSL engagement report |
| `--report-scope TEXT` | — | Scope description for VSL engagement report |
| `--report-html FILE` | — | Export unified VSL client report (HTML) |
| `--report-pdf FILE` | — | Export unified VSL client report (PDF, requires fpdf2) |

## Output Formats

| Format | Flag | Description |
|--------|------|-------------|
| Console | (default) | Rich progress and findings table with OWASP API Top 10 mapping |
| JSON | `--json FILE` | Machine-readable full result set |
| HTML | `--html FILE` | Dark-theme standalone report |
| Client HTML | `--report-html FILE` | Unified VampSecure Labs engagement report |
| Client PDF | `--report-pdf FILE` | PDF version of the VSL client report |

## OWASP API Top 10 Coverage

| ID | Category | Severity |
|----|----------|----------|
| API1:2023 | Broken Object Level Authorization (BOLA) | CRITICAL / HIGH |
| API2:2023 | Broken Function Level Authorization (BFLA) | CRITICAL / HIGH |
| API3:2023 | Broken Object Property Level Authorization / Mass Assignment | CRITICAL |
| API4:2023 | Unrestricted Resource Consumption (Rate Limiting) | HIGH |
| API5:2023 | Broken Function Level Authorization / Broken Authentication | CRITICAL |
| API6:2023 | Unrestricted Access to Sensitive Business Flows | HIGH |
| API8:2023 | Security Misconfiguration | MEDIUM |
| API9:2023 | Improper Inventory Management | MEDIUM |

## Exit Codes

| Code | Meaning | CI/CD Behavior |
|------|---------|----------------|
| `0` | No critical or high findings | Pipeline passes |
| `1` | CRITICAL or HIGH findings detected | Pipeline fails — review required |
| `2` | Connection or configuration error | Pipeline fails — check target |

## Legal Notice

Use exclusively on systems you own or for which you hold explicit written authorization from the system owner. VampSecure Studios assumes no liability for unauthorized use.

## Part of VampSecure Labs Toolkit

`vamp-api-probe` is one tool in the VampSecure Labs security research toolkit. For the full toolkit including the orchestrator that runs all tools in sequence and aggregates findings into a single engagement report, see:

- Portfolio: [github.com/belky-me](https://github.com/belky-me)
- Orchestrator: [github.com/belky-me/vamp-orchestrator](https://github.com/belky-me/vamp-orchestrator)

---

© VampSecure Studios — VampSecure Labs Security Research Division

## Versión
v1.0 — VampSecure Labs Security Research Division
