OpenPAKT report writer for Detektor scan results

[meisterware-admin]

Overview

Introduce an OpenPAKT report writer responsible for generating structured security scan reports from Detektor findings.

The report writer converts normalized internal findings produced by the scanner pipeline into a report that conforms to the OpenPAKT report schema.

This report will serve as the primary output of Detektor and can be consumed by:

• CI systems
• security dashboards
• automated policy evaluation tools
• external reporting pipelines

The report writer ensures that Detektor outputs are interoperable with tools that understand the OpenPAKT specification.

---

Motivation

Detektor is designed to generate security findings that can be evaluated by CI systems and shared across tools using the OpenPAKT specification.

Without a dedicated report writer component:

• findings cannot be exported in a standard format
• CI systems cannot evaluate results consistently
• results cannot be shared across tools

A structured OpenPAKT report enables:

• deterministic CI pass/fail evaluation
• interoperability between scanners and tooling
• machine-readable security findings
• consistent reporting across environments

This component is responsible for producing the final output artifact of a Detektor scan.

---

Proposed Approach

Implement a report writer that converts normalized internal findings into a structured OpenPAKT report.

The report writer should:

1. Accept the collection of findings produced by the scanner.
2. Generate the required OpenPAKT report structure.
3. Populate report metadata and summary information.
4. Serialize the report as JSON.

High-level pipeline:

CLI
 ↓
Artifact Loader
 ↓
Rule Engine
 ↓
Findings
 ↓
OpenPAKT Report Writer
 ↓
detektor-report.json

The generated report should follow the OpenPAKT report structure, which includes:

schema_version
scan
target
summary
findings

Where:

• schema_version identifies the OpenPAKT version
• scan contains metadata about the scan execution
• target identifies the scanned repository or artifact
• summary provides severity counts and overall statistics
• findings contains the list of detected security issues

The output report should be written to a file such as:

detektor-report.json

---

Alternatives Considered

1. Output findings directly to the console

The scanner could output findings only as console logs.

However, console output is not suitable for CI automation or machine-readable analysis.

2. Use an existing reporting format (for example SARIF)

SARIF is widely used for static analysis tools.

However, OpenPAKT provides a format specifically designed for AI agent security findings and scenarios.

Future versions of Detektor may support exporting additional formats, but v0.1 should focus on OpenPAKT.

---

Risks and Trade-offs

Specification changes

If the OpenPAKT report schema evolves, the report writer may require updates.

This risk is mitigated by keeping the implementation aligned with the OpenPAKT version used by Detektor.

Incomplete metadata

Early versions of the scanner may not populate all metadata fields fully.

The implementation should focus on producing a valid and deterministic minimal report.

Output format rigidity

Supporting only one report format initially may limit integrations.

Additional export formats can be introduced in later versions.

---

Open Questions

• Should the report file name be configurable?
• Should the report be printed to stdout in addition to being written to a file?
• Should Detektor support multiple output formats in future versions?
• Should scan metadata include scanner version and runtime environment details?

---

Examples

Example CLI usage:

detektor scan ./repo

Example output file:

detektor-report.json

Example report structure:

{
  "schema_version": "0.1",
  "scan": {},
  "target": {},
  "summary": {},
  "findings": []
}

---

Next Steps

If this proposal is accepted:

1. Implement the OpenPAKT report writer component.
2. Map internal findings to the OpenPAKT report structure.
3. Generate summary information from findings.
4. Serialize the report as JSON.
5. Integrate the report writer into the scan pipeline.