ReportGen — Penetration Test Report Generator

Import findings from JSON, generate markdown/HTML reports. Severity classifications, CVSS v3.1 scoring, executive summaries.

---

Architecture

graph TD
    subgraph "Input"
        JSON["findings.json<br/>(findings + metadata)"]
    end

    subgraph "ReportGen Engine"
        FM["Finding Model<br/>(title, severity, CVSS)"]
        CVSS["CVSS Calculator<br/>(v3.1 Base Score)"]
        SM["Severity Classifier<br/>(Critical → Info)"]
        ES["Executive Summary<br/>Generator"]
        TD["Technical Details<br/>Builder"]
    end

    subgraph "Output"
        MD["Markdown Report"]
        HTML["HTML Report<br/>(styled)"]
    end

    JSON --> FM
    FM --> SM
    FM --> CVSS
    FM --> ES
    FM --> TD
    SM --> MD
    CVSS --> MD
    ES --> MD
    TD --> MD
    MD --> HTML

    style JSON fill:#1a237e,stroke:#3949ab,color:#fff
    style MD fill:#004d40,stroke:#00796b,color:#fff
    style HTML fill:#004d40,stroke:#00796b,color:#fff

Loading

Data Flow

sequenceDiagram
    participant U as User
    participant RG as ReportGen
    participant F as File System

    U->>RG: load_findings_from_json("findings.json")
    RG->>F: read JSON
    F-->>RG: findings data
    RG->>RG: parse & validate
    RG->>RG: classify severities
    RG->>RG: calculate CVSS scores

    U->>RG: generate_markdown()
    RG->>RG: build executive summary
    RG->>RG: sort findings by severity
    RG->>RG: render technical details
    RG-->>U: markdown string

    U->>RG: save_markdown("report.md")
    RG->>F: write report
    F-->>U: file saved

    U->>RG: save_html("report.html")
    RG->>RG: convert to HTML
    RG->>F: write report
    F-->>U: file saved

Loading

---

Installation

pip install -r requirements.txt

Usage

# Markdown report
python3 reportgen.py findings.json -o report.md

# HTML report
python3 reportgen.py findings.json -f html -o report.html

# Both formats
python3 reportgen.py findings.json -f both -o report

Input JSON Format

{
    "title": "Web App Penetration Test",
    "client": "ACME Corp",
    "assessor": "S8C88",
    "date": "2026-07-17",
    "scope": "https://app.acme.com",
    "executive_summary": "A comprehensive assessment...",
    "findings": [
        {
            "title": "SQL Injection in Login",
            "description": "The login endpoint...",
            "severity": "Critical",
            "cvss_score": 9.8,
            "impact": "Full database compromise...",
            "remediation": "Use parameterized queries...",
            "references": ["https://owasp.org/www-community/attacks/SQL_Injection"],
            "affected_resource": "/api/login",
            "cve": "CVE-2026-1234"
        }
    ]
}

Or as a simple list:

[
    {
        "title": "XSS in Search",
        "description": "...",
        "severity": "Medium"
    }
]

---

Project Structure

ReportGen/
├── reportgen.py
├── requirements.txt
├── LICENSE
├── README.md
├── docs/
│   └── engineering-report.md
└── tests/
    └── test_reportgen.py

License

MIT