asyncapi: 2.6.0
info:
  title: Cortex XSIAM Data Ingestion
  version: 1.0.0
  description: >
    Cortex XSIAM Data Ingestion provides streaming log and event ingestion
    endpoints for collecting security telemetry from external data sources
    into the XSIAM data lake. The ingestion service accepts data via HTTPS
    with streaming support, enabling high-throughput log collection for SIEM
    replacement and XDR-native data lake consolidation. Supported ingestion
    methods include Syslog forwarding over TCP/UDP/TLS, HTTPS log forwarding
    via REST endpoints, and XDR data forwarding from integrated Palo Alto
    Networks products. Ingested data is processed by the XSIAM correlation
    and analytics engines for threat detection, investigation, and automated
    response. Each ingestion event results in normalized data being indexed
    into the appropriate XSIAM dataset identified by vendor, product, and
    log type.
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
    email: support@paloaltonetworks.com
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal

servers:
  xsiam-collector:
    url: 'https://api-{fqdn}/logs/v1/event'
    protocol: https
    description: >
      Cortex XSIAM HTTP log collector endpoint for streaming log and event
      data ingestion. The FQDN is specific to the XSIAM tenant and is
      found in Settings > Configurations > Data Collection > HTTP Collectors.
      All requests require API key authentication using the x-xdr-auth-id
      header (key ID) and the Authorization header (API key value). Payloads
      may be gzip-compressed using the Content-Encoding: gzip header for
      improved throughput efficiency.
    variables:
      fqdn:
        description: >
          The XSIAM tenant fully qualified domain name, such as
          xsiam-tenant.xdr.us.paloaltonetworks.com.
    security:
    - apiKeyAuth: []

  syslog-receiver:
    url: '{syslogHost}:{syslogPort}'
    protocol: tcp
    description: >
      Syslog receiver endpoint for forwarding logs from external systems
      using Syslog over TCP, UDP, or TLS. Configure the source system to
      forward Syslog messages (RFC 3164 or RFC 5424) to this endpoint.
      TLS encryption is supported for secure log forwarding.
    variables:
      syslogHost:
        description: Hostname or IP address of the XSIAM Syslog receiver.
      syslogPort:
        description: Port number for Syslog ingestion (default 514 for UDP/TCP, 6514 for TLS).

tags:
- name: ingestion
  description: Log and event data ingestion into the XSIAM data lake
- name: logs
  description: Raw log data submission and forwarding events
- name: xsiam
  description: Cortex XSIAM platform data collection events
- name: streaming
  description: High-throughput streaming data ingestion operations

defaultContentType: application/json

channels:
  log_data/ingested:
    description: >
      Event channel for raw log data ingestion. Logs are submitted to the
      XSIAM HTTP collector endpoint as structured JSON batches. Each log
      entry must include dataset, vendor, product, log_type, and raw_log
      fields to route the data to the correct parsing pipeline. The XSIAM
      ingestion engine parses, normalizes, and indexes the log data into
      the appropriate dataset for analytics and correlation.
    subscribe:
      operationId: onLogDataIngested
      summary: Raw log data ingested into XSIAM
      description: >
        Fired when raw log data is submitted to the XSIAM log ingestion
        endpoint. The payload conforms to the XSIAM HTTP collector schema
        with dataset routing metadata and raw log content.
      message:
        $ref: '#/components/messages/LogDataIngested'
      bindings:
        http:
          method: POST

  event_data/ingested:
    description: >
      Event channel for structured event data ingestion. Pre-parsed events
      with normalized field mappings are submitted directly to the XSIAM
      data lake, bypassing the raw log parsing pipeline. Each event must
      include dataset, vendor, product, log_type, and timestamp metadata
      along with the normalized event fields. Used when the source system
      has already normalized data into XSIAM-compatible field mappings.
    subscribe:
      operationId: onEventDataIngested
      summary: Structured event data ingested into XSIAM
      description: >
        Fired when pre-normalized event data is submitted to the XSIAM
        event ingestion endpoint for direct indexing into the data lake
        without additional parsing.
      message:
        $ref: '#/components/messages/EventDataIngested'
      bindings:
        http:
          method: POST

  xdr_data/forwarded:
    description: >
      Event channel for XDR data forwarding from integrated Palo Alto
      Networks products including PAN-OS firewalls, Prisma Access, Cortex
      XDR agents, and other Strata products. Forwarded XDR data is
      automatically normalized and correlated within XSIAM for unified
      threat detection and investigation across the Palo Alto Networks
      security platform.
    subscribe:
      operationId: onXdrDataForwarded
      summary: XDR data forwarded from a Palo Alto Networks product
      description: >
        Fired when telemetry data is forwarded from an integrated XDR-enabled
        product. The payload includes product identification, tenant context,
        event identification, and the forwarded log content.
      message:
        $ref: '#/components/messages/XdrDataForwarded'
      bindings:
        http:
          method: POST

