Obsidian Security

Overview

Obsidian Security collects Obsidian alerts, events and audit logs by polling the Obsidian Security API. Each record is forwarded with the original Obsidian JSON as the log body and tagged with obsidian.data_type:

Value	What it is
alert	Every alert on the Obsidian Alerts page: threats Obsidian detected with machine learning, expert rules and other methods, and alerts it takes in from connected services (for example Google Workspace alerts).
event	Activity in every connected SaaS service (Google Workspace, Salesforce, Microsoft, Zoom, …): who did what to which target, with the service's original event.
audit	User and admin activity inside the Obsidian platform itself.

One request covers every connected service; there is no tenant to configure.

Supported types: Logs

Supported platforms

• Linux: Logs
• Windows: Logs
• macOS: Logs

Requires collector v0.5.73 or later. Earlier releases do not build the Obsidian receiver, and the node will not be offered for older agents.

Authentication

Attach one Bearer Token (bearertokenauth) credential holding an Obsidian API token:

Field	Value
token	The Obsidian API token
scheme	Leave empty (means Bearer)

Create the token in Obsidian:

1. Sign in as an admin and go to Settings → API access tokens
2. Click Create token: role API, Full data access to all services and tenants, expiry Forever.
3. Copy the token into the credential's token field.

The token is stored encrypted and reaches the collector as a credential reference, never in plaintext in the pipeline config. A 401 or 403 in the collector log means the token is expired, revoked, in the wrong region, or missing data access.

Configuration

Field	Default	Description
Region (region)	US	The suffix of your Obsidian console URL: *.obsec.io is US, *.obsec.eu EU, *.sy.obsec.io AU. The token only works in its own region.
Collect Alerts / Events / Audit Logs	on	Turn each data set on or off.
Poll Interval (poll_interval)	60 s	How often alerts, events and audit logs are polled. Minimum 30 seconds.
Lookback (lookback)	86400 s (24 h)	On first start, how far back to collect alerts, events and audit logs. After that, collection continues from where it stopped.
Persist Offsets (persist_offsets)	on	Saves where each data type stopped, so a restart skips nothing. A few records at the resume point may be sent again. Off: every restart collects the last Lookback again.
Page Size (advanced.limit)	500	Alerts, events or audit logs per request, 1 to 1000.
Delay (advanced.delay)	300 s	Records are collected up to this far behind now, so records Obsidian is still writing are not skipped. 0 to 3600 seconds.
HTTP Timeout (advanced.timeout)	60 s	How long one request to Obsidian may take, including reading the response. Large event pages can take over 30 seconds.

How collection works

• The collector always connects to Obsidian over HTTPS and checks Obsidian's certificate against the system's trusted CAs. There are no TLS settings to configure.
• Alerts, events and audit logs are each read oldest first, from where the last poll stopped up to now − Delay, page by page. Alerts are read by when Obsidian raised them and events by when Obsidian processed them, so an alert or event recorded long after its activity is still collected. After every delivered page the time of its newest record is saved, so a restart resumes from that time with no gaps. Records at exactly that time are sent again, so a restart or failure can repeat a few records.
• What is saved is only one time per data type (where alerts, events and audit logs stopped), never a list of record IDs, so the saved state stays tiny however much data is collected.
• A time range holding more records than Obsidian returns for one query is read with several queries, so nothing is cut off. One poll reads at most 100 pages per data set; a large backlog (for example on first start) is caught up over the next polls.
• Alerts and audit logs are collected before events, so a large backlog of events never delays them.
• If the pipeline is busy, or Obsidian or the network is down, the next poll catches up; nothing is skipped.
• A poll that finds nothing new is normal: the source simply moves on to the next window.
• If a request to Obsidian fails (a server error that persists after retries, an empty response, or a timeout), that poll stops at the last delivered record and the next poll continues from there. The error appears in the collector log and on the node's error metrics; the other data types keep being collected. A 401 or 403 means the token needs attention (see Authentication).
• An alert is delivered when it is raised. Later changes to it (its workflow status) are not re-sent.

Output

Each record becomes one log:

• Body: the record's original JSON from Obsidian. Every field (actor, IP, service, event name, the service's original event, …) is here; none is duplicated into attributes.
• Attribute: only obsidian.data_type: alert, event or audit, which says where the record came from.
• Timestamp: the record's own time (alert eventDatetime, event datetime, audit timestamp).
• Severity: alerts use Obsidian's severity (CRITICAL, HIGH, MEDIUM, LOW); a failed audit action is WARN; everything else is INFO.

An alert's body carries the alert ID and ticket number, when it was raised (generatedDatetime) and when its activity happened (eventDatetime), severity, the detection (name, description, MITRE technique), actors and targets, the service, workflow status and resolution, and IP and location details.