{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/json-structure/cortex-xdr-incident-structure.json",
  "name": "Cortex XDR Incident",
  "description": "Schema for a Cortex XDR security incident object returned by the Cortex XDR API. Incidents are aggregated collections of related alerts representing a potential security threat or attack campaign. They are automatically created by Cortex XDR's analytics engine when correlated alerts meet grouping criteria based on shared endpoints, users, or behavioral patterns, or manually created by analysts. The incident object provides a unified attack story view including affected hosts, users, alert severity breakdown, investigation status, and source data attribution.",
  "type": "object",
  "properties": {
    "incident_id": {
      "type": "string",
      "description": "Unique numeric identifier for the incident assigned by Cortex XDR upon creation. Used to reference the incident in all API operations including status updates, alert associations, and webhook event correlation."
    },
    "incident_name": {
      "type": "string",
      "description": "Human-readable name of the incident, either auto-generated by Cortex XDR from the highest-severity correlated alert or manually assigned by an analyst. Provides a concise summary of the detected threat activity."
    },
    "creation_time": {
      "type": "int32",
      "description": "Unix epoch timestamp in milliseconds indicating when the incident was first created by Cortex XDR's correlation engine. Corresponds to the time the first correlated alert triggered incident creation."
    },
    "modification_time": {
      "type": "int32",
      "description": "Unix epoch timestamp in milliseconds indicating the most recent modification to the incident record. Updated when incident properties change, new alerts are correlated, status is updated, or analyst assignments change."
    },
    "status": {
      "type": "string",
      "description": "Current investigation status of the incident. 'new' indicates an untriaged incident awaiting analyst review. 'under_investigation' means an analyst is actively working the incident. The resolved statuses indicate final determination and closure with specific resolution reason.",
      "enum": [
        "new",
        "under_investigation",
        "resolved_threat_handled",
        "resolved_known_issue",
        "resolved_duplicate",
        "resolved_false_positive",
        "resolved_auto"
      ]
    },
    "severity": {
      "type": "string",
      "description": "Overall severity of the incident, determined by the highest-severity correlated alert or manually overridden by an analyst. Drives prioritization in the incident queue and can trigger automated escalation or response actions.",
      "enum": [
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "assigned_user_mail": {
      "type": "string",
      "description": "Email address of the analyst or user currently assigned to investigate this incident. Null or absent when the incident is unassigned."
    },
    "assigned_user_pretty_name": {
      "type": "string",
      "description": "Display name of the assigned analyst as configured in their Cortex XDR user profile. Provides a human-friendly label for the assignee alongside the email address."
    },
    "description": {
      "type": "string",
      "description": "Detailed description of the incident providing context about the detected threat, affected systems, and attack techniques. May be auto-generated from correlated alert content or manually authored by an analyst during investigation."
    },
    "alert_count": {
      "type": "int32",
      "description": "Total number of individual alerts correlated and grouped into this incident. Includes alerts of all severity levels from all contributing detection sources.",
      "minimum": 0
    },
    "low_severity_alert_count": {
      "type": "int32",
      "description": "Number of alerts within the incident rated at low severity. Low severity alerts typically indicate suspicious but low-risk activity that provides supporting context for the overall investigation.",
      "minimum": 0
    },
    "med_severity_alert_count": {
      "type": "int32",
      "description": "Number of alerts within the incident rated at medium severity. Medium severity alerts indicate potentially harmful activity warranting investigation and may indicate early-stage attack activity.",
      "minimum": 0
    },
    "high_severity_alert_count": {
      "type": "int32",
      "description": "Number of alerts within the incident rated at high severity. High severity alerts indicate likely malicious activity requiring prompt analyst response and may indicate active compromise.",
      "minimum": 0
    },
    "user_count": {
      "type": "int32",
      "description": "Total number of distinct user accounts associated with alerts in this incident. Provides a quick measure of the identity blast radius of the detected threat activity.",
      "minimum": 0
    },
    "host_count": {
      "type": "int32",
      "description": "Total number of distinct endpoints or hosts involved in alerts in this incident. Provides a quick measure of the infrastructure blast radius of the detected threat activity.",
      "minimum": 0
    },
    "notes": {
      "type": "string",
      "description": "Free-form analyst notes attached to the incident during investigation. Used to document investigation findings, timeline reconstruction, and context that is not captured in the structured alert data."
    },
    "resolve_comment": {
      "type": "string",
      "description": "Analyst-provided comment explaining the resolution decision when closing the incident. Documents the investigation conclusion, root cause determination, and any remediation actions taken."
    },
    "alert_sources": {
      "type": "array",
      "description": "List of detection source identifiers that contributed alerts to this incident. Identifies which Cortex XDR engines, modules, or integrated third-party products generated the underlying detection events.",
      "items": {
        "type": "string",
        "description": "Name of a detection source that contributed at least one alert to this incident (e.g., XDR Agent, XDR Analytics, XDR Analytics BIOC, XDR BIOC, Cortex XDR - IOC, 3rd Party)."
      }
    },
    "network_artifacts": {
      "type": "array",
      "description": "List of network-based indicators of compromise associated with this incident, such as malicious IP addresses, domains, and URLs observed across the correlated alerts.",
      "items": {
        "$ref": "#/$defs/NetworkArtifact"
      }
    },
    "file_artifacts": {
      "type": "array",
      "description": "List of file-based indicators of compromise associated with this incident, such as malicious files, executables, and scripts identified across the correlated alerts.",
      "items": {
        "$ref": "#/$defs/FileArtifact"
      }
    },
    "xdr_url": {
      "type": "uri",
      "description": "Direct URL link to the incident detail and investigation page in the Cortex XDR management console. Provides single-click access to the full incident timeline, alert list, and forensic investigation interface."
    }
  },
  "required": [
    "incident_id"
  ],
  "definitions": {
    "NetworkArtifact": {
      "type": "object",
      "description": "A network-based indicator of compromise associated with a Cortex XDR incident. Represents malicious or suspicious network endpoints such as IP addresses, domains, or URLs observed in the correlated alert data.",
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of network artifact indicating the kind of network indicator.",
          "enum": [
            "IP",
            "DOMAIN",
            "URL"
          ]
        },
        "network_domain": {
          "type": "string",
          "description": "Domain name associated with the network artifact, if applicable. May represent a malicious C2 domain or phishing site domain."
        },
        "network_remote_ip": {
          "type": "string",
          "description": "Remote IP address associated with the network artifact. May represent a C2 server, malware distribution host, or other malicious infrastructure."
        },
        "network_remote_port": {
          "type": "int32",
          "description": "Remote port number associated with the network connection artifact."
        },
        "network_country": {
          "type": "string",
          "description": "Country associated with the remote IP address based on geolocation lookup, if available."
        },
        "alert_count": {
          "type": "int32",
          "description": "Number of alerts in the incident that reference this network artifact.",
          "minimum": 0
        },
        "is_manual": {
          "type": "boolean",
          "description": "Whether this artifact was manually added by an analyst rather than automatically extracted from alert data.",
          "default": false
        }
      },
      "name": "NetworkArtifact"
    },
    "FileArtifact": {
      "type": "object",
      "description": "A file-based indicator of compromise associated with a Cortex XDR incident. Represents malicious or suspicious files, executables, or scripts identified in the correlated detection data.",
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of file artifact indicating the nature of the file-based indicator.",
          "enum": [
            "HASH",
            "FILE"
          ]
        },
        "file_name": {
          "type": "string",
          "description": "Name of the file associated with the artifact, as observed during detection."
        },
        "file_path": {
          "type": "string",
          "description": "Full filesystem path where the file was observed on the affected endpoint."
        },
        "file_sha256": {
          "type": "string",
          "description": "SHA-256 cryptographic hash of the file, used as the primary unique identifier for cross-referencing with threat intelligence databases and WildFire verdicts.",
          "pattern": "^[a-fA-F0-9]{64}$"
        },
        "file_signature_status": {
          "type": "string",
          "description": "Digital signature verification status of the file.",
          "enum": [
            "SIGNED",
            "UNSIGNED",
            "INVALID_SIGNATURE"
          ]
        },
        "alert_count": {
          "type": "int32",
          "description": "Number of alerts in the incident that reference this file artifact.",
          "minimum": 0
        },
        "is_manual": {
          "type": "boolean",
          "description": "Whether this artifact was manually added by an analyst rather than automatically extracted from alert data.",
          "default": false
        },
        "wildfire_verdict": {
          "type": "string",
          "description": "WildFire malware analysis verdict for this file if it has been submitted to WildFire for sandbox analysis.",
          "enum": [
            "BENIGN",
            "MALWARE",
            "GRAYWARE",
            "PHISHING",
            "PENDING"
          ]
        }
      },
      "name": "FileArtifact"
    }
  }
}