Events Streaming

📘

The Events Streaming feature is not enabled by default, so you'll need to reach out to Opal Support to request it.

Events Streaming allows administrators set up a near real-time stream of Opal Events to a configured URL destination of choice (e.g. SIEM/logging sink). You can easily and flexibly integrate rich access data from Opal into your existing security logging stack for further auditing, notification, or detection purposes.

Configuration

Use the following steps to set up event streaming in Opal.

1. Add Event Streaming Connection

Go to Settings > Event Streaming and select + Event Streaming Connection.

2. Fill in connection details

1. Provide a Name for the Event Stream Connection.
2. Enter a URL webhook endpoint you would like Opal to send the Events payloads to.
3. Select your Authorization Type.
4. Click Add Connection.

📘

Test message

Opal will send a test POST message to the end system to ensure that the endpoint can be reached before allowing for the Connection to be successfully configured.

Authorization Types

1. API Key

Add a Key , Value pair via:

• Header (recommended)
• Query Parameter (not recommended for secrets)

2. HMAC

Verify that requests originated from Opal by checking signatures against a shared signing secret.

Opal adds X-Opal-Signature HTTP header on each request sent. The signature is created by combining the signing secret with the body of the request sent using a standard HMAC-SHA256 keyed hash.

A connection may have a max of 2 HMAC secrets to facilitate key rotation without any downtime. In this case, the value of X-Opal-Signature will be comma delimited (e.g., X-Opal-Signature: <signature 1>, <signature 2>), with each signature corresponding to one of the HMAC secrets.

How to: Verify HMAC Signature

const timestamp = request.header('X-Opal-Request-Timestamp')
const signingSecret = 'SIGNING_SECRET'
const sigBaseString = 'v0:' + timestamp + ':' + JSON.stringify(request.body)
const hmac = crypto.createHmac('sha256', signingSecret);
hmac.write(sigBaseString)
const actualSignature = hmac.digest('hex'))
const expectedSignature = request.header('X-Opal-Signature')

console.log("Are equal?", actualSignature === expectedSignature)

Events payload

All Event Streaming payloads have the same structure. Fields that are bespoke to the event_type will be nested under the data field, as in the following example object.

{
  "id": "cb8318b9-5719-4e5f-9740-a345650e22ca",
  "transaction_id": "491a0ece-5f7c-4227-957e-932977aca70b",
  "event_type": "EVENT_STREAM_CONNECTIONS_TESTED",
  "severity": "INFO",
  "timestamp": "2024-10-22T18:20:31.62251Z",
  "actor_email": "[email protected]",
  "actor_ip_address": "127.0.0.1",
  "actor_name": "Tester tester",
  "actor_user_id": "23b48b0e-db20-45ac-bb0c-7520e978d655",
  "actor_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
  "data": {
    "connection_type": "WEBHOOK",
    "message": "This is a test message to validate the event stream connection"
  }
}

Fields

Limitations

You can set up at most three connections.

Enable and disable connections

New Event Stream Connections are Enabled by default.

If you need to Disable the connection—e.g. you need to rotate an API Key or change query parameters—edit the connection, then disable the Connection Enabled toggle. This pauses streaming of events to the endpoint. If the connection is disabled for 7+ days, the next time it is re-enabled, it will stream from the latest events, instead of the time at which it was paused.

Errors and notifications

Errors and delivery failures

Admins can see a list of failed event deliveries from the last 30 days.

Notifications sent to admins

Notifications are sent to admins in the following cases:

• If messages for any connection failed to be delivered (daily notification)
• Connection has been auto-disabled by Opal due to an abnormally high failure rate (non- 200 Status Code, frequent timeouts, etc)

Example end systems to receive events

Datadog

To configure your Event Stream to point to directly to Datadog:

1. Get the Logs API URL that corresponds to your Datadog Site.
2. In Opal, go to event streaming (/settings#event-streaming), and create a new connection:
   1. Name the connection
   2. URL should be the one copied in the previous step
   3. Select API Key
      1. Key: DD-API-KEY
      2. Value:
      3. Select Header
3. [Optional] To include metadata, specify a second API Key for the Log API's ddtag query string parameter.
4. Click Add Connection.

Sumologic

To configure your Event Stream to point directly to Sumologic:

1. Generate an Access Key in Sumo Logic.
2. Base64 encode the Access Key.
3. In Sumo Logic, create an HTTP source for a hosted Collector. If a hosted Collector doesn’t already exist, then create a new hosted Collector
4. Copy the HTTP source URL.
5. In Opal, go to event streaming (/settings#event-streaming), and create a new connection:
   1. Name the connection.
   2. URL should be the one copied in the previous step.
   3. Select API Key and set the following values.
      1. Key: Authorization
      2. Value: Basic <base64 encoded Access Key from step 2>
      3. Select Header
6. Click Add Connection.