Telemetry Schema

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

Base Fields

Field	Type	Description
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	text	When the event occurred
ProcessedTime	text	When Workshop processed the event

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	bytes	Code directory hash
SigningID	text	Signing identifier
TeamID	text	Team identifier
SecureSigningTime	timestamp	Secure timestamp from signing
SigningTime	timestamp	Signing timestamp

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	Array of Entitlement	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

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

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
EntitlementInfo	EntitlementInfo	The entitlements attached to this binary
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)

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)

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	FileInfoLight	The file being accessed
PolicyName	text	The name of the file-access policy
PolicyVersion	text	The version 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

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

Authentication & Session Events

authentication

Authentication attempts. This event type has subtypes with different fields depending on the authentication method.

Field	Type	Description
Success	boolean	Authentication result
OD	OpenDirectory	OpenDirectory authentication subtype data
TouchID	TouchID	Touch ID authentication subtype data
Token	Token	Token authentication subtype data
AutoUnlock	AutoUnlock	Auto unlock authentication subtype data

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
User	UserInfo	User logging in
Success	boolean	Whether login was successful
FailureMessage	text	Error message if login failed

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

openssh

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
DetectedPath	text	Path where malware was originally detected
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

launch_item

Launch item registration/removal events.

Field	Type	Description
Instigator	ProcessInfoLight	Process handling the launch item registration
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)
Action	text	Whether a launch item was added or removed, e.g. ACTION_ADD
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