santa.proto

// Important: This schema is currently in BETA

syntax = "proto3";

import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
import "Source/santad/ProcessTree/process_tree.proto";

option objc_class_prefix = "SNTPB";

package santa.pb.v1;

// User ID and associated username
message UserInfo {
  optional int32 uid = 1;
  optional string name = 2;
}

// Group ID and associated group name
message GroupInfo {
  optional int32 gid = 1;
  optional string name = 2;
}

// A process is uniquely identified on macOS by its pid and pidversion
message ProcessID {
  optional int32 pid = 1;
  optional int32 pidversion = 2;
}

// Code signature information
message CodeSignature {
  // The code directory hash identifies a specific version of a program
  optional bytes cdhash = 1;

  // The signing id of the code signature
  optional string signing_id = 2;

  // The team id of the code signature
  optional string team_id = 3;
}

// Stat information for a file
// Mimics data from `stat(2)`
message Stat {
  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;
}

// Hash value and metadata describing hash algorithm used
message Hash {
  enum HashAlgo {
    HASH_ALGO_UNKNOWN = 0;
    HASH_ALGO_SHA256 = 1;
  }

  optional HashAlgo type = 1;
  optional string hash = 2;
}

// File information
message FileInfo {
  // File path
  optional string path = 1;

  // Whether or not the path is truncated
  optional bool truncated = 2;

  // Stat information
  optional Stat stat = 3;

  // Hash of file contents
  optional Hash hash = 4;
}

// Light variant of `FileInfo` message to help minimize on-disk/on-wire sizes
message FileInfoLight {
  // File path
  optional string path = 1;

  // Whether or not the path is truncated
  optional bool truncated = 2;
}

