---
# IR Writing Guidelines for AI Assistants
#
# This file contains two distinct components with different authorship and licensing:
#
# 1. WRITING GUIDELINES (this file's primary content)
#    Author: Lenny Zeltser
#    License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
#    These guidelines capture writing best practices for incident response reports.
#
# 2. IR REPORT TEMPLATE (referenced, not contained here)
#    Authors: Lenny Zeltser and Elisabetta Tiani, with input from Daniel Trauner
#    Attribution: Originally developed at Axonius Inc.
#    License: CC BY 4.0
#    Location: public/media/archive/cybersecurity-privacy-incident-report-template.md
#
# The template license applies to the template itself; reports you create are yours.
#
# URL PATHS: All paths in this file are relative to baseUrl.
# Example: "/media/archive/file.md" resolves to "https://zeltser.com/media/archive/file.md"

# Metadata for this guidelines file
title: "IR Writing Guidelines for AI Assistants"
version: "1.4.0"
author: "Lenny Zeltser"
date: "2026-01-13"
license: "Copyright (c) 2026 Lenny Zeltser"
baseUrl: "https://zeltser.com"
articleUrl: "/incident-response-report-template"

# Metadata for the associated IR Report Template (separate file, separate authorship)
template:
  title: "Cybersecurity and Privacy Incident Report Template"
  authors: "Lenny Zeltser and Elisabetta Tiani, with input from Daniel Trauner"
  attribution: "Originally developed at Axonius Inc."
  license: "Copyright (c) 2026 Lenny Zeltser"
  downloadUrl: "/media/archive/cybersecurity-privacy-incident-report-template.md"
  wordTemplateUrl: "/media/archive/cybersecurity-privacy-incident-report-template.docx"
  exampleReportUrl: "/media/docs/cybersecurity-incident-report-example.docx"

# MCP Server Metadata
mcp:
  toolPrefix: "ir"
  privacyStatement: "This server never requests your incident notes and instructs your AI to keep them local. The IR tools return guidelines to your AI."
  fallbackUrl: "https://zeltser.com/incident-response-report-template"

# Writing Guidelines
guidelines:
  fiveElements:
    - name: "Information"
      principles:
        - "Answer what readers want to know, not what you want to tell them"
        - "Include all necessary details: who, what, when, where, why, how"
        - "Balance technical depth with business relevance"
        - "Teaching orientation: explain 'why' and 'how', not just 'what'"

    - name: "Tone"
      principles:
        - "Professional but approachable"
        - "Confident without being arrogant"
        - "Helpful without being condescending"
        - "Collaborative, not combative"
        - "Critique processes, not people"
        - "Include what went well, not just what went wrong"
        - "No FUD tactics — use business justification, not fear"

    - name: "Words"
      principles:
        - "Delete words whose absence doesn't change meaning"
        - "Avoid passive voice — it leads to ambiguity"
        - "Be specific: use numbers, not 'some' or 'many'"
        - "Adapt terminology to your audience — technical precision for practitioners, plain language for executives"
        - "Define technical terms on first use for mixed audiences"
        - "Avoid buzzwords that obscure meaning (leverage, robust, holistic)"
        - "Keep sentences under 15 words when possible"

    - name: "Structure"
      principles:
        - "Lead with the most important point in each section"
        - "Use frameworks, numbered lists, and clear organization"
        - "Include headings for scanability"
        - "Break long paragraphs into shorter ones"
        - "Executive summary must stand alone"
        - "Maintain flow: sentences should connect ideas, paragraphs should develop thoughts"
        - "Avoid choppy, bullet-point-like prose where each sentence stands in isolation"
        - "Avoid one-sentence paragraphs unless spotlighting a key point"

    - name: "Look"
      principles:
        - "Use consistent formatting throughout"
        - "Tables for structured data (action items, timelines)"
        - "Err on the side of simplicity"
        - "Well-formatted reports are more likely to be read"

  sentenceRules:
    - rule: "Keep sentences under 15 words when possible"
      note: "Shorter sentences are easier to parse under stress"
    - rule: "Delete words whose absence doesn't change meaning"
      example:
        bad: "It is important to note that the attacker gained access"
        good: "The attacker gained access"
    - rule: "Avoid passive voice — it leads to ambiguity"
      example:
        bad: "The server was compromised"
        good: "The attacker compromised the server"
    - rule: "Be specific with numbers"
      example:
        bad: "Several servers were affected for many hours"
        good: "3 servers were affected for 14 hours"
    - rule: "Adapt terminology to your audience"
      note: "Technical terms are appropriate for technical readers; explain or replace for executives"
      example:
        bad: "The threat actor leveraged a zero-day to pivot laterally"
        good: "The attacker used an unpatched vulnerability to access additional servers"

  paragraphRules:
    - rule: "Place your most important point at the beginning"
    - rule: "Split long paragraphs for easier skimming"
    - rule: "Avoid one-sentence paragraphs unless spotlighting a key point"
    - rule: "Maintain flow: sentences should connect ideas, not stand in isolation"
    - rule: "Delete paragraphs that don't contribute to the flow"

  toneRules:
    - rule: "Be collaborative, not combative"
    - rule: "Focus on processes and systems, not individuals"
    - rule: "No FUD tactics — justify with business impact, not fear"
    - rule: "Be confident without being arrogant"
    - rule: "Include positive findings — what worked well"
    - rule: "Frame lessons as improvement opportunities"

  executiveSummaryRules:
    - rule: "Must make sense to non-technical executives"
    - rule: "Connect findings to business relevance: risks, compliance, costs"
    - rule: "Keep to one paragraph (150 words max)"
    - rule: "Use concrete statements with numbers"
    - rule: "Must stand alone if distributed separately"
    - rule: "Bridge technical and business perspectives"
    - rule: "Connect findings to business context"
      note: "Reference risks, compliance requirements, metrics, or contractual obligations"
    - rule: "Use concrete statements — they build more trust than abstract language"
      note: "Research shows specific language communicates truth more effectively"
    - rule: "Use bullet points for scannability"
    - rule: "Answer 'so what?' for every fact and conclusion"
      note: "Executives think in terms of actions and business impact"

