macOS: Implement ES Authentication Events Table #8565

tmc · 2025-03-12T04:06:02Z

This commit implements the first of the new EndpointSecurity event tables, focused on authentication events. It introduces a new CoreEventRouter system that categorizes events and routes them to specialized tables.

The new es_authentication_events table captures:

General authentication events
SSH login and logout events
Login window events
Screen sharing events
SU and SUDO command execution (on macOS 14+)

This is part of a multi-PR plan to modularize the EndpointSecurity events in osquery for better organization, query performance, and maintainability.

Changes include:

Core event categorization and routing infrastructure
New es_authentication_events table and schema
Documentation updates
Example queries in the macos-endpoint-security pack

Implements a new table for capturing authentication events via EndpointSecurity. This is the first of several modular ES event tables, introducing a new CoreEventRouter system for event categorization. The es_authentication_events table captures: - Authentication events (login/logout) - SSH sessions - Login window activity - Screen sharing connections - SU/SUDO executions (macOS 14+) Changes: - Implement es_authentication_events table - Update documentation - Add example queries to macos-endpoint-security pack

osquery/events/darwin/es_event_categories.cpp

Reorganizes ES event categories by moving malware events to a dedicated "security" category and adds additional event types to existing categories. Implements the genTable method for authentication events to properly return query results.

sharvilshah

Thanks for your contribution!

I will get the review going this week, but some quick observations from a cursory look:

We would want to create a new es_client for these events, like we do for process events and file events. I didn't see that? Have you considered that?
I don't think we should create our own uuid for event correlation. I would want a discussion on that (since we will be using different es_clients_, and I believe we should use the provided audit_tokens if we want a similar functionality.
I am a little concerned about backwards compatibility, have you been able to do much testing on older macOS versions?

directionless · 2025-03-29T17:01:22Z

specs/darwin/es_authentication_events.table

+    Column("ssh_login_username", TEXT, "Username for SSH login (may differ from process username)"),
+    Column("su_from_username", TEXT, "Original username for su events"),
+    Column("su_to_username", TEXT, "Target username for su events"),
+    Column("sudo_command", TEXT, "Command executed with sudo"),


on one hand, I can see why you might want one authentication events table. On the other hand, this feels really unrelated and messy

tmc · 2025-04-30T04:12:52Z

Definitely open to any design input and ordering in terms of breaking #8564 down

This is a model-assisted cut at making that large PR more manageable https://github.com/tmc/osquery/blob/endpointsecurity-expansion-stacked-diff-planning/osquery/events/darwin/ES_DIFF_PLAN.md

I'm open to input here and am also starting a slack thread.

Perhaps a good way to tackle this is a read out of current ES coverage gaps and then aligning on the most useful parts to tackle in which order.

tmc · 2025-04-30T05:08:54Z

This is a model-assisted breakdown of circumstances to cover and areas to expand coverage.

Legend:

✅ : Feature set directly enables or significantly simplifies detection/analysis for this use case with high confidence using ES events.
☑️ : Possible with the current feature set, but requires significant correlation, inference, joining with non-ES tables, complex queries, or lacks specific detail provided by later features. Confidence is lower.
❌ : Not directly possible or highly impractical using only the ES event data covered up to that column's features.

#	Key Malware-Related Use Case	Current ES Tables¹	Enhanced ES Tables²	Add `tcc_events`³	Add Network Events⁴	Add Privilege Events⁵	Add FS Metadata/Mount Events⁶	Add IPC/Exec Flow Events⁷	Add Sys Config/State Events⁸
	Initial Execution & Context
1	Track specific malware process execution flow & lineage	☑️⁹	✅	❌	❌	❌	❌	❌	❌
2	Identify execution of unsigned/suspiciously signed code	✅	✅	❌	❌	❌	❌	❌	❌
3	Detect unexpected parent spawning malicious child (e.g. Office -> Shell)	☑️⁹	✅	❌	❌	❌	❌	❌	❌
	Persistence
