Metadata-Version: 2.4
Name: vamp-penreport
Version: 2.1
Summary: Penetration test report generator for VampSecure Labs assessments
Author-email: VampSecure Studios <contact@vampsecurestudios.com>
License: MIT
Project-URL: Homepage, https://github.com/Vampsecure-Labs/vamp-penreport
Project-URL: Repository, https://github.com/Vampsecure-Labs/vamp-penreport
Keywords: security,pentest,audit,cybersecurity,vampsecure,reporting,pentest-report,documentation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# vamp-penreport

![Version](https://img.shields.io/badge/version-2.0.0-crimson)
![Python](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![VampSecure Labs](https://img.shields.io/badge/VampSecure-Labs-7c3aed)

**Professional pentest report aggregator for VampSecure Labs toolkit.**

`vamp-penreport` reads JSON output files from any VSL tool, normalizes and deduplicates all findings, computes a global risk score, and produces polished HTML, PDF, and Markdown reports ready for client delivery.

It is **not a scanner** — it is a report aggregator and generator. It has no finding prefix of its own; it works with findings produced by other VSL tools.

---

## Features

- Ingests multiple VSL JSON output files in a single run
- Normalizes severity labels and deduplicates findings across tools
- Computes global risk score (0–100) with qualitative label (Low / Moderate / High / Critical)
- Executive summary with inline SVG gauge and category bar chart
- Prioritized remediation roadmap (4 phases: Immediate / Urgent / Planned / Continuous)
- **MITRE ATT&CK coverage section**: auto-detected from `vamp-log-analyzer` FORA-NNN findings — 25 detectors mapped to 12 tactics; rendered as an interactive table with severity badges and technique tooltips
- Detailed technical findings section with estimated CVSS range
- **Local logo embedding**: `--logo-file PATH` embeds any PNG/JPG/SVG as a base64 data URI — the HTML is fully self-contained with no external requests
- Printable HTML with full CSS `@media print` support
- Native PDF via `fpdf2` (no browser required)
- Markdown output for integration into wikis or documentation systems
- Consolidated JSON export for pipeline integration

---

## Installation

```bash
cd vamp-penreport
pip install -r requirements.txt
```

`fpdf2` is only required for PDF output. HTML and Markdown generation work with Python stdlib alone.

---

## Usage

### Basic — HTML only

```bash
python3 vamp_penreport.py scan1.json \
  --client "Acme Corp" \
  --engagement "External Pentest Q3 2026"
```

### Full report — HTML + PDF + Markdown

```bash
python3 vamp_penreport.py scan1.json scan2.json scan3.json \
  --client "Acme Corp" \
  --engagement "External Pentest Q3 2026" \
  --auditor "VampSecure Labs Red Team" \
  --scope "Perimeter web applications and exposed APIs" \
  --start-date 2026-07-01 \
  --end-date 2026-07-31 \
  --logo-file /path/to/client_logo.png \
  --report-html report.html \
  --report-pdf report.pdf \
  --report-md report.md \
  --report-json consolidated.json
```

### Executive summary only (no detailed technical findings)

```bash
python3 vamp_penreport.py scan1.json scan2.json \
  --client "Acme Corp" \
  --engagement "Quick Assessment" \
  --executive-only \
  --report-html executive_summary.html
```

### Forensic log report with MITRE ATT&CK coverage

When the input includes output from `vamp-log-analyzer`, the report automatically adds a **MITRE ATT&CK coverage section** showing which tactics and techniques were observed:

```bash
python3 vamp_penreport.py \
  recon.json ssl.json http.json logs_forensic.json \
  --client "Acme Corp" \
  --engagement "Full Perimeter Assessment" \
  --report-html full_report.html
```

### All options

```
usage: vamp-penreport [-h] --client NOMBRE [--engagement DESC]
                      [--auditor NOMBRE] [--scope TEXTO]
                      [--start-date FECHA] [--end-date FECHA]
                      [--report-html FILE] [--report-pdf FILE]
                      [--report-md FILE] [--report-json FILE]
                      [--logo-url URL] [--logo-file FICHERO]
                      [--executive-only] [--verbose]
                      INPUT [INPUT ...]

positional arguments:
  INPUT                One or more VSL JSON output files

options:
  --client NOMBRE      Client name (required)
  --engagement DESC    Engagement description
  --auditor NOMBRE     Auditor name/team (default: VampSecure Labs)
  --scope TEXTO        Engagement scope
  --start-date FECHA   Start date (YYYY-MM-DD)
  --end-date FECHA     End date (YYYY-MM-DD)
  --report-html FILE   HTML output file (default: report.html)
  --report-pdf FILE    PDF output file (requires fpdf2)
  --report-md FILE     Markdown output file
  --report-json FILE   Consolidated JSON output file
  --logo-url URL       Client logo URL (HTML only, optional)
  --logo-file FILE     Local logo file embedded as base64 (PNG/JPG/SVG)
  --executive-only     Executive summary only, no technical findings
  --verbose            Verbose/debug output
```

---

## Input JSON schema

VSL tools produce output files in the following standard schema. All fields are optional except `findings`.

| Field | Type | Description |
|-------|------|-------------|
| `tool` | string | Tool name (e.g. `vamp-docker-audit`) |
| `version` | string | Tool version |
| `target` | string | Scan target (hostname, IP, path…) |
| `timestamp` | string | ISO 8601 scan timestamp |
| `findings` | array | Array of finding objects (see below) |
| `summary` | object | Count by severity (optional, for reference) |

### Finding object

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Finding identifier (e.g. `DOCK-001`, `FORA-001`) |
| `severity` | string | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO` |
| `title` | string | Short finding title |
| `description` | string | Technical description |
| `evidence` | string | Raw evidence / proof of concept |
| `remediation` | string | Recommended fix |
| `references` | array | External references (CVEs, CWEs, URLs…) |

Alternative field names are also accepted: `results`/`issues`/`vulnerabilities` instead of `findings`; `risk`/`level` instead of `severity`; `detail`/`details` instead of `description`; `output`/`proof` instead of `evidence`; `fix`/`recommendation` instead of `remediation`.

---

## Report sections

| Section | Description |
|---------|-------------|
| **Cover page** | Client name, dates, auditor, CONFIDENTIAL classification, optional logo |
| **Table of contents** | Navigable index with dynamic numbering |
| **Executive summary** | Risk gauge (SVG), severity table, top 5 findings, tool distribution chart |
| **Remediation roadmap** | 4-phase plan: Immediate (0–7d), Urgent (7–30d), Planned (30–90d), Continuous |
| **MITRE ATT&CK coverage** | Auto-generated when FORA-NNN findings are present — tactics matrix with severity badges and technique tooltips |
| **Technical findings** | Full detail per finding: description, evidence, remediation, CVSS estimate, references |
| **Methodology** | Tools used, severity classification table |
| **Disclaimer** | Confidentiality notice |

> The MITRE ATT&CK section only appears when the report contains findings from `vamp-log-analyzer` (FORA-NNN prefix). Section numbers adjust automatically.

---

## MITRE ATT&CK Coverage

When `vamp-log-analyzer` output is included, `vamp-penreport` automatically maps the 25 FORA-NNN detectors to MITRE ATT&CK tactics and renders a coverage matrix. Example:

| Tactic | Detected | Detectors |
|--------|----------|-----------|
| Credential Access | CRITICAL×2, HIGH×1 | `FORA-001` `FORA-002` `FORA-022` |
| Reconnaissance | HIGH×1 | `FORA-009` |
| Initial Access | MEDIUM×1 | `FORA-007` |
| … | … | … |

The 25 detectors cover 12 tactics: Reconnaissance, Initial Access, Execution, Persistence, Privilege Escalation, Defense Evasion, Credential Access, Discovery, Lateral Movement, Collection, Command & Control, Exfiltration.

---

## Compatible VSL tools

`vamp-penreport` works with JSON output from any tool in the VampSecure Labs toolkit:

- `vamp-log-analyzer` — Forensic log analysis — 25 MITRE ATT&CK detectors, STIX 2.1 *(triggers ATT&CK section)*
- `vamp-docker-audit` — Docker container and daemon security
- `vamp-k8s-audit` — Kubernetes cluster security review
- `vamp-ssl-audit` — TLS/SSL certificate and configuration analysis
- `vamp-secrets-scanner` — Hardcoded secrets and credential detection
- `vamp-http-audit` — HTTP headers and web security checks
- `vamp-wp2shell-audit` — WordPress vulnerability assessment
- `vamp-passive-recon` — OSINT and passive reconnaissance
- `vamp-subdomain-takeover` — Subdomain takeover detection
- `vamp-cve-oracle` — CVE correlation and vulnerability lookup
- `vamp-jwt-audit` — JWT token security analysis
- `vamp-k8s-audit` — Kubernetes cluster security review
- `vamp-llm-probe` — LLM endpoint security assessment
- `vamp-mail-audit` — Email security (SPF/DKIM/DMARC)
- `vamp-arp-sentinel` — ARP spoofing and network analysis
- `vamp-entropy-watch` — Entropy-based anomaly detection
- `vamp-forticheck` — Multi-vendor edge device CVE scanner
- `vamp-cloud-enum` — Cloud asset enumeration

---

## License

MIT — See `LICENSE` file.

---

© VampSecure Studios — VampSecure Labs Security Research Division

*Authorized use only in environments with explicit written permission.*
