# AgentRisk Incident Schema v1.0
# This schema defines the required and optional fields for incident YAML files.
# All incident files in data/incidents/ must conform to this schema.

schema_version: "1.0"

fields:

  # === REQUIRED FIELDS ===

  id:
    type: string
    required: true
    pattern: "^AR-\\d{3,}$"
    description: "Unique incident identifier. Format: AR-NNN (zero-padded, monotonically increasing)."
    example: "AR-001"

  title:
    type: string
    required: true
    max_length: 200
    description: "One-line summary of the incident. Should describe what happened, not the category."
    example: "Agent transfers excess tokens after a session reset"

  severity:
    type: string
    required: true
    enum: [CRITICAL, HIGH, MEDIUM, LOW]
    description: |
      Severity rating based on impact scope and reversibility.
        CRITICAL: Irreversible harm, large financial loss, or platform-wide compromise.
        HIGH: Significant harm, partial reversibility, or multi-user impact.
        MEDIUM: Moderate harm, mostly reversible, limited scope.
        LOW: Minor harm, fully reversible, single-user impact.

  category:
    type: string
    required: true
    enum: [Financial, Security, Data, Autonomy, Multi-agent, Governance]
    description: "Primary failure category."

  failure_type:
    type: string
    required: true
    description: "Specific failure type within the category (e.g., Tool Misuse, Auth Bypass, Data Exfiltration)."
    example: "Tool Misuse"

  date_reported:
    type: string
    required: true
    format: "YYYY-MM-DD"
    description: "Date the incident was reported or documented."

  date_occurred:
    type: string
    required: true
    format: "YYYY-MM-DD"
    description: "Date the incident actually occurred (best estimate if exact date unknown)."

  platform:
    type: string
    required: true
    description: "Platform, product, or system where the incident occurred."
    example: "OpenClaw"

  agent_type:
    type: string
    required: true
    description: "Type of agent involved (e.g., autonomous-task-agent, multi-agent-platform, coding-agent, browsing-agent)."

  description:
    type: string
    required: true
    min_length: 200
    description: |
      Detailed narrative of the incident. Should include:
        - What the agent was doing
        - What went wrong
        - How the failure manifested
        - Immediate consequences
      Minimum 200 characters (~50 words). Aim for 500+ words for high-quality submissions.

  root_cause:
    type: string
    required: true
    description: |
      Analysis of why the incident occurred. Use a numbered list of contributing factors.
      Focus on systemic causes, not surface symptoms.

  failure_mode:
    type: string
    required: true
    description: "Concise technical description of the failure mechanism."
    example: "Incorrect transaction magnitude — 62,500x overpayment"

  impact:
    type: object
    required: true
    fields:
      financial_loss_usd:
        type: number
        required: true
        description: "Estimated financial loss in USD. Use 0 if no direct financial loss."
      reversibility:
        type: string
        required: true
        enum: [none, partial, full]
        description: "Whether the damage could be reversed."
      affected_parties:
        type: string
        required: true
        description: "Number or description of affected parties."
      chain:
        type: string
        required: true
        description: "Description of the causal chain or blast radius."

  mitigations:
    type: array
    required: true
    min_items: 1
    item_fields:
      id:
        type: string
        required: true
        pattern: "^MIT-\\d{3,}$"
        description: "Unique mitigation identifier."
      control:
        type: string
        required: true
        description: "Name of the control or safeguard."
      description:
        type: string
        required: true
        description: "What this mitigation does and why it helps."
      implementation:
        type: string
        required: true
        description: "How to implement the mitigation (technical guidance)."
      effectiveness:
        type: string
        required: true
        enum: [high, medium, low]
        description: "Expected effectiveness of the mitigation."

  owasp_asi_mapping:
    type: array
    required: true
    min_items: 1
    description: |
      Legacy project ASI labels, retained for compatibility. These are not a verified
      crosswalk to the current OWASP Agentic Top 10.
      Valid values: ASI-01 through ASI-10.
        ASI-01: Agent Goal Hijack
        ASI-02: Agentic Knowledge Poisoning
        ASI-03: Excessive Agency
        ASI-04: Uncontrolled Code Execution
        ASI-05: Identity & Privilege Abuse
        ASI-06: Cross-Agent Trust Exploitation
        ASI-07: System Prompt Leakage
        ASI-08: Tool & Integration Exploitation
        ASI-09: Insufficient Monitoring
        ASI-10: Unintended Multi-Agent Orchestration

  tags:
    type: array
    required: true
    min_items: 1
    description: "Lowercase, hyphenated tags for search and filtering."
    example: ["financial", "tool-misuse", "irreversible"]

  # === OPTIONAL FIELDS ===

  tools_involved:
    type: array
    required: false
    description: "List of tools or APIs the agent was using when the incident occurred."
    example: ["crypto-wallet-api", "transaction-executor"]

  references:
    type: array
    required: false
    item_fields:
      type:
        type: string
        required: true
        enum: [source, related_incident, standard, advisory, news]
        description: "Type of reference."
      url:
        type: string
        required: true
        description: "URL to the reference material."
      description:
        type: string
        required: true
        description: "Brief description of what the reference contains."

  related_incidents:
    type: array
    required: false
    description: "List of related AR-* incident IDs."
    example: ["AR-001", "AR-005"]

  aivss_score:
    type: number
    required: false
    min: 0.0
    max: 10.0
    description: "OWASP AIVSS score (0.0-10.0) if calculated. See https://aivss.owasp.org/"