# Required fields for completeness checking
# Used by ir_check_completeness tool
requiredFields:
  - "timeline"
  - "affected_systems"
  - "root_cause"
  - "actions_taken"
  - "business_impact"
  - "what_went_well"
  - "third_party_involvement"
  - "data_exposure"

# Clarifying Questions for Missing Sections
# Used by ir_check_completeness to identify gaps
clarifyingQuestions:
  timeline:
    - "When was the incident first detected?"
    - "When did the incident actually occur (if different from detection)?"
    - "How long did the incident last before containment?"
  affected_systems:
    - "Which systems, applications, or data were affected?"
    - "How many users or customers were impacted?"
    - "Was any sensitive data exposed or exfiltrated?"
  root_cause:
    - "What was the root cause of the incident?"
    - "How was the root cause determined?"
    - "Were there contributing factors (missing patches, misconfigurations)?"
  actions_taken:
    - "What immediate containment actions were taken?"
    - "What remediation steps have been completed?"
    - "Who was notified (internal teams, customers, regulators)?"
  business_impact:
    - "What was the business impact (downtime, data loss, financial)?"
    - "Were any compliance obligations triggered?"
    - "What is the current operational status?"
  what_went_well:
    - "What security controls worked as intended?"
    - "How was the incident detected, and what enabled rapid detection?"
    - "Which response actions were particularly effective?"
    - "What processes or training helped limit the impact?"
  third_party_involvement:
    - "Were any third parties (vendors, partners, customers) affected?"
    - "What notification obligations exist (contractual, regulatory, NDA)?"
    - "Have affected third parties been notified?"
    - "Is coordination with third parties required for remediation?"
  data_exposure:
    - "Was any PII or regulated data exposed or exfiltrated?"
    - "What specific data types were affected (names, financial, health, credentials)?"
    - "Which regulatory frameworks apply (GDPR, CCPA, HIPAA, PCI-DSS)?"
    - "What is the scope of exposure (number of records, individuals affected)?"

# Related Articles
relatedArticles:
  - url: "/good-incident-reports"
    title: "How to Write Good Incident Response Reports"
    relevance: "Full methodology and video presentation"
  - url: "/writing-tips-for-it-professionals"
    title: "Writing Tips for IT Professionals"
    relevance: "Comprehensive writing cheat sheet"
  - url: "/executive-summary-for-security-assessment-report-tips"
    title: "Write a Strong Executive Summary"
    relevance: "Detailed executive summary guidance"
  - url: "/security-assessment-report-as-critique"
    title: "Security Assessment Report as Critique"
    relevance: "Tone guidance for sensitive reports"
  - url: "/cybersecurity-writing-mistakes"
    title: "Top 10 Cybersecurity Writing Mistakes"
    relevance: "Common pitfalls to avoid"

# Voice Guidelines
# Prescriptive style guidance capturing the author's distinctive writing approach
voiceGuidelines:
  description: "Style guidance for writing in a clear, professional voice"

  doUse:
    - "Direct, practical language that gets to the point"
    - "'such as' (not 'like') for introducing examples"
    - "Teaching orientation — explain 'why' and 'how', not just 'what'"
    - "Business terms alongside technical terms to bridge audiences"
    - "Specific numbers over vague quantities ('3 servers' not 'several servers')"
    - "Active voice for clarity and accountability"

  avoid:
    - "Emojis (unless organizational culture expects them)"
    - "FUD tactics — justify with business impact, not fear"
    - "Jargon that obscures meaning for the intended audience"
    - "Passive voice (causes ambiguity about who did what)"
    - "Phrases that sound like marketing copy ('Here's the thing', 'The cool part?')"
    - "Over-the-top validation or excessive praise"
    - "Sounding superior or condescending to colleagues"
    - "One-sentence paragraphs (except to spotlight key points)"

  tone:
    - "Professional but approachable"
    - "Confident without arrogance"
    - "Collaborative, not combative"
    - "Critique processes and systems, not people"
    - "Acknowledge what went well, not just problems"

  examples:
    - principle: "Critique processes, not people"
      bad: "The user's negligent password practices directly caused this breach"
      good: "Password reuse between personal and corporate accounts enabled the initial compromise"
      note: "Focus on the process gap (password policy), not the individual"
    - principle: "No FUD tactics"
      bad: "This terrifying breach could have resulted in catastrophic, company-ending losses"
      good: "The attempted wire fraud of $847,000 was blocked; no financial loss occurred"
      note: "State facts and actual impact without emotional language"
    - principle: "Include what went well"
      bad: "Our security completely failed to prevent this attack"
      good: "EDR detection triggered within 17 minutes of encryption starting, enabling rapid containment"
      note: "Acknowledge effective controls alongside gaps"
    - principle: "Be collaborative, not combative"
      bad: "IT's failure to implement geo-blocking was inexcusable"
      good: "Geographic access restrictions were not configured; this has been added as a remediation item"
      note: "Frame as improvement opportunity, not blame"

# Review Guidance
# For providing constructive critique of existing IR reports
# Used by ir_review_report tool
reviewGuidance:
  purpose: >
    Guidance for providing constructive critique of existing IR reports.
    The goal is to help improve the report, not to judge the author.

  feedbackStructure:
    - "Start with what the report does well — identify specific strengths"
    - "Identify areas for improvement with concrete, actionable suggestions"
    - "Reference specific sections and quote text when providing feedback"
    - "Offer alternatives or examples, not just criticisms"
    - "Prioritize feedback by impact on the report's effectiveness"
    - "Distinguish between critical issues and minor improvements"

  reviewerMindset:
    - "You are helping improve the report, not judging the author"
    - "Assume good intent — gaps may reflect incomplete information, not carelessness"
    - "The author wrote under time pressure during a stressful incident"
    - "Focus on the document's effectiveness for its intended audience"
    - "Consider what information the author might not have had access to"

  feedbackTone:
    - "Use collaborative language ('consider', 'you might', 'this could be strengthened by')"
    - "Avoid judgmental phrases ('you failed to', 'this is wrong', 'obviously')"
    - "Frame gaps as opportunities ('adding X would help readers understand Y')"
    - "Acknowledge constraints ('if this information is available, including it would...')"

