Osquery macOS: EndpointSecurity Framework Integration

The problem with osquery macOS monitoring is not Apple hiding every useful signal. It is teams collecting state, EndpointSecurity events, and unified logs without knowing which source should answer which question.

Mac fleets look simple until the first incident. An application bundle may be present but never launched. A process may run for two seconds and vanish. A system extension may be approved by MDM but fail to load. An EndpointSecurity table may return zero rows because Full Disk Access is missing, not because nothing happened. Osquery can expose each condition. You need to choose the right source and prove the collection path works.

This matters beyond Mac administration. Verizon published its 2026 Data Breach Investigations Report in May 2026 after examining more than 31,000 incidents and more than 22,000 confirmed breaches. Vulnerability exploitation led initial access at 31 percent. A precise application version, signing identity, security control state, and process record can change a broad vulnerability finding into a specific action.

What does osquery macOS visibility include?

Use state tables for questions about what exists now. apps lists application bundles and versions. homebrew_packages covers formulae and casks that may bypass the normal application inventory. launchd and startup_items expose persistence. system_extensionsshows modern system extensions, including whether MDM manages them. disk_encryption,sip_config, and gatekeeper describe platform controls.

Choose event tables when the evidence may disappear between intervals. Apple introduced the EndpointSecurity API in macOS 10.15. Osquery uses it for es_process_events andes_process_file_events. The former records executions and exits with path, command line, user, signing identity, team identity, and code signing flags. The latter connects a process to file activity. These are investigation records, not posture snapshots.

Turn to unified_log for messages emitted by macOS services and applications. It is not a substitute for EndpointSecurity. Logs report what a component chose to say. EndpointSecurity reports system events through an Apple API designed for security products. For a wider map of portable and platform tables, start with the 25 most useful osquery tables.

How do you enable EndpointSecurity in osquery?

Two flags enable the event system and the EndpointSecurity publisher. The official osquery process auditing documentation also requires Full Disk Access for the osqueryd executable. If that permission is absent, osquery continues running and the event table stays empty. It does not present an interactive permission prompt. That quiet failure is why “zero events” is never a valid health check.

Deploy the vendor package or your own properly signed application bundle. An organization that builds and signs its own osquery package must obtain Apple’s EndpointSecurity Client entitlement for its signing certificate. Then grant Full Disk Access through MDM privacy preferences, restart osqueryd, and validate an event generated on a test host. The control plane, entitlement, privacy grant, process restart, and query schedule all have to agree.

Test the daemon, not only osqueryi. The shell and daemon are separate processes. A permission granted to one path does not prove the other path can collect. Keep a canary query on a small test group and alert when a known event stops arriving. Event volume can fall because the fleet got quiet. It can also fall because an MDM profile changed. You need a way to tell the difference.

What should you query from es_process_events?

Start with identity, not every column. A useful process record says what ran, who ran it, who signed it, and what parent was responsible. The official table schema includes path, cmdline,username, parent, responsible_pid, signing_id,team_id, platform_binary, and event_type.

Do not ship that query across the whole fleet before measuring it. Suppose 2,500 Macs each produce 50 process rows a minute. That is 125,000 rows a minute and 180 million rows a day. Even if your actual number is one tenth as large, a SIEM bill will notice. Filter known platform binaries, shorten retention for raw events, or send the full stream to cheaper storage while forwarding only detections to the SIEM.

A better first detection returns unsigned execution from user writable paths, then compares the path and hash against your software inventory. Avoid a universal “non Apple equals malicious” rule. Most enterprise Mac fleets run signed software from many developers. Team identity, bundle inventory, user, path, and first seen time matter together. Raw signing status is a clue.

Consider a developer tool that launches a helper from a user library directory. The path looks risky in isolation. The event becomes easier to judge when the team identity matches the approved application, the parent process is that application, the same hash appears on the rest of the engineering cohort, and the first seen time matches a planned update. If the team identity is empty and the parent is a downloaded shell script, the response changes. Endpoint evidence earns its cost through that comparison.

Record both execution and exit events only when the use case needs them. Exit codes help diagnose a security control that fails to start, but they double part of the event stream and add little to many threat hunts. Keep command line and environment collection narrow because secrets sometimes appear there. The right schema is the smallest one that lets an investigator decide what happened and who owns the next action.

How should you query the macOS unified log?

