NAME

eslogger — log Endpoint Security events

SYNOPSIS

eslogger [--oslog] [--format format] [--oslog-subsystem subsystem] [--oslog-category category] event [...]

eslogger --list-events

DESCRIPTION

eslogger interfaces with Endpoint Security to log events to standard output or to the unified logging system.

Like all Endpoint Security clients, eslogger must be run as super-user and requires the responsible process to have TCC Full Disk Access authorization. See TCC AUTHORIZATION below. To avoid feedback loops when filtering output using shell pipelines, eslogger automatically suppresses events for all processes that are part of its process group.

eslogger is not intended to be used by applications. It is not meant provide the same functionality, performance and schema stability as natively interfacing with the Endpoint Security API does. It cannot provide the integrity protection granted to System Extensions. Applications should continue to interface with EndpointSecurity(7) natively.

IMPORTANT: eslogger is NOT API in any sense. Do NOT rely on the structure or information emitted for ANY reason. It may change from release to release without warning.

OPTIONS

--format format: Log format to use. Default, and the only format currently supported, is json. See FORMATS below.
--list-events: List supported events on standard output and exit.
--oslog: Emit event data to the unified logging system instead of to standard output. See log(1) on configuring and using the unified logging system. The default subsystem and category are configured for oversize messages, resulting in a message size limit of 32k. Larger messages will be truncated.
--oslog-subsystem subsystem: Log subsystem to use with --oslog. Default is com.apple.eslogger. Changing the subsystem will make the default log profile ineffective, resulting in a message size limit of 1k. Configuring subsystem for oversize messages is recommended when using --oslog-subsystem.
--oslog-category category: Log category to use with --oslog. Default is events. Changing the subsystem will make the default log profile ineffective, resulting in a message size limit of 1k. Configuring category for oversize messages is recommended when using --oslog-category. eslogger uses the main category for operational logging, such as fatal errors.

EVENTS

Events are specified by their short name, such as exec or exit. Use --list-events to list the currently supported events by their short name. eslogger supports all notify events that EndpointSecurity supports. By design, eslogger does not support any auth events.

Some fields available in native Endpoint Security API clients are not available in eslogger. Currently, the only such field is es_token_t state part of es_thread_state_t, which is used only in remote_thread_create events.

FORMATS

The only supported format for event data is json, which is either JSON Lines, when writing to standard output, or JSON, when writing to the unified logging system. While no formal schema is provided, the data is modelled after es_message_t as provided by EndpointSecurity(7). Semantics, field names and optionality corresponds to the C counterparts as documented in the libEndpointSecurity(3) header documentation in the SDK. A schema_version is provided with every event. No schema stability guarantees are being made across schema_version changes. New events may be added without bumping schema_version. schema_version is specific to the JSON representation of events. schema_version is distinct from the version field, which denotes the message version as emitted by EndpointSecurity(7).

EXAMPLES

Subscribe to process lifecycle events and append event data to a file:

% sudo eslogger exec fork exit
  >>/tmp/proc.log

Subscribe to screensharing events and write event data to the unified logging system with the default subsystem and category:

% sudo eslogger --oslog
  screensharing_attach screensharing_detach

List available events:

% eslogger --list-events

Postprocess the output in a shell pipeline with jq:

% sudo eslogger exec | jq -r
  'select(.process.executable.path ==
  "/bin/zsh")|"\(.process.audit_token.pid):
  \(.process.executable.path) ->
  \(.event.exec.target.executable.path)"'

TCC AUTHORIZATION

eslogger requires the responsible process to have been authorized for Full Disk Access. For running eslogger in an SSH session, enable "Allow full disk access for remote users" in System Preferences > Sharing > Remote Login. Running eslogger from an app, including Terminal.app or a third-party terminal emulator, requires the respective app to be authorized for Full Disk Access in System Preferences > Security & Privacy > Privacy > Full Disk Access. Running eslogger as a launch daemon requires eslogger itself to be authorized for Full Disk Access in System Preferences > Security & Privacy > Privacy > Full Disk Access. MDM servers can grant Full Disk Access authorization using the Privacy Preferences Policy Control payload, identified by payload type com.apple.TCC.configuration-profile-policy, and its service dictionary key SystemPolicyAllFiles.