# Article Key Points
# Actionable guidance extracted from related articles
articleKeyPoints:
  goodIncidentReports:
    title: "From: How to Write Good Incident Response Reports"
    points:
      - "Write with readers in mind — address questions they want answered, not what you want to say"
      - "Effective reports require empathy with readers' needs and expectations"
      - "Succinct writing demands extra effort but significantly enhances communication"
      - "Balance technical details with business impact explanations"
      - "Templates and checklists maintain clarity under stress"
      - "Tone influences cooperation and perception within the organization"
      - "Put key takeaways first — respects readers' time and attention"
      - "Visual appeal affects reader engagement and willingness to read"
      - "Lessons learned must be actionable — assign responsibilities"

  critiqueNotCriticism:
    title: "From: Security Report as Critique, Not Criticism"
    points:
      - "Write as critique (well-rounded assessment) not criticism (fault-finding)"
      - "Comment on processes and organizational structure, not individuals"
      - "Angry readers ignore key messages — focus on situation, not person"
      - "Acknowledge positive findings — what's working, not just gaps"
      - "Positive reinforcement is often more effective than negative in changing behavior"
      - "Avoid personalizing identified issues"

  writingMistakes:
    title: "From: Top 10 Cybersecurity Writing Mistakes"
    points:
      - "Structure, look, words, tone, and information work together"
      - "All five elements must align to capture and hold reader attention"
      - "Common mistakes span all five areas — check each systematically"

  executiveSummaryTips:
    title: "From: Write a Strong Executive Summary"
    points:
      - "Most readers only see the executive summary — put key takeaways there"
      - "Must make sense to non-technical audience while holding up to technical scrutiny"
      - "Connect to business: risks, compliance, metrics, contractual obligations"
      - "Keep to one page maximum"
      - "Concrete statements build trust — avoid 'some' or 'many'"

  writingTipsForIT:
    title: "From: Writing Tips for IT Professionals"
    points:
      - "Craft text knowing some readers will only skim"
      - "Delete words whose absence doesn't change meaning"
      - "Avoid semicolons/parentheses — break into separate sentences"
      - "Maintain parallelism across headings and list elements"
      - "Include at least one paragraph between two headings"
      - "Craft captions that guide readers to conclusions"
      - "Refer to every figure and appendix from main text"

# Section Review Criteria
# Used by ir_review_draft tool for section-specific feedback
sectionReviewCriteria:
  executive_summary:
    checkFor:
      - "Understandable to non-technical executives"
      - "Connects to business relevance (risks, compliance, impact)"
      - "Under 150 words"
      - "Uses concrete numbers, not vague terms"
      - "Stands alone without requiring rest of report"
      - "Key takeaways appear in first sentences"
    commonIssues:
      - "Too technical — uses jargon executives won't understand"
      - "Too long — exceeds one page"
      - "Too vague — uses 'some', 'many', 'several' instead of numbers"
      - "Missing business context — only describes technical details"

  timeline:
    checkFor:
      - "Clear chronological sequence with specific dates/times"
      - "Includes timezone information"
      - "Distinguishes between when events occurred vs. when discovered"
      - "Uses active voice to clarify who did what"
    commonIssues:
      - "Vague timing ('recently', 'last week')"
      - "Missing timezone"
      - "Passive voice obscures responsibility"
      - "Gaps in timeline not acknowledged"

  root_cause:
    checkFor:
      - "Explains 'why' not just 'what'"
      - "Distinguishes root cause from symptoms"
      - "Describes how root cause was determined (evidence)"
      - "Avoids blaming individuals"
    commonIssues:
      - "Describes symptoms as root cause"
      - "Blames individuals rather than processes"
      - "No evidence for root cause determination"
      - "Multiple possible causes without prioritization"

  actions_taken:
    checkFor:
      - "Specific actions with who performed them"
      - "Chronological or logical ordering"
      - "Distinguishes containment from remediation from recovery"
      - "Includes both successful and unsuccessful attempts"
    commonIssues:
      - "Vague actions ('addressed the issue')"
      - "Missing attribution (who did what)"
      - "Only lists successful actions"
      - "No distinction between phases of response"

  lessons_learned:
    checkFor:
      - "Actionable recommendations with assigned owners"
      - "Each action has an expected completion date or timeframe"
      - "Actions prioritized by urgency (immediate, short-term, long-term)"
      - "Acknowledges what went well, not just gaps"
      - "Focuses on processes and systems, not individuals"
      - "Prioritized by impact"
    commonIssues:
      - "Generic lessons without specific actions"
      - "No ownership assigned"
      - "Missing timelines or target dates"
      - "Only negative findings"
      - "Blames individuals"

  business_impact:
    checkFor:
      - "Quantified where possible (systems, users, records, hours, cost)"
      - "Includes both confirmed and potential impact"
      - "Addresses multiple stakeholder concerns"
      - "Uses business terminology"
    commonIssues:
      - "Technical impact only (no business translation)"
      - "Vague quantities"
      - "Missing potential/ongoing impact"
      - "Only worst-case without context"

  what_went_well:
    checkFor:
      - "Identifies specific controls or processes that worked"
      - "Quantifies effectiveness where possible (detection time, containment speed)"
      - "Acknowledges team actions that limited impact"
      - "Balanced with improvement areas (not defensive)"
    commonIssues:
      - "Omitted entirely — report is only negative findings"
      - "Too vague ('our team responded well')"
      - "Defensive tone rather than objective assessment"
      - "Not connected to lessons learned"

  third_party:
    checkFor:
      - "Identifies all affected third parties"
      - "Documents notification status and timeline"
      - "Addresses contractual and regulatory obligations"
      - "Outlines coordination requirements"
    commonIssues:
      - "Third parties not identified until late in investigation"
      - "Notification obligations overlooked"
      - "No documentation of what was shared with third parties"
      - "Missing follow-up requirements"

  data_exposure:
    checkFor:
      - "Specific data types identified (not just 'sensitive data')"
      - "Scope quantified (records, individuals)"
      - "Regulatory implications addressed"
      - "Distinguishes confirmed vs. potential exposure"
    commonIssues:
      - "Vague descriptions ('some data may have been accessed')"
      - "Regulatory requirements not identified"
      - "Scope not quantified"
      - "No distinction between accessed vs. exfiltrated"

