docs(security): define the initial threat model

[back1ash]

Summary

Document the initial security model for processing untrusted API specifications and GitHub events. Identify assets, actors, trust boundaries, abuse cases, mitigations, verification requirements, and accepted residual risks before production implementation begins.

Scope

Cover malformed YAML/JSON and parser vulnerabilities; nesting, aliases, oversized input and resource exhaustion; recursive, cyclic, escaping or remote $ref; SSRF, path traversal and unintended egress; webhook and installation-token handling; untrusted specification and repository metadata; report injection and disclosure; cross-repository leakage; replay, duplicate delivery and stale results; and artifact integrity, retention, deletion and visibility changes.

Acceptance criteria

• Protected assets, threat actors, entry points, and trust boundaries are documented.
• Each threat includes impact, priority, mitigation, and residual risk.
• Parser and resolver limits cover size, depth, time, references, cycles, and diagnostic volume.
• External-reference and network-egress policy is explicit.
• Token permissions, lifetime, storage, redaction, and rotation expectations are documented.
• Untrusted content is treated only as data throughout parsing and rendering.
• Report visibility, retention, deletion, and repository-visibility-change behavior are defined.
• Required security tests and visible failure behavior are listed.
• Open risks have an owner and review point.
• The designated security owner reviews the document.

Dependencies

• Current product requirements and proposed data flow.
• Preliminary validator candidates.
• GitHub fork feasibility findings as they become available.

Non-goals

• Implementing mitigations.
• Performing a penetration test or external audit.
• Claiming compliance with a certification framework.
• Accepting material residual risk without owner approval.