Crate endpoint_sec_sys

Available on macOS only.

Raw manual bindings for the Endpoint Security Framework for Apple targets (macOS) (referred to as ES in the following documentation).

Everything that was not present in the original release is feature gated to the macOS version that saw it released, so you can ensure you don’t use any newer functions and types. Additional checks are done at runtime to return None or an Err when using something not yet available, in the endpoint-sec crate. This crate does not perform the checks since it contains the raw types and extern "C" declaration. This is done because 1) the performance hit of a version check is negligible in my experience and 2) even if compiled for a newer version where information A is available, your program will still be able to handle older versions since A will be returned in an Option.

Debug implementations (and PartialEq, Eq, Hash)

Several types do not have a Debug implementation because it depends on the es_message_t version field. In this case, use the endpoint-sec crate, which bundle the version with the data (for example with es_event_exec_t), allowing to implement Debug, PartialEq, Eq and Hash correctly.

For lots of other types, it’s because the implementation would be useless because they contain pointers like es_string_token_t: implementing Debug for it in a useful way needs unsafe code that we don’t want to hide in a Debug impl. See the endpoint-sec crate, with its higher level types for useful Debug impls (and PartialEq, Eq, Hash).

Re-exports

• pub use block2;

Structs

• ShouldNotBeNull
  A wrapper type around *mut T to communicate a pointer should not be null without introducing undefined behaviour.
• _aclmacos_10_15_1
  Never use directly, use acl_t instead
• attrlist
• au_tid_t
• audit_token_t
  The audit token is an opaque token which identifies Mach tasks and senders of Mach messages as subjects to the BSM audit system. Only the appropriate BSM library routines should be used to interpret the contents of the audit token as the representation of the subject identity within the token may change over time.
• es_action_type_t
  Type of action to take after receiving a message
• es_address_type_t
  Type of a network address.
• es_auth_result_t
  Valid authorization values to be used when responding to a es_message_t auth event
• es_authentication_type_t
  This enum describes the types of authentications that ES_EVENT_TYPE_NOTIFY_AUTHENTICATION can describe.
• es_auto_unlock_type_t
  See es_event_authentication_auto_unlock_t.
• es_btm_item_type_t
  Type of launch item.
• es_btm_launch_item_tmacos_13_0_0
  Structure describing a BTM launch item
• es_clear_cache_result_t
  Error conditions for clearing the authorisation caches
• es_client_t
  Opaque type that stores the endpoint security client state.
• es_destination_type_t
• es_event_access_tmacos_10_15_1
  Test file access
• es_event_authentication_auto_unlock_tmacos_13_0_0
  Auto Unlock authentication data for type ES_AUTHENTICATION_TYPE_TOKEN.
• es_event_authentication_od_tmacos_13_0_0
  OpenDirectory authentication data for type ES_AUTHENTICATION_TYPE_OD.
• es_event_authentication_tmacos_13_0_0
  Notification that an authentication was performed.
• es_event_authentication_token_tmacos_13_0_0
  Token authentication data for type ES_AUTHENTICATION_TYPE_TOKEN.
• es_event_authentication_touchid_tmacos_13_0_0
  TouchID authentication data for type ES_AUTHENTICATION_TYPE_TOUCHID.
• es_event_btm_launch_item_add_tmacos_13_0_0
  Notification for launch item being made known to background task management. This includes launch agents and daemons as well as login items added by the user, via MDM or by an app.
• es_event_btm_launch_item_remove_tmacos_13_0_0
  Notification for launch item being removed from background task management. This includes launch agents and daemons as well as login items added by the user, via MDM or by an app.
• es_event_chdir_tmacos_10_15_1
  Changes directories
• es_event_chroot_tmacos_10_15_1
  Changes the root directory for a process
• es_event_clone_tmacos_10_15_1
  Clone a file
• es_event_close_t
  Close a file descriptor
• es_event_copyfile_tmacos_12_0_0
  Copy a file using the copyfile syscall.
• es_event_create_t
  Create a file system object.
