Skip to main content

Audit

Every change made to Workshop, whether by UI or API, is recorded in the audit logging system. This provides a complete record of all actions taken in your Workshop deployment for security, compliance, and debugging purposes.

Event Types​

Audit events are categorized by the type of resource or action being performed. Each event includes:

  • ID: A unique identifier for the event
  • Transaction ID: Links related events together (e.g., a vote that triggers rule creation)
  • Timestamp: When the event occurred
  • Actor: Who initiated the action (user, API key, host, or system)
  • Event Type: The specific action performed
  • Resource: The identifier of the affected resource
  • Outcome: Whether the action succeeded, failed, or was rejected
  • Details: Additional context about the event (often includes JSON data)
  • Previous Value: For update operations, the state before the change

Example Event Types​

Here are some common audit events tracked by Workshop:

API Keys

  • APIKEY_CREATE: A new API key was created
  • APIKEY_DELETE: An API key was deleted

Rules

  • RULE_UPSERT: A rule was created or updated
  • RULE_DELETE: A rule was removed

Hosts

  • HOST_CREATE: A new host registered with Workshop
  • HOST_UPDATE: Host information was modified
  • HOST_SYNC: Host synchronized with Workshop
  • HOST_CLEAN_SYNC: Host performed a clean sync (full rule refresh)
  • HOST_MANUAL_PUSH: Rules were manually pushed to a host

Tags

  • TAG_CREATE: A new tag was created
  • TAG_DELETE: A tag was removed
  • TAG_SET_ORDER: Tag resolution order was changed

Settings

  • SETTINGS_UPDATE_SYNC_SETTINGS: Santa sync settings were updated
  • SETTINGS_TELEMETRY_CLOUD_BUCKET_UPDATE: Telemetry export bucket configured
  • APPROVAL_WORKFLOW_SETTINGS_UPDATE: Approval workflow settings changed

Approval Workflows

  • SELF_SERVICE_RULE_CREATION: User created a rule via self-service
  • DESIGNATED_APPROVER_REQUEST: Approval request was submitted
  • DESIGNATED_APPROVER_REQUEST_APPROVE: Request was approved
  • DESIGNATED_APPROVER_REQUEST_REJECT: Request was rejected
  • VOTE_CAST: A vote was cast on a blockable

Risk Engine

  • RISK_ENGINE_EXCEPTION_CREATE: A risk engine exception was created
  • BLOCKABLE_FLAG_MALICIOUS: A blockable was flagged as malicious

Viewing Audit Events​

Accessing the Audit Log​

Navigate to the Audit page in the Workshop UI to view all audit events. The audit table provides:

  • Filtering: Search and filter by event type, actor, resource, outcome, and date range
  • Sorting: Sort by timestamp, event type, or outcome
  • Expandable Rows: Click any row to see full event details including JSON diffs for updates
  • Transaction Linking: Click a transaction ID to view all related events

Querying Examples​

Filter by event type: Use the event type filter to show only specific types of events, such as all rule changes or host syncs.

Filter by actor: Find all actions performed by a specific user, API key, or host by filtering on the actor field.

Filter by date range: Select a date range to view events within a specific time period.

View related events: Click on a transaction ID to see all events that are part of the same transaction. This is useful for tracking complex operations like approval workflows that generate multiple audit events.

Event Details​

When you expand an audit event row, you'll see:

  • Complete event metadata (ID, transaction ID, timestamp, actor)
  • The full resource identifier
  • Detailed information about what changed
  • For update operations, a side-by-side diff showing before and after values

Audit Log Export​

Workshop can automatically export audit logs to cloud storage for long-term retention, compliance requirements, or integration with external SIEM systems.

Configuring Export​

  1. Navigate to Settings → Audit Export
  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

Requirements:

  • The Workshop service account must have read/write access to the specified bucket:

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:PutObject"],
			"Resource": ["arn:aws:s3:::<bucket-name>/*"]
		}
	]
}

Export Behavior​

  • Audit events are exported once per hour
  • Each export batch is limited to 5,000 events
  • If you have a large number of existing audit events, the initial export after configuration may take several hours to complete
  • Events are written as newline-delimited JSON (NDJSON) files
  • The export process tracks the last exported event ID to ensure no events are missed
  • You can view the last exported event ID in the Settings page to monitor export progress
  • Export resumes automatically from the last checkpoint if interrupted

Exported Data Format​

Each line in the exported files is a complete JSON object representing one audit event, including all fields such as ID, timestamp, actor, event type, resource, outcome, details, and previous values.