tool-finding-narrative-annotator

Tool Finding Narrative Annotator

Read related findings, weave them into a coherent per-domain story. Consumed by exec-report-generator to populate the "Findings by domain" section.

Context needs: artifact-stream, full-file

Inputs

• Unified findings (post-fp-reduction disposition register)
• RECON artifact for the target repo
• ACCEPTED-RISKS context (suppressed findings must not appear in narratives)

Output

• memory/narratives-<slug>.md

Markdown structure (one ## per domain):

# Narrative Annotations

## PII Flow
[3-8 paragraphs of prose. Citations as `<rule_id>` at `<file:line>`.]

## ML Edge Cases
[3-8 paragraphs.]

## NATS / Messaging Auth
[3-8 paragraphs.]

## Crypto Cross-File
[3-8 paragraphs.]

Four narrative domains

Findings may appear in multiple domains (e.g. a hardcoded LLM API key is both "secrets" and "ML edge cases").

1. PII flow

Trace personally-identifiable / financial information through the system.

Questions to answer:

• Where does PII enter the system? (endpoints, fields)
• Which stages store, transform, or forward it?
• Which stages could leak it? (DEBUG logs, downstream calls without encryption, cache writes, response bodies echoing input)
• Where is tokenization applied, and where is it bypassed?

Supporting rule prefixes: gitleaks.*.pan, semgrep.*.pii-log, semgrep.*.unencrypted-storage, business-logic.fraud.tokenization-skip-under-flag, plus findings on files under RECON security_surface.auth_paths + secrets_referenced.

2. ML edge cases

Questions:

• Where does the ML model run in this service?
• What features feed it (server-computed vs. client-controlled)?
• How are model artifacts loaded (integrity, provenance)?
• What happens when the model fails (fail-open vs. fail-closed)?
• Emulation modes reachable in production?

Supporting rule prefixes: business-logic.fraud.fail-open-scoring, ...feature-poisoning, ...emulation-mode-bypass, ...model-endpoint-confusion, model-hash-verify.ml.*, semgrep.llm-safety.*.