Internal finding model for normalized security findings

[meisterware-admin]

Overview

Introduce a normalized internal finding model used by Detektor to represent detected security issues.

Detection rules executed by the rule engine will produce findings. These findings must be represented in a consistent internal format before they are written to an OpenPAKT report.

The internal finding model serves as the canonical structure used within the scanner pipeline to collect and manage detected issues.

This model will later be transformed into the OpenPAKT report format.

---

Motivation

Detektor detection rules may identify different types of security risks across various artifact types.

Without a normalized internal representation, findings generated by different rules could vary in structure and format.

A standardized internal finding model provides:

• a consistent structure for rule outputs
• easier aggregation of findings across rules
• simplified report generation
• clear mapping to the OpenPAKT report schema

This abstraction ensures the rule engine and report generation components remain loosely coupled.

---

Proposed Approach

Introduce an internal Finding object used by the rule engine and scanner pipeline.

The object should represent a detected issue in a structured and normalized way.

Example internal model:

Finding
- id
- type
- severity
- component
- description
- evidence

Where:

• id — unique identifier for the finding instance
• type — OpenPAKT taxonomy identifier (for example prompt_injection)
• severity — canonical severity level
• component — part of the system where the issue occurred
• description — explanation of the detected issue
• evidence — supporting context from the artifact or rule

The internal finding model should closely align with the structure expected by the OpenPAKT report schema so that serialization into the report format is straightforward.

---

Alternatives Considered

1. Allow each rule to produce custom finding structures

Rules could emit arbitrary data structures.

However, this would make report generation significantly more complex and increase the risk of inconsistent outputs.

2. Generate OpenPAKT findings directly from rules

Rules could directly produce OpenPAKT-compatible findings.

While possible, this tightly couples rules to the reporting format and reduces flexibility for internal processing.

Using a normalized internal finding model provides a clean separation of responsibilities.

---

Risks and Trade-offs

Model rigidity

If the internal model is too rigid, future extensions may require refactoring.

Designing the model with optional fields or extensibility can mitigate this risk.

Mapping complexity

Differences between the internal model and the OpenPAKT schema could require additional mapping logic.

Keeping the internal structure closely aligned with OpenPAKT helps reduce this risk.

---

Open Questions

• Should findings support additional metadata fields in v0.1?
• Should the internal model allow rule-specific metadata extensions?
• Should the model support source location information (for example file path or line number)?
• Should evidence be structured or represented as free-form text?

---

Examples

Example finding produced by a detection rule:

Finding
- id: finding-001
- type: prompt_injection
- severity: high
- component: agent.prompt
- description: Agent followed malicious instructions embedded in external content.
- evidence:
    summary: Tool call triggered by attacker-controlled prompt content.

The finding will later be included in the OpenPAKT report during report generation.

---

Next Steps

If this proposal is accepted:

1. Define the internal finding data structure.
2. Implement finding creation in the rule engine.
3. Aggregate findings during the scanning process.
4. Prepare mapping between internal findings and OpenPAKT report output.
5. Integrate findings into the report writer component.