• es_event_create_t_anon_0_anon_0
  See es_event_create_t_anon_0
• es_event_create_t_anon_1_anon_0macos_10_15_1
  See es_event_create_t_anon_1
• es_event_cs_invalidated_tmacos_11_0_0
  Code signing status for process was invalidated.
• es_event_deleteextattr_tmacos_10_15_1
  Delete an extended attribute
• es_event_dup_tmacos_10_15_1
  Duplicate a file descriptor
• es_event_exchangedata_t
  Exchange data atomically between two files
• es_event_exec_t
  Execute a new process
• es_event_exec_t_anon_0_anon_0
  See [es_event_exec_t_anon_0.anon_0]
• es_event_exit_t
  Terminate a process
• es_event_fcntl_tmacos_10_15_1
  File control
• es_event_file_provider_materialize_t
  Materialize a file via the FileProvider framework
• es_event_file_provider_update_t
  Update file contents via the FileProvider framework
• es_event_fork_t
  Fork a new process
• es_event_fsgetpath_tmacos_10_15_1
  Retrieve file system path based on FSID.
• es_event_get_task_inspect_tmacos_11_3_0
  Get a process’s task inspect port.
• es_event_get_task_name_tmacos_11_0_0
  Get a process’s task name port.
• es_event_get_task_read_tmacos_11_3_0
  Get a process’s task read port.
• es_event_get_task_t
  Get a process’s task control port.
• es_event_getattrlist_tmacos_10_15_1
  Retrieve file system attributes
• es_event_getextattr_tmacos_10_15_1
  Retrieve an extended attribute
• es_event_id_t
  Unique ID for an event
• es_event_iokit_open_t
  Open a connection to an I/O Kit IOService.
• es_event_kextload_t
  Load a kernel extension
• es_event_kextunload_t
  Unload a kernel extension
• es_event_link_t
  Link to a file
• es_event_listextattr_tmacos_10_15_1
  List extended attributes of a file
• es_event_login_login_tmacos_13_0_0
  Notification for authenticated login event from /usr/bin/login.
• es_event_login_logout_tmacos_13_0_0
  Notification for authenticated logout event from /usr/bin/login.
• es_event_lookup_t
  Lookup a file system object.
• es_event_lw_session_lock_tmacos_13_0_0
  Notification that LoginWindow locked the screen of a session.
• es_event_lw_session_login_tmacos_13_0_0
  Notification that LoginWindow has logged in a user.
• es_event_lw_session_logout_tmacos_13_0_0
  Notification that LoginWindow has logged out a user.
• es_event_lw_session_unlock_tmacos_13_0_0
  Notification that LoginWindow unlocked the screen of a session.
• es_event_mmap_t
  Memory map a file
• es_event_mount_t
  Mount a file system
• es_event_mprotect_t
  Control protection of pages
• es_event_open_t
  Open a file system object.
• es_event_openssh_login_tmacos_13_0_0
  Notification for OpenSSH login event.
• es_event_openssh_logout_tmacos_13_0_0
  Notification for OpenSSH logout event.
• es_event_proc_check_tmacos_10_15_4
  Access control check for retrieving process information
• es_event_proc_suspend_resume_tmacos_11_0_0
  Fired when one of pid_suspend, pid_resume or pid_shutdown_sockets is called on a process
• es_event_pty_close_tmacos_10_15_4
  Fired when a pseudoterminal control device is closed
• es_event_pty_grant_tmacos_10_15_4
  Fired when a pseudoterminal control device is granted
• es_event_readdir_tmacos_10_15_1
  Read directory entries
• es_event_readlink_t
  Resolve a symbolic link.
• es_event_remote_thread_create_tmacos_11_0_0
  Notification that a process has attempted to create a thread in another process by calling one of the thread_create or thread_create_running MIG routines
• es_event_remount_tmacos_10_15_1
  Remount a file system
• es_event_rename_t
  Rename a file system object.
• es_event_rename_t_anon_0_anon_0
  See es_event_rename_t_anon_0
