macOS Telemetry Schema

This page documents the complete schema for all telemetry event types collected by Workshop from Santa agents on macOS.

Each event type below is also the table-name prefix in SQL queries: Execution fields live in execution_2025, execution_202501, or execution_20250125 (see table naming). Columns drift across Santa versions, so DESCRIBE execution_20250125 on your own data is the authoritative list.

Contents

Event tables

• Process Events: execution, fork, exit, proc_suspend_resume, codesigning_invalidated
• File System Events: close, file_access, rename, link, unlink, clone, exchangedata, copyfile
• Authentication & Session Events: authentication, login_logout, login_window_session, open_ssh
• Security Events: allowlist, bundle, gatekeeper_override, tcc_modification, xprotect, screen_sharing
• System Events: disk, launch_item
• Network Events: network_activity
• Inventory Events: packages

Common types

ProcessID, UserInfo, GroupInfo, Hash, Stat, FileInfoLight, FileInfo, CodeSignature, CertificateInfo, Entitlement, EntitlementInfo, ProcessInfoLight, ProcessInfo, FileDescriptor, SocketAddress, GraphicalSession

Base Fields

Field	Type	Description
EventID	text	Unique identifier for the event
MachineID	text	The unique machine ID (host UUID)
Hostname	text	The hostname of the machine at the time of the event
BootSessionUUID	text	Unique identifier for the boot session
EventTime	timestamp	When the event occurred
ProcessedTime	timestamp	When Workshop processed the event
OperatingSystem	text	The platform the telemetry came from, always macos in these tables

Process Events

execution

Process execution events.

