audit-forwarding

Audit Forwarding

Audit Forwarding is a fantastic feature offered by Segment. However, there are two limitations.

• You can't tell at a glance which workspace user triggered the event
• All events are named 'audit'

This Custom Source will:

1. Fetch the email address of the workspace user who triggered the event
2. Enhance event names

Note: The second enhancement allows Slack templates to be much more dynamic and only inlcude relevant fields. This repo includes slack templates you can use!

Getting Started

Prerequisites

Functions Access

You must have to access Functions. To request access to Functions, navigate to the Build page of the catalog here.

Workspace Access Token

You need a workspace access token. As a workspace owner, you can create access tokens via the Access Management page in Admin settings. All tokens are required to have a description.

Warning: Secret Token

Note that you can not retrieve the plain-text token later, so you should save it in a secret manager. If you lose the token you can generate a new one.

Step 1 - Custom Source Setup

1. Navigate to the Build page in the Catalog here and click on “Create Source”
2. Give your Custom Source a name
3. From the source overview page, click Write New Function to open the web editor
4. Copy the code from the handler.js file in this repo's folder and paste it into the Source Function Editor
5. Add two settings. To add a setting click on the settings within the Source Function Editor and click Add a Setting
6. Add a Text input setting with the name workspaceSlug and enter your workspace slug as a value.
7. Add a Text input setting with the name workspaceToken and enter your workspace access token as a value. Make sure to check the Encypted box!
8. Save your Function by pressing the blue Save button in the bottom left

Step 2 - setup HTTP Source and Webhook

Audit events do not function the same as 'regular' events. Thus you cannot forward Audits events directly to a Custom Source. Therefore we need to set up a Source that will receive the events and forward them to your Custom Source.

1. Create an HTTP API Source
2. Add a Webhooks destination
3. Go to Settings >> Connection Settings >> Webhooks URL
4. Enter the webhook URL from the Custom Source you created in step 1

Step 3 - Enable Audit Forwarding

1. Go to Settings >> Audit Forwarding
2. Press the dropdown and select the HTTP API Source you created in step 2
3. Toggle the button to enable Audit Forwarding

Set up Slack!

Setup

1. Follow these instructions to connect your Custom Function to a Slack Destination
2. For each event template, click Add another Event Name to create a new event setting
3. Enter the Event Name Regex Pattern into Segment Event Name field
4. Copy the corresponding Event Template into the Event Template field
5. Toggle on Regex Matching

Event Templates

Audience Events

Events
Audience Created
Audience Deleted
Audience Modified
Audience CSV Downloaded
Audience Run Failed
Audience Destination Sync Failed

Event Name Regex Pattern

^Audience

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Computed Trait Events

Events
Computed Trait Created
Computed Trait Modified
Computed Trait Deleted
Computed Trait CSV Downloaded
Computed Trait Run Failed
Computed Trait Destination Sync Failed

Event Name Regex Pattern

^Computed Trait

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Destination Filter Events

Events
Destination Filter Created
Destination Filter Modified
Destination Filter Enabled
Destination Filter Disabled
Destination Filter Deleted

Event Name Regex Pattern

^Destination Filter

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Integrations Events

Events
Integration Created
Integration Modified
Integration Enabled
Integration Disabled
Integration Deleted

Event Name Regex Pattern

