Palo Alto Cortex XSIAM

SIEM Platform

Synopsis

The Palo Alto Cortex XSIAM target forwards events to a Cortex XSIAM HTTP Log Collector over HTTPS. It handles batching and delivery, sending newline-delimited JSON or text records under the collector's token. The same target works with a Cortex XDR HTTP Log Collector, which accepts the same requests.

Schema

- name: <string>
  description: <string>
  type: xsiam
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    url: <string>
    api_key: <string>
    format: <string>
    batch_size: <integer>
    timeout: <integer>
    field_format: <string>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration

The following fields are used to define the target:

Field	Required	Default	Description
`name`	Y		Target name
`description`	N	-	Optional description
`type`	Y		Must be `xsiam`
`pipelines`	N	-	Optional post-processor pipelines
`status`	N	`true`	Enable/disable the target

Connection

Field	Required	Default	Description
`url`	Y	-	The HTTP Log Collector's API URL, from Custom Collectors in Cortex XSIAM, e.g. `https://api-<tenant>.xdr.<region>.paloaltonetworks.com/logs/v1/event`. Takes an environment variable (`$env{XSIAM_URL}`) or a vault secret (`$secret{id=...}`) in place of the value
`api_key`	Y	-	The token Cortex XSIAM shows once, when the collector is created. Sent as the `Authorization` header exactly as stored, with no `Bearer` prefix. Takes a `$env{...}` or `$secret{...}` reference as `url` does
`format`	N	`json`	`json` or `text`. Must match the collector's Log Format: `json` for a JSON collector, sent as `application/json`; `text` for a Raw, CEF or LEEF collector, sent as `text/plain`
`max_bytes`	N	`1048576` (1 MB)	Maximum size of a single request body or batch, in bytes. The default is the size Cortex XSIAM recommends; it accepts up to 10 MB

note

max_bytes caps the size of a single request body or batch. It behaves differently from max_size on the file-writing targets, and the difference is easy to get wrong:

An explicit max_bytes: 0 IS honoured and removes the ceiling on targets that have no ceiling of their own. The value is read with Int64, which returns what you wrote — unlike max_size, which is read with MustInt64 and silently substitutes its default for a zero. Where a target has a fixed ceiling of its own, its page says so and a zero is clamped to that ceiling instead.
A negative value is rejected at configuration time with max_bytes must not be negative.

The ceiling is validated when the target is built and enforced again on every batch, so a value the receiving service will refuse fails early rather than per request.

Batch Configuration

Field	Required	Default	Description
`batch_size`	N	`1000`	Maximum records per POST, one record per line
`timeout`	N	`30`	HTTP client timeout, in seconds

Processing

Field	Required	Default	Description
`field_format`	N	-	Optional target-side normalization format applied before delivery. See applicable Normalization section

Scheduling

See Scheduling and Pool Behavior for interval and cron fields shared by all targets.

Debug Options

Field	Required	Default	Description
`debug.status`	N	`false`	Enable debug logging
`debug.dont_send_logs`	N	`false`	Process logs but don't send to target (testing)

Details

This target is transport-only. It sends each event as the pipeline leaves it, buffers events in memory, and delivers them as one HTTP POST, one record per line, once batch_size or max_bytes is reached or during finalization. Cortex XSIAM parses each line by the collector's own settings and stores it in the dataset named after the collector's vendor and product, <vendor>_<product>_raw.

Setting Up the Collector

In Cortex XSIAM, add an HTTP Log Collector under Custom Collectors and set:

Compression to uncompressed. The target does not compress its requests.
Log Format to the format your pipeline produces. Use JSON when the events reach the target as JSON documents, and Raw, CEF or LEEF when they are text. Then set format on the target to match.
Vendor and Product, which name the dataset the events land in.

Save the collector and copy the token it shows. Cortex XSIAM shows it only once: if it is lost, generate a new one and update api_key.

Endpoint and Authentication

url is the collector's API URL and api_key is its token, sent as the Authorization header with nothing in front of it. Configuration validation rejects a target that is missing either one, or whose format is not json or text. Both url and api_key resolve an environment variable or a vault secret reference ($env{NAME}, or the ${NAME} form the examples on this page use, and $secret{id=...}) when the target starts. A plain value is sent exactly as stored.

