Principle:Protectai Modelscan Scan Report Generation
| Knowledge Sources | |
|---|---|
| Domains | ML_Security, Reporting |
| Last Updated | 2026-02-14 12:00 GMT |
Overview
A pluggable reporting system that transforms raw scan results into human-readable or machine-parseable output formats for security review and automated processing.
Description
Scan Report Generation addresses the need to present security findings in formats appropriate for different consumers. Security engineers need rich, color-coded terminal output for interactive review. CI/CD pipelines need structured JSON for automated decision-making. Custom integrations may need entirely different formats (e.g., SARIF, CSV, or webhook payloads).
The principle separates result aggregation from result presentation. The scanning engine produces a structured results dictionary (summary, issues, errors, skipped files), and the reporting layer transforms this data into the desired output format. Report modules are loaded dynamically via fully-qualified class paths, allowing users to plug in custom reporters without modifying the scanning engine.
Usage
Apply this principle when:
- Reviewing scan results interactively in a terminal (console report)
- Integrating scan results into automated pipelines (JSON report)
- Building custom integrations that consume scan results (custom report module)
- Exporting findings to files for archival or audit purposes
Theoretical Basis
The reporting system follows the Strategy pattern: an abstract base class defines the interface, and concrete implementations provide format-specific behavior. The strategy is selected at runtime via configuration:
# Pseudo-code for pluggable reporting
class Report(ABC):
@staticmethod
def generate(scan, settings) -> Optional[str]:
"""Transform scan results into output format."""
class ConsoleReport(Report):
"""Rich-formatted terminal output with severity colors."""
class JSONReport(Report):
"""Structured JSON output, optionally written to file."""
# Dynamic loading via configuration
report_class = load_class(settings["reporting"]["module"])
report_class.generate(scan=scanner, settings=report_settings)
The results dictionary produced by _generate_results() provides a normalized data contract:
# Result dict structure
{
"summary": {
"total_issues": int,
"total_issues_by_severity": {"CRITICAL": int, "HIGH": int, ...},
"scanned": {"total_scanned": int, "scanned_files": [str]},
"skipped": {"total_skipped": int, "skipped_files": [dict]},
"input_path": str,
"modelscan_version": str,
"timestamp": str,
},
"issues": [{"description": str, "operator": str, "module": str, ...}],
"errors": [{"error": str, ...}],
}