Reports and remediation
Canonical report JSON, approval, deterministic exports, patch proposals, static rescans, and human-controlled GitHub pull requests.
Canonical first
Versioned Pydantic JSON is the report source of truth. UI views and every export render from the same revision. Agent prose never becomes an export without schema validation, evidence validation, and adjudication.
The report includes executive summary, coverage, architecture, trust boundaries, threat model, findings, tradeoffs, recommendations, remediation plan, SBOM reference, cost summary, and an evidence appendix.
Export pipeline
| Format | Derivation |
|---|---|
| JSON | canonical schema serialization |
| Markdown | deterministic renderer from JSON |
| Mermaid | approved constructs from canonical graph views |
| SVG / PNG | server-rendered Mermaid, sanitized before storage |
| DOCX | deterministic OOXML template |
| conversion from the verified DOCX |
Exports validate schema, links, diagram syntax, SVG safety, text extraction, pagination, and representative visual regressions. Format-specific failures are retryable without rerunning the audit.
Remediation flow
- A Developer or Analyst requests remediation for a confirmed finding.
- The Remediation Engineer proposes a bounded diff and identifies every touched file.
- The patch is applied in a disposable working copy.
- Static scanners rerun against the diff; builds and tests are not executed.
- An Analyst, Admin, or Owner reviews and approves the proposal.
- The connected GitHub App receives a short-lived, project-scoped write token and creates one branch and pull request.
- Hyperoru records pull-request state but never merges automatically.
Workflow changes require explicit approval
The GitHub App includes Workflow write permission, but Hyperoru adds it to the short-lived publication token only when an approved, validated patch changes .github/workflows/. Audits never receive write access.