# Complex Incident Guidance
# For multi-day or multi-phase incidents
complexIncidentGuidance:
  principles:
    - "Structure timeline by phase: initial access, persistence, lateral movement, action on objective"
    - "Distinguish attacker activity timeline from investigation/response timeline"
    - "For ongoing investigations, clearly mark what is confirmed vs. under investigation"
    - "Document dwell time (time from initial access to detection) separately from response time"
    - "For multi-day incidents, use a summary timeline in executive summary with detailed timeline in body"

  incidentTypeConsiderations:
    businessEmailCompromise:
      - "Document reconnaissance period separately from fraud attempt"
      - "Identify all accounts with access to sensitive communications"
      - "Check for inbox rules, forwarding, and OAuth app grants"
      - "Assess whether attacker knowledge suggests prior access"
    ransomware:
      - "Document encryption start time, detection time, and containment time"
      - "Distinguish between encrypted systems and systems at risk"
      - "Address data exfiltration separately from encryption"
      - "Document backup status and recovery timeline"
    dataExfiltration:
      - "Quantify data volume and timespan of exfiltration"
      - "Identify staging locations and exfiltration methods"
      - "Distinguish between accessed, copied, and confirmed exfiltrated"
      - "Document what data the attacker could have accessed vs. what they actually took"
    insiderThreat:
      - "Document authorization levels and access patterns"
      - "Distinguish between policy violation and malicious intent"
      - "Address HR and legal coordination requirements"
      - "Handle attribution carefully to protect ongoing investigations"
    supplyChainCompromise:
      - "Document the vendor/software involved and its access scope"
      - "Identify all systems that received compromised updates"
      - "Coordinate disclosure timeline with vendor"
      - "Address downstream customer notification requirements"

# ============================================================================
# AI-Native Guidance (v2.0)
# ============================================================================
# The following sections provide semantic guidance for AI tools to analyze
# user content locally, rather than sending it to the server for regex-based
# analysis. This improves both privacy (user data stays local) and efficacy
# (AI semantic understanding vs. keyword matching).
#
# These sections are used by the ir_load_context tool, which returns this
# guidance to the AI tool. The AI then applies its own reasoning to analyze
# user notes against these semantic descriptions.
# ============================================================================