• es_event_screensharing_attach_tmacos_13_0_0
  Notification that Screen Sharing has attached to a graphical session.
• es_event_screensharing_detach_tmacos_13_0_0
  Notification that Screen Sharing has detached from a graphical session.
• es_event_searchfs_tmacos_11_0_0
  Access control check for searching a volume or a mounted file system
• es_event_setacl_tmacos_10_15_1
  Set a file ACL.
• es_event_setattrlist_t
  Modify file system attributes
• es_event_setegid_tmacos_12_0_0
  Notification that a process has called setegid()
• es_event_seteuid_tmacos_12_0_0
  Notification that a process has called seteuid()
• es_event_setextattr_t
  Set an extended attribute
• es_event_setflags_t
  Modify file flags information.
• es_event_setgid_tmacos_12_0_0
  Notification that a process has called setgid()
• es_event_setmode_t
  Modify file mode.
• es_event_setowner_t
  Modify file owner information
• es_event_setregid_tmacos_12_0_0
  Notification that a process has called setregid()
• es_event_setreuid_tmacos_12_0_0
  Notification that a process has called setreuid()
• es_event_settime_tmacos_10_15_1
  Modify the system time
• es_event_setuid_tmacos_12_0_0
  Notification that a process has called setuid()
• es_event_signal_t
  Send a signal to a process.
• es_event_stat_tmacos_10_15_1
  View stat information of a file
• es_event_trace_tmacos_11_0_0
  Fired when one process attempts to attach to another process
• es_event_truncate_t
  Truncate to a file
• es_event_type_t
  The valid event types recognized by Endpoint Security.
• es_event_uipc_bind_tmacos_10_15_1
  Fired when a UNIX-domain socket is about to be bound to a path
• es_event_uipc_connect_tmacos_10_15_1
  Fired when a UNIX-domain socket is about to be connected.
• es_event_unlink_t
  Unlink a file system object.
• es_event_unmount_t
  Unmount a file system
• es_event_utimes_tmacos_10_15_1
  Change file access and modification times (e.g. via utimes(2))
• es_event_write_t
  Write to a file
• es_event_xp_malware_detected_tmacos_13_0_0
  Notification that XProtect detected malware.
• es_event_xp_malware_remediated_tmacos_13_0_0
  Notification that XProtect remediated malware.
• es_fd_tmacos_11_0_0
  An open file descriptor
• es_fd_t_anon_0_pipemacos_11_0_0
  Pipe information available in es_fd_t if the fdtype field is PROX_FDTYPE_PIPE
• es_file_t
  Provides the stat information and path to a file that relates to a security event. The path may be truncated, which is indicated by the path_truncated flag.
• es_get_task_type_t
• es_message_t
  This is the top level datatype that encodes information sent from the ES subsystem to its clients. Each security event being processed by the ES subsystem will be encoded in an es_message_t. A message can be an authorization request or a notification of an event that has already taken place.
• es_mute_inversion_type_t
• es_mute_inverted_return_t
  Return type for mute inversion
• es_mute_path_type_t
  Values that will be paired with path strings to describe the type of the path
• es_muted_path_t
  Structure to describe attributes of a muted path
• es_muted_paths_t
  Structure for a set of muted paths
• es_muted_process_t
  Structure to describe attributes of a muted process
• es_muted_processes_t
  Structure for a set of muted processes
• es_new_client_result_t
  Error conditions for creating a new client
• es_openssh_login_result_type_t
  See es_event_openssh_login_t
• es_proc_check_type_t
  This enum describes the type of es_event_proc_check_t events that are currently used.
• es_proc_suspend_resume_type_t
  This enum describes the type of suspend/resume operations that are currently used