Field	Type	Description
Instigator	ProcessInfoLight	Parent process
Target	ProcessInfo	Executed process
Script	FileInfo	The script that was being executed, if applicable
WorkingDirectory	FileInfo	The working directory
Args	text array	Command-line arguments
Envs	text array	Environment variables
FDs	FileDescriptor array	The open file descriptors at time of execution
FDListTruncated	boolean	Whether the list in FDs is truncated
Decision	text	The decision that was made by Santa, e.g. DECISION_ALLOW
Reason	text	The reason that Santa made the decision it did, e.g. REASON_CERT
Mode	text	Santa's client mode at the time of the event, e.g. MODE_MONITOR
CertificateInfo	CertificateInfo	The common name and hash of the leaf certificate that signed this binary, if applicable
Explain	text	Possible additional context related to this execution
QuarantineURL	text	The URL the binary was downloaded from, if known
OriginalPath	text	The original on-disk path of the target executable, applies when binaries are translocated (https://developer.apple.com/forums/thread/724969)
EntitlementInfo	EntitlementInfo	The entitlements attached to this binary
RuleID	number	The ID of the rule that produced the decision, if applicable
StaticRule	boolean	Whether the decision came from a static (configuration profile) rule
AuditReturn	boolean	Whether the decision was made in audit (non-blocking) mode
TemporaryMonitorMode	boolean	Whether the reported Mode came from an active Temporary Monitor Mode session rather than the configured client mode

fork

Process fork events.

Field	Type	Description
Instigator	ProcessInfoLight	Parent process
Child	ProcessInfoLight	Child processes

exit

Process termination events.

Field	Type	Description
Instigator	ProcessInfoLight	Exiting process
ExitCode	number	Exit code of the process (set when process exits normally)
Signaled	number	Signal number that terminated the process (set when terminated by signal)
Stopped	number	Signal number that stopped the process (set when stopped by signal)

proc_suspend_resume

Process suspend and resume events.

Field	Type	Description
Instigator	ProcessInfoLight	The process that initiated the suspend/resume action
Target	ProcessInfo	The process being suspended or resumed
Type	text	The type of action, e.g. TYPE_SUSPEND

codesigning_invalidated

Code signature invalidation events.

Field	Type	Description
Instigator	ProcessInfoLight	Process with invalidated signature

File System Events

close

File close events.

Field	Type	Description
Instigator	ProcessInfoLight	The process closing the file
Target	FileInfo	The file being closed
Modified	boolean	Whether file was modified

file_access

File access monitoring events.

Field	Type	Description
Instigator	ProcessInfo	The process accessing the file
Target	FileInfo	The file being accessed
PolicyVersion	text	The version of the file-access policy
PolicyName	text	The name of the file-access policy
AccessType	text	The type of event that attempted access, e.g. ACCESS_TYPE_UNLINK
PolicyDecision	text	The decision that was made, e.g. POLICY_DECISION_ALLOWED_AUDIT_ONLY
OperationID	text	Unique operation identifier, used to link a single operation when a single operation violates multiple policies
RuleID	number	The ID of the file-access rule that produced the decision, if applicable

rename

File rename/move events.

Field	Type	Description
Instigator	ProcessInfoLight	The process that is renaming the file
Source	FileInfo	The source file
Target	text	The destination path
TargetExisted	boolean	Whether or not the destination path already existed

link

Hard link creation events.

Field	Type	Description
Instigator	ProcessInfoLight	The process making the link
Source	FileInfo	The source file
Target	text	Link path

unlink

File deletion events.

Field	Type	Description
Instigator	ProcessInfoLight	The process unlinking the file
Target	FileInfo	The deleted file info

clone

File clone (copy-on-write) events.

Field	Type	Description
Instigator	ProcessInfoLight	Process performing the clone
Source	FileInfo	Source file
Target	text	Clone destination

exchangedata

Atomic data exchange between files events.

Field	Type	Description
Instigator	ProcessInfoLight	Process performing the exchange
File1	FileInfo	First file
File2	FileInfo	Second file

copyfile

File copy events.

Field	Type	Description
Instigator	ProcessInfoLight	The process performing the copy
Source	FileInfo	The source file
Target	text	The destination path
TargetExisted	boolean	Whether or not the destination path already existed
Mode	number	The mode of the copied file
Flags	number	The copyfile flags for the operation

Authentication & Session Events

authentication

Authentication attempts. Exactly one of the subtype fields is populated, depending on the authentication method.

Field	Type	Description
Success	boolean	Authentication result
OD	OpenDirectory subtype	OpenDirectory authentication data, when the attempt used it
TouchID	TouchID subtype	Touch ID authentication data, when the attempt used it
Token	Token subtype	Token authentication data, when the attempt used it
AutoUnlock	AutoUnlock subtype	Auto unlock authentication data, when the attempt used it

OpenDirectory subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process performing the authentication
TriggerProcess	ProcessInfoLight	Process that triggered the authentication
TriggerID	ProcessID	Process ID of the trigger process
RecordType	text	OpenDirectory record type
RecordName	text	OpenDirectory record name
NodeName	text	OpenDirectory node name
DBPath	text	Path to the OpenDirectory database

TouchID subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process performing the authentication
TriggerProcess	ProcessInfoLight	Process that triggered the authentication
TriggerID	ProcessID	Process ID of the trigger process
Mode	text	Touch ID mode
User	UserInfo	User being authenticated

Token subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process performing the authentication
TriggerProcess	ProcessInfoLight	Process that triggered the authentication
TriggerID	ProcessID	Process ID of the trigger process
PubkeyHash	text	Hash of the public key
TokenID	text	Token identifier
KerberosPrincipal	text	Kerberos principal

AutoUnlock subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process performing the authentication
UserInfo	UserInfo	User being authenticated
Type	text	Auto unlock type

login_logout

Console login/logout events. This event type has subtypes for login and logout.

Login subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the login
Success	boolean	Whether login was successful
FailureMessage	text	Error message if login failed
User	UserInfo	User logging in

Logout subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the logout
User	UserInfo	User logging out

login_window_session

GUI session events. This event type has subtypes for different session actions.

Login subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the session login
User	UserInfo	User logging in
GraphicalSession	GraphicalSession	Graphical session information

Logout subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the session logout
User	UserInfo	User logging out
GraphicalSession	GraphicalSession	Graphical session information

Lock subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the session lock
User	UserInfo	User whose session is being locked
GraphicalSession	GraphicalSession	Graphical session information

Unlock subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the session unlock
User	UserInfo	User whose session is being unlocked
GraphicalSession	GraphicalSession	Graphical session information

open_ssh

SSH authentication events. This event type has subtypes for SSH login and logout.

Login subtype:

Field	Type	Description
Instigator	ProcessInfoLight	SSH daemon process
Result	text	Authentication result
Source	SocketAddress	Source address of the SSH connection
User	UserInfo	User attempting to log in

Logout subtype:

Field	Type	Description
Instigator	ProcessInfoLight	SSH daemon process
Source	SocketAddress	Source address of the SSH connection
User	UserInfo	User logging out

Security Events

allowlist

Binary allowlist addition events.

Field	Type	Description
Instigator	ProcessInfoLight	Process that added the binary to the allowlist
Target	FileInfo	Binary being added to the allowlist

bundle

Bundle hash events.

Field	Type	Description
FileHash	Hash	Hash of the individual file
BundleHash	Hash	Hash of the entire bundle
BundleName	text	Name of the bundle
BundleID	text	Bundle identifier
BundlePath	text	Path to the bundle
Path	text	Path to the file within the bundle

gatekeeper_override

Gatekeeper bypass events.

Field	Type	Description
Instigator	ProcessInfoLight	Process that bypassed Gatekeeper
Target	FileInfo	File that was allowed to run despite Gatekeeper
CodeSignature	CodeSignature	Code signing information

tcc_modification

TCC (Transparency, Consent, and Control) database modification events.

Field	Type	Description
Instigator	ProcessInfoLight	Process modifying TCC database
Service	text	TCC service being modified (e.g., camera, microphone)
Identity	text	Identity being granted/revoked access
IdentityType	text	Type of identity (bundle ID, path, etc.)
EventType	text	Type of modification event
AuthorizationRight	text	Authorization right being modified
AuthorizationReason	text	Reason for the authorization change
TriggerProcess	ProcessInfoLight	Process that triggered the modification
TriggerID	ProcessID	Process ID of the trigger process
ResponsibleProcess	ProcessInfoLight	Process responsible for the modification
ResponsibleID	ProcessID	Process ID of the responsible process

xprotect

XProtect malware detection and remediation events. This event type has subtypes for detection and remediation.

Detected subtype:

Field	Type	Description
Instigator	ProcessInfoLight	XProtect process that detected the malware
SignatureVersion	text	Version of the XProtect signature that detected the malware
MalwareIdentifier	text	Identifier for the detected malware
IncidentIdentifier	text	Unique identifier for this detection incident
DetectedPath	text	Path where malware was detected

Remediated subtype:

Field	Type	Description
Instigator	ProcessInfoLight	XProtect process that remediated the malware
SignatureVersion	text	Version of the XProtect signature
MalwareIdentifier	text	Identifier for the remediated malware
IncidentIdentifier	text	Unique identifier for this remediation incident
ActionType	text	Type of remediation action taken
Success	boolean	Whether remediation was successful
ResultDescription	text	Description of the remediation result
RemediatedPath	text	Path that was remediated
RemediatedProcessID	ProcessID	Process ID of the remediated process, if applicable

screen_sharing

Screen sharing connection events. This event type has subtypes for attach and detach.

Attach subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the screen sharing connection
Success	boolean	Whether the connection was successful
Source	SocketAddress	Source address of the connection
Viewer	text	Identifier of the viewer
AuthenticationType	text	Type of authentication used
AuthenticationUser	UserInfo	User that authenticated
SessionUser	UserInfo	User whose session is being shared
ExistingSession	boolean	Whether connecting to an existing session
GraphicalSession	GraphicalSession	Graphical session information

Detach subtype:

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the disconnection
Source	SocketAddress	Source address of the connection
Viewer	text	Identifier of the viewer
GraphicalSession	GraphicalSession	Graphical session information

System Events

disk

Disk mount/unmount events.

Field	Type	Description
Action	text	Whether the disk appeared or disappeared, e.g. ACTION_APPEARED
Mount	text	The path the disk is mounted at
Volume	text	The name of the volume that was attached
BSDName	text	The BSD name of the disk (e.g. /dev/disk2s1)
FS	text	The filesystem on the disk
Model	text	Device vendor and model information
Serial	text	The serial number of the attached disk
Bus	text	The bus path/protocol of the attached disk
DMGPath	text	The path of the backing disk image, if the disk is a disk image
Appearance	timestamp	The time the device appeared/disappeared
MountFrom	text	The path mounted from
Encrypted	boolean	Whether the disk is encrypted

launch_item

Launch item registration/removal events.

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the launch item registration
Action	text	Whether a launch item was added or removed, e.g. ACTION_ADD
TriggerProcess	ProcessInfoLight	The process that triggered registration (one of TriggerProcess or TriggerID will be set)
TriggerID	ProcessID	Process ID that triggered registration (one of TriggerProcess or TriggerID will be set)
RegistrantProcess	ProcessInfoLight	The app that registered the launch item (may be set)
RegistrantID	ProcessID	Process ID of the app that registered the launch item (may be set)
ItemType	text	The kind of item that was registered, e.g. ITEM_TYPE_AGENT, ITEM_TYPE_DAEMON
Legacy	boolean	Whether or not the launch item is a legacy plist
Managed	boolean	Whether or not the launch item is managed by MDM
ItemUser	UserInfo	User information related to the launch item
ItemPath	text	The location of the launch item
AppPath	text	The path of the app the launch item is attributed to
ExecutablePath	text	If available, the associated executable path from the launch item plist

Network Events

network_activity

Network connection activity events. Each row represents a single network connection associated with a process.

Field	Type	Description
Process	ProcessInfo	The process that initiated or received the flow
ID	text	Unique identifier for this flow
Hash	text	Hash of the flow
RemoteAddress	text	Remote IP address
RemotePort	number	Remote port number
RemoteHostname	text	Remote hostname, if known
LocalAddress	text	Local IP address
LocalPort	number	Local port number
ProtocolRaw	number	IANA protocol number
Protocol	text	Protocol name (e.g., TCP, UDP)
SocketFamily	text	Socket family (e.g., SOCKET_FAMILY_INET)
Direction	text	Flow direction (e.g., DIRECTION_OUTBOUND)
Decision	text	The decision that was made for the flow
DecisionTier	text	The tier that produced the decision
RuleID	number	The ID of the rule that produced the decision, if applicable
RuleName	text	The name of the rule that produced the decision, if applicable
BytesInbound	number	Number of bytes received
BytesOutbound	number	Number of bytes sent
StartTime	timestamp	When the flow started
CloseTime	timestamp	When the flow closed

info

LocalAddress is often 0.0.0.0 or :: for outbound flows. Santa records the flow when macOS first reports it, before macOS chooses the local interface.

RemoteHostname is present when the app resolved the hostname through Network framework, NSURLSession, or system DNS, or when another app resolved it shortly before. It is usually empty when the app connects to an IP address directly or uses its own DNS resolver. For hosts behind a CDN, the hostname can be a different name for the same address.

Inventory Events

Unlike every other table on this page, inventory tables are not populated by the continuous telemetry stream. They are produced on demand by the Package Inventory command (Hosts → Commands → Run command), which asks each targeted host to run a read-only scan and upload the results into its normal telemetry prefix. A host that has never been scanned has no rows.

Two consequences worth knowing when querying:

• BootSessionUUID is always empty. An on-demand scan isn't tied to a boot session.
• EventTime is the scan time, not the time a package was installed — the scan observes current state and has no visibility into when it came to be.

packages

One row per package discovered on a host. Every ecosystem shares this single table, distinguished by Ecosystem, so a fleet-wide query needs no unions.

Field	Type	Description
EventID	text	Unique identifier for the inventory record
MachineID	text	The unique machine ID (host UUID)
Hostname	text	The hostname of the scanned host
BootSessionUUID	text	Always empty because an inventory scan is not tied to a boot session
EventTime	timestamp	When the inventory scan observed the package
ProcessedTime	timestamp	When Workshop processed the inventory record
OperatingSystem	text	The platform the scanned host is running
RecordType	text	Always package in this table
RunID	text	Identifier shared by every row from one scan; use it to isolate a single scan's results
Profile	text	Scan profile that produced the row: baseline, project, or deep
Ecosystem	text	npm, pypi, go, rubygems, packagist, mcp, editor-extension, browser-extension, homebrew, agent-skill, or nix
PackageName	text	Package name as written in the manifest or lock file
NormalizedName	text	Ecosystem-normalized name — join on this rather than PackageName
Version	text	Installed version. Empty when no exact version could be determined
ProjectPath	text	Root of the project the package belongs to, for project-scoped finds
RootKind	text	Why the containing directory was walked: global_package_root, user_package_root, project_root, editor_extension_root, browser_extension_root, mcp_config_root, homebrew_root, nix_root, agent_skill_root, deep_home_root, or unknown
InstallScope	text	Ecosystem-specific dependency scope (e.g. prod/dev for npm and pnpm, indirect for Go modules)
PackageManager	text	Manager that installed the package (e.g. npm, pnpm, homebrew, firefox-extension)
SourceType	text	Kind of evidence the row came from (e.g. package.json, browser-extension)
SourceFile	text	Path to the manifest, lock file, or metadata file the row was read from
DirectDependency	boolean	Whether the package is directly depended on rather than transitive. Null when the ecosystem can't distinguish
HasLifecycleScripts	boolean	Whether the package declares install-time lifecycle scripts — these execute on install, so they are a supply-chain execution surface
LifecycleScripts	text array	Names of the declared lifecycle scripts
Confidence	text	How certain the identification is: high; medium when the name or version had to be inferred; or low when the row records that something is present without identifying what it is — an MCP server entry with no resolvable package, or an agent skill with no upstream source
RequestedSpec	text	For MCP entries configured by spec, the requested selector (e.g. @playwright/mcp@latest) with PackageName normalized to the bare name
LocalAlias	text	Local name assigned in a config file, where that differs from the package it resolves to. Set only for mcp (the key under mcpServers) and agent-skill (the local skill name)

Common Nested Types

The following types are used throughout the telemetry schema to represent shared data structures.

ProcessID

Unique identifier for a process during OS runtime.

Field	Type	Description
PID	number	Process ID
PIDVersion	number	Process ID version for tracking across PID reuse

UserInfo

User identification information.

Field	Type	Description
UID	number	User ID
Name	text	User name

GroupInfo

Group identification information.

Field	Type	Description
GID	number	Group ID
Name	text	Group name

Hash

Cryptographic hash information.

Field	Type	Description
Type	text	Hash algorithm (e.g., HASH_ALGO_SHA256)
Hash	text	Hash value

Stat

File metadata from stat(2) syscall.

Field	Type	Description
Dev	number	Device ID
Mode	number	File mode and permissions
Nlink	number	Number of hard links
Ino	number	Inode number
User	UserInfo	File owner
Group	GroupInfo	File group
Rdev	number	Device ID for special files
AccessTime	timestamp	Last access time
ModificationTime	timestamp	Last modification time
ChangeTime	timestamp	Last status change time
BirthTime	timestamp	Creation time
Size	number	File size in bytes
Blocks	number	Number of blocks allocated
Blksize	number	Block size for filesystem I/O
Flags	number	User defined flags
Gen	number	File generation number

FileInfoLight

Basic file information with path only.

Field	Type	Description
Path	text	File path
Truncated	boolean	Whether the path was truncated

FileInfo

Comprehensive file information.

Field	Type	Description
Path	text	File path
Truncated	boolean	Whether the path was truncated
Stat	Stat	File metadata
Hash	Hash	File content hash

CodeSignature

Code signing information.

Field	Type	Description
CDHash	text	Code directory hash (hex)
SigningID	text	Signing identifier
TeamID	text	Team identifier
SigningTime	timestamp	Signing timestamp
SecureSigningTime	timestamp	Secure timestamp from signing

CertificateInfo

Certificate information for signed code.

Field	Type	Description
Hash	Hash	Certificate hash
CommonName	text	Certificate common name

Entitlement

Individual entitlement key-value pair.

Field	Type	Description
Key	text	Entitlement key
Value	text	Entitlement value

EntitlementInfo

Collection of process entitlements.

Field	Type	Description
EntitlementsFiltered	boolean	Whether the entitlements list was filtered
Entitlements	Entitlement array	List of entitlements

ProcessInfoLight

Lightweight process information.

Field	Type	Description
ID	ProcessID	Process identifier
ParentID	ProcessID	Parent process identifier
OriginalParentPID	number	Original parent PID (before reparenting)
GroupID	number	Process group ID
SessionID	number	Session ID
EffectiveUser	UserInfo	Effective user
EffectiveGroup	GroupInfo	Effective group
RealUser	UserInfo	Real user
RealGroup	GroupInfo	Real group
Executable	FileInfoLight	Executable file path
Annotations	text array	Names of the annotations added to the process by CEL rules via add_annotation(), sorted

ProcessInfo

Full process information.

Field	Type	Description
ID	ProcessID	Process identifier
ParentID	ProcessID	Parent process identifier
ResponsibleID	ProcessID	Responsible process identifier
OriginalParentPID	number	Original parent PID (before reparenting)
GroupID	number	Process group ID
SessionID	number	Session ID
EffectiveUser	UserInfo	Effective user
EffectiveGroup	GroupInfo	Effective group
RealUser	UserInfo	Real user
RealGroup	GroupInfo	Real group
IsPlatformBinary	boolean	Whether this is a platform binary
IsESClient	boolean	Whether this is an Endpoint Security client
CodeSignature	CodeSignature	Code signing information
CSFlags	number	Code signing flags
Executable	FileInfo	Executable file information
TTY	FileInfoLight	Associated TTY device
StartTime	timestamp	Process start time
Annotations	text array	Names of the annotations added to the process by CEL rules via add_annotation(), sorted

FileDescriptor

An open file descriptor.

Field	Type	Description
FD	number	File descriptor number
FDType	text	The type of file descriptor, e.g. FD_TYPE_PIPE
PipeID	number	The unique ID of the pipe, when the descriptor is a pipe

SocketAddress

A network socket address.

Field	Type	Description
Address	bytes	The socket address
Type	text	The address type, e.g. SOCKET_ADDRESS_TYPE_IPV4

GraphicalSession

A graphical (windowed) session identifier.

Field	Type	Description
ID	number	Graphical session identifier