# Field Guidance for Completeness Checking
# Each field includes semantic descriptions that teach the AI what to look for,
# rather than keywords to match. The AI can detect implied information, synonyms,
# and contextual coverage that keyword matching would miss.
fieldGuidance:
  - id: timeline
    displayName: Incident Timeline
    purpose: >
      Establishes when events occurred, enabling readers to understand the
      sequence and duration of the incident. Critical for regulatory reporting
      deadlines and post-incident analysis.
    whatIndicatesPresence:
      - Specific dates and times (not vague references like "recently")
      - Duration information (how long the attack was active)
      - Sequence of events from initial access to containment
      - When alerts fired or anomalies were first noticed
      - Gap between actual compromise and detection
    commonProblems:
      - Vague timeframes ("last week", "recently") instead of specific dates
      - Missing the gap between initial compromise and detection
      - Timeline stops at detection without covering response milestones
      - No distinction between when incident occurred vs. when discovered
    clarifyingQuestions:
      - When was the incident first detected?
      - When did the incident actually begin (if different from detection)?
      - What is the timeline of key response milestones?
      - How long was the attacker in the environment before detection?
    exampleGood: >
      The attacker gained initial access on January 15, 2025 at 14:32 UTC via
      a phishing email. Lateral movement to the file server occurred on January 17.
      The security team detected the activity on January 19 at 09:15 when EDR
      alerts fired. Containment was completed by January 19 at 18:00.
    examplePoor: >
      The incident happened sometime last week. We found out about it recently.

  - id: affected_systems
    displayName: Affected Systems
    purpose: >
      Documents what was compromised, helping stakeholders understand the scope
      and prioritize remediation. Essential for insurance claims and regulatory filings.
    whatIndicatesPresence:
      - Specific system names, IP addresses, or hostnames
      - Count of affected servers, workstations, or accounts
      - Types of systems (production vs. development, on-prem vs. cloud)
      - Business functions impacted by affected systems
    commonProblems:
      - Vague descriptions ("some servers") without specifics
      - Missing the scope (how many systems total)
      - No distinction between directly compromised vs. potentially exposed
    clarifyingQuestions:
      - Which specific systems were confirmed compromised?
      - How many systems were affected (total count)?
      - Were any critical business systems impacted?
      - What data did these systems contain or process?
    exampleGood: >
      Three systems were compromised: the file server (FS01), a domain controller
      (DC02), and the HR manager's workstation (WS-HR-001). An additional 12
      workstations showed signs of reconnaissance activity but no confirmed compromise.
    examplePoor: >
      Several servers and some workstations were affected.

  - id: root_cause
    displayName: Root Cause
    purpose: >
      Explains how the attacker succeeded. Critical for preventing recurrence
      and demonstrating due diligence to regulators and leadership.
    whatIndicatesPresence:
      - Initial access vector (phishing, vulnerability, credential theft)
      - Specific vulnerability exploited (CVE number if applicable)
      - Security control that failed or was missing
      - Human factor if applicable (who clicked, what was misconfigured)
    commonProblems:
      - Stopping at "phishing" without explaining why it succeeded
      - Missing the underlying security gap that enabled the attack
      - Confusing symptoms with root cause
    clarifyingQuestions:
      - How did the attacker gain initial access?
      - What security control failed or was missing?
      - Was a specific vulnerability exploited?
      - Why did existing defenses not prevent or detect this sooner?
    exampleGood: >
      Initial access was via a phishing email containing a malicious attachment.
      The user (Accounting Dept.) opened the attachment, which exploited CVE-2024-1234
      in the document viewer. EDR was not deployed on this workstation due to
      a gap in the deployment process for new hires.
    examplePoor: >
      The attacker used phishing to get in.

  - id: actions_taken
    displayName: Actions Taken
    purpose: >
      Documents the response, showing stakeholders that appropriate steps were
      taken and creating a record for future incidents.
    whatIndicatesPresence:
      - Containment actions (isolation, credential resets, blocks)
      - Eradication steps (malware removal, system rebuilds)
      - Recovery activities (restoration, validation)
      - Communication actions (notifications, briefings)
    commonProblems:
      - Too high-level ("we contained the incident")
      - Missing who took each action
      - No indication of timing or sequence
    clarifyingQuestions:
      - What containment actions were taken and when?
      - How was the malware/attacker removed?
      - What recovery steps were performed?
      - Who was involved in the response?
    exampleGood: >
      Upon detection, the SOC immediately isolated the three affected systems
      from the network (January 19, 18:30). IT reset passwords for all
      administrative accounts within 2 hours. The IR team rebuilt FS01 from
      clean backups on January 21 after forensic imaging.
    examplePoor: >
      We contained and remediated the incident.

  - id: business_impact
    displayName: Business Impact
    purpose: >
      Quantifies the harm to the organization, essential for leadership
      decisions, insurance claims, and demonstrating severity.
    whatIndicatesPresence:
      - Financial costs (response, recovery, lost revenue)
      - Operational disruption (downtime, delayed projects)
      - Reputational impact (customer notifications, media coverage)
      - Regulatory consequences (fines, required actions)
    commonProblems:
      - Missing quantification ("significant impact")
      - Only covering direct costs, missing indirect impact
      - No business context for technical impacts
    clarifyingQuestions:
      - What was the estimated financial impact?
      - How long were business operations disrupted?
      - Were any customers or partners affected?
      - What regulatory or legal consequences are expected?
    exampleGood: >
      The incident resulted in 3 days of degraded file server access, affecting
      approximately 200 employees. Estimated costs: $50,000 in incident response
      services, $30,000 in lost productivity, and potential regulatory fines
      pending GDPR notification outcome.
    examplePoor: >
      The incident had a significant business impact.

  - id: what_went_well
    displayName: What Went Well
    purpose: >
      Identifies effective response elements to preserve and build upon.
      Provides balance and recognizes team efforts.
    whatIndicatesPresence:
      - Successful detection mechanisms
      - Effective response actions
      - Tools or processes that worked as intended
      - Team collaboration or communication successes
    commonProblems:
      - Omitting this section entirely (all negative)
      - Vague praise without specifics
      - Confusing "got lucky" with "worked well"
    clarifyingQuestions:
      - What detection mechanisms helped identify this incident?
      - Which response actions were particularly effective?
      - What tools or processes worked as intended?
      - How did the team collaborate effectively?
    exampleGood: >
      The EDR solution detected the lateral movement within 18 hours of initial
      compromise. The pre-established communication channel with the CISO enabled
      rapid executive notification. Clean backups were available and tested,
      enabling recovery without ransom payment.
    examplePoor: >
      The team did a good job responding.

  - id: third_party_involvement
    displayName: Third-Party Involvement
    purpose: >
      Documents external parties for coordination, cost tracking, and
      demonstrating appropriate escalation.
    whatIndicatesPresence:
      - IR consultants or forensic firms engaged
      - Law enforcement notifications
      - Legal counsel consultation
      - Insurance carrier notification
      - Vendor involvement (affected or supporting)
    commonProblems:
      - Missing legal counsel involvement
      - Not documenting law enforcement decisions
      - Forgetting insurance notification requirements
    clarifyingQuestions:
      - Were any external IR or forensic firms engaged?
      - Was law enforcement notified? If not, why?
      - When was legal counsel consulted?
      - Was the cyber insurance carrier notified?
    exampleGood: >
      External parties engaged: CrowdStrike for forensic analysis (January 20),
      outside counsel (Baker McKenzie) for breach notification guidance,
      FBI field office notified (January 22), cyber insurance carrier (AIG)
      notified within 24-hour policy requirement.
    examplePoor: >
      We worked with some external parties.

  - id: data_exposure
    displayName: Data Exposure
    purpose: >
      Documents what data was at risk, critical for notification decisions,
      regulatory compliance, and risk assessment.
    whatIndicatesPresence:
      - Types of data accessed or exfiltrated
      - Volume of records affected
      - Sensitivity classification
      - Data subjects affected (employees, customers, partners)
    commonProblems:
      - Not distinguishing accessed vs. exfiltrated
      - Missing data subject counts
      - Vague data descriptions ("sensitive data")
    clarifyingQuestions:
      - What types of data were accessed or exfiltrated?
      - How many records or individuals were affected?
      - Was personal data (PII) involved?
      - Is there evidence of actual exfiltration vs. just access?
    exampleGood: >
      The attacker accessed a file share containing HR records for 1,247 current
      and former employees, including names, SSNs, and salary information.
      Network logs confirm 2.3 GB of data was exfiltrated to an external IP.
      No customer data was on the affected systems.
    examplePoor: >
      Some sensitive data may have been exposed.

  - id: confidence_level
    displayName: Confidence Level
    purpose: >
      Communicates certainty of findings, enabling appropriate decision-making
      and setting expectations for potential revisions.
    whatIndicatesPresence:
      - Explicit confidence statements (high/moderate/low)
      - Basis for conclusions (evidence cited)
      - Acknowledged gaps or uncertainties
      - Preliminary vs. final designation
    commonProblems:
      - Presenting uncertain findings as definitive
      - Not explaining basis for conclusions
      - Missing acknowledgment of investigation gaps
    clarifyingQuestions:
      - How confident are you in the root cause determination?
      - What evidence supports the key conclusions?
      - Are there gaps in the investigation?
      - Is this a preliminary or final assessment?
    exampleGood: >
      Confidence level: Moderate. The root cause assessment is based on EDR
      telemetry and email gateway logs. Full forensic analysis of the initial
      workstation is pending. The exfiltration volume is confirmed via netflow
      data, but content analysis is ongoing.
    examplePoor: >
      (No confidence level stated; findings presented as certain)

