package santa.sync.v1

Get desktop application:
View/edit binary Protocol Buffers messages

SantaSync is service used to distribute configuration settings and rules to Santa.

• rpc Preflight (PreflightRequest, PreflightResponse)

  syncv1.proto:16

  Preflight is used to send current configuration data to the server and to retrieve new configuration values from the server.

  message PreflightRequest

  syncv1.proto:37

  • string serial_number = 1

  • string hostname = 2

  • string os_version = 3

  • string os_build = 4

  • string model_identifier = 5

  • string santa_version = 6

  • string primary_user = 7

  • string push_notification_token = 8

  • ClientMode client_mode = 9

  • bool request_clean_sync = 10

  • uint32 binary_rule_count = 11

  • uint32 certificate_rule_count = 12

  • uint32 compiler_rule_count = 13

  • uint32 transitive_rule_count = 14

  • uint32 teamid_rule_count = 15

  • uint32 signingid_rule_count = 16

  • uint32 cdhash_rule_count = 17

  • string machine_id = 18

    The UUID of the machine that is sending this preflight.

  message PreflightResponse

  syncv1.proto:99

  • ClientMode client_mode = 1

    The client mode that the client should move into at the end of this sync. The mode does not change until the Postflight request has been made, to ensure the client has received all the needed rules before potentially going into Lockdown.

  • optional SyncType sync_type = 2

  • uint32 batch_size = 3

    Controls how many events Santa should upload in a single EventUpload request. If the server doesn't specify, the default is 50.

  • optional bool enable_bundles = 4

    Enable bundle hashing and bundle rules.

  • optional bool enable_transitive_rules = 5

    Enable transitive (ALLOWLIST_COMPILER) rules. Without this enabled, any received ALLOWLIST_COMPILER rules will be treated as ALLOWLIST.

  • optional bool enable_all_event_upload = 6

    Ordinarily, Santa will only upload events about executions that are denied or would be denied if the machine were in LOCKDOWN mode. With this enabled, Santa will upload details about all events.

  • optional bool disable_unknown_event_upload = 7

    Ordinarily, Santa will only upload events about executions that are denied or would be denied if the machine were in LOCKDOWN mode. With this enabled, Santa will NOT upload events for binaries that would have been blocked in LOCKDOWN.

  • uint32 full_sync_interval_seconds = 8

    Specifies the time interval in seconds between full syncs. Defaults to 600 (10 minutes). Cannot be set lower than 60.

  • uint32 push_notification_full_sync_interval_seconds = 9

    When push notifications are enabled, this overrides the full_sync_interval above. It is expected that Santa will not need to perform a full sync as frequently when push notifications are working. Defaults to 14400 (6 hours).

  • uint32 push_notification_global_rule_sync_deadline_seconds = 10

    The maximum number of seconds Santa can wait before triggering a rule sync after receiving a "global rule sync" notification. As these notifications cause every Santa client to try and sync, we add a random delay to each client to try and spread the load out on the sync server. This defaults to 600 (10 minutes).

  • optional string allowed_path_regex = 11

    These two regexes are used to allow/block executions whose path matches. The provided regex must conform to ICU format. While this feature can be useful, its use should be very carefully considered as it is much riskier than real rules.

  • optional string blocked_path_regex = 12

  • optional bool block_usb_mount = 13

    Enable USB mount blocking

  • repeated string remount_usb_mode = 14

    If set, if a mount of a USB device happens and the mount flags match, the mount will be allowed. If the flags do not match, Santa will deny the mount but then remount with the provided flags.

  • optional FileAccessAction override_file_access_action = 15

    Overrides the File Access Authorization (FAA) policy to change the performed action. Allowed values: `disable`: No action will be taken `auditonly`: Actions that would be denied are logged but allowed `none`: The policy will be applied as written

  • optional bool deprecated_enabled_transitive_whitelisting = 1000

    These fields are deprecated forms of other fields and exist here solely for backwards compatibility

  • optional bool deprecated_transitive_whitelisting_enabled = 1001

  • optional bool deprecated_bundles_enabled = 1002

  • optional uint32 deprecated_fcm_full_sync_interval_seconds = 1003

  • optional uint32 deprecated_fcm_global_rule_sync_deadline_seconds = 1004

  • optional string deprecated_whitelist_regex = 1005

  • optional string deprecated_blacklist_regex = 1006

  • optional bool deprecated_clean_sync = 1007

    Deprecated but still supported key that acts like sync_type was set to "CLEAN" unless the client had requested a clean sync, in which case it acts like "CLEAN_ALL"

• rpc EventUpload (EventUploadRequest, EventUploadResponse)

  syncv1.proto:20

  EventUpload sends details about blocked (or would-be-blocked) executions to the server.

  message EventUploadRequest

  syncv1.proto:239

  • repeated Event events = 1

  • string machine_id = 2

    The UUID of the machine where the event(s) occurred

  message EventUploadResponse

  syncv1.proto:245

  • repeated string event_upload_bundle_binaries = 1

    A list of SHA-256's of bundle binaries that need to be uploaded.

