ADR 0002: Report Format Availability Policy

Status

Accepted

Context

The Vulnerability Scanner handles multiple report formats (XML, PDF, HTML). The “Sent Reports” overview is responsible for managing visual reports distributed to contact persons.

A strict validation logic might enforce that for every XML report (used for analytics), a corresponding visual report (PDF or HTML) must exist, or that if one visual format exists, the other must as well.

However, in many operational workflows: * XML reports may be generated solely for backend analytics or machine ingestion, without any intent to distribute them to end-users. * A user might choose to generate/upload only a PDF, or only an HTML file, depending on their preference or specific requirements. * Enforcing the presence of alternate formats would flag valid, intentional configurations as errors, creating noise and confusion for administrators.

Decision

  • Single Visual Format Logic: We will NOT treat the absence of a specific visual format (PDF or HTML) as an error, provided at least one visual format exists if the report is intended for distribution.

  • Managed Scope: The Sent Reports overview manages uploaded visual reports. It does not enforce a 1:1 mapping with XML analytics files.

  • Flexibility: The system must support scenarios where only a PDF, or only an HTML file, is present.

  • XML Dependency: While visual reports are flexible, an underlying XML (or equivalent structured data) is typically required for metadata extraction (finding IPs, etc.), so a “Missing XML” alert is still valid for orphan PDF/HTML files if analytics are expected. However, the reverse (XML without PDF/HTML) is a valid “analytics-only” state and should not clutter the Sent Reports view unless explicitly configured otherwise.

Consequences

  • Reduced Noise: Administrators will not see “Missing HTML” alerts for PDF-only workflows, and vice versa.

  • Clearer Scope: The Sent Reports view focuses on what is available for sending, rather than policing what could be available.

  • Analytics Separation: Allows for a cleaner separation between reports meant for automated ingestion (XML only) and those meant for human consumption.