// File descriptor information
message FileDescriptor {
  // Enum types gathered from `<sys/proc_info.h>`
  enum FDType {
    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 descriptor value
  optional int32 fd = 1;

  // Type of file object
  optional FDType fd_type = 2;

  // 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`
  optional uint64 pipe_id = 3;
}

// Process information
message ProcessInfo {
  // Process ID of the process
  optional ProcessID id = 1;

  // Process ID of the parent process
  optional ProcessID parent_id = 2;

  // Process ID of the process responsible for this one
  optional ProcessID responsible_id = 3;

  // Original parent ID, remains stable in the event a process is reparented
  optional int32 original_parent_pid = 4;

  // Process group id the process belongs to
  optional int32 group_id = 5;

  // Session id the process belongs to
  optional int32 session_id = 6;

  // Effective user/group info
  optional UserInfo effective_user = 7;
  optional GroupInfo effective_group = 8;

  // Real user/group info
  optional UserInfo real_user = 9;
  optional GroupInfo real_group = 10;

  // Whether or not the process was signed with Apple certificates
  optional bool is_platform_binary = 11;

  // Whether or not the process is an ES client
  optional bool is_es_client = 12;

  // Code signature information for the process
  optional CodeSignature code_signature = 13;

  // Codesigning flags for the process (from `<Kernel/kern/cs_blobs.h>`)
  optional uint32 cs_flags = 14;

  // File information for the executable backing this process
  optional FileInfo executable = 15;

  // File information for the associated TTY
  optional FileInfoLight tty = 16;

  // Time the process was started
  optional google.protobuf.Timestamp start_time = 17;

  optional process_tree.Annotations annotations = 18;
}

// Light variant of ProcessInfo message to help minimize on-disk/on-wire sizes
message ProcessInfoLight {
  // Process ID of the process
  optional ProcessID id = 1;

  // Process ID of the parent process
  optional ProcessID parent_id = 2;

  // Original parent ID, remains stable in the event a process is reparented
  optional int32 original_parent_pid = 3;

  // Process group id the process belongs to
  optional int32 group_id = 4;

  // Session id the process belongs to
  optional int32 session_id = 5;

  // Effective user/group info
  optional UserInfo effective_user = 6;
  optional GroupInfo effective_group = 7;

  // Real user/group info
  optional UserInfo real_user = 8;
  optional GroupInfo real_group = 9;

  // File information for the executable backing this process
  optional FileInfoLight executable = 10;

  optional process_tree.Annotations annotations = 11;
}

// Certificate information
message CertificateInfo {
  // Hash of the certificate data
  optional Hash hash = 1;

  // Common name used in the certificate
  optional string common_name = 2;
}

// Information about a single entitlement key/value pair
message Entitlement {
  // The name of an entitlement
  optional string key = 1;

  // The value of an entitlement
  optional string value = 2;
}

// Information about entitlements
message EntitlementInfo {
  // 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).
  optional bool entitlements_filtered = 1;

  // The set of entitlements associated with the target executable
  // Only top level keys are represented
  // Values (including nested keys) are JSON serialized
  repeated Entitlement entitlements = 2;
}

// Information about a process execution event
message Execution {
  // The process that executed the new image (e.g. the process that called
  // `execve(2)` or `posix_spawn(2)``)
  optional ProcessInfoLight instigator = 1;

  // Process info for the newly formed execution
  optional ProcessInfo target = 2;

  // 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 script = 3;

  // The current working directory of the `target` at exec time
  optional FileInfo working_directory = 4;

  // List of process arguments
  repeated bytes args = 5;

  // List of environment variables
  repeated bytes envs = 6;

  // List of file descriptors
  repeated FileDescriptor fds = 7;

  // Whether or not the list of `fds` is complete or contains partial info
  optional bool fd_list_truncated = 8;

  // Whether or not the target execution was allowed
  enum Decision {
    DECISION_UNKNOWN = 0;
    DECISION_ALLOW = 1;
    DECISION_DENY = 2;
  }
  optional Decision decision = 9;

  // The policy applied when determining the decision
  enum Reason {
    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;
  }
  optional Reason reason = 10;

  // The mode Santa was in when the decision was applied
  enum Mode {
    MODE_UNKNOWN = 0;
    MODE_LOCKDOWN = 1;
    MODE_MONITOR = 2;
  }
  optional Mode mode = 11;

  // Certificate information for the target executable
  optional CertificateInfo certificate_info = 12;

  // Additional Santa metadata
  optional string explain = 13;

  // Information known to LaunchServices about the target executable file
  optional string quarantine_url = 14;

  // The original path on disk of the target executable
  // Applies when executables are translocated
  optional string original_path = 15;

  // Entitlement information about the target executbale
  optional EntitlementInfo entitlement_info = 16;
}

// Information about a fork event
message Fork {
  // The forking process
  optional ProcessInfoLight instigator = 1;

  // The newly formed child process
  optional ProcessInfoLight child = 2;
}

// Information about an exit event
message Exit {
  // The process that is exiting
  optional ProcessInfoLight instigator = 1;

  // Exit status code information
  message Exited {
    optional int32 exit_status = 1;
  }

  // Signal code
  message Signaled {
    optional int32 signal = 1;
  }

  // Information on how/why the process exited
  oneof ExitType {
    Exited exited = 2;
    Signaled signaled = 3;
    Signaled stopped = 4;
  }
}

// Information about an open event
message Open {
  // The process that is opening the file
  optional ProcessInfoLight instigator = 1;

  // The file being opened
  optional FileInfo target = 2;

  // 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...)
  optional int32 flags = 3;
}

// Information about a close event
message Close {
  // The process closing the file
  optional ProcessInfoLight instigator = 1;

  // The file being closed
  optional FileInfo target = 2;

  // Whether or not the file was written to
  optional bool modified = 3;
}

// Information about an exchagedata event
// This event is not applicable to all filesystems (notably APFS)
message Exchangedata {
  // The process that is exchanging the data
  optional ProcessInfoLight instigator = 1;

  // File information for the two files in the exchangedata operation
  optional FileInfo file1 = 2;
  optional FileInfo file2 = 3;
}

// Information about a rename event
message Rename {
  // The process renaming the file
  optional ProcessInfoLight instigator = 1;

  // The source file being renamed
  optional FileInfo source = 2;

  // The target path when the rename is complete
  optional string target = 3;

  // Whether or not the target path previously existed
  optional bool target_existed = 4;
}

// Information about an unlink event
message Unlink {
  // The process deleting the file
  optional ProcessInfoLight instigator = 1;

  // The file being deleted
  optional FileInfo target = 2;
}

// Information about a processes codesigning invalidation event
message CodesigningInvalidated {
  optional ProcessInfoLight instigator = 1;
}

// Information about a link event
message Link {
  // The process performing the link
  optional ProcessInfoLight instigator = 1;

  // The source file being linked
  optional FileInfo source = 2;

  // The path of the new link
  optional string target = 3;
}

// Information about when disks are added or removed
message Disk {
  // Whether the disk just appeared or disappeared from the system
  enum Action {
    ACTION_UNKNOWN = 0;
    ACTION_APPEARED = 1;
    ACTION_DISAPPEARED = 2;
  }
  optional Action action = 1;

  // Volume path
  optional string mount = 2;

  // Volume name
  optional string volume = 3;

  // Media BSD name
  optional string bsd_name = 4;

  // Kind of volume
  optional string fs = 5;

  // Device vendor and model information
  optional string model = 6;

  // Serial number of the device
  optional string serial = 7;

  // Device protocol
  optional string bus = 8;

  // Path of the DMG
  optional string dmg_path = 9;

  // Time device appeared/disappeared
  optional google.protobuf.Timestamp appearance = 10;

  // Path mounted from
  optional string mount_from = 11;
}

// Information emitted when Santa captures bundle information
message Bundle {
  // This is the hash of the file within the bundle that triggered the event
  optional Hash file_hash = 1;

  // This is the hash of the hashes of all executables in the bundle
  optional Hash bundle_hash = 2;

  // Name of the bundle
  optional string bundle_name = 3;

  // Bundle identifier
  optional string bundle_id = 4;

  // Bundle path
  optional string bundle_path = 5;

  // Path of the file within the bundle that triggered the event
  optional string path = 6;
}

// Information for a transitive allowlist rule
message Allowlist {
  // The process that caused the allowlist rule to be generated
  optional ProcessInfoLight instigator = 1;

  // The file the new allowlist rule applies to
  optional FileInfo target = 2;
}

// Information about access to a watched path
message FileAccess {
  // The process that attempted to access the watched path
  optional ProcessInfo instigator = 1;

  // The path that was accessed
  optional FileInfoLight target = 2;

  // The version of the policy when the decision was made
  optional string policy_version = 3;

  // The name of the specific policy that triggered this log
  optional string policy_name = 4;

  // The event type that attempted to access the watched path
  enum AccessType {
    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;
  }
  optional AccessType access_type = 5;

  // Whether the operation was allowed or denied and why
  enum PolicyDecision {
    POLICY_DECISION_UNKNOWN = 0;
    POLICY_DECISION_DENIED = 1;
    POLICY_DECISION_DENIED_INVALID_SIGNATURE = 2;
    POLICY_DECISION_ALLOWED_AUDIT_ONLY = 3;
  }
  optional PolicyDecision policy_decision = 6;
}

// Session identifier for a graphical session
// Note: Identifiers are opaque and have no meaning outside of correlating Santa
// events with the same identifier
message GraphicalSession {
  optional uint32 id = 1;
}

// Information about a socket address and its type
message SocketAddress {
  // The socket address
  optional bytes address = 1;

  enum Type {
    TYPE_UNKNOWN = 0;
    TYPE_NONE = 1;
    TYPE_IPV4 = 2;
    TYPE_IPV6 = 3;
    TYPE_NAMED_SOCKET = 4;
  }

  // The type of the socket address
  optional Type type = 2;
}

// Information about a user logging in via loginwindow
message LoginWindowSessionLogin {
  // The process that emitted the login event
  optional ProcessInfoLight instigator = 1;

  // Name of the user logging in
  optional UserInfo user = 2;

  // Graphical session information for this session
  optional GraphicalSession graphical_session = 3;
}

// Information about a user logging out via loginwindow
message LoginWindowSessionLogout {
  // The process that emitted the logout event
  optional ProcessInfoLight instigator = 1;

  // Name of the user logging out
  optional UserInfo user = 2;

  // Graphical session information for this session
  optional GraphicalSession graphical_session = 3;
}

// Information about a user locking their session via loginwindow
message LoginWindowSessionLock {
  // The process that emitted the lock event
  optional ProcessInfoLight instigator = 1;

  // Name of the user locking their session
  optional UserInfo user = 2;

  // Graphical session information for this session
  optional GraphicalSession graphical_session = 3;
}

// Information about a user unlocking their session via loginwindow
message LoginWindowSessionUnlock {
  // The process that emitted the unlock event
  optional ProcessInfoLight instigator = 1;

  // Name of the user unlocking their session
  optional UserInfo user = 2;

  // Graphical session information for this session
  optional GraphicalSession graphical_session = 3;
}

// Information about loginwindow events
message LoginWindowSession {
  oneof event {
    LoginWindowSessionLogin login = 1;
    LoginWindowSessionLogout logout = 2;
    LoginWindowSessionLock lock = 3;
    LoginWindowSessionUnlock unlock = 4;
  }
}

// Information about a login event from the `login(1)` utility
message Login {
  // The process that emitted the login event
  optional ProcessInfoLight instigator = 1;

  // Whether or not the login was successful
  optional bool success = 2;

  // Login failure message, if applicable
  optional bytes failure_message = 3;

  // Information about the user that attempted to log in
  // Note: `uid` data may not always exist on failed attempts
  optional UserInfo user = 4;
}

// Information about a logout event from the `login(1)` utility
message Logout {
  // The process that emitted the logout event
  optional ProcessInfoLight instigator = 1;

  // Information about the user that logged out
  optional UserInfo user = 2;
}

// Information about login and logout events from the `login(1)` utility
message LoginLogout {
  oneof event {
    Login login = 1;
    Logout logout = 2;
  }
}

// Information related to Screen Sharing attaching to a graphical session
message ScreenSharingAttach {
  // The process that emitted the attach event
  optional ProcessInfoLight instigator = 1;

  // Whether or not the attach was successful
  optional bool success = 2;

  // Source address information
  optional SocketAddress source = 3;

  // Apple ID of the viewer
  optional bytes viewer = 4;

  // Type of authentication used
  optional bytes authentication_type = 5;

  // User that attempted authentication, if applicable
  optional UserInfo authentication_user = 6;

  // Username of the loginwindow session, if available
  optional UserInfo session_user = 7;

  // Whether or not there was an existing session
  optional bool existing_session = 8;

  // Graphical session information for this session
  optional GraphicalSession graphical_session = 9;
}

// Information related to Screen Sharing detaching from a graphical session
message ScreenSharingDetach {
  // The process that emitted the detach event
  optional ProcessInfoLight instigator = 1;

  // Source address information
  optional SocketAddress source = 2;

  // Apple ID of the viewer
  optional bytes viewer = 3;

  // Graphical session information for this session
  optional GraphicalSession graphical_session = 4;
}

// Information about Screen Sharing attach and detach events
message ScreenSharing {
  oneof event {
    ScreenSharingAttach attach = 1;
    ScreenSharingDetach detach = 2;
  }
}

// Information about SSH login events from the macOS OpenSSH implementation
message OpenSSHLogin {
  // The process that emitted the login event
  optional ProcessInfoLight instigator = 1;

  enum Result {
    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;
  }

  // The result of the login attempt
  // Note: Successful if type == `RESULT_AUTH_SUCCESS`
  optional Result result = 2;

  // Source address of the connection
  optional SocketAddress source = 3;

  // Name of the user that attempted to login
  // Note: `uid` data may not always exist on failed attempts
  optional UserInfo user = 4;
}

// Information about SSH logout events from the macOS OpenSSH implementation
message OpenSSHLogout {
  // The process that emitted the logout event
  optional ProcessInfoLight instigator = 1;

  // Source address of the connection
  optional SocketAddress source = 2;

  // Information about the user that logged out
  optional UserInfo user = 3;
}

// Information about login/logout events from the macOS OpenSSH implementation
message OpenSSH {
  oneof event {
    OpenSSHLogin login = 1;
    OpenSSHLogout logout = 2;
  }
}

// A message encapsulating a single event
message SantaMessage {
  // Machine ID of the host emitting this log
  // Only valid when EnableMachineIDDecoration configuration option is set
  optional string machine_id = 1;

  // Timestamp when the event occurred
  optional google.protobuf.Timestamp event_time = 2;

  // Timestamp when Santa finished processing the event
  optional google.protobuf.Timestamp processed_time = 3;

  // Event type being described by this message
  oneof event {
    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;
  };
}

message SantaMessageBatch {
  repeated SantaMessage messages = 1;
}

message LogBatch {
  repeated google.protobuf.Any records = 1;
}