Events

The Events interface provides visibility into events across your Santa-protected fleet. This feature lets administrators track, analyze, and respond to what Santa saw and decided throughout your organization.

Events vs. telemetry

Workshop collects endpoint data in two separate streams, and they are easy to mix up. The short version: events tell you what to allow, telemetry tells you what happened.

Events

An event is something Santa decided and thought you should know about. Executions are only part of it. The Events section has a tab for each kind:

Whatever the kind, the shape is the same. An event is a small record built around the identifiers you need to write or change a rule: CDHash, binary SHA-256, Signing ID, Team ID, certificate, path, remote peer. Workshop stores them and you search them from this console. Rules, Approval Workflows and the Risk Engine all run off them. Event Export pushes them into a bucket of your own.

Execution events arrive out of the box. The rest appear only after you set up a policy that watches for them. An empty File Access or Network tab means nothing is configured, not that nothing is happening.

Signals are the odd one out. A signal is a CEL detection rule that runs on the host against telemetry. A match produces a signal report, and the report lands here in Events. Signals need telemetry enabled, so they are the one place where the two streams meet.

Telemetry

Telemetry is the raw record of what the machine did, with no policy applied. It covers forks and exits, every file write and rename, logins, SSH sessions, TCC changes, disk mounts, launch items and network activity. Executions are in there too, whether or not Santa had an opinion about them.

Each record holds more than an event does: the full argument vector, environment variables, entitlements, the parent process chain, the whole certificate chain. Telemetry lands in your own cloud storage bucket and you query it with SQL. Use it when something has already happened and you need to reconstruct it.

How often Santa uploads an event

Santa doesn’t upload an event for every execution. There would be far too many, so it drops repeats on the host. The throttling changes what the numbers in this console mean.

Blocks are never throttled. When Santa stops an execution, it sends the event straight away instead of waiting for the next sync. Blocked file access events work the same way.

Allowed executions are filtered twice.

First, most of them never become an event. By default Santa records an allowed execution only when the binary was unknown, which is what happens in Monitor mode, or when an audit rule matched. An execution that matched a rule you already wrote records nothing. You already know about it. Set EnableAllEventUpload if you want every allow recorded.

Second, whatever is left is throttled to one event per binary per host every 4 hours. Santa keeps an in-memory cache keyed on the binary’s SHA-256. A repeat inside that window is dropped, not queued. A tool that runs a thousand times a day produces at most six events on that host. Restarting the Santa daemon clears the cache.

Allowed events don’t go up straight away either. They wait in the host’s event table for the next sync, which runs every 10 minutes by default.

Other event types have their own windows:

:::warning Event counts are not execution counts

Counting rows in the events table won’t tell you how often a binary ran. Use telemetry, the aggregate counts in Reports, or the binary’s own execution history.

:::

Apple platform binaries produce no individual events unless you ask for them. They are the highest-volume decision, so Workshop keeps aggregate counts only. Those counts show up in reports, dashboard charts and a binary’s execution history. See Platform binaries to store each one instead.

Telemetry has none of these windows. Every occurrence of every event is recorded. The only thing that removes records is you. Filter Expressions drop or redact events on the host before upload, so if you configure any, your bucket holds what survived them.

Which one to use

Most work uses both. A block shows up in Events, you look at the binary, you write a rule. Later you want to know what else that process touched, or which other hosts saw it. That’s telemetry.

To cut telemetry volume before it leaves the host, see Filter Expressions.

Execution events

The execution events table displays information about each execution event:

• Host Name: The name of the endpoint where the event occurred
• File Name: The name of the executed binary
• Decision: Whether the execution was allowed or blocked
• Reason: The reason for the decision
• Timestamp: When the execution attempt occurred

Platform binaries

Executions that Santa allowed because the binary ships with the operating system are the highest-volume decision by a wide margin. By default Workshop records only their aggregate counts and does not retain or export the individual events.

To store each one instead, enable Platform binary events in the Sync section of a tag’s settings. The setting is per tag, so you can turn it on for a subset of your fleet. Expect a large increase in stored events: turn it on when you need platform binary executions to be searchable, filterable and exportable, and scope it to the hosts that need it.

Once stored, the events appear in the execution events table with a Reason of Platform. Filter the table by that reason to see them on their own.

The aggregate counts are recorded either way, so turning the setting on or off never changes the numbers in reports or charts. It only changes whether the individual events are kept.

A change can take up to 5 minutes to take effect on each host, because Workshop caches the resolved setting per host while it processes a host’s uploads.

Event details

Click a file name in the events table to open a detailed view with additional information about the binary:

• SHA-256: The cryptographic hash of the binary
• CDHash: The code directory hash used by macOS for code signing verification
• Team ID: The Apple Developer Team ID associated with the binary
• Signing ID: The signing identity used to sign the binary
• Entitlements: A list of entitlements granted to the binary
• First Seen: When this binary was first observed in your environment

Creating rules from event details

From the event details page, you can create execution rules directly using the Create Rule dropdown. The dropdown lets you pick which identifier type to use (CDHash, Binary SHA-256, Signing ID, Certificate SHA-256, or Team ID) based on the event’s binary.