4	Monitor creation/modification of LaunchAgents/Daemons (FIM)	✅	✅	❌	❌	❌	✅	❌	❌
5	Detect installation of malicious Configuration Profiles	❌	❌	❌	❌	❌	❌	❌	✅
6	Detect loading/unloading of new System Extensions	❌	❌	❌	❌	❌	❌	✅	❌
	Privilege Escalation
7	Detect direct `setuid`/`seteuid` privilege escalation attempts	❌	❌	❌	❌	✅	❌	❌	❌
8	Detect successful `sudo` usage for escalation	☑️¹⁰	☑️¹⁰	❌	❌	✅	❌	❌	❌
9	Monitor for bypass attempts via Authorization prompts	❌	❌	❌	❌	✅	❌	❌	❌
	Defense Evasion
10	Detect TCC permission grants for sensitive access (FDA, Mic, Cam)	❌	❌	✅	❌	❌	❌	❌	❌
11	Detect modification/disabling of security tool configs (FIM)	✅	✅	❌	❌	❌	✅	❌	❌
12	Detect clearing/tampering with specific log files (FIM)	✅	✅	❌	❌	❌	✅	❌	❌
13	Detect changes to critical system binary permissions/owner	❌	❌	❌	❌	❌	✅	❌	❌
14	Detect mounting of hidden/suspicious disk images	❌	❌	❌	❌	❌	✅	❌	❌
15	Detect CS flags invalidation (code patching)	❌	❌	❌	❌	❌	❌	✅	❌
16	Detect termination of security agents via Signal/Exit	✅	✅	❌	❌	❌	❌	✅	❌
17	Detect modification of Gatekeeper DB or XProtect (FIM)	✅	✅	❌	❌	❌	✅	❌	❌
	Credential Access
18	Monitor SSH login activity	❌	❌	❌	❌	✅	❌	❌	❌
19	Detect access/modification of Keychain files (FIM/FS)	☑️¹¹	☑️¹¹	❌	❌	❌	✅	❌	❌
20	Detect processes reading sensitive config files (e.g., SSH keys, AWS creds)	☑️¹²	☑️¹²	❌	❌	❌	✅	❌	❌
	Discovery / Lateral Movement Prep
21	Monitor screensharing activation	❌	❌	❌	❌	❌	❌	❌	✅
22	Detect process enumerating network config via `sysctl`	❌	❌	❌	❌	❌	❌	❌	✅
	Command & Control
23	Detect outbound network connections to non-standard ports	❌	❌	❌	✅	❌	❌	❌	❌
24	Detect malware binding a port for reverse connections	❌	❌	❌	✅	❌	❌	❌	❌
	Execution / Code Injection
25	Detect remote thread creation into another process	❌	❌	❌	❌	❌	❌	✅	❌
26	Detect suspicious cross-process signaling	❌	❌	❌	❌	❌	❌	✅	❌
27	Monitor for suspicious XPC service connections	❌	❌	❌	❌	❌	❌	✅	❌
28	Detect direct access/manipulation of other process task ports	❌	❌	❌	❌	❌	❌	✅	❌
29	Detect use of PTYs for interactive shells/evasion	❌	❌	❌	❌	❌	❌	✅	❌
30	Detect process checking for debugger presence (proc_check)	❌	❌	❌	❌	❌	❌	✅	❌

Footnotes:

