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

Telemetry

Workshop provides powerful telemetry capabilities for analyzing Santa security events. The telemetry system integrates with Santa’s telemetry collection to store and enable querying of detailed endpoint activity data in cloud storage buckets.

Telemetry vs. events

Telemetry and Events are separate streams. Events are Santa’s policy decisions: executions, file access, network flows, mounts and signal reports. They stay small so you can turn them into rules. Every block is uploaded, but an allowed execution is reported at most once per binary per host every 4 hours, so event counts are not execution counts.

Telemetry records what the host did, with no policy applied, no throttling and more detail per record. Use it to work out after the fact what happened. The only thing that removes records is a Filter Expression you configured yourself.

Events vs. telemetry has the full comparison.

Querying telemetry

Table naming convention

Workshop uses dynamic table names:

Table FormatDescriptionExample
<event>_YYYYAll events of type for yearexecution_2025
<event>_YYYYMMEvents for specific monthexecution_202501
<event>_YYYYMMDDEvents for specific dayexecution_20250125
<event>_YYYY_<hostid>Host-specific eventsexecution_2025_a1b2c3d4
<event>_YYYYMM_<hostid>Host & month specificexecution_202501_a1b2c3d4
<event>_YYYYMMDD_<hostid>Host & date specificexecution_20250125_a1b2c3d4

Event Types: execution, fork, close, file_access, etc. For complete details on event types and their data, see the Schema page.

Schema discovery

There is no table catalog. Tables resolve from object storage when a query names one, so SHOW TABLES and information_schema return no rows. To see a table’s columns and types, run DESCRIBE on a table name, or SUMMARIZE for per-column statistics:

-- Columns and types for one day of execution events
DESCRIBE execution_20250125;

-- Per-column stats: min, max, approximate unique count, null percentage
SUMMARIZE SELECT * FROM execution_20250125 LIMIT 1000;

Columns vary across Santa versions, so DESCRIBE on your own data is the authoritative list. The Schema page documents every event type and field.

SQL examples

-- Count total execution events this year
SELECT COUNT(*) FROM execution_2025;

-- Recent execution events for a specific host
SELECT *
FROM execution_20250125_a1b2c3d4_e5f6_g7h8
LIMIT 10;

-- Execution events for a specific binary
SELECT *
FROM execution_20250125
WHERE Target.Executable.Hash.Hash = 'sha256-hash-here'
LIMIT 10;

-- Find processes with dangerous entitlements
SELECT EventTime, Hostname, Instigator.Executable.Path
FROM execution_20250125
WHERE list_contains(
  list_transform(EntitlementInfo.Entitlements, x -> x.Key),
  'com.apple.security.cs.allow-jit'
)
LIMIT 10;

-- Processes with specific environment variables
SELECT *
FROM execution_20250125
WHERE list_contains(
  list_transform(Envs, x -> starts_with(x, 'HOMEBREW_PREFIX=')),
  true
)
LIMIT 10;

-- Names the resolver said do not exist
SELECT Name, COUNT(*) AS n
FROM dns_activity_20260125
WHERE Outcome = 'OUTCOME_ANSWERED' AND RCode = 'NXDOMAIN'
GROUP BY Name
ORDER BY n DESC
LIMIT 10;

-- Everything that touched a name: questions and connections
SELECT 'dns' AS kind, StartTime, Process.Executable.Path AS process, Name AS name
FROM dns_activity_20260125
WHERE Name = 'github.com'
UNION ALL
SELECT 'flow', StartTime, Process.Executable.Path, RemoteHostname
FROM network_activity_20260125
WHERE RemoteHostname = 'github.com'
ORDER BY StartTime
LIMIT 10;

-- A lookup and the connection it led to: same host and process, the peer
-- address is in the answers, and the connection starts within 5 seconds
-- (a dual-stack socket reports an IPv4 peer as ::ffff:a.b.c.d)
SELECT d.Name, c.RemoteAddress, c.RemotePort
FROM dns_activity_20260125 d
JOIN network_activity_20260125 c
  ON c.MachineID = d.MachineID AND c.Process.ID = d.Process.ID
 AND list_contains(list_transform(d.Answers, a -> a.Data), regexp_replace(c.RemoteAddress, '^::ffff:', ''))
 AND c.StartTime BETWEEN d.CloseTime AND d.CloseTime + INTERVAL 5 SECOND
LIMIT 10;

Package and AI account inventory

The packages and ai_credentials tables are filled only when you run the Package inventory and AI account inventory commands, not by the continuous telemetry stream. A host that has never been scanned has no rows. See Package inventory results and AI account inventory results for how to find a scan’s output and for example queries.

Filtering telemetry on the client

Hosts can run CEL expressions to drop or redact events before they are uploaded to your bucket. This is useful for reducing volume, excluding noisy event types, or scrubbing sensitive values like tokens out of events. See Filter Expressions for details.

Additional resources

For detailed information about all event types and their complete schemas, see the Schema page.

For more information about Santa’s telemetry capabilities, visit Santa’s telemetry documentation.