components:
  messages:
    LogDataIngested:
      name: LogDataIngested
      title: Log Data Ingested
      summary: >
        Raw log data submitted to the XSIAM HTTP log collector for parsing
        and ingestion into the data lake
      contentType: application/json
      headers:
        type: object
        properties:
          x-xdr-auth-id:
            type: string
            description: >
              API key identifier for authenticating requests to the XSIAM
              HTTP collector. Provided as a numeric string.
          Authorization:
            type: string
            description: >
              API key value for authenticating requests to the XSIAM HTTP
              collector. Provided as a Bearer token or raw key string.
          Content-Encoding:
            type: string
            description: >
              Content encoding of the request body. Use 'gzip' for
              compressed payloads to improve ingestion throughput.
            enum:
            - gzip
            - identity
      payload:
        $ref: '#/components/schemas/LogDataPayload'
      examples:
      - name: FirewallTrafficLogIngestion
        summary: Batch of PAN-OS firewall traffic logs ingested via HTTP collector
        payload:
          dataset: firewall_traffic_raw
          vendor: Palo Alto Networks
          product: PAN-OS
          log_type: traffic
          raw_log: >-
            Nov 15 10:32:01 PA-3260 1,2024/01/15 10:32:01,012345678901,TRAFFIC,end,
            2049,2024/01/15 10:32:01,10.0.1.100,10.0.2.200,0.0.0.0,0.0.0.0,
            allow-web,,,web-browsing,vsys1,trust,untrust,ethernet1/1,ethernet1/2,
            default,2024/01/15 10:32:01,12345,1,54321,80,0,0,0x19,tcp,allow,1500,800,700
          timestamp: '2024-01-15T10:32:01.000Z'
          tenant_id: xsiam-tenant-001
          event_id: evt-20240115-103201-001

        x-microcks-default: true
    EventDataIngested:
      name: EventDataIngested
      title: Event Data Ingested
      summary: >
        Structured and normalized event data submitted directly to the XSIAM
        data lake for indexing without additional parsing
      contentType: application/json
      payload:
        $ref: '#/components/schemas/EventDataPayload'
      examples:
      - name: AuthenticationEventIngestion
        summary: Normalized authentication event submitted directly to data lake
        payload:
          dataset: authentication_events
          vendor: Microsoft
          product: Active Directory
          log_type: authentication
          raw_log: '{"EventID":4625,"AccountName":"jsmith","LogonType":3,"FailureReason":"Unknown user name or bad password"}'
          timestamp: '2024-01-15T10:28:00.000Z'
          tenant_id: xsiam-tenant-001
          event_id: evt-20240115-102800-002

        x-microcks-default: true
    XdrDataForwarded:
      name: XdrDataForwarded
      title: XDR Data Forwarded
      summary: >
        Telemetry data forwarded from a Palo Alto Networks XDR-enabled
        product to XSIAM for unified detection and correlation
      contentType: application/json
      payload:
        $ref: '#/components/schemas/XdrDataPayload'
      examples:
      - name: CortexXdrAgentForwarding
        summary: Endpoint telemetry forwarded from Cortex XDR agent
        payload:
          dataset: xdr_agent_raw
          vendor: Palo Alto Networks
          product: Cortex XDR Agent
          log_type: xdr_data
          raw_log: '{"type":"PROCESS_EVENT","hostname":"WORKSTATION-042","pid":4821,"process_name":"powershell.exe","command_line":"powershell.exe -enc base64encodedcommand","user":"DOMAIN\\jsmith"}'
          timestamp: '2024-01-15T10:35:00.000Z'
          tenant_id: xsiam-tenant-001
          event_id: evt-20240115-103500-003

        x-microcks-default: true
  schemas:
    LogDataPayload:
      type: object
      description: >
        The payload structure for raw log data ingestion via the XSIAM HTTP
        collector. Contains routing metadata to direct the log to the correct
        parsing pipeline, the raw log content, and optional event
        identification fields.
      required:
      - dataset
      - vendor
      - product
      - log_type
      - raw_log
      - timestamp
      - tenant_id
      - event_id
      properties:
        dataset:
          type: string
          description: >
            The target XSIAM dataset name that this log data should be
            indexed into. Dataset names correspond to XSIAM data lake
            tables and determine the schema applied during normalization.
          example: firewall_traffic_raw
        vendor:
          type: string
          description: >
            The name of the vendor that produced the log data. Used in
            combination with product and log_type to identify the correct
            parsing rule for normalizing the raw log content.
          example: Palo Alto Networks
        product:
          type: string
          description: >
            The name of the specific product or component that generated the
            log. Used in combination with vendor and log_type to route the
            log to the appropriate XSIAM parsing pipeline.
          example: PAN-OS
        log_type:
          type: string
          description: >
            The log type identifier that classifies the nature of the log
            content, such as traffic, threat, authentication, or syslog.
            Used to select the correct normalization schema.
          example: traffic
        raw_log:
          type: string
          description: >
            The raw log content in its original format as produced by the
            source system. May be a syslog message, CSV line, JSON string,
            CEF record, or any other log format supported by the configured
            XSIAM parsing rules.
          example: 'Nov 15 10:32:01 PA-3260 1,2024/01/15...'
        timestamp:
          type: string
          format: date-time
          description: >
            The ISO 8601 date-time string indicating when this log event
            occurred at the source. If not provided, the ingestion receipt
            time is used as the event timestamp.
          example: '2024-01-15T10:32:01.000Z'
        tenant_id:
          type: string
          description: >
            The XSIAM tenant identifier that this log data belongs to.
            Used for multi-tenant environments to route data to the correct
            tenant data lake partition.
          example: xsiam-tenant-001
        event_id:
          type: string
          description: >
            A unique identifier for this individual log event, generated by
            the submitting system or the XSIAM ingestion service. Used for
            deduplication and event correlation tracking.
          example: evt-20240115-103201-001

    EventDataPayload:
      type: object
      description: >
        The payload structure for pre-normalized event data ingestion directly
        into the XSIAM data lake. Contains all required routing metadata plus
        the normalized event content for direct dataset indexing.
      required:
      - dataset
      - vendor
      - product
      - log_type
      - raw_log
      - timestamp
      - tenant_id
      - event_id
      properties:
        dataset:
          type: string
          description: >
            The target XSIAM dataset name for direct indexing. Must match an
            existing dataset schema in the XSIAM data lake.
          example: authentication_events
        vendor:
          type: string
          description: >
            The vendor that produced the source event data.
          example: Microsoft
        product:
          type: string
          description: >
            The product that generated the source event.
          example: Active Directory
        log_type:
          type: string
          description: >
            The log type or event category identifier for schema selection
            during indexing.
          example: authentication
        raw_log:
          type: string
          description: >
            The original raw event content from the source system, preserved
            alongside normalized fields for audit and reprocessing purposes.
          example: '{"EventID":4625,"AccountName":"jsmith",...}'
        timestamp:
          type: string
          format: date-time
          description: >
            The ISO 8601 date-time string indicating when the original event
            occurred at the source system.
          example: '2024-01-15T10:28:00.000Z'
        tenant_id:
          type: string
          description: >
            The XSIAM tenant identifier for multi-tenant data routing.
          example: xsiam-tenant-001
        event_id:
          type: string
          description: >
            A unique identifier for this event record used for deduplication
            and correlation reference.
          example: evt-20240115-102800-002

    XdrDataPayload:
      type: object
      description: >
        The payload structure for XDR data forwarding from integrated Palo
        Alto Networks products. Contains product identification, tenant
        context, event identification, and the forwarded telemetry content
        for correlation in the XSIAM unified data lake.
      required:
      - dataset
      - vendor
      - product
      - log_type
      - raw_log
      - timestamp
      - tenant_id
      - event_id
      properties:
        dataset:
          type: string
          description: >
            The target XSIAM dataset name for the forwarded XDR data.
          example: xdr_agent_raw
        vendor:
          type: string
          description: >
            The Palo Alto Networks product vendor designation for the
            forwarding source. Typically 'Palo Alto Networks'.
          example: Palo Alto Networks
        product:
          type: string
          description: >
            The specific Palo Alto Networks product forwarding XDR data,
            such as Cortex XDR Agent, PAN-OS, Prisma Access, or
            Strata Logging Service.
          example: Cortex XDR Agent
        log_type:
          type: string
          description: >
            The XDR data type or telemetry category being forwarded
            (e.g., xdr_data, endpoint_event, network_event).
          example: xdr_data
        raw_log:
          type: string
          description: >
            The raw XDR telemetry content as serialized JSON from the
            forwarding product. Contains all available event fields from
            the source product's data model.
          example: '{"type":"PROCESS_EVENT","hostname":"WORKSTATION-042",...}'
        timestamp:
          type: string
          format: date-time
          description: >
            The ISO 8601 date-time string indicating when the XDR event
            was captured by the source product.
          example: '2024-01-15T10:35:00.000Z'
        tenant_id:
          type: string
          description: >
            The XSIAM tenant identifier to which this XDR data belongs.
            Ensures forwarded data is routed to the correct tenant
            environment in multi-tenant deployments.
          example: xsiam-tenant-001
        event_id:
          type: string
          description: >
            A unique identifier for this forwarded XDR event, used for
            deduplication, correlation, and audit trail tracking.
          example: evt-20240115-103500-003

  securitySchemes:
    apiKeyAuth:
      type: httpApiKey
      description: >
        API key authentication for XSIAM HTTP collector endpoints. Requires
        two headers: x-xdr-auth-id containing the API key ID (numeric), and
        Authorization containing the API key value. Both are generated in
        XSIAM Settings > Configurations > Integrations > API Keys.
      name: Authorization
      in: header