# Incident Type Guidance
# Semantic indicators for identifying incident types, replacing keyword lists.
# The AI uses these descriptions to recognize patterns rather than matching strings.
incidentTypes:
  - id: ransomware
    displayName: Ransomware
    description: >
      Attack where malicious software encrypts files or systems, with attackers
      demanding payment for decryption keys.
    indicators:
      - Files or systems encrypted and inaccessible
      - Ransom demand received (email, text file, screen message)
      - Payment requested in cryptocurrency
      - Known ransomware variant mentioned (LockBit, BlackCat, Cl0p)
      - Encrypted files have unusual extensions
      - Backups or shadow copies deleted
    reportingConsiderations:
      - Document ransom amount and payment address demanded
      - Note whether data was exfiltrated before encryption (double extortion)
      - Record encryption scope (specific systems vs. entire network)
      - Preserve any attacker communications for law enforcement
      - Document backup availability and recovery options
    commonPatterns:
      - Initial access via phishing or exploited VPN/RDP
      - Lateral movement using legitimate admin tools
      - Credential harvesting before encryption
      - Data exfiltration for double extortion leverage
      - Encryption during off-hours to maximize impact

  - id: bec
    displayName: Business Email Compromise (BEC)
    description: >
      Social engineering attack using email to manipulate employees into
      transferring funds or sensitive information.
    indicators:
      - Fraudulent wire transfer or payment redirection
      - Invoice manipulation or fake vendor communications
      - Executive impersonation emails
      - Compromised email account used to send internal requests
      - Urgency and secrecy emphasized in requests
    reportingConsiderations:
      - Document the fraudulent transaction details and amounts
      - Identify the compromised or spoofed account
      - Trace the communication chain that led to the fraud
      - Note what validation steps were bypassed
      - Record fund recovery efforts and bank notifications
    commonPatterns:
      - Credential phishing to compromise legitimate accounts
      - Domain spoofing with lookalike domains
      - Thread hijacking in existing email conversations
      - Targeting of finance, HR, or executive assistants
      - Requests timed around travel or busy periods

  - id: data_breach
    displayName: Data Breach
    description: >
      Unauthorized access to or exfiltration of sensitive data, potentially
      triggering notification requirements.
    indicators:
      - Evidence of data exfiltration (network logs, file access)
      - Unauthorized access to databases or file shares
      - Personal data or trade secrets accessed
      - Data appearing on dark web or paste sites
      - Anomalous data transfers to external destinations
    reportingConsiderations:
      - Quantify records and individuals affected
      - Classify data types exposed (PII, PHI, financial)
      - Determine geographic scope for notification requirements
      - Document evidence of actual exfiltration vs. access only
      - Prepare for notification timeline requirements
    commonPatterns:
      - SQL injection or application vulnerabilities
      - Compromised credentials with data access
      - Insider access abuse
      - Cloud storage misconfigurations
      - Third-party/vendor compromise

  - id: insider_threat
    displayName: Insider Threat
    description: >
      Malicious or negligent actions by employees, contractors, or partners
      with authorized access.
    indicators:
      - Unusual data access patterns by authorized users
      - Large file downloads or transfers before departure
      - Access outside normal working hours or locations
      - Circumvention of security controls
      - Policy violations discovered through monitoring
    reportingConsiderations:
      - Document the insider's role and access level
      - Distinguish between malicious and negligent actions
      - Preserve evidence for potential legal action
      - Coordinate with HR and legal before confrontation
      - Consider privacy implications of monitoring evidence
    commonPatterns:
      - Departing employees taking data
      - Privileged access abuse for personal gain
      - Accidental exposure through misconfiguration
      - Credential sharing leading to unauthorized access
      - Coercion or recruitment by external actors

  - id: supply_chain
    displayName: Supply Chain Compromise
    description: >
      Attack through a trusted third party, vendor, or software component.
    indicators:
      - Malicious update from trusted software vendor
      - Compromised vendor credentials used for access
      - Exploitation of vendor-managed systems
      - Third-party breach affecting shared data
      - Malicious code in dependencies or libraries
    reportingConsiderations:
      - Identify the compromised vendor or component
      - Determine scope of vendor access to your environment
      - Document timeline of malicious updates or access
      - Coordinate disclosure with affected vendor
      - Assess impact on other customers if relevant
    commonPatterns:
      - Software update mechanism compromise
      - MSP/MSSP credential theft for customer access
      - Open source dependency poisoning
      - Hardware implants or firmware modifications
      - Trusted connection/VPN abuse

# Notification Requirement Guidance
# Semantic descriptions of when regulations may apply, not keyword triggers.
# Always reminds users to consult legal counsel for authoritative guidance.
notifications:
  - regulation: GDPR
    deadline: 72 hours from becoming aware of breach
    triggers:
      - Personal data of EU/EEA residents accessed or exfiltrated
      - EU employees, customers, or partners affected
      - Data processed under EU operations or targeting EU market
    scope: >
      Applies to organizations processing personal data of EU residents,
      regardless of where the organization is located.
    caveats:
      - Consult legal counsel for authoritative interpretation
      - 72-hour clock starts when breach is confirmed, not suspected
      - May require individual notification in addition to authority notification
      - Document decision-making process if determining notification not required

  - regulation: CCPA/CPRA
    deadline: Expedient notification, no fixed hour deadline
    triggers:
      - Personal information of California residents accessed
      - Unencrypted personal data acquired by unauthorized person
      - Categories include name + SSN, driver's license, financial account, medical, biometric
    scope: >
      Applies to businesses meeting California thresholds that experience
      breach of California resident personal information.
    caveats:
      - Consult California-licensed counsel for specific requirements
      - Definition of "breach" requires acquisition, not just access
      - Safe harbor for encrypted data if key not compromised
      - May trigger private right of action if security was inadequate

  - regulation: HIPAA
    deadline: 60 days from discovery for breaches over 500 individuals
    triggers:
      - Protected health information (PHI) accessed or disclosed
      - Healthcare provider, health plan, or business associate involved
      - Unsecured PHI acquired by unauthorized person
    scope: >
      Applies to covered entities (healthcare providers, plans) and their
      business associates handling protected health information.
    caveats:
      - Consult healthcare compliance counsel
      - Smaller breaches have annual reporting, not immediate
      - Risk assessment may determine notification not required
      - HHS Office for Civil Rights must be notified for large breaches

  - regulation: State Breach Laws
    deadline: Varies by state (24 hours to 90 days)
    triggers:
      - Personal information of state residents accessed
      - Definitions vary by state (some include username/password)
      - Multi-state incidents may trigger multiple requirements
    scope: >
      All 50 US states plus territories have breach notification laws with
      varying definitions, timelines, and requirements.
    caveats:
      - Consult counsel familiar with multi-state notification
      - Some states require AG notification in addition to individuals
      - Credit monitoring requirements vary by state
      - Document which states' residents are affected

