package santa.pb.v1

Get desktop application:
View/edit binary Protocol Buffers messages

Information for a transitive allowlist rule

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process that caused the allowlist rule to be generated

• optional FileInfo target = 2

  The file the new allowlist rule applies to

Information emitted when Santa captures bundle information

Used in: SantaMessage

• optional Hash file_hash = 1

  This is the hash of the file within the bundle that triggered the event

• optional Hash bundle_hash = 2

  This is the hash of the hashes of all executables in the bundle

• optional string bundle_name = 3

  Name of the bundle

• optional string bundle_id = 4

  Bundle identifier

• optional string bundle_path = 5

  Bundle path

• optional string path = 6

  Path of the file within the bundle that triggered the event

Certificate information

Used in: Execution

• optional Hash hash = 1

  Hash of the certificate data

• optional string common_name = 2

  Common name used in the certificate

Information about a close event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process closing the file

• optional FileInfo target = 2

  The file being closed

• optional bool modified = 3

  Whether or not the file was written to

Code signature information

Used in: ProcessInfo

• optional bytes cdhash = 1

  The code directory hash identifies a specific version of a program

• optional string signing_id = 2

  The signing id of the code signature

• optional string team_id = 3

  The team id of the code signature

Information about a processes codesigning invalidation event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

Information about when disks are added or removed

Used in: SantaMessage

• optional Disk.Action action = 1

• optional string mount = 2

  Volume path

• optional string volume = 3

  Volume name

• optional string bsd_name = 4

  Media BSD name

• optional string fs = 5

  Kind of volume

• optional string model = 6

  Device vendor and model information

• optional string serial = 7

  Serial number of the device

• optional string bus = 8

  Device protocol

• optional string dmg_path = 9

  Path of the DMG

• optional google.protobuf.Timestamp appearance = 10

  Time device appeared/disappeared

• optional string mount_from = 11

  Path mounted from

Whether the disk just appeared or disappeared from the system

Used in: Disk

• ACTION_UNKNOWN = 0

• ACTION_APPEARED = 1

• ACTION_DISAPPEARED = 2

Information about a single entitlement key/value pair

Used in: EntitlementInfo

• optional string key = 1

  The name of an entitlement

• optional string value = 2

  The value of an entitlement

Information about entitlements

Used in: Execution

• optional bool entitlements_filtered = 1

  Whether or not the set of reported entilements is complete or has been filtered (e.g. by configuration or clipped because too many to log).

• repeated Entitlement entitlements = 2

  The set of entitlements associated with the target executable Only top level keys are represented Values (including nested keys) are JSON serialized

Information about an exchagedata event This event is not applicable to all filesystems (notably APFS)

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process that is exchanging the data

• optional FileInfo file1 = 2

  File information for the two files in the exchangedata operation

• optional FileInfo file2 = 3

