Documentation / Audit events for your SIEM

Audit events for your SIEM

The pull is not tied to one product. Splunk and Microsoft Sentinel are worked examples below. Elastic, Datadog, Sumo Logic, and Google SecOps collect the same feed, and so does any other collector that can store a cursor between polls. The key returns only your organization's events. The request has no organization parameter. Onaro's own security monitoring is a separate system and is not part of this feed.

Create the key

1. In Meridian, open Settings → Audit read keys.
2. Name the key for the collector, for example "Splunk production" or "Sentinel workspace", and choose Live or Test.
3. Select Create key. Copy the key before you close the dialog. Meridian stores only a hash, so a lost key cannot be shown again. Revoke it and create another.

The key's scope is audit:read. It can read this organization's audit events and nothing else. A revoked key is rejected on the next request.

The pull

Send the pull to https://api.onaro.io. A staging collector uses https://api-staging.onaro.io. Any other host does not serve this route.

GET https://api.onaro.io/api/v1/audit/events?since=0&limit=500
Authorization: Bearer <your audit:read key>

The response is JSON:

{
  "events": [ { "...": "one event" } ],
  "next_cursor": 120
}

• since is the cursor. Start at 0. It asks for events whose sequence number is greater than that value.
• next_cursor is the sequence number of the last event on this page when another page exists. Send it back as since. When next_cursor is null, you are caught up. Keep the cursor in the collector. It does not move backward.
• limit is 1 to 500. Optional event_type matches one action name. Optional start and end bound the event time.
• The key is limited to 60 reads a minute. A faster poll receives HTTP 429. A revoked or unknown key receives HTTP 401.

Fields

Each object in events has these fields:

• time: when the event happened, in milliseconds.
• class_uid, class_name, category_uid, category_name, and activity_id: a coarse class for the event.
• severity_id and status_id: a coarse success or failure mark.
• metadata.uid: the event id. metadata.product names Onaro Meridian.
• actor.user.uid and actor.user.email_addr: who did it, when that is known.
• src_endpoint.ip and http_request.user_agent.
• unmapped.sequence: the cursor value. unmapped.action is the event name, such as invite_sent or sign_in. unmapped.outcome is success or failure. unmapped.actor_kind, unmapped.error_code, unmapped.target_type, unmapped.target_id, unmapped.before, and unmapped.after carry the rest.

Some of those names also appear in OCSF. This response is the JSON above, not an OCSF event. A full mapping onto OCSF is a planned option.

Events are kept for 90 days, which is the Trust Center period for admin and security logs. A daily job then deletes older rows. A gap in sequence numbers after that cleanup is expected. Keep polling from the last cursor you stored.

You will not see another organization's events, even if you pass their cursor or add an organization query parameter. The route does not accept that parameter. A key from your Settings cannot be turned into a feed for anyone else.

Splunk

Use a scripted input or a modular input that performs the GET on a schedule. Store next_cursor in a checkpoint file or in KV Store, and send that value as since on the next run. Index the JSON body with sourcetype onaro:audit. Point the input at https://api.onaro.io, or at https://api-staging.onaro.io for a staging collector, and send the key only in the Authorization header.

1. Create a Live key named for this Splunk instance and put it in the input's secret store.
2. Schedule the input at one request a minute or slower, so the 60-read limit has room.
3. On each run, request since from the checkpoint. If next_cursor is a number, save it and request again until it is null.
4. If the key is revoked, the input starts receiving 401. Create a new key and update the secret. The cursor you already stored is still valid.

Microsoft Sentinel

Use a Logic App or an Azure Function on a timer. The timer calls the same GET, writes the events into a custom table with the Logs Ingestion API, and saves next_cursor in a storage blob or a table so the next run can send it as since.

1. Create a Live key named for the Sentinel workspace and store it in Key Vault.
2. The timer reads the checkpoint, then GETs https://api.onaro.io/api/v1/audit/events with the bearer key.
3. Send events to the custom table. Write next_cursor back to the checkpoint. Repeat while next_cursor is a number.
4. A 401 means the key was revoked. A 429 means the timer is polling faster than 60 reads a minute.

Other collectors

Elastic, Datadog, Sumo Logic, and Google SecOps use this same pull. Point an HTTPS input, a function, or an agent at the endpoint, send the audit key as a bearer token, and store next_cursor for the next poll. The fields, the cursor, and the 90-day retention are the ones above.