• es_process_t
  Information related to a process. This is used both for describing processes that performed an action (e.g. in the case of the [es_message_t.process] field, or are targets of an action (e.g. for exec events this describes the new process being executed, for signal events this describes the process that will receive the signal).
• es_respond_result_t
  Error conditions for responding to a message
• es_result_t
  Indicates the result of the ES subsystem authorization process
• es_result_type_t
  Valid authorization values to be used when responding to a es_message_t auth event
• es_return_t
  Return value for functions that can only fail in one way
• es_set_or_clear_t
  Whether an ACL is being set or cleared
• es_string_token_t
  Structure for handling strings
• es_thread_state_tmacos_11_0_0
  Machine-specific thread state as used by thread_create_running and other Mach API functions.
• es_thread_tmacos_11_0_0
  Information related to a thread
• es_token_t
  Structure buffer with size
• es_touchid_mode_t
  See es_event_authentication_touchid_t
• stat
• statfs
• timespec
• timeval

Enums

• ClearCacheError
  Clearing authorisation caches failed.
• MuteInvertedTypemacos_13_0_0
  Type of muting for a specific es_mute_inversion_type_t
• MuteTypeErrormacos_13_0_0
  Getting the mute type failed.
• NewClientError
  Creating a new client failed.
• OpensshLoginError
  OpenSSH login failed.
• RespondError
  Responding to a message failed.
• ReturnError
  Basic error without additional informations.
• c_void
  Equivalent to C’s void type when used as a pointer.

Functions

• audit_token_to_asid^⚠
  Extract the audit session ID from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• audit_token_to_au32^⚠
  Extract information from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects to the audit system. audit_tokent_to_au32() is the only method that should be used to parse an audit_token_t, since its internal representation may change over time. A pointer parameter may be NULL if that information is not needed. audit_token_to_au32() has been deprecated because the terminal ID information is no longer saved in this token. The last parameter is actually the process ID version. The API calls audit_token_to_auid(), audit_token_to_euid(), audit_token_to_ruid(), audit_token_to_rgid(), audit_token_to_pid(), audit_token_to_asid(), and/or audit_token_to_pidversion() should be used instead.
• audit_token_to_auid^⚠
  Extract the audit user ID from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• audit_token_to_egid^⚠
  Extract the effective group ID from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• audit_token_to_euid^⚠
  Extract the effective user ID from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• audit_token_to_pid^⚠
  Extract the process ID from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• audit_token_to_pidversion^⚠
  Extract the process ID version from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• audit_token_to_rgid^⚠
  Extract the real group ID from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• audit_token_to_ruid^⚠
  Extract the real user ID from an audit_token_t, used to identify Mach tasks and senders of Mach messages as subjects of the audit system.
• es_clear_cache^⚠
  Clear all cached results for all clients.
• es_copy_message^⚠
  Retains an es_message_t, returning a non-const pointer to the given es_message_t for compatibility with existing code.
• es_delete_client^⚠
  Destroy an es_client_t, freeing resources and disconnecting from the ES subsystem
• es_exec_arg^⚠
  Get the argument at the specified position in the message containing an es_event_exec_t
• es_exec_arg_count^⚠
  Get the number of arguments in a message containing an es_event_exec_t
• es_exec_env^⚠
  Get the environment variable at the specified position in the message containing an es_event_exec_t
• es_exec_env_count^⚠
  Get the number of environment variables in a message containing an es_event_exec_t
• es_exec_fd^⚠macos_11_0_0
  Get the file descriptor at the specified position in the message containing an es_event_exec_t
• es_exec_fd_count^⚠macos_11_0_0
  Get the number of file descriptors in a message containing an es_event_exec_t
• es_free_message^⚠
  Releases the memory associated with the given es_message_t that was retained via es_copy_message()
• es_invert_muting^⚠macos_13_0_0
  Invert the mute state of a given mute dimension
• es_message_size^⚠
  Calculate the size of an es_message_t.
• es_mute_path^⚠macos_12_0_0
  Suppress all events matching a path.
• es_mute_path_events^⚠macos_12_0_0
  Suppress a subset of events matching a path.
• es_mute_path_literal^⚠
  Suppress events matching a path literal
• es_mute_path_prefix^⚠
  Suppress events matching a path prefix
• es_mute_process^⚠
  Suppress all events from the process described by the given audit_token
• es_mute_process_events^⚠macos_12_0_0
  Suppress a subset of events from the process described by the given audit_token
• es_muted_paths_events^⚠macos_12_0_0
  Retrieve a list of all muted paths.
• es_muted_processes^⚠
  List muted processes
• es_muted_processes_events^⚠macos_12_0_0
  Retrieve a list of all muted processes.
• es_muting_inverted^⚠macos_13_0_0
  Query mute inversion state
• es_new_client^⚠
  Initialise a new es_client_t and connect to the ES subsystem
• es_release_message^⚠macos_11_0_0
  Releases the given es_message_t that was previously retained with es_retain_message()
• es_release_muted_paths^⚠macos_12_0_0
  Delete a set of muted paths obtained from es_muted_paths_events, freeing resources.
• es_release_muted_processes^⚠macos_12_0_0
  Delete a set of muted processes obtained from es_muted_processes_events, freeing resources.
• es_respond_auth_result^⚠
  Respond to an auth event that requires an es_auth_result_t response
• es_respond_flags_result^⚠
  Respond to an auth event that requires an u32 flags response
• es_retain_message^⚠macos_11_0_0
  Retains the given es_message_t, extending its lifetime until released with es_release_message().
• es_subscribe^⚠
  Subscribe to some set of events
• es_subscriptions^⚠
  List subscriptions
• es_unmute_all_paths^⚠
  Unmute all paths
• es_unmute_all_target_paths^⚠macos_13_0_0
  Unmute all target paths
• es_unmute_path^⚠macos_12_0_0
  Unmute a path for all event types.
• es_unmute_path_events^⚠macos_12_0_0
  Unmute a path for a subset of event types.
• es_unmute_process^⚠
  Unmute a process for all event types
• es_unmute_process_events^⚠macos_12_0_0
  Unmute a process for a subset of event types.
• es_unsubscribe^⚠
  Unsubscribe from some set of events
• es_unsubscribe_all^⚠
  Unsubscribe from all events
• stat^⚠
• statfs^⚠

Type Definitions

• acl_tmacos_10_15_1
  Pointer to opaque type for Endpoint Security ACL.
• attrgroup_t
• au_asid_t
• c_char
• c_int
  Equivalent to C’s signed int (int) type.
• c_uint
  Equivalent to C’s unsigned int type.
• c_ushort
  Equivalent to C’s unsigned short type.
• cpu_subtype_tmacos_13_0_0
• cpu_type_tmacos_13_0_0
• dev_t
• es_graphical_session_id_tmacos_13_0_0
  A session identifier identifying a on-console or off-console graphical session.
• es_handler_block_t
  The type of block that will be invoked to handled messages from the ES subsystem
• gid_tNeither target_os="espidf" nor target_os="horizon" nor target_os="vita" nor target_os="nto"
• mode_t
• pid_t
• size_t
• uid_tNeither target_os="espidf" nor target_os="horizon" nor target_os="vita" nor target_os="nto"
• user_addr_t
• user_size_t

Unions

• es_event_authentication_t_anon0macos_13_0_0
  See es_event_authentication_t
• es_event_authentication_touchid_t_anon0macos_13_0_0
  See es_event_authentication_touchid_t
• es_event_close_t_anon_0
  See es_event_close_t.
• es_event_create_t_anon_0
  See es_event_create_t
• es_event_create_t_anon_1
  See es_event_create_t
• es_event_exec_t_anon_0
  See [es_event_exec_t.anon_0]
• es_event_login_login_t_anon0macos_13_0_0
  See es_event_login_login_t
• es_event_openssh_login_t_anon0macos_13_0_0
  See es_event_openssh_login_t
• es_event_rename_t_anon_0
  See es_event_rename_t
• es_event_setacl_t_anon_0macos_10_15_1
  See es_event_setacl_t
• es_events_t
  Union of all possible events that can appear in an es_message_t
• es_fd_t_anon_0macos_11_0_0
  See [es_fd_t_anon_0.anon_0]
• es_message_t_anon_0
• es_result_t_anon_0
  See es_result_t