Information about a process execution event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process that executed the new image (e.g. the process that called `execve(2)` or `posix_spawn(2)``)

• optional ProcessInfo target = 2

  Process info for the newly formed execution

• optional FileInfo script = 3

  Script file information Only valid when a script was executed directly and not as an argument to an interpreter (e.g. `./foo.sh`, not `/bin/sh ./foo.sh`)

• optional FileInfo working_directory = 4

  The current working directory of the `target` at exec time

• repeated bytes args = 5

  List of process arguments

• repeated bytes envs = 6

  List of environment variables

• repeated FileDescriptor fds = 7

  List of file descriptors

• optional bool fd_list_truncated = 8

  Whether or not the list of `fds` is complete or contains partial info

• optional Execution.Decision decision = 9

• optional Execution.Reason reason = 10

• optional Execution.Mode mode = 11

• optional CertificateInfo certificate_info = 12

  Certificate information for the target executable

• optional string explain = 13

  Additional Santa metadata

• optional string quarantine_url = 14

  Information known to LaunchServices about the target executable file

• optional string original_path = 15

  The original path on disk of the target executable Applies when executables are translocated

• optional EntitlementInfo entitlement_info = 16

  Entitlement information about the target executbale

Whether or not the target execution was allowed

Used in: Execution

• DECISION_UNKNOWN = 0

• DECISION_ALLOW = 1

• DECISION_DENY = 2

The mode Santa was in when the decision was applied

Used in: Execution

• MODE_UNKNOWN = 0

• MODE_LOCKDOWN = 1

• MODE_MONITOR = 2

The policy applied when determining the decision

Used in: Execution

• REASON_UNKNOWN = 0

• REASON_BINARY = 1

• REASON_CERT = 2

• REASON_COMPILER = 3

• REASON_PENDING_TRANSITIVE = 5

• REASON_SCOPE = 6

• REASON_TEAM_ID = 7

• REASON_TRANSITIVE = 8

• REASON_LONG_PATH = 9

• REASON_NOT_RUNNING = 10

• REASON_SIGNING_ID = 11

• REASON_CDHASH = 12

Information about an exit event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process that is exiting

• oneof ExitType

  Information on how/why the process exited

  • Exit.Exited exited = 2

  • Exit.Signaled signaled = 3

  • Exit.Signaled stopped = 4

Exit status code information

Used in: Exit

• optional int32 exit_status = 1

Signal code

Used in: Exit

• optional int32 signal = 1

Information about access to a watched path

Used in: SantaMessage

• optional ProcessInfo instigator = 1

  The process that attempted to access the watched path

• optional FileInfoLight target = 2

  The path that was accessed

• optional string policy_version = 3

  The version of the policy when the decision was made

• optional string policy_name = 4

  The name of the specific policy that triggered this log

• optional FileAccess.AccessType access_type = 5

• optional FileAccess.PolicyDecision policy_decision = 6

The event type that attempted to access the watched path

Used in: FileAccess

• ACCESS_TYPE_UNKNOWN = 0

• ACCESS_TYPE_OPEN = 1

• ACCESS_TYPE_RENAME = 2

• ACCESS_TYPE_UNLINK = 3

• ACCESS_TYPE_LINK = 4

• ACCESS_TYPE_CLONE = 5

• ACCESS_TYPE_EXCHANGEDATA = 6

• ACCESS_TYPE_COPYFILE = 7

• ACCESS_TYPE_CREATE = 8

• ACCESS_TYPE_TRUNCATE = 9

Whether the operation was allowed or denied and why

Used in: FileAccess

• POLICY_DECISION_UNKNOWN = 0

• POLICY_DECISION_DENIED = 1

• POLICY_DECISION_DENIED_INVALID_SIGNATURE = 2

• POLICY_DECISION_ALLOWED_AUDIT_ONLY = 3

File descriptor information

Used in: Execution

• optional int32 fd = 1

  File descriptor value

• optional FileDescriptor.FDType fd_type = 2

  Type of file object

• optional uint64 pipe_id = 3

  Unique id of the pipe for correlation with other file descriptors pointing to the same or other end of the same pipe Note: Only valid when `fd_type` is `FD_TYPE_PIPE`

Enum types gathered from `<sys/proc_info.h>`

Used in: FileDescriptor

• FD_TYPE_UNKNOWN = 0

• FD_TYPE_ATALK = 1

• FD_TYPE_VNODE = 2

• FD_TYPE_SOCKET = 3

• FD_TYPE_PSHM = 4

• FD_TYPE_PSEM = 5

• FD_TYPE_KQUEUE = 6

• FD_TYPE_PIPE = 7

• FD_TYPE_FSEVENTS = 8

• FD_TYPE_NETPOLICY = 9

• FD_TYPE_CHANNEL = 10

• FD_TYPE_NEXUS = 11

File information

Used in: Allowlist, Close, Exchangedata, Execution, Link, Open, ProcessInfo, Rename, Unlink

• optional string path = 1

  File path

• optional bool truncated = 2

  Whether or not the path is truncated

• optional Stat stat = 3

  Stat information

• optional Hash hash = 4

  Hash of file contents

Light variant of `FileInfo` message to help minimize on-disk/on-wire sizes

Used in: FileAccess, ProcessInfo, ProcessInfoLight

• optional string path = 1

  File path

• optional bool truncated = 2

  Whether or not the path is truncated

Information about a fork event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The forking process

• optional ProcessInfoLight child = 2

  The newly formed child process

Session identifier for a graphical session Note: Identifiers are opaque and have no meaning outside of correlating Santa events with the same identifier

Used in: LoginWindowSessionLock, LoginWindowSessionLogin, LoginWindowSessionLogout, LoginWindowSessionUnlock, ScreenSharingAttach, ScreenSharingDetach

• optional uint32 id = 1

Group ID and associated group name

Used in: ProcessInfo, ProcessInfoLight, Stat

• optional int32 gid = 1

• optional string name = 2

Hash value and metadata describing hash algorithm used

Used in: Bundle, CertificateInfo, FileInfo

• optional Hash.HashAlgo type = 1

• optional string hash = 2

Used in: Hash

• HASH_ALGO_UNKNOWN = 0

• HASH_ALGO_SHA256 = 1

Information about a link event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process performing the link

• optional FileInfo source = 2

  The source file being linked

• optional string target = 3

  The path of the new link

• repeated google.protobuf.Any records = 1

Information about a login event from the `login(1)` utility

Used in: LoginLogout

• optional ProcessInfoLight instigator = 1

  The process that emitted the login event

• optional bool success = 2

  Whether or not the login was successful

• optional bytes failure_message = 3

  Login failure message, if applicable

• optional UserInfo user = 4

  Information about the user that attempted to log in Note: `uid` data may not always exist on failed attempts

Information about login and logout events from the `login(1)` utility

Used in: SantaMessage

• oneof event

  • Login login = 1

  • Logout logout = 2

Information about loginwindow events

Used in: SantaMessage

• oneof event

  • LoginWindowSessionLogin login = 1

  • LoginWindowSessionLogout logout = 2

  • LoginWindowSessionLock lock = 3

  • LoginWindowSessionUnlock unlock = 4

Information about a user locking their session via loginwindow

Used in: LoginWindowSession

• optional ProcessInfoLight instigator = 1

  The process that emitted the lock event

• optional UserInfo user = 2

  Name of the user locking their session

• optional GraphicalSession graphical_session = 3

  Graphical session information for this session

Information about a user logging in via loginwindow

Used in: LoginWindowSession

• optional ProcessInfoLight instigator = 1

  The process that emitted the login event

• optional UserInfo user = 2

  Name of the user logging in

• optional GraphicalSession graphical_session = 3

  Graphical session information for this session

Information about a user logging out via loginwindow

Used in: LoginWindowSession

• optional ProcessInfoLight instigator = 1

  The process that emitted the logout event

• optional UserInfo user = 2

  Name of the user logging out

• optional GraphicalSession graphical_session = 3

  Graphical session information for this session

Information about a user unlocking their session via loginwindow

Used in: LoginWindowSession

• optional ProcessInfoLight instigator = 1

  The process that emitted the unlock event

• optional UserInfo user = 2

  Name of the user unlocking their session

• optional GraphicalSession graphical_session = 3

  Graphical session information for this session

Information about a logout event from the `login(1)` utility

Used in: LoginLogout

• optional ProcessInfoLight instigator = 1

  The process that emitted the logout event

• optional UserInfo user = 2

  Information about the user that logged out

Information about an open event

• optional ProcessInfoLight instigator = 1

  The process that is opening the file

• optional FileInfo target = 2

  The file being opened

• optional int32 flags = 3

  Bitmask of flags used to open the file Note: Represents the mask applied by the kernel, not the typical `open(2)` flags (e.g. FREAD, FWRITE instead of O_RDONLY, O_RDWR, etc...)

Information about login/logout events from the macOS OpenSSH implementation

Used in: SantaMessage

• oneof event

  • OpenSSHLogin login = 1

  • OpenSSHLogout logout = 2

Information about SSH login events from the macOS OpenSSH implementation

Used in: OpenSSH

• optional ProcessInfoLight instigator = 1

  The process that emitted the login event

• optional OpenSSHLogin.Result result = 2

  The result of the login attempt Note: Successful if type == `RESULT_AUTH_SUCCESS`

• optional SocketAddress source = 3

  Source address of the connection

• optional UserInfo user = 4

  Name of the user that attempted to login Note: `uid` data may not always exist on failed attempts

Used in: OpenSSHLogin

• RESULT_UNKNOWN = 0

• RESULT_LOGIN_EXCEED_MAXTRIES = 1

• RESULT_LOGIN_ROOT_DENIED = 2

• RESULT_AUTH_SUCCESS = 3

• RESULT_AUTH_FAIL_NONE = 4

• RESULT_AUTH_FAIL_PASSWD = 5

• RESULT_AUTH_FAIL_KBDINT = 6

• RESULT_AUTH_FAIL_PUBKEY = 7

• RESULT_AUTH_FAIL_HOSTBASED = 8

• RESULT_AUTH_FAIL_GSSAPI = 9

• RESULT_INVALID_USER = 10

Information about SSH logout events from the macOS OpenSSH implementation

Used in: OpenSSH

• optional ProcessInfoLight instigator = 1

  The process that emitted the logout event

• optional SocketAddress source = 2

  Source address of the connection

• optional UserInfo user = 3

  Information about the user that logged out

A process is uniquely identified on macOS by its pid and pidversion

Used in: ProcessInfo, ProcessInfoLight

• optional int32 pid = 1

• optional int32 pidversion = 2

Process information

Used in: Execution, FileAccess

• optional ProcessID id = 1

  Process ID of the process

• optional ProcessID parent_id = 2

  Process ID of the parent process

• optional ProcessID responsible_id = 3

  Process ID of the process responsible for this one

• optional int32 original_parent_pid = 4

  Original parent ID, remains stable in the event a process is reparented

• optional int32 group_id = 5

  Process group id the process belongs to

• optional int32 session_id = 6

  Session id the process belongs to

• optional UserInfo effective_user = 7

  Effective user/group info

• optional GroupInfo effective_group = 8

• optional UserInfo real_user = 9

  Real user/group info

• optional GroupInfo real_group = 10

• optional bool is_platform_binary = 11

  Whether or not the process was signed with Apple certificates

• optional bool is_es_client = 12

  Whether or not the process is an ES client

• optional CodeSignature code_signature = 13

  Code signature information for the process

• optional uint32 cs_flags = 14

  Codesigning flags for the process (from `<Kernel/kern/cs_blobs.h>`)

• optional FileInfo executable = 15

  File information for the executable backing this process

• optional FileInfoLight tty = 16

  File information for the associated TTY

• optional google.protobuf.Timestamp start_time = 17

  Time the process was started

• optional process_tree.Annotations annotations = 18

Light variant of ProcessInfo message to help minimize on-disk/on-wire sizes

Used in: Allowlist, Close, CodesigningInvalidated, Exchangedata, Execution, Exit, Fork, Link, Login, LoginWindowSessionLock, LoginWindowSessionLogin, LoginWindowSessionLogout, LoginWindowSessionUnlock, Logout, Open, OpenSSHLogin, OpenSSHLogout, Rename, ScreenSharingAttach, ScreenSharingDetach, Unlink

• optional ProcessID id = 1

  Process ID of the process

• optional ProcessID parent_id = 2

  Process ID of the parent process

• optional int32 original_parent_pid = 3

  Original parent ID, remains stable in the event a process is reparented

• optional int32 group_id = 4

  Process group id the process belongs to

• optional int32 session_id = 5

  Session id the process belongs to

• optional UserInfo effective_user = 6

  Effective user/group info

• optional GroupInfo effective_group = 7

• optional UserInfo real_user = 8

  Real user/group info

• optional GroupInfo real_group = 9

• optional FileInfoLight executable = 10

  File information for the executable backing this process

• optional process_tree.Annotations annotations = 11

Information about a rename event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process renaming the file

• optional FileInfo source = 2

  The source file being renamed

• optional string target = 3

  The target path when the rename is complete

• optional bool target_existed = 4

  Whether or not the target path previously existed

A message encapsulating a single event

Used in: SantaMessageBatch

• optional string machine_id = 1

  Machine ID of the host emitting this log Only valid when EnableMachineIDDecoration configuration option is set

• optional google.protobuf.Timestamp event_time = 2

  Timestamp when the event occurred

• optional google.protobuf.Timestamp processed_time = 3

  Timestamp when Santa finished processing the event

• oneof event

  Event type being described by this message

  • Execution execution = 10

  • Fork fork = 11

  • Exit exit = 12

  • Close close = 13

  • Rename rename = 14

  • Unlink unlink = 15

  • Link link = 16

  • Exchangedata exchangedata = 17

  • Disk disk = 18

  • Bundle bundle = 19

  • Allowlist allowlist = 20

  • FileAccess file_access = 21

  • CodesigningInvalidated codesigning_invalidated = 22

  • LoginWindowSession login_window_session = 23

  • LoginLogout login_logout = 24

  • ScreenSharing screen_sharing = 25

  • OpenSSH open_ssh = 26

• repeated SantaMessage messages = 1

Information about Screen Sharing attach and detach events

Used in: SantaMessage

• oneof event

  • ScreenSharingAttach attach = 1

  • ScreenSharingDetach detach = 2

Information related to Screen Sharing attaching to a graphical session

Used in: ScreenSharing

• optional ProcessInfoLight instigator = 1

  The process that emitted the attach event

• optional bool success = 2

  Whether or not the attach was successful

• optional SocketAddress source = 3

  Source address information

• optional bytes viewer = 4

  Apple ID of the viewer

• optional bytes authentication_type = 5

  Type of authentication used

• optional UserInfo authentication_user = 6

  User that attempted authentication, if applicable

• optional UserInfo session_user = 7

  Username of the loginwindow session, if available

• optional bool existing_session = 8

  Whether or not there was an existing session

• optional GraphicalSession graphical_session = 9

  Graphical session information for this session

Information related to Screen Sharing detaching from a graphical session

Used in: ScreenSharing

• optional ProcessInfoLight instigator = 1

  The process that emitted the detach event

• optional SocketAddress source = 2

  Source address information

• optional bytes viewer = 3

  Apple ID of the viewer

• optional GraphicalSession graphical_session = 4

  Graphical session information for this session

Information about a socket address and its type

Used in: OpenSSHLogin, OpenSSHLogout, ScreenSharingAttach, ScreenSharingDetach

• optional bytes address = 1

  The socket address

• optional SocketAddress.Type type = 2

  The type of the socket address

Used in: SocketAddress

• TYPE_UNKNOWN = 0

• TYPE_NONE = 1

• TYPE_IPV4 = 2

• TYPE_IPV6 = 3

• TYPE_NAMED_SOCKET = 4

Stat information for a file Mimics data from `stat(2)`

Used in: FileInfo

• optional int32 dev = 1

• optional uint32 mode = 2

• optional uint32 nlink = 3

• optional uint64 ino = 4

• optional UserInfo user = 5

• optional GroupInfo group = 6

• optional int32 rdev = 7

• optional google.protobuf.Timestamp access_time = 8

• optional google.protobuf.Timestamp modification_time = 9

• optional google.protobuf.Timestamp change_time = 10

• optional google.protobuf.Timestamp birth_time = 11

• optional int64 size = 12

• optional int64 blocks = 13

• optional int32 blksize = 14

• optional uint32 flags = 15

• optional int32 gen = 16

Information about an unlink event

Used in: SantaMessage

• optional ProcessInfoLight instigator = 1

  The process deleting the file

• optional FileInfo target = 2

  The file being deleted

User ID and associated username

Used in: Login, LoginWindowSessionLock, LoginWindowSessionLogin, LoginWindowSessionLogout, LoginWindowSessionUnlock, Logout, OpenSSHLogin, OpenSSHLogout, ProcessInfo, ProcessInfoLight, ScreenSharingAttach, Stat

• optional int32 uid = 1

• optional string name = 2