Turn validated YAML findings into consistent security assessment reports.

RedReport is a Python CLI that validates engagement metadata and findings before generating self-contained Markdown and HTML reports. It keeps severity, CVSS, CWE, OWASP mappings, evidence, impact, and remediation in a reviewable source format.

report.yaml + findings/*.yaml → validate → prioritize → Markdown + HTML

Features

• Strict Pydantic schemas with unknown fields rejected.
• Severity and CVSS consistency checks.
• Duplicate finding ID detection.
• Critical-to-informational ordering.
• Risk distribution and aggregate score.
• Self-contained HTML with responsive dark theme.
• Markdown output suitable for Git and Pull Requests.
• Automation-friendly exit codes.
• Reusable demo engagement.

Installation

git clone https://github.com/guuszz/redreport.git
cd redreport
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
python -m pip install -e .

Quick start

redreport init my-assessment
redreport validate my-assessment
redreport build my-assessment --format all --output dist

Generated artifacts:

my-assessment/dist/
├── report.md
└── report.html

Project format

assessment/
├── report.yaml
├── findings/
│   ├── RR-001-bola.yaml
│   └── RR-002-debug.yaml
├── evidence/
└── dist/

Finding example:

id: RR-001
title: Broken object-level authorization exposes user records
severity: high
status: open
description: The endpoint does not verify ownership of the requested object.
impact: An authenticated account can access records belonging to other users.
remediation: Enforce ownership checks in the service layer for every object request.
affected_assets:
  - https://api.example.test/v1/users/{id}
cwe: CWE-639
owasp: API1:2023 Broken Object Level Authorization
cvss:
  score: 8.1
  vector: CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:N

Validation behavior

redreport validate examples/demo-engagement

VALID title='API Security Assessment — Demo Lab' findings=2 risk_score=5

RedReport rejects malformed IDs, invalid statuses, reversed engagement dates, unknown fields, duplicate IDs, and CVSS scores that conflict with their declared severity.

Development

python -m pip install -e ".[dev]"
ruff check .
pytest --cov=redreport --cov-report=term-missing

Roadmap

• YAML schemas and deterministic validation.
• Markdown and self-contained HTML reports.
• CVSS/severity consistency checks.
• PDF export.
• ScopeGuard JSON import.
• Evidence integrity hashes.
• Executive and technical report profiles.
• SARIF and security tool importers.
• Custom organization themes.

License

MIT