Module: vvaharness/report

docs / modules / report

← all docs

Module: vvaharness/report

Role. The print shop. Enriches findings with CVSS/CWE/CMDB context, redacts secrets, and turns the Markdown report into SARIF 2.1.0.

Size. 5 files · ~1,708 LOC.


flowchart LR IN["Input\nFindings Markdown (+ cmdb.csv)"] --> ACT["Action\nEnrich with CVSS/CWE/CMDB context and redact sensitive values"] ACT --> VAL["Validation\nLuhn/IIN-gated redaction check at the write boundary"] VAL --> OUT["Output\nEnriched report.md + report.sarif (redacted)"]

This package turns raw findings into trustworthy paperwork. It computes standard severity scores (CVSS), attaches the canonical weakness names (CWE), factors in environment data from the CMDB, and — critically — redacts any secrets or personal data before they can appear in the report. It also emits the machine-readable SARIF file that other tools can ingest.

Explain-it-simply. The print shop that formats the final report, stamps severities, and blacks out anything sensitive before printing.

Data-flow (this module)

flowchart LR MD[(findings markdown)] --> EN[enrich.py<br/>CVSS env + CMDB] CMDB[(cmdb.csv)] --> EN EN --> RED[redact.py<br/>mask secrets/PII] RED --> OUT[report.md + report.sarif] CVSS[cvss.py] -.-> EN CWE[cwe.py] -.-> EN

Technical details

flowchart LR IN["Input\nFindings Markdown (+ cmdb.csv)"] --> ACT["Action\nEnrich with CVSS/CWE/CMDB context and redact sensitive values"] ACT --> VAL["Validation\nLuhn/IIN-gated redaction check at the write boundary"] VAL --> OUT["Output\nEnriched report.md + report.sarif (redacted)"]

enrich.py (~1,130 LOC) reads a findings Markdown carrying CVSS base vectors, applies environmental/temporal scoring and CMDB lookup (load_cmdb_csv, lookup_app), and renders the enriched MD→SARIF. cvss.py is the CVSS 3.1 base calculator (score, rating); cwe.py maps CWE ids to canonical MITRE names (cwe_name, cwe_for, cwe_label). redact.py performs Luhn/IIN-gated card masking, validated SSN masking, and keyword-gated credential masking at the write boundary (redact, redact_counts, redact_tree).

File map (quick scan)

File LOC Purpose
report/__init__.py 15 —
report/cvss.py 83 CVSS 3.1 base-score calculator (FIRST.org spec §7).
report/cwe.py 146 CWE id → canonical MITRE name. Single source of truth for MD rendering,
report/enrich.py 1128 Reads a findings markdown that already contains CVSS 3.1 base vectors,
report/redact.py 336 Sensitive-data redaction for emitted reports (MD + SARIF).

Files & functions, explained

Every class and function below has a one-line plain-English note — readable whether you write code or not. _name marks an internal helper.

report/__init__.py

15 LOC. Utility / support module.

No top-level classes or functions (package init / constants).

report/cvss.py

83 LOC. CVSS 3.1 base-score calculator (FIRST.org spec §7).

Functions - _roundup1() — (internal helper) Provides the “roundup1” logic. - score() — Checks / decides the score value. - rating() — Provides the “rating” logic.

report/cwe.py

146 LOC. CWE id → canonical MITRE name. Single source of truth for MD rendering,

Functions - cwe_name() — Provides the “weakness type name” logic. - cwe_for() — Provides the “weakness type for” logic. - cwe_label() — Provides the “weakness type label” logic.

report/enrich.py

1128 LOC. Reads a findings markdown that already contains CVSS 3.1 base vectors,

Classes - AppInfo — Represents the “AppInfo” data/behaviour used in this file. - cr() — Provides the “confidentiality-requirement” logic. - ir() — Provides the “integrity-requirement” logic. - ar() — Provides the “availability-requirement” logic. - mav() — Provides the “mav” logic. - env_summary() — Provides the “environment settings summary” logic. - VsvsResult — Represents the “VsvsResult” data/behaviour used in this file. - Finding — Represents the “candidate issue” data/behaviour used in this file.

Functions - _yes() — (internal helper) Provides the “yes” logic. - _nz() — (internal helper) Provides the “not-empty” logic. - normalize_app_id() — Reads and cleans up the app identifier step. - _csv_col() — (internal helper) Provides the “csv col” logic. - _cmdb_enrichment_differs() — (internal helper) Provides the “asset inventory enrichment differs” logic. - load_cmdb_csv() — Looks up / reads the asset inventory csv step. - _pick() — (internal helper) checks / decides the pick value. - _merge_with_parent() — (internal helper) adds detail to the with parent step. - lookup_app() — Looks up / reads the app value. - _cia() — (internal helper) Provides the “confidentiality/integrity/availability” logic. - _req() — (internal helper) Provides the “requirement” logic. - _temporal_e() — (internal helper) Provides the “temporal e” logic. - _temporal_rl() — (internal helper) Provides the “temporal remediation-level” logic. - _temporal_rc() — (internal helper) Provides the “temporal report-confidence” logic. - round_up1() — Provides the “round up1” logic. - parse_vector() — Reads and cleans up the vector value. - cvss31_base_score() — Provides the “cvss31 base score” logic. - qualitative() — Provides the “qualitative” logic. - _env_vector() — (internal helper) Provides the “environment settings vector” logic. - vsvs_score() — Provides the “environment-adjusted severity score” logic. - _contains_any() — (internal helper) Provides the “contains any” logic. - offensive_priority_for() — Provides the “offensive priority for” logic. - compute_offensive_priority() — Provides the “compute offensive priority” logic. - annotate_md_cvss_vsvs() — Adds detail to the Markdown report severity score environment-adjusted severity step. - annotate_md_offensive() — Adds detail to the Markdown report offensive step. - parse_findings() — Reads and cleans up the candidate issues value. - _driver_rules() — (internal helper) runs the rules value. - _cwe_taxonomy() — (internal helper) Provides the “weakness type taxonomy” logic. - _sarif_level() — (internal helper) Provides the “machine-readable report level” logic. - _security_severity() — (internal helper) Provides the “security severity” logic. - _cvss_rating() — (internal helper) Provides the “severity score rating” logic. - generate_sarif() — Provides the “generate machine-readable report” logic. - md_to_sarif() — Provides the “Markdown report to machine-readable report” logic. - enrich() — Adds detail to the enrich value. - main() — Runs the main value.

report/redact.py

336 LOC. Sensitive-data redaction for emitted reports (MD + SARIF).

Functions - _luhn() — (internal helper) Provides the “luhn” logic. - _cc_network() — (internal helper) Provides the “cc network” logic. - _ssn_valid() — (internal helper) Provides the “ssn valid” logic. - _bearer_credential() — (internal helper) Provides the “bearer credential” logic. - _redact_impl() — (internal helper) hides sensitive data in the impl value. - redact() — Hides sensitive data in the secret hiding value. - redact_counts() — Hides sensitive data in the counts value. - redact_tree() — Hides sensitive data in the tree value.


See also: HLD · LLD · Data Flow · module index.