• rpc RuleDownload (RuleDownloadRequest, RuleDownloadResponse)

  syncv1.proto:23

  RuleDownload retrieves new rules from the server.

  message RuleDownloadRequest

  syncv1.proto:296

  • string cursor = 1

  • string machine_id = 2

    The UUID of the machine that is requesting the rules.

  message RuleDownloadResponse

  syncv1.proto:302

  • repeated Rule rules = 1

  • string cursor = 2

• rpc Postflight (PostflightRequest, PostflightResponse)

  syncv1.proto:27

  Postflight sends status data back to the server after applying any new configuration received in the previous stages.

  message PostflightRequest

  syncv1.proto:307

  • uint32 rules_received = 1

  • uint32 rules_processed = 2

  • string machine_id = 3

    The UUID of the machine that is sending this postflight.

  message PostflightResponse

  syncv1.proto:314

  (message has no fields)

Used in: Event

• string sha256 = 1

• string cn = 2

• string org = 3

• string ou = 4

• uint32 valid_from = 5

• uint32 valid_until = 6

ClientMode represents the operating mode for an agent.

Used in: PreflightRequest, PreflightResponse

• UNKNOWN_CLIENT_MODE = 0

• MONITOR = 1

• LOCKDOWN = 2

Used in: Event

• DECISION_UNKNOWN = 0

• ALLOW_UNKNOWN = 1

• ALLOW_BINARY = 2

• ALLOW_CERTIFICATE = 3

• ALLOW_SCOPE = 4

• ALLOW_TEAMID = 5

• ALLOW_SIGNINGID = 6

• ALLOW_CDHASH = 7

• BLOCK_UNKNOWN = 8

• BLOCK_BINARY = 9

• BLOCK_CERTIFICATE = 10

• BLOCK_SCOPE = 11

• BLOCK_TEAMID = 12

• BLOCK_SIGNINGID = 13

• BLOCK_CDHASH = 14

• BUNDLE_BINARY = 15

Used in: EventUploadRequest

• string file_sha256 = 1

• string file_path = 2

• string file_name = 3

• string executing_user = 4

• double execution_time = 5

• repeated string logged_in_users = 6

• repeated string current_sessions = 7

• Decision decision = 8

• string file_bundle_id = 9

• string file_bundle_path = 10

• string file_bundle_executable_rel_path = 11

• string file_bundle_name = 12

• string file_bundle_version = 13

• string file_bundle_version_string = 14

• string file_bundle_hash = 15

• uint32 file_bundle_hash_millis = 16

• uint32 file_bundle_binary_count = 17

• int32 pid = 18

  pid_t is an int32

• int32 ppid = 19

• string parent_name = 20

• string team_id = 21

• string signing_id = 22

• string cdhash = 23

• string quarantine_data_url = 24

• string quarantine_referer_url = 25

• uint32 quarantine_timestamp = 26

  Seconds since UNIX epoch. This field would ideally be an int64 but the protobuf library encodes that as a string, unlike NSJSONSerialization

• string quarantine_agent_bundle_id = 27

• repeated Certificate signing_chain = 28

Used in: PreflightResponse

• FILE_ACCESS_ACTION_UNSPECIFIED = 0

  An unspecified FileAccessAction will fallback to not changing any settings on the host

• NONE = 1

  The policy will be applied as written

• None = 1

• AUDIT_ONLY = 2

  Actions that would be denied are logged but allowed

• AuditOnly = 2

• DISABLE = 3

  No action will be taken

• Disable = 3

Used in: Rule

• POLICY_UNKNOWN = 0

• ALLOWLIST = 1

• ALLOWLIST_COMPILER = 2

• BLOCKLIST = 3

• SILENT_BLOCKLIST = 4

• REMOVE = 5

• WHITELIST = 1

  These enum values are deprecated and remain here for backward compatibility.

• WHITELIST_COMPILER = 2

• BLACKLIST = 3

• SILENT_BLACKLIST = 4

Used in: RuleDownloadResponse

• string identifier = 1

• Policy policy = 2

• RuleType rule_type = 3

• string custom_msg = 4

  For BLOCK_* rules, this will override the default block message shown to users.

• string custom_url = 5

  For BLOCK_* rules, this will override the URL used by the "Open" button in the UI. The same format values used by the EventDetailURL configuration value can be used here. See: https://santa.dev/deployment/configuration#eventdetailurl

• string file_bundle_hash = 6

  These two fields are used for bundle binaries.

• uint32 file_bundle_binary_count = 7

• string deprecated_sha256 = 1000

  Use identifier instead

Used in: Rule

• RULETYPE_UNKNOWN = 0

• BINARY = 1

• CERTIFICATE = 2

• TEAMID = 3

• SIGNINGID = 4

• CDHASH = 5

Used in: PreflightResponse

• SYNC_TYPE_UNSPECIFIED = 0

  An unspecified SyncType will fallback to default "NORMAL" handling

• NORMAL = 1

  Standard, progressive sync

• normal = 1

• CLEAN = 2

  Delete all non-transitive, previously received rules before applying the newly received rules.

• clean = 2

• CLEAN_ALL = 3

  Delete all previously received rules before applying the newly received rules.

• clean_all = 3