# Architecture And Design Rationale ## Objective Create one canonical incident system that records structured facts once and generates the required documentation and communication artifacts for engineering, security, executives, customers, regulators, auditors, and support teams. ## Reference Baseline The framework uses the requested source families and current public guidance as design input: - NIST SP 800-61r2 and the current NIST SP 800-61r3 Computer Security Incident Handling Guide: https://csrc.nist.gov/pubs/sp/800/61/r2/final and https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-61r3.pdf - NIST Cybersecurity Framework 2.0: https://www.nist.gov/cyberframework and https://nvlpubs.nist.gov/nistpubs/CSWP/NIST.CSWP.29.pdf - CISA Federal Government Cybersecurity Incident and Vulnerability Response Playbooks: https://www.cisa.gov/resources-tools/resources/federal-government-cybersecurity-incident-and-vulnerability-response-playbooks - FIRST CSIRT Services Framework: https://www.first.org/standards/frameworks/csirts/csirt_services_framework_v2.1 - ISO/IEC 27035 and ISO 22301 public overview material: https://www.iso.org/standard/44379.html and https://www.iso.org/standard/75106.html - MITRE ATT&CK and D3FEND: https://attack.mitre.org/matrices/ and https://d3fend.mitre.org/ - Google SRE incident response and postmortem culture: https://sre.google/workbook/incident-response/ and https://sre.google/workbook/postmortem-culture/ - PagerDuty Incident Response Documentation: https://response.pagerduty.com/ - Atlassian Statuspage incident templates: https://support.atlassian.com/statuspage/docs/incident-template-library/ - AWS Well-Architected Reliability Pillar: https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/welcome.html - Microsoft incident response overview: https://learn.microsoft.com/en-us/security/operations/incident-response-overview - Public postmortem patterns from Cloudflare and GitHub: https://blog.cloudflare.com/tag/post-mortem/ and https://github.blog/news-insights/company-news/oct21-post-incident-analysis/ NIST SP 800-61r2 was requested, but it has been superseded by SP 800-61r3. The framework retains the classic preparation, detection/analysis, containment, eradication, recovery, and post-incident phases while adding CSF 2.0-style governance and modern reliability practices. ## Design Decisions ### Single Canonical Incident Object All deliverables derive from one `Incident` object plus append-only child records: - Timeline events - Evidence items - Attachments - Impact assessments - Decisions - Communications - Tasks/action items - RCA findings - Regulatory assessments - Audit events This avoids inconsistent reports, repeated copy/paste, and drift between technical, executive, customer, and audit outputs. ### Extensible Category Taxonomy Incident categories are not a schema enum. Each category is a taxonomy record: - `category.id` - `category.name` - `category.family` - `category.tags` - `category.playbookBindings` - `category.requiredExtensions` This supports future categories without migrations. Examples: `data_corruption`, `vendor_outage`, `dns_incident`, `privacy_incident`, `emergency_maintenance`, or `enerflo_migration_data_integrity`. ### Lifecycle With Immutable Transitions Lifecycle state is mutable, but every transition is immutable. Default lifecycle: `draft -> open -> acknowledged -> investigating -> identified -> mitigating -> contained -> recovering -> monitoring -> resolved -> postmortem -> verified -> closed` Each transition records: - From state - To state - Actor - Timestamp and timezone - Reason - Evidence references - Approval references - Automation source if automated ### Audience-Specific Generation Layer Generators read the canonical model and render documents through templates. Templates are grouped by audience: - Engineering - Security/SOC - Executive - Customer - Status page - Internal chat/email - Regulatory/audit Each generator has a view policy that controls redaction, length, detail level, tone, and approval requirements. ### Evidence Is A First-Class System Evidence is immutable by default and versioned if corrected. Each evidence item includes SHA-256, file size, MIME type, collector, source, chain-of-custody, retention policy, confidentiality, related timeline events, and related systems/users. ### Security And Reliability Extensions Security and reliability are optional structured extensions on the same incident: - Security extension: threat actor, attack vector, kill chain, MITRE ATT&CK, D3FEND, IOCs, IOAs, CVEs, CVSS, compromised accounts, exfiltration assessment, detection rules, notification obligations. - Reliability extension: availability, latency, error rate, saturation, traffic, capacity, autoscaling, failover, rollback, SLO/SLI/SLA/error budget, deployment metadata. ### Blameless But Accountable Postmortems use blameless language and focus on system, process, tooling, and organizational contributors. Accountability is expressed through action items with owners, due dates, evidence, and verification methods. ## Component Architecture ```mermaid flowchart LR A["Incident Intake"] --> B["Canonical Incident Store"] B --> C["Timeline Engine"] B --> D["Evidence Store"] B --> E["Impact/RCA Engine"] B --> F["Communication Center"] B --> G["Report Generator"] B --> H["Audit Ledger"] I["Integrations"] --> A I --> C I --> D G --> J["Markdown/HTML/PDF/JSON/CSV"] F --> K["Slack/Teams/Email/Statuspage"] H --> L["Audit/Compliance Exports"] ``` ## Lifecycle Detail | State | Purpose | Required Before Exit | | --- | --- | --- | | Draft | Unconfirmed report or exercise | Initial category, reporter, affected environment | | Open | Incident record exists | Incident commander assigned | | Acknowledged | Team is aware | Severity, owner, initial timeline | | Investigating | Active diagnosis | Hypotheses, evidence capture, impact estimate | | Identified | Cause or likely cause known | Root cause hypothesis and mitigation plan | | Mitigating | Fix/containment underway | Change log and rollback plan | | Contained | Blast radius stopped | Containment evidence | | Recovering | Service/data restoration | Recovery plan, backup/restore evidence | | Monitoring | Fix deployed/restoration complete | Monitors, customer checks, residual risk | | Resolved | User impact ended | Resolution evidence and customer impact summary | | Postmortem | Learning phase | RCA, action items, decision log | | Verified | Corrective actions validated | Verification evidence | | Closed | Completed and archived | Approvals, retention policies, final exports | ## Roles - Incident Commander: owns coordination, state, urgency, handoffs. - Engineering Lead: owns technical diagnosis and recovery. - Security Lead: owns threat, forensics, containment, and security reporting. - Communications Lead: owns internal/customer/status updates. - Scribe: owns timeline, evidence references, and decision log. - Executive Sponsor: resolves tradeoffs and external notification decisions. - Legal/Privacy Approver: approves regulatory/customer language when needed. - Customer Success Owner: owns impacted customer handling. ## Supported Incident Categories The category matrix supports: cybersecurity, service outage, partial outage, infrastructure failure, cloud provider failure, network incident, DNS incident, authentication incident, database incident, API failure, deployment failure, performance degradation, capacity incident, data corruption, data loss, privacy incident, compliance incident, vendor incident, scheduled maintenance, emergency maintenance, disaster recovery, business continuity, internal operations, and customer escalation. ## UI Recommendations ### Incident Dashboard - Current severity/state, commander, duration, affected services, customer impact, next update due. - Clear phase indicators and required exit criteria. - Safe high-impact action prompts for public/customer notifications. ### Timeline - Ordered, filterable timeline with confidence, source, actor, automation flag, evidence links. - Collapsible correlated events and generated-from-log markers. ### Evidence Viewer - Immutable evidence cards with hash verification, classification, source, and chain-of-custody. - Preview common file types, but never render secrets by default. ### Report Generator - Audience selector. - Redaction preview. - Approval workflow. - Export to Markdown, HTML, PDF, JSON, CSV. ### Communication Center - Status page, Slack/Teams, email, executive update, and customer update views. - Approval gates for customer-facing and regulatory content. - Required next-update timestamp. ### Accessibility And Mobile - WCAG AA contrast. - Keyboard navigation. - Dark mode. - Timeline readable on mobile. - Audit/evidence screens optimized for dense scanning. ## Automation ### Ingestion - PagerDuty/Opsgenie incident creation. - Slack/Teams incident room creation. - GitHub/GitLab/Bitbucket PR and deployment correlation. - Jira/Linear/ServiceNow ticket creation. - Grafana/Prometheus/Datadog/Splunk/Elastic/Sentry/Honeycomb/OpenTelemetry alerts. - CloudWatch/Azure Monitor/GCP Monitoring events. ### Generation - Timeline generation from logs and chat. - Evidence hash/checksum calculation. - Draft customer/status/executive updates. - Suggested MITRE ATT&CK/D3FEND mappings. - Suggested RCA contributing factors. - Suggested action items with owners from code ownership and service ownership. ### Guardrails - Never auto-send customer/regulatory communications without approval. - Mark all generated text with source fields and confidence. - Require human validation for root cause, data exposure, customer impact, and notification obligations. ## Security And Governance - Role-based access control by incident sensitivity, customer, business unit, and evidence classification. - Field-level redaction for PII, secrets, tokens, keys, and regulated data. - Immutable audit ledger for state transitions, evidence access, exports, and approvals. - Retention policy per evidence item and incident type. - Legal hold support. - Chain-of-custody export for forensic evidence.