Findings Report Generator¶

The Findings Report Generator extension generates and publishes compliance and security reports to GitHub repositories. It can create overview reports and detailed per-version reports for specified finding types and components.

Configuration Example¶

findings_report:
  schedule: '0 2 * * *'              # daily at 2 AM
  successful_jobs_history_limit: 1
  failed_jobs_history_limit: 1
  mappings:
    - type: finding/malware
      component:
        component_name: acme.org/my-product
        ocm_repo_url: null
        time_range:
          days_from: -365          # Last 365 days
          days_to: 0
      github_repository: github.com/acme/security-reports
      branch: gh-pages
      filename: malware-report.md
      dirname: malware-reports
      auto_merge: false
      trigger_absent_scans: false
      report_to_saf: false
    - type: finding/vulnerability
      component:
        component_name: acme.org/my-product
        time_range:
          days_from: -90           # Last 90 days
          days_to: 0
      github_repository: github.com/acme/security-reports
      branch: main
      filename: vulnerability-overview.md
      dirname: vuln-reports
      auto_merge: true
      trigger_absent_scans: true
      report_to_saf: false

Top-Level Options¶

Option	Type	Default	Description
`schedule`	string	`0 2 * * *`	Cron schedule for running the cronjob (daily at 2 AM by default).
`successful_jobs_history_limit`	int	`1`	Number of successful job executions to retain in history.
`failed_jobs_history_limit`	int	`1`	Number of failed job executions to retain in history.
`mappings`	list	`[]`	Report configurations. See mapping fields below.

Mapping Fields¶

Each entry in the mappings list supports the following fields:

Option	Type	Required	Description
`type`	string	yes	Finding type to report on (e.g., `finding/malware`, `finding/vulnerability`).
`component`	object	yes	Component specification. See component fields below.
`github_repository`	string	yes	GitHub repository where report is published (e.g., `github.com/org/repo`).
`branch`	string	`gh-pages`	Target branch for report publication.
`filename`	string	`report.md`	Relative path for the overview report file.
`dirname`	string	`reports`	Relative path for detailed per-version reports directory.
`auto_merge`	bool	`false`	Automatically merge the pull request that updates the report.
`trigger_absent_scans`	bool	`false`	Create backlog items for missing scans.
`report_to_saf`	bool	`false`	Upload results to SAF API.

Component Fields¶

The component object contains:

Option	Type	Required	Description
`component_name`	string	yes	OCM component name to report on.
`ocm_repo_url`	string	no	Override default OCM repository lookup.
`time_range.days_from`	int	yes	Start of time range (negative = days in past).
`time_range.days_to`	int	yes	End of time range (0 = today).

Configuration Details¶

GitHub Repository¶

The target GitHub repository where reports are published. The extension creates a pull request with the updated report files.

Required permissions: The configured GitHub credentials (via secrets.github) must have write access to the target repository.

Branch Strategy¶

The branch field determines where reports are committed:

gh-pages (default): Suitable for GitHub Pages-hosted reports

branch: gh-pages

main or master: Suitable for repositories where reports are part of documentation

branch: main

Dedicated branch: Suitable for review workflows

branch: reports/automated

Report Structure¶

The extension generates two types of files:

Overview report (filename): Summary across all component versions
Detailed reports (dirname/): One file per component version with full finding details

Example structure:

reports/
├── malware-report.md              # Overview (filename)
└── malware-reports/               # Detailed reports (dirname)
    ├── 1.0.0.md
    ├── 1.1.0.md
    └── 1.2.0.md

Auto Merge¶

When auto_merge: true, the extension automatically merges the pull request that updates the report. This is useful for:

Automated compliance dashboards
Continuous reporting pipelines
Read-only report repositories

Recommendation: Only enable for repositories dedicated to reports, not repositories with manual review processes.

Trigger Absent Scans¶

When trigger_absent_scans: true, the extension creates backlog items for artefacts identified as missing scans during report generation. This ensures comprehensive coverage.

Use case: Detecting gaps in scanning coverage during audit preparation