Constrain time and volume before content. Unified logging is large, and the table requires bounded work. In osquery 5.23.0, released April 25, 2026, the project added level filtering to unified_log. The osquery release history records that change. It fixes a practical gap in older examples where the SQL engine filtered rows only after the table had already reached its internal row limit.

Use subsystem and category constraints for a known question, such as Gatekeeper failures or a security agent that cannot load. A general collection of all error messages produces a queue of software defects, network retries, and harmless noise. Send diagnostic logs when they explain a control failure. Do not make the security team own every application complaint emitted by macOS.

Version changes matter here too. The same April 2026 release fixed the gatekeeper table on macOS 15 and newer. Osquery 5.21.0, released December 18, 2025, added support for modern Login Items and Background Services. A query library written against a 2024 schema misses both developments. Track the agent version and the operating system version with every result.

Which macOS posture checks earn a schedule?

Schedule checks that express a policy with a named owner. FileVault disabled belongs to endpoint engineering. SIP disabled may belong to a lab exception process. An unapproved system extension belongs to security and device management together. A new launch daemon needs the binary signature and package owner before anyone calls it persistence.

• Daily: applications, Homebrew packages, operating system version, FileVault, SIP, Gatekeeper, and system extension state.
• Every few hours: launch daemons, launch agents, login items, browser extensions, and local user changes.
• Continuous: selected process and file events tied to a detection or investigation need.

Keep state and event pipelines distinct. A state query can report only changes through differential logging. An event table already represents change and needs expiration, retention, and back pressure decisions. Theosquery file integrity monitoring guide explains that event buffer model in detail. The performance tuning guide covers query cost and watchdog evidence.

For application inventory, decide which version field drives vulnerability matching and test it against real bundles. Marketing versions, bundle versions, package receipts, and Homebrew versions do not always match the string in a vendor advisory. Keep the raw values and normalize a separate comparison field. When the match is uncertain, return the application path and signing identity with the finding instead of inventing precision.

Put exceptions on a clock. A disabled control for a diagnostic session may be reasonable. The same exception six months later is drift. Store the approver, affected hosts, reason, and expiration beside the policy, then make the query return expired exceptions. This turns a posture table into an operating control and keeps the security team from reopening the same conversation every week.

What usually breaks in a macOS deployment?

Privacy permissions break quietly. Package signing and entitlements break at install or update time. New macOS releases change private data sources and table behavior. User scoped data can disappear when queries run outside the active user context. None of these failures is solved by adding more SQL.

Build an acceptance test for every agent release. Confirm the package signature, Full Disk Access profile, EndpointSecurity events, FileVault result, system extension inventory, and one bounded unified log query. Record the row count and query time on a busy Mac. Then promote the release in stages. Five engineers spending two hours chasing an empty table is ten hours lost to a permission that a test could have caught.

Finally, do not turn a Mac fleet into an undifferentiated event lake. Deep endpoint context with AI driven analysis can help decide which findings matter, and that is how Artemes AI approaches the problem. The same principle applies if humans do the reading. Collect enough context to make a judgment, then keep the output short enough that someone still reads it.

Frequently asked questions

Does osquery need Full Disk Access on macOS?

Core state tables can work without it, but EndpointSecurity process events require Full Disk Access. Some other tables that read protected files need it as well. Grant it to the exact deployed osqueryd path.

What is the difference between EndpointSecurity and unified logs?

EndpointSecurity delivers structured system events such as process execution. Unified logs contain messages that components chose to emit. Use events for activity evidence and logs for diagnostic context.

Can osquery see Apple silicon Macs?

Yes. Current packages include native macOS arm64 builds. Verify your fleet does not run an older Intel binary through translation unless that choice is deliberate.

Can osquery replace an MDM?

No. Osquery reads state and events. MDM grants privacy permissions, installs profiles, enforces settings, and runs device management actions. The two systems should verify each other.

The takeaway

Choose one Mac question from each source: current state, EndpointSecurity activity, and unified log diagnostics. Prove the daemon permission path, measure a week of volume on ten devices, and name the owner of every exception before expanding. Osquery macOS monitoring works when empty results are treated as a test failure until proven otherwise. That one habit prevents the most expensive kind of visibility gap, the one that looks like clean data.

Use the installation guide for packaging, the fleet guide for remote schedules, and the definitive osquery handbook for the full cluster. Our older article on configuration drift and changing risk shows why a Mac control that passed yesterday still needs current evidence.