aiwg/agentic/code/frameworks/forensics-complete/schemas/finding.yaml

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

# Schema: Forensic Finding
#
# Defines the structure for a single finding in a forensic investigation report.
# A finding represents a confirmed observation with security significance —
# a compromise, a misconfiguration, a policy violation, or an anomaly.
#
# Each finding maps to a section in forensic-report.md and links to:
# - Evidence items in the evidence manifest
# - IOCs in the IOC register
# - Remediation actions in the remediation plan
# - ATT&CK techniques in the MITRE framework
#
# CVSS scoring reference: https://www.first.org/cvss/
# ATT&CK reference:       https://attack.mitre.org/
#
# Required fields are marked "(required)".
# Optional fields are marked "(optional)".

---
schema_version: "1.0.0"
schema_name: finding

# --- Identification (all required) ---

id:
  # (required) Unique finding identifier within this case.
  # Format: F-NNN (e.g., F-001, F-012)
  type: string
  pattern: "^F-[0-9]{3,}$"
  example: "F-001"

case_id:
  # (required) Case identifier linking this finding to an investigation.
  type: string
  example: "2026-02-27-001"

title:
  # (required) Short, descriptive title for the finding.
  # Be specific: "Unauthorized SSH Key Added to root Account" not "SSH Issue"
  # Aim for 5-10 words that clearly convey what was found.
  type: string
  example: "Unauthorized SSH Authorized Key Added to root Account"

severity:
  # (required) Severity classification of the finding.
  #
  # CRITICAL: Active compromise with ongoing attacker access or confirmed data exfiltration.
  #           Requires immediate containment action.
  #
  # HIGH: Confirmed compromise with significant impact; attacker access terminated
  #       but forensic evidence of unauthorized access is clear.
  #
  # MEDIUM: Evidence of attempted compromise or confirmed policy violation with
  #         limited impact. No confirmed data exfiltration or persistent access.
  #
  # LOW: Misconfiguration, anomaly, or observation with no confirmed malicious
  #      activity. Warrants remediation but not incident response.
  type: string
  allowed:
    - CRITICAL
    - HIGH
    - MEDIUM
    - LOW
  example: "HIGH"

description:
  # (required) Full description of what was found, how it was discovered, and why it
  # is significant. Written for a technical audience. Should be self-contained —
  # a reader should understand the finding without consulting other documents.
  # Minimum: 2-3 sentences. For CRITICAL/HIGH findings: 1-3 paragraphs.
  type: string

evidence:
  # (required) Primary evidence supporting this finding.
  # Include log excerpts, command output, or file content.
  # For long evidence blocks, reference the evidence item and storage path.
  # Example: "E-003: auth.log lines 1847-1903" or inline log excerpt.
  type: string

# --- ATT&CK mapping ---

attack_technique:
  # (optional) Primary MITRE ATT&CK technique ID.
  # Format: T followed by 4 digits, optional period and 3-digit sub-technique.
  type: string
  pattern: "^T[0-9]{4}(\\.[0-9]{3})?$"
  example: "T1098.004"
  # T1098.004 = Account Manipulation: SSH Authorized Keys

attack_tactic:
  # (optional) ATT&CK tactic for the primary technique.
  type: string
  allowed:
    - reconnaissance
    - resource-development
    - initial-access
    - execution
    - persistence
    - privilege-escalation
    - defense-evasion
    - credential-access
    - discovery
    - lateral-movement
    - collection
    - command-and-control
    - exfiltration
    - impact
  example: "persistence"

additional_techniques:
  # (optional) Additional ATT&CK techniques observed in connection with this finding.
  # Use when a finding spans multiple techniques (e.g., an exploit that achieves
  # both initial access and privilege escalation in one step).
  type: array
  items:
    technique_id:
      type: string
      pattern: "^T[0-9]{4}(\\.[0-9]{3})?$"
    tactic:
      type: string
    description:
      type: string

# --- Scope ---

affected_systems:
  # (optional) Systems confirmed or likely affected by this finding.
  # If only the target system is affected, record the hostname here.
  # If lateral movement is confirmed, list all affected systems.
  type: array
  items:
    type: string
  example:
    - "web-prod-01.example.com"
    - "db-prod-01.example.com"

affected_accounts:
  # (optional) User accounts compromised or involved in this finding.
  type: array
  items:
    type: string
  example:
    - "root"
    - "deploy"

# --- Evidence references ---

evidence_items:
  # (optional) Evidence item IDs from the evidence manifest that support this finding.
  type: array
  items:
    type: string
    pattern: "^E-[0-9]{3,}$"
  example:
    - "E-005"
    - "E-008"

evidence_path:
  # (optional) Storage path to the primary evidence file for this finding.
  type: string
  example: "/evidence/2026-02-27-001/filesystem/root_authorized_keys.txt"

evidence_hash:
  # (optional) SHA-256 hash of the primary evidence file to ensure integrity.
  type: string
  example: "e3b0c44298fc1c149afbf4c8996fb924..."

ioc_references:
  # (optional) IOC IDs from the IOC register associated with this finding.
  type: array
  items:
    type: string
    pattern: "^IOC-[0-9]{3,}$"
  example:
    - "IOC-002"
    - "IOC-005"

# --- Analysis ---

analysis:
  # (optional) Investigator's analysis: how the finding fits into the attack chain,
  # what it reveals about threat actor intent, and how confident the assessment is.
  # Distinguish between confirmed facts and inferences. Use hedging where appropriate:
  # "confirmed", "likely", "possibly", "cannot determine from available evidence".
  type: string

impact:
  # (optional) Actual or potential impact of this finding.
  # Describe in concrete terms: data at risk, systems affected, business impact.
  # Example: "Attacker had root-level persistent access to the production web server
  # for approximately 14 days. All data processed by this server during that period
  # must be considered potentially compromised."
  type: string

timeline_reference:
  # (optional) Timestamp or time range when this finding's activity occurred.
  # Reference the incident timeline for context.
  type: string
  example: "2026-02-13T03:14:00Z to 2026-02-27T08:57:22Z"

# --- Remediation ---

remediation:
  # (optional) Summary of remediation actions for this finding.
  # Full remediation detail belongs in remediation-plan.md.
  # Reference the remediation plan action IDs here.
  type: string
  example: "Remove unauthorized SSH key (IA-001). Audit all authorized_keys files (ST-002). Rotate root credentials (IA-002)."

remediation_actions:
  # (optional) List of remediation plan action IDs addressing this finding.
  type: array
  items:
    type: string
  example:
    - "IA-001"
    - "IA-002"
    - "ST-002"

# --- Scoring ---

cvss_score:
  # (optional) CVSS v3.1 base score (0.0 - 10.0).
  # Use for findings tied to CVEs or where a standardized severity score is needed.
  # Compute using: https://www.first.org/cvss/calculator/3.1
  type: number
  minimum: 0.0
  maximum: 10.0
  example: 8.8

cvss_vector:
  # (optional) Full CVSS v3.1 vector string.
  # Example: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
  type: string
  example: "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:N"

# --- References ---

references:
  # (optional) External references relevant to this finding.
  # Include CVE IDs, security advisories, ATT&CK pages, or vendor documentation.
  type: array
  items:
    title:
      type: string
    url:
      type: string
  example:
    - title: "ATT&CK T1098.004: Account Manipulation: SSH Authorized Keys"
      url: "https://attack.mitre.org/techniques/T1098/004/"
    - title: "NIST SP 800-92: Guide to Computer Security Log Management"
      url: "https://csrc.nist.gov/publications/detail/sp/800-92/final"