Skip to main content

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 three 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

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 all binary executions detected by Santa on your macOS endpoints. This includes allowed and blocked executions, along with binary metadata and host information.

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

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.

You can provide access to your bucket to the Workshop service role using a bucket policy like the one below, replacing <123456789123> and <bucket-name> appropriately:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"AWS": "arn:aws:iam::<123456789123>:role/WorkshopTaskExecutionRole"
			},
			"Action": [
				"s3:GetBucketLocation",
				"s3:PutObject"
			],
			"Resource": ["arn:aws:s3:::<bucket-name>/*"]
		}
	]
}
tip

You can use the same bucket for all three event types, 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
    • Execution and File Access events are exported every 10 minutes
  • Each export batch is limited to 10,000 events
  • 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 many hours to complete
  • 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
  • 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.)