Current ES Tables: es_process_events (Exec, Fork, Exit), es_process_file_events (Create, Write, Rename, Truncate for FIM paths).
Enhanced ES Tables: Adds Audit Tokens for stable correlation, adds richer parent/responsible process context (path, signing ID, team ID) to existing tables.
Add tcc_events Table: Dedicated table for ES_EVENT_TYPE_NOTIFY_TCC_MODIFY events, showing changes to privacy permissions.
Add Network Events (via ES): Captures ES_EVENT_TYPE_NOTIFY_CONNECT, _BIND for TCP/UDP/UDS. Provides real-time connection/bind attempts.
Add Privilege Events (via ES): Captures ES_EVENT_TYPE_NOTIFY_SETUID/_SETGID series, _SUDO, _SU, _AUTHENTICATION, _AUTHORIZATION. Provides semantic detail on privilege changes & auth prompts.
Add FS Metadata/Mount Events (via ES): Captures ES_EVENT_TYPE_NOTIFY_MOUNT/_UNMOUNT, _CHMOD, _SETOWNER, _SETFLAGS, _SETEXTATTR, _SETACL, _LINK, _CHROOT, _CHDIR, _OPEN, _READDIR, _READLINK, _LOOKUP, _UTIMES, _SETTIME, etc. Covers non-content file/FS actions.
Add IPC/Exec Flow Events (via ES): Captures ES_EVENT_TYPE_NOTIFY_REMOTE_THREAD_CREATE, _SIGNAL, _XPC_CONNECT, _PTY_GRANT/_CLOSE, _GET_TASK, _PROC_CHECK, _CS_INVALIDATED, _PROC_SUSPEND_RESUME, _SYSTEM_EXTENSION_LOAD/_UNLOAD, _IOGOPEN, etc. Covers inter-process interactions and advanced execution flows.
Add Sys Config/State Events (via ES): Captures ES_EVENT_TYPE_NOTIFY_PROFILE_ADD/_REMOVE, _SCREENSHARING_ATTACH/_DETACH, _SETTIME, _SYSCTL, _OD_* (OpenDirectory user/group changes), etc. Covers system-wide config and state changes.
Process Lineage/Correlation (Current): Possible via Parent PID, but PID reuse makes it unreliable. Audit Tokens (Enhanced Tables) are crucial.
Sudo/Su via Process: Detectable by seeing sudo/su execution in es_process_events, but lacks details (success/fail, target user) provided by dedicated Privilege Events.
Keychain Access (FIM/FS): Detects file operations (open, write, modify) on keychain database files (e.g., ~/Library/Keychains/login.keychain-db) if monitored via FIM or FS Metadata events. Does not interpret the keychain content or specific item access.
Sensitive File Read: Requires monitoring ES_EVENT_TYPE_NOTIFY_OPEN (under FS Metadata) for specific sensitive file paths. Depends on configuration/filtering.

tmc force-pushed the endpointsecurity-expansion-1 branch from 4fa4774 to 9653579 Compare March 12, 2025 05:09

tmc marked this pull request as ready for review March 12, 2025 05:09

tmc requested review from a team as code owners March 12, 2025 05:09

tmc mentioned this pull request Mar 12, 2025

macOS: EndpointSecurity expansion #8564

Draft

7 tasks

tmc commented Mar 12, 2025

View reviewed changes

osquery/events/darwin/es_event_categories.cpp Outdated Show resolved Hide resolved

tmc force-pushed the endpointsecurity-expansion-1 branch from 6280695 to 1bf9f49 Compare March 16, 2025 09:11

sharvilshah reviewed Mar 25, 2025

View reviewed changes

directionless reviewed Mar 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

macOS: Implement ES Authentication Events Table #8565

macOS: Implement ES Authentication Events Table #8565

Uh oh!

tmc commented Mar 12, 2025

Uh oh!

Uh oh!

sharvilshah left a comment

Uh oh!

directionless Mar 29, 2025

Uh oh!

tmc commented Apr 30, 2025

Uh oh!

tmc commented Apr 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

macOS: Implement ES Authentication Events Table #8565

Are you sure you want to change the base?

macOS: Implement ES Authentication Events Table #8565

Uh oh!

Conversation

tmc commented Mar 12, 2025

Uh oh!

Uh oh!

sharvilshah left a comment

Choose a reason for hiding this comment

Uh oh!

directionless Mar 29, 2025

Choose a reason for hiding this comment

Uh oh!

tmc commented Apr 30, 2025

Uh oh!

tmc commented Apr 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants