Skip to content
Lockstep VM Docs

Reporting & output

The output/ package renders scored and enriched vulnerability data into deliverables. Three formats are supported, each with its own generator:

FormatGeneratorBest for
Excel (.xlsx)output.formatters.excel.ExcelReportGeneratoranalyst-facing, multi-sheet working reports
Word (.docx)output.formatters.docx.DOCXReportGeneratorbranded executive & technical client deliverables
CSVCLI export helpers (csv.DictWriter / DataFrame.to_csv)raw data hand-off / spreadsheet import

All three read the same in-memory models — VulnerabilityFinding, ApplicationRiskScore, RiskMetrics, ReportMetadata from output/core/models.py — so severity, CVSS, EPSS and exploit flags render consistently across formats. Styling and branding are centralized in output/config/formatting.py.

Sample outputs are shipped with the docs:

  • Executive summary (DOCX): sample_executive_summary.docx
  • Technical report (DOCX): sample_technical_report.docx
  • Excel workbooks: foxit_comprehensive_report.xlsx, foxit_full_enrichment_report.xlsx, rapid7_complete_system_report.xlsx, complete_report_all_assets.xlsx, version_tracking.xlsx — all under /docs/examples/reports/.
  • CSV: server_report.csv, server_with_cves.csv, server_full_details.csv.

Excel (.xlsx) reports

ExcelReportGenerator (built on openpyxl) composes a workbook from modular sheet handlers — one class per sheet, each with add_to_workbook(...). A shared ExcelStyler supplies fonts, header fills, borders and severity coloring (critical red C00000, high FFC7CE, medium FFEB9C, low C6EFCE).

generate_full_report() — the comprehensive workbook

Assembles, in order:

SheetContents
CoverTitle, client name, report date, CONFIDENTIAL classification, company info
Security BulletinsMain findings table — CVE ID, Severity, CVSS, Application, Vendor, Patch Available (severity-colored)
Vendor SummaryPer-vendor rollup — applications, critical vulns, priority
High Priority AppsApplications with ≥ 50 devices
Risk AnalysisPer-app risk scores, sorted highest-first (Application, Vendor, Devices, Vulns, Critical, Risk Score, Priority)
Remediation TrackingSLA table — CVE, Severity, Application, SLA Days, Due Date, Status, Owner
Research SourcesReference links (NVD, CVE.org, CISA KEV, X-Force, GitHub CVE) as clickable hyperlinks

generate_findings_only() is the lighter variant: Cover + Security Bulletins + Remediation Tracking.

Integration & enrichment sheets

output/formatters/excel/sheets.py also defines source- and enrichment-specific sheets used when the corresponding data is present:

  • Rapid7 Vulnerabilities — raw InsightVM data (title, CVSS, CVE ids, exploits, malware kits, solution, references), frozen header, filtered.
  • Defender Vulnerabilities — Defender data (exposed machines, exploit verified/public, exploit types); exposed-machine counts > 50 are highlighted.
  • Version Spread Overview — software version fragmentation (install counts, version count, % on most-common version, oldest/newest).
  • Executive Summary, All Vulnerabilities, Risk Scoring, Threat Intelligence, Enrichment Details, Action Items — the enrichment-driven sheets that render an EnrichedCVE/ScoredCVE JSON payload (OTX pulses, threat actors, MITRE techniques, CPE matches, per-source success/fail, ranked risk scores, timeline-mapped actions). CVE ids link to NVD and CWEs to cwe.mitre.org.

A separate output/rapid7_report.py (Rapid7ExcelReport) produces a standalone multi-sheet dump of everything a Rapid7 pull returns — this is what generated the rapid7_*_report.xlsx examples.

DOCX branded reports

DOCXReportGenerator (built on python-docx) produces Lockstep-branded Word documents. Branding is applied through DOCXStyler and output/config/formatting.py:

  • Fonts: Archivo (titles/headings/body), Bilo (subheadings).
  • Brand color: Lockstep orange #E85E28 (RGB 232, 94, 40); deep grey #3D3D3C for headers.
  • Every page gets a right-aligned logo in the header (falls back to a text company name if the logo file isn’t found), a CONFIDENTIAL watermark (a rotated VML text shape behind content, with a plain-text fallback), a confidentiality footer, and Page X of Y fields.
  • Severity uses the brand palette (critical = Lockstep orange, high/medium = accent oranges, low = renewing green).

_setup_document_structure() wires up the header/footer/watermark before any content is added. Four report templates are available:

generate_executive_summary()

The client-facing summary — six numbered sections:

  1. Executive Summary — intro + vulnerability overview (severity counts from RiskMetrics.from_findings).
  2. Risk Assessment — risk metrics and narrative.
  3. Top Priority Findings — top 10 critical/high findings as a summary table.
  4. Remediation — recommendations section.
  5. Detailed Vulnerability Listings — up to 20 findings, each a numbered sub-section with a details table (Application, CVSS, CWE, Exploited, EPSS, Affected Versions), description, solution, and references.
  6. Security Analysis — placeholder for custom analysis.

→ See sample_executive_summary.docx.

generate_technical_report()

The full technical deliverable: severity overview followed by all findings sorted by severity weight then CVSS, with complete descriptions.

→ See sample_technical_report.docx.

generate_compliance_report() & generate_remediation_tracking()

  • Compliance — maps findings to a framework’s controls (built-in mappings for NIST CSF, CIS Controls, SOC 2).
  • Remediation tracking — a remediation/SLA table as a standalone document.

CSV export

CSV is produced directly by the CLI rather than by a dedicated generator:

  • vulnmgmt export <data.csv> --format csv -o filtered.csv writes a filtered application inventory via pandas DataFrame.to_csv.
  • vulnmgmt integrations explore rapid7 <resource> --export <file>.csv streams live Rapid7 assets/devices/vulnerabilities to CSV via csv.DictWriter. The server_report.csv, server_with_cves.csv and server_full_details.csv examples came from this path (--include-vulns adds the CVE columns).
Terminal window
# Filtered inventory to CSV
vulnmgmt export data/AppInventory.csv --format csv --min-devices 50 -o filtered.csv


# Live Rapid7 assets / devices with vulns to CSV
vulnmgmt integrations explore rapid7 assets --limit 0 --export assets.csv
vulnmgmt integrations explore rapid7 devices --include-vulns --export server_full_details.csv

How the CLI produces reports

The primary entry point is vulnmgmt vuln export, which turns a scan/enrichment JSON result into a report and chooses the generator from the --format flag:

Terminal window
# Scan + enrich → JSON
vulnmgmt vuln scan apps.json --enrich --sources otx -o foxit.json


# JSON → Excel (default) or DOCX
vulnmgmt vuln export foxit.json -o foxit_report.xlsx
vulnmgmt vuln export foxit.json -o foxit_report.docx -f docx
  • -f xlsx (default) → _generate_excel_report() builds a workbook (including the enrichment sheets such as Executive Summary and All Vulnerabilities) from the JSON.
  • -f docx → _generate_docx_report() constructs a ReportMetadata and calls DOCXReportGenerator.generate_executive_summary().

Other commands emit reports too:

  • vulnmgmt process <inventory.csv> -o report.xlsx — one-shot process → workbook.
  • vulnmgmt vuln pipeline <apps.json> -o results.json --excel report.xlsx — the full convert → scan → enrich → score → report pipeline, optionally also writing Excel.
  • vulnmgmt versions <data.csv> -o version_report.xlsx — the version-spread workbook (see version_tracking.xlsx).