# Writing Analysis Guidance
# Semantic descriptions of writing issues to check, with examples.
# Replaces the hardcoded jargon dictionary and regex-based detection.
writingAnalysis:
  jargon:
    whatToCheck: Technical terms and acronyms that may confuse non-technical readers
    whyItMatters: >
      IR reports are read by executives, legal counsel, insurance adjusters,
      and regulators—not just security engineers. Unexplained jargon creates
      confusion and undermines credibility.
    examples:
      - bad: lateral movement
        good: spread to other systems
        explanation: Executive readers may not know this term
      - bad: C2 or C&C
        good: command-and-control server (the attacker's remote control point)
      - bad: IOCs
        good: indicators of compromise (evidence of the attack)
      - bad: TTPs
        good: tactics, techniques, and procedures (the attacker's methods)
      - bad: exfiltrated
        good: stolen or transferred out of the network
      - bad: persistence mechanism
        good: method for maintaining access
      - bad: privilege escalation
        good: gained higher-level access or obtained administrator rights
      - bad: beaconing
        good: regularly communicating with attacker's server
      - bad: living off the land
        good: using legitimate system tools for malicious purposes
      - bad: EDR
        good: endpoint detection and response (security monitoring software)
      - bad: SIEM
        good: security information and event management (log analysis system)
      - bad: APT
        good: advanced persistent threat (sophisticated, targeted attacker)
      - bad: zero-day
        good: previously unknown vulnerability
      - bad: payload
        good: malicious code or malware component
      - bad: dropper
        good: program that installs malware

  passiveVoice:
    whatToCheck: Sentences where the actor is unclear or responsibility is obscured
    whyItMatters: >
      Incident reports must clearly attribute actions. Passive voice obscures
      whether the attacker, defender, or system performed an action, creating
      ambiguity that can have legal implications.
    examples:
      - bad: "The server was accessed and files were exfiltrated."
        good: "The attacker accessed the server and exfiltrated 50GB of files."
        explanation: Clarifies who performed the action
      - bad: "Credentials were reset."
        good: "The IT team reset all administrative credentials within 2 hours."
        explanation: Attributes the response action
      - bad: "The malware was discovered on the system."
        good: "EDR detected the malware on WS-001 at 14:32 UTC."
        explanation: Specifies what detected it and when
      - bad: "A decision was made to isolate the network segment."
        good: "The CISO directed the SOC to isolate the network segment."
        explanation: Documents decision-making authority

  vagueTerms:
    whatToCheck: Imprecise quantifiers that should be replaced with specific numbers
    whyItMatters: >
      Stakeholders need specifics for decision-making, insurance claims, and
      regulatory filings. Vague terms undermine the report's usefulness and
      credibility.
    examples:
      - bad: "Several servers were affected."
        good: "Three servers were affected: FS01, DC02, and WEB03."
      - bad: "The attacker was in the network for some time."
        good: "The attacker maintained access for 18 days."
      - bad: "A significant amount of data was exfiltrated."
        good: "Approximately 2.3 GB of data (1,247 records) was exfiltrated."
      - bad: "Many users' credentials were compromised."
        good: "Credentials for 47 user accounts were compromised."
      - bad: "The incident had a substantial financial impact."
        good: "The incident cost approximately $130,000 in response and recovery."

  sentenceLength:
    whatToCheck: Overly long sentences that are difficult to parse
    whyItMatters: >
      Clear communication requires digestible sentences. Long, complex sentences
      increase the chance of misunderstanding, especially for non-native English
      readers or those skimming the report.
    examples:
      - bad: >
          The attacker, having gained initial access through a phishing email
          that was sent to an employee in the accounting department who clicked
          on a malicious link that exploited a vulnerability in the browser,
          then proceeded to move laterally through the network using stolen
          credentials until reaching the file server.
        good: >
          The attacker gained initial access through a phishing email to an
          accounting employee. The malicious link exploited a browser vulnerability.
          Using stolen credentials, the attacker moved laterally until reaching
          the file server.
        explanation: Break complex sequences into separate sentences

  documentFormatting:
    whatToCheck: Document structure and formatting for readability
    whyItMatters: >
      A well-formatted report is more likely to be read and taken seriously.
      Visual organization signals clear thinking and professionalism.
    aiCheckable:
      - "Consistent heading hierarchy (H1 for title, H2 for sections, H3 for subsections)"
      - "Tables used for structured data (timelines, action items, affected systems)"
      - "Bullet points for lists rather than run-on paragraphs"
      - "Each section can stand alone if excerpted"
    userReminders:
      - "Sufficient whitespace between sections"
      - "Professional fonts and consistent styling"
      - "Page breaks before major sections in final document"
      - "Tables fit on page without awkward wrapping"
      - "Consistent date and time formats throughout"

# Action Item Extraction Guidance
# Semantic descriptions of urgency categories for action items.
actionGuidance:
  - category: immediate
    description: >
      Actions that must be taken within hours to contain active threats or
      prevent further damage.
    indicators:
      - Words like "immediately", "now", "urgent", "critical"
      - Active threat requiring containment
      - Ongoing data exfiltration or system access
      - Imminent regulatory deadline
    examplePhrases:
      - "must immediately isolate"
      - "urgent: reset all"
      - "block the attacker's IP now"
      - "critical: notify within 72 hours"

  - category: short_term
    description: >
      Actions to complete within days to weeks, typically remediation and
      initial hardening measures.
    indicators:
      - Words like "should", "need to", "must complete"
      - Post-incident remediation tasks
      - Addressing the specific vulnerability exploited
      - Evidence preservation and documentation
    examplePhrases:
      - "should implement MFA for"
      - "need to patch the vulnerability"
      - "review and update firewall rules"
      - "conduct password reset for affected accounts"

  - category: long_term
    description: >
      Strategic improvements to prevent recurrence, typically projects taking
      months to implement.
    indicators:
      - Words like "consider", "evaluate", "plan for", "invest in"
      - Architectural or process changes
      - New tool or capability deployment
      - Training or awareness programs
    examplePhrases:
      - "consider implementing zero trust"
      - "evaluate EDR solutions for"
      - "develop an incident response plan"
      - "invest in security awareness training"

# Stakeholder Identification Guidance
# Helps AI identify relevant parties mentioned in incident notes.
stakeholderGuidance:
  internal:
    - C-suite and executive leadership (CISO, CIO, CEO, CFO)
    - Legal and compliance teams
    - IT and security operations staff
    - Human resources (if employee data involved)
    - Communications/PR team
    - Business unit leaders for affected operations
    - Internal audit
    - Board of directors (for significant incidents)
  external:
    - category: Incident Response
      description: External firms providing forensic analysis or response support
      examples:
        - CrowdStrike, Mandiant, Secureworks
        - Forensic imaging specialists
        - Malware analysis services
    - category: Legal
      description: Outside counsel for breach notification and liability guidance
      examples:
        - Privacy/breach notification specialists
        - Litigation counsel
        - Regulatory counsel
    - category: Law Enforcement
      description: Government agencies for criminal investigation
      examples:
        - FBI (cyber division)
        - Secret Service (financial crimes)
        - Local law enforcement
        - International agencies (Europol, INTERPOL)
    - category: Regulators
      description: Government bodies requiring notification
      examples:
        - State Attorneys General
        - HHS/OCR (for HIPAA)
        - Data Protection Authorities (for GDPR)
        - SEC (for public companies)
    - category: Insurance
      description: Cyber insurance carriers and brokers
      examples:
        - Primary cyber insurance carrier
        - Insurance broker
        - Claims adjusters
    - category: Vendors
      description: Third parties affected by or supporting response
      examples:
        - Compromised vendor (if supply chain)
        - Cloud service providers
        - Managed security service providers

# Audience Guidance
# Helps ensure the report addresses what different stakeholders need to know
audienceGuidance:
  purpose: >
    Ensure the report addresses what different stakeholders need to know.
    Write with readers in mind—address the questions they want answered
    in a way that's easy to absorb.
  empathyPrinciple: >
    Effective incident reports require empathy with readers' needs and
    expectations. Most readers only see the executive summary, but different
    audiences need different information from the full report.
  stakeholderNeeds:
    executives:
      - "Business impact and financial costs"
      - "Regulatory exposure and compliance implications"
      - "Strategic risks and reputation concerns"
      - "Key decisions that require their input"
    technical:
      - "Root cause details and attack chain"
      - "Indicators of compromise (IOCs)"
      - "Remediation steps and hardening measures"
      - "Forensic findings and evidence"
    legal:
      - "Data exposure scope and affected individuals"
      - "Notification triggers and deadlines"
      - "Evidence preservation status"
      - "Third-party contractual obligations"
    insurance:
      - "Timeline of events and response actions"
      - "Containment and mitigation measures"
      - "Financial impact breakdown"
      - "Policy compliance and notification timing"

  terminologyByAudience:
    description: >
      The same technical finding may require different language depending on
      the audience. Use precise terminology for practitioners, plain language
      for executives, and define-on-first-use for mixed audiences.
    examples:
      - term: "lateral movement"
        forTechnical: "lateral movement via compromised credentials"
        forExecutive: "the attacker spread to additional systems using stolen passwords"
        forMixed: "lateral movement (spreading to additional systems) via compromised credentials"
      - term: "C2 communications"
        forTechnical: "established C2 communications with 185.x.x.x"
        forExecutive: "established a remote control connection to an attacker server"
        forMixed: "established command-and-control (C2) communications with the attacker's server"
      - term: "CVSS score"
        forTechnical: "CVSS 9.8 (Critical)"
        forExecutive: "rated 9.8 out of 10 on the industry severity scale (Critical)"
        forMixed: "CVSS 9.8 (Critical) — the industry-standard severity rating where 10 is most severe"
    principle: >
      Technical precision terms (CVSS, CVE, IOCs) are expected by security teams
      and compliance frameworks — use them. But define them for executives and
      mixed audiences. Buzzwords like 'leverage', 'robust', and 'holistic' should
      be avoided for all audiences — they add no precision.

# Length Guidance
# Context-aware guidance on when brevity vs. detail is appropriate
lengthGuidance:
  principle: >
    Knowing when to be brief is as important as knowing how to be brief.
    Different sections serve different purposes and audiences.
  bySection:
    executive_summary:
      guidance: "Under 150 words—executives lack time and need key takeaways quickly"
      brevity: true
    timeline:
      guidance: "Detailed for legal/forensic purposes—comprehensive record is appropriate"
      brevity: false
    root_cause:
      guidance: "Brief explanation for executives, with supporting evidence for technical readers"
      brevity: balanced
    lessons_learned:
      guidance: "Specific and actionable, not verbose platitudes—quality over quantity"
      brevity: true
    actions_taken:
      guidance: "Comprehensive for audit trail and insurance documentation"
      brevity: false
    business_impact:
      guidance: "Quantified and specific—numbers matter more than narrative"
      brevity: true
    data_exposure:
      guidance: "Detailed for notification decisions—scope and evidence are critical"
      brevity: false

# Cross-Cutting Criteria
# Quality checks that apply across all sections
crossCuttingCriteria:
  businessRelevance:
    description: "Every section should connect technical details to business context"
    checkFor:
      - "Does each section explain why the information matters to stakeholders?"
      - "Are compliance and regulatory implications addressed where relevant?"
      - "Would a non-technical executive understand the significance?"
      - "Is the 'so what?' answered for facts and conclusions?"
  consistency:
    description: "Information should be consistent throughout the document"
    checkFor:
      - "Are numbers consistent across sections (affected systems count, timeline dates)?"
      - "Do terms and acronyms match throughout the document?"
      - "Are severity characterizations consistent?"
      - "Do timeline references in different sections align?"
  completeness:
    description: "Each section should be self-contained enough to be excerpted"
    checkFor:
      - "Can each major section stand alone if shared separately?"
      - "Are key findings repeated in the executive summary?"
      - "Are all action items captured in the action items section (not buried in narrative)?"
---