Skip to main content
Send a POST request to /api/sessions/start to ship a signed exercise archive to a SIEM destination. ThreatLab downloads the archive into memory, rebases log timestamps so the latest event lands two hours ahead of now, and delivers events to the target SIEM — all without writing anything to disk. Method: POST
Path: /api/sessions/start
Auth: Session cookie with manage_exercises capability

​
Request Body

​
archiveDownloadUrl
string
required
A signed URL pointing to the exercise archive. The archive must be a .zip file — .tar.gz is not supported on this endpoint.
​
siem
string
required
The SIEM name exactly as configured in Admin > Resources. ThreatLab resolves the destination driver and payload format from this value.
​
indexName
string
Override the destination index name. This field is ignored for syslog_tcp destinations and applies only to index-aware drivers like splunk_hec and elastic_bulk.
​
syslogSourceIdentity
string
Override the syslog source host for this shipment. Only applies to syslog_tcp destinations — when set, ThreatLab forces synthesized syslog headers with this value as the source host, regardless of the destination’s default Source identity or Header mode. Ignored on splunk_hec and elastic_bulk destinations.Typically set by the orchestrator to the per-exercise identifier produced by QRadar log source provisioning so every event lands on the right QRadar log source.

​
Shipping Behavior

ThreatLab selects the shipping path based on the destination’s configured payload_format: LEEF destinations (Splunk, syslog TCP — default): ThreatLab extracts .log and .txt files from the archive, rebases devTime so the latest event equals now plus two hours, applies the syslog envelope if applicable (supporting preserve_raw, synthesize_if_missing, and force_synthesize modes), and ships events line by line. ECS destinations (Elastic): ThreatLab extracts .ndjson and .json documents and bulk indexes them directly into the target Elastic index.
The archive must be a .zip file. ThreatLab validates this before downloading. Pass a properly signed URL from Supabase Storage or another pre-authorized source.

​
Response Fields

​
ok
boolean
true on success.
​
siem
string
The SIEM name used for this shipment.
​
driver
string
The resolved delivery driver: splunk_hec, syslog_tcp, or elastic_bulk.
​
events
number
Total number of log events shipped to the SIEM.
​
files
number
Number of files extracted from the archive and processed.
​
shiftDays
number
Number of days log timestamps were shifted forward to bring the latest event to now plus two hours.

​
Example

curl -X POST https://threatlab.your-org.com/api/sessions/start \
  -H 'Content-Type: application/json' \
  -H 'Cookie: sb-access-token=YOUR_TOKEN' \
  -d '{
    "archiveDownloadUrl": "https://storage.example.com/signed-url",
    "siem": "Splunk",
    "indexName": "threatlab-section-a"
  }'

​
Error Cases

StatusCause
401Not authenticated — no valid session cookie present
403Authenticated but missing the manage_exercises capability
400Invalid request body, missing required fields, or a non-.zip archive URL
500SIEM unreachable, connection refused, or an unexpected server error