AI agents: see /llms.txt for a full index of this site, or /llms-full.txt for concatenated documentation.

Workshop Docs

Enterprise control plane for Santa. Manage rules, approvals, telemetry, and policies across your macOS fleet.

Workshop Docs
View chapters on this page

Event Export

Workshop can automatically export events to cloud storage for long-term retention, compliance requirements, or integration with external SIEM systems and analytics platforms.

Supported Event Types

Workshop supports exporting the following types of events:

  • Audit Events: All changes made to Workshop (rules, settings, tags, etc.)
  • Execution Events: Santa execution events from macOS endpoints
  • File Access Events: Santa file access monitoring events from macOS endpoints
  • Network Events: Santa network flow events from macOS endpoints
  • Removable Media Events: Santa removable media (e.g. USB mass storage device) mount events from macOS endpoints
  • Network Mount Events: Santa network mount events from macOS endpoints
  • Host Metrics: The latest CPU and memory reading Workshop holds for each endpoint

Each event type can be configured independently with its own cloud storage bucket.

Configuring Event Export

Navigate to Settings → Event Export to configure export settings for each event type.

Audit Event Export

Audit events track all changes made to Workshop, whether by UI or API. Exporting audit logs provides a complete record of all actions for security, compliance, and debugging purposes.

To configure:

  1. Navigate to the Audit Events section
  2. Enter your cloud storage bucket URL in one of these formats:
    • AWS S3: s3://your-bucket-name
    • Google Cloud Storage: gs://your-bucket-name
  3. Click Save Changes

See the Audit documentation for more details on audit event types and viewing audit logs.

Execution Event Export

Execution events record binary executions detected by Santa on your macOS endpoints. This includes allowed and blocked executions, along with binary metadata and host information.

Executions allowed because the binary is an Apple platform binary are not exported by default. Workshop keeps only their aggregate counts, so there are no individual events to export. To store and export them for a set of hosts, enable Platform binary events in the Sync section of a tag’s settings — see Platform binaries.

To configure:

  1. Navigate to the Execution Events section
  2. Enter your cloud storage bucket URL
  3. Click Save Changes

Execution events include details such as:

  • Binary SHA-256, file path, and signing information
  • Execution decision (allowed, blocked, or blocked by bundle)
  • Host information (hostname, primary user, OS version)
  • Process information (PID, PPID, executing user)
  • Tags applied to the host at execution time

File Access Event Export

File access events record Santa’s file access monitoring activity, which tracks access to protected paths on your endpoints.

To configure:

  1. Navigate to the File Access Events section
  2. Enter your cloud storage bucket URL
  3. Click Save Changes

File access events include:

  • Accessed file path and details
  • Access type and decision
  • Process information for the accessing application
  • Host and user information

Network Event Export

Network events record the network flows observed and evaluated by Santa’s network extension on your endpoints.

To configure:

  1. Navigate to the Network Events section
  2. Enter your cloud storage bucket URL
  3. Click Save Changes

Network events include:

  • Remote and local address and port, protocol, and direction
  • Resolved hostname for the flow
  • Flow decision, decision tier, and the rule that matched
  • Process information for the process that made the connection
  • Host and user information

Removable Media Event Export

Removable media event record Santa’s mount monitoring and blocking activity for things like USB devices.

To configure:

  1. Navigate to the Removable Media Events section
  2. Enter your cloud storage bucket URL
  3. Click Save Changes

Removable media events include:

  • Device details like protocol, model and vendor
  • Mount path and decision
  • Remount arguments if configured
  • Host and user information

Network Mount Event Export

Network mount event record Santa’s network filesystem mount monitoring and blocking activity.

To configure:

  1. Navigate to the Network Mount Events section
  2. Enter your cloud storage bucket URL
  3. Click Save Changes

Network mount events include:

  • Mount path from and mount path on
  • Filesystem type
  • Host and user information

Host Metrics Export

Santa reports on its own CPU and memory use as it syncs. Workshop keeps the latest reading for each host, and each export writes the current reading of every host, one record per host. This is a point-in-time picture of the fleet rather than a stream of events, so consecutive exports form the time series.

To configure:

  1. Navigate to the Host Metrics section
  2. Enter your cloud storage bucket URL
  3. Click Save Changes

Host metrics records include:

  • Host and user information
  • When Workshop last updated the reading
  • CPU used in user and in system mode, as a percentage of one core
  • Resident memory of the Santa daemon, in bytes

A percentage is measured between a host’s two most recent submissions, so it is absent until a host has submitted twice. Any value the host has not reported is left out of the record rather than written as zero.

Cloud Storage Access

The Workshop service account must have read/write access to the specified buckets. Both AWS S3 and Google Cloud Storage are supported.

:::tip You can use the same bucket for every event type, or configure separate buckets for organizational purposes. Events are written to different file paths based on type. :::

Export Behavior

Scheduling

  • Events are exported periodically
    • Audit events are exported once per hour
    • All other event types are exported every 10 minutes
  • Each export batch is limited to 25,000 records
  • If more events are available after a batch, export continues automatically until fewer than 1,000 events remain
  • Exports run independently for each event type

Initial Export

  • If you have a large number of existing events, the initial export after configuration may take some time to complete as it works through the backlog in batches
  • The export process will gradually work through historical events until it’s caught up

Progress Tracking

  • The export process tracks the last exported event ID for each event type
  • You can view the last exported event ID in the Settings page to monitor export progress
  • Click on the event ID to view that specific event in Workshop
  • Host metrics are a full dump with no per-record cursor, so the Settings page shows when the last export ran instead
  • Export resumes automatically from the last checkpoint if interrupted

Data Format

  • Events are written as newline-delimited JSON (NDJSON) files
  • Each line in the exported files is a complete JSON object representing one event
  • Files are organized by event type and timestamp
  • All event fields are included in the export (IDs, timestamps, metadata, details, etc.)