Struct es_process_t

#[repr(C)]
pub struct es_process_t {

    pub audit_token: audit_token_t,
    pub ppid: pid_t,
    pub original_ppid: pid_t,
    pub group_id: pid_t,
    pub session_id: pid_t,
    pub codesigning_flags: u32,
    pub is_platform_binary: bool,
    pub is_es_client: bool,
    pub cdhash: [u8; 20],
    pub signing_id: es_string_token_t,
    pub team_id: es_string_token_t,
    pub executable: ShouldNotBeNull<es_file_t>,
    pub tty: *mut es_file_t,
    pub start_time: timeval,
    pub responsible_audit_token: audit_token_t,
    pub parent_audit_token: audit_token_t,
}

Available on macOS only.

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).

Values such as pid, pidversion, uid, gid, etc. can be extracted from audit tokens using API provided in libbsm.h.

Identifying unique process execution on a single machine

The tuple (pid, pidversion) identifies a specific process execution, and should be used to link events to the process that emitted them. Executing an executable image in a process using the exec or posix_spawn family of syscalls increments the pidversion. However, (pid, pidversion) is not meant to be unique across reboots or across multiple systems.

Multiple ES clients

Clients should take caution when processing events where is_es_client is true. If multiple ES clients exist, actions taken by one client could trigger additional actions by the other client, causing a potentially infinite cycle.

Code signing

Fields related to code signing in the target es_process_t reflect the state of the process at the time the message is generated. In the specific case of exec, this is after the exec completed in the kernel, but before any code in the process has started executing. At that point, XNU has validated the signature itself and has verified that the CDHash is correct in that the hash of all the individual page hashes in the Code Directory matches the signed CDHash, essentially verifying the signature was not tampered with. However, individual page hashes are not verified by XNU until the corresponding pages are paged in once they are accessed while the binary executes. It is not until the individual pages are paged in that XNU determines if a binary has been tampered with and will update the code signing flags accordingly.

Endpoint Security provides clients the current state of the CS flags in the codesigning_flags member of the es_process_t struct. The CS_VALID bit in the codesigning_flags means that everything the kernel has validated up to that point in time was valid, but not that there has been a full validation of all the pages in the executable file. If page content has been tampered with in the executable, we won’t know until that page is paged in. At that time, the process will have its CS_VALID bit cleared and, if CS_KILL is set, the process will be killed, preventing any tampered code from being executed.

CS_KILL is generally set for platform binaries and for binaries having opted into the hardened runtime. An ES client wishing to detect tampered code before it is paged in, for example at exec time, can use the Security framework to do so, but should be cautious of the potentially significant performance cost. The Endpoint Security subsystem itself has no role in verifying the validity of code signatures.

Fields

audit_token: audit_token_t

Audit token of the process

ppid: pid_t

Parent pid of the process. It is recommended to instead use the parent_audit_token field.

original_ppid: pid_t

Original ppid of the process. This field stays constant even in the event this process is reparented.

group_id: pid_t

Process group id the process belongs to

session_id: pid_t

Session id the process belongs to

codesigning_flags: u32

Code signing flags of the process. The values for these flags can be found in the include file cs_blobs.h (#include <kern/cs_blobs.h>).

is_platform_binary: bool

is_es_client: bool

Indicates this process has the Endpoint Security entitlement

cdhash: [u8; 20]

The code directory hash of the code signature associated with this process

signing_id: es_string_token_t

The signing id of the code signature associated with this process

team_id: es_string_token_t

The team id of the code signature associated with this process

executable: ShouldNotBeNull<es_file_t>

The executable file that is executing in this process.

tty: *mut es_file_t

Available on crate feature macos_10_15_1 only.

The TTY this process is associated with, or NULL if the process does not have an associated TTY. The TTY is a property of the POSIX session the process belongs to. A process’ session may be associated with a TTY independently from whether its stdin or any other file descriptors point to a TTY device (as per isatty(3), tty(1)).

Field available only if message version >= 2.

start_time: timeval

Available on crate feature macos_10_15_4 only.

Process start time, i.e. time of fork creating this process.

Field available only if message version >= 3.

responsible_audit_token: audit_token_t

Available on crate feature macos_11_0_0 only.

Audit token of the process responsible for this process, which may be the process itself in case there is no responsible process or the responsible process has already exited.

Field available only if message version >= 4.

parent_audit_token: audit_token_t

Available on crate feature macos_11_0_0 only.

Audit token of the parent process.

Field available only if message version >= 4.

Implementations

impl es_process_t

Accessors for ShouldNotBeNull fields

pub unsafe fn executable(&self) -> &es_file_t

Gives a references to the field while checking for null.

Safety

See ShouldNotBeNull safety requirements.

impl es_process_t

Accessors for *mut and *const fields

pub unsafe fn tty(&self) -> Option<&es_file_t>

Helper to avoid the is_null() + deref every time.

Safety

The pointer must be valid (aligned & initialized) for a value of the expected type.