--- title: "Schema - Workshop Docs" description: "Schema - Enterprise control plane for Santa. Manage rules, approvals, telemetry, and policies across your macOS fleet." doc_version: "1" last_updated: "2026-05-22" canonical: "https://northpole.security/docs/workshop/telemetry/schema" --- # 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](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) ### 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 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 ## Network Events ### network\_activity Network connection activity events. Each row represents a single network flow 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 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`) BytesInbound number Number of bytes received BytesOutbound number Number of bytes sent StartTime timestamp When the flow started CloseTime timestamp When the flow closed ## Sitemap - [Home](https://northpole.security/index.md) - [Workshop](https://northpole.security/workshop.md) - [Santa](https://northpole.security/santa.md) - [Features](https://northpole.security/features.md) - [Cookbook](https://northpole.security/cookbook.md) - [Docs](https://northpole.security/docs.md) - [Blog](https://northpole.security/blog.md) - [Glossary](https://northpole.security/glossary.md) - [About](https://northpole.security/about.md) - [Contact](https://northpole.security/contact.md)