^Integration

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}}\n 
*metadata_id:* {{properties.details.metadata_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*source_id:* {{properties.details.source_id}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Personas Warehouse Events

Events
Personas Warehouse Source Created
Personas Warehouse Source Modified
Personas Warehouse Source Deleted

Event Name Regex Pattern

^Personas Warehouse

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Schema Events

Events
Schema Default Edited To Allow Identify Traits On Violation
Schema Default Edited To Allow New Group Traits
Schema Group Property Allowed
Schema Group Property Blocked
Schema Default Edited To Omit New Identify Traits
Schema Identify Trait Archived
Schema Event Property Rule Edited To Required
Schema Event Property Conditions Edited
Schema Event Property Rule Edited To Forbidden
Schema Event Property Rule Edited To Optional
Schema Identify Trait Allowed
Schema Event Archived
Schema Identify Trait Blocked
Schema Event Blocked
Schema Event Allowed
Schema Default Edited To Allow New Events
Schema Default Edited To Omit Identify Traits On Violation
Schema Default Edited To Allow New Identify Traits
Schema Default Edited To Omit New Event Properties
Schema Default Edited To Allow Group Traits On Violation
Schema Default Edited To Omit New Group Traits
Schema Default Edited To Allow New Event Properties
Schema Default Edited To Block New Events
Schema JSON File Upload

Event Name Regex Pattern

^Schema

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}}\n 
*description:* {{properties.details.description}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*source_id:* {{properties.details.source_id}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Source Events

Events
Source Created
Source Modified
Source Enabled
Source Disabled
Source Deleted
Source Function Updated
Source Run Failed
Source Function Updated
Source Run Failed
Source Connected To Tracking Plan
Source Disconnected From Tracking Plan
Source Connected To Space
Source Disconnected From Space

Event Name Regex Pattern

^Source

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*source_id:* {{properties.details.source_id}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Space Events

Events
Space Created
Space Modified
Space Deleted

Event Name Regex Pattern

^Space

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Tracking Plan Events

Events
Tracking Plan Created
Tracking Plan Modified
Tracking Plan Deleted
Tracking Plan Inferred
Tracking Plan New Event Blocked
Tracking Plan New Event Allowed
Tracking Plan New Group Trait Omitted
Tracking Plan New Identify Trait Omitted
Tracking Plan New Track Property Omitted
Tracking Plan Operations Updated
Tracking Plan Updated

Event Name Regex Pattern

^Tracking Plan

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Violation Events

Events
Violations Detected

Event Name Regex Pattern

Violations Detected

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*timestamp:* {{timestamp}}

Warehouse Events

Events
Warehouse Created
Warehouse Modified
Warehouse Enabled
Warehouse Disabled
Warehouse Deleted
Warehouse Run Failed

Event Name Regex Pattern

^Warehouse

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*subject:* {{properties.details.subject}} \n 
*target:* {{properties.details.target}} \n 
*warehouse_id:* {{properties.details.warehouse_id}} \n 
*timestamp:* {{timestamp}}

System Events

Events
New Event Allowed

Event Name Regex Pattern

New Event Allowed

Event Template

:gear: *{{properties.type}}* \n 
*system_event:* This event was triggered by the system. \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*blocked:* {{properties.details.blocked}} \n 
*message_id:* {{properties.details.message_id}} \n 
*name:* {{properties.details.name}} \n 
*planned:* {{properties.details.planned}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*source_id:* {{properties.details.source_id}} \n 
*source_name:* {{properties.details.source_name}} \n 
*source_slug:* {{properties.details.source_slug}} \n 
*target:* {{properties.details.target}} \n 
*tracking_plan_connected:* {{properties.details.tracking_plan_connected}} \n 
*tracking_plan_id:* {{properties.details.tracking_plan_id}} \n 
*type:* {{properties.details.type}} \n 
*timestamp:* {{timestamp}}

Permission Check Event

Events
Permission Check

Event Name Regex Pattern

Permission Check

Event Template

:gear: *{{properties.type}}* \n 
*email:* {{properties.email}} \n 
*userId:* {{userId}} \n 
*workspace_id:* {{properties.workspace_id}} \n 
*action:* {{properties.details.action}} \n 
*resource_id:* {{properties.details.resource_id}} \n 
*resource_type:* {{properties.details.resource_type}} \n 
*sso_connection_id:* {{properties.details.sso_connection_id}} \n 
*subject_id:* {{properties.details.subject_id}} \n 
*subject_type:* {{properties.details.subject_type}} \n 
*timestamp:* {{timestamp}}

Want to Block Permission Check Events?

Uncomment the following code that is already in the Custom Source Function code.

if (requestBody.properties.type === 'Permission Check') {
  return;
}