The URL names only the tenant and holds no credential. The token travels in a header, so it is not part of a logged URL. In the console, API key offers the Manual, Environment variable and Vault sources, and the URL field accepts only an https:// address.

Batching and Retry

Events buffer until batch_size or max_bytes is reached, then POST as a single request. A failed POST does not retry the batch internally: the buffer is cleared unconditionally after Finalize, and delivery failure is surfaced to the sender pool, which handles redelivery through the JetStream layer. Error responses include up to the first 1 MB of the response body for troubleshooting.

Cortex XSIAM accepts up to 400 requests per second for each endpoint, and answers 429 above that.

note

The target does not convert events to the collector's format. With format: json, every event must already be a JSON document when it reaches the target: a raw syslog line sent to a JSON collector is refused. Route such events through a pipeline that produces JSON, set field_format, or use a Raw collector with format: text.

Examples

Basic Configuration

Sending JSON events to a Cortex XSIAM HTTP Log Collector set to the JSON log format...

targets:
  - name: xsiam
    type: xsiam
    properties:
      url: "https://api-example.xdr.us.paloaltonetworks.com/logs/v1/event"
      api_key: "${XSIAM_API_KEY}"

CEF or Raw Text

Sending text records, such as CEF lines, to a collector set to the CEF, LEEF or Raw log format...

targets:
  - name: xsiam-cef
    type: xsiam
    properties:
      url: "${XSIAM_URL}"
      api_key: "${XSIAM_API_KEY}"
      format: text

High-Volume Configuration

Increasing batch size and timeout for high-volume ingestion, within the 10 MB request limit...

targets:
  - name: xsiam-high-volume
    type: xsiam
    properties:
      url: "${XSIAM_URL}"
      api_key: "${XSIAM_API_KEY}"
      batch_size: 5000
      max_bytes: 5242880
      timeout: 45

Troubleshooting

The xsiam target behaves the same way as the datadog target and reports the same errors for the same causes: a refused credential, a wrong or unreachable endpoint, certificate failures, rejected bodies, oversized records, throttling, and the silent failures that leave the target looking healthy. Use the Troubleshooting section of the Datadog target for the full list of errors, causes and fixes, and Target Delivery Errors for how Director logs and retries target failures.

Read those entries with this target's type in place of datadog. A refusal from the collector is logged as xsiam api returned status <code>: followed by the response body, up to its first 1 MB.

What differs

500 means the records do not match the collector's Log Format. Cortex XSIAM answers a format mismatch with 500 and the body {"error": "error processing request, error: failed to process the request"}, and Director adds (the records may not match the collector's Log Format; check the target's format against the collector's setting) to the log line. Check format against the collector's Log Format, and with format: json check that every event is a JSON document. Like every 5xx, it is retried until fixed, so no data is lost and the queue grows meanwhile. A real outage at Cortex XSIAM answers 500 as well, which is why it is not treated as permanent.
401 means a wrong token, or a collector that was disabled or deleted. api_key must be the token of the collector that url names. It is retried until fixed.
Both settings are required. A missing one is reported as xsiam target requires url (the HTTP Log Collector's API URL) or xsiam target requires api_key (the HTTP Log Collector's token), and a wrong format as xsiam format must be "json" or "text", got "<value>".
max_bytes defaults to 1048576 (1 MB), the size Cortex XSIAM recommends. It accepts up to 10 MB, so raising max_bytes past 10485760 turns a large batch into a 413, which loses that batch after four deliveries. Each record must also stay under 5 MB.
The body is newline-delimited, one record per line, so an event whose own text contains a raw newline reaches the collector as more than one line. A JSON collector keeps a multiline JSON document together on its own, and a Raw collector does when its Multiline Parsing Regex marks where an event starts. Without either, each line becomes a record of its own, so emit single-line records.

Synopsis​

Schema​

Configuration​

Connection​

Batch Configuration​

Processing​

Scheduling​

Debug Options​

Details​

Setting Up the Collector​

Endpoint and Authentication​

Batching and Retry​

Examples​

Basic Configuration​

CEF or Raw Text​

High-Volume Configuration​

Troubleshooting​

What differs​