Overview

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). Customers can seamlessly and flexibly integrate rich access data from Opal into their existing security logging stack for further auditing, notification, or detection purposes.

Getting Started

Step 1: Add Event Streaming Connection

Navigate to Settings > Event Streaming and click + Event Streaming Connection

Step 2: Enter a Name, URL, and Authorization Type

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. Then, click Add Connection.

📘

Test Message

Note: 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 e.g.,

{
  "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

Considerations

• Max # of connections: 3

Enabling and Disabling a Connection

When adding a new Event Stream Connection, it is Enabled by default.

In situations where you would like to Disable the connection (e.g. rotating an API Key, changing query parameters), toggle off the Connection Enabled. This will pause 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 in the last 30 days

Notifications will be sent to Admins:

• 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)

Examples of End Systems to Stream Events to:

Datadog

You can 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, navigate 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

You can 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

   1. If a hosted Collector doesn’t already exist, then create a new hosted Collector

4. Copy the HTTP source URL

5. In Opal, navigate 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: Authorization
      2. Value: Basic <base64 encoded Access Key from step 2>
      3. Select Header
   4. Click Add Connection