elastic / elastic/integrations
[New Integration] macOS Unified Logs
- Dominant language
- Handlebars
- Stars
- 333
- Forks
- 647
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 225
Description
### Integration Name
macOS Unified Logs (`macos_unified_logs`)
**new package**. This is a proposal for a dedicated `type: integration` package; it is not in the Integration Name dropdown.
### Dataset Name
New data streams, one per Unified Logs subsystem group:
- `macos_unified_logs.apple_events` inter-app automation and control
- `macos_unified_logs.tcc` privacy-consent grants/denials
- `macos_unified_logs.authentication` auth decisions, directory lookups
- `macos_unified_logs.session` login/logout/unlock sessions
- `macos_unified_logs.gatekeeper` code-signing policy, XProtect/Gatekeeper malware scans
### Integration Version
N/A the integration does not exist yet. Context comes from `unifiedlogs` 0.5.2 (current).
### Agent Version
8.19.0+ assumed (matches the current unifiedlogs input requirements).
### User Goal
Collect **macOS Unified Logs security telemetry** as a supported, ECS-mapped integration with proper data streams so that prebuilt detection rules in `elastic/detection-rules` can target it. macOS Unified Logs are the system-wide log facility on macOS and carry high-value security telemetry that no integration currently ships in structured form: Apple Events (inter-app automation a common abuse primitive for collection and lateral movement), TCC privacy-consent decisions, authentication and session activity, and Gatekeeper/XProtect verdicts.
Prebuilt rule validation requires the data_stream contract that only a standard integration provides enumerable datasets, per-dataset field schemas and pipelines, and per-version support. This was discussed in #21024, which closed with the conclusion that neither restructuring the `unifiedlogs` input package nor special-casing input packages in detection-rules tooling is the right long-term answer; a dedicated package is.
### Existing Features
Security enrichment content added to that package in #17644 (`unified_log.*` / `apple_event.*`
fields and a package-root ingest pipeline) is effectively inactive on default deployments for the same structural reasons. Fleet has no defined installation path for a package-root pipeline in an input package, and the `pipeline` var default references a pipeline that is never created. See the closing note in #21024; that content is the natural seed for this new package, where Fleet would install and version each pipeline natively.
### Anything else?
- **Related:** #21024 (closed restructuring the input package rejected; this proposal is the follow-up direction),
- [#17644](https://github.com/elastic/integrations/pull/17644) the enrichment content that would migrate into this
package
- **A note on the existing enrichment content for the team to consider:** given the pipeline
installation gap above, the security enrichment added in #17644 (the package-root pipeline, the
`unified_log.*`/`apple_event.*` fields, and the `pipeline` var default) is effectively inactive on default deployments, and where enabled manually it overrides the user-configured dataset and
drops the original event timestamp.
- If a dedicated package moves forward, that content would migrate there so it may be worth considering whether to revert it from unifiedlogs in a future release and return the package to a purely generic collection tool, consistent with the other custom input packages.
-
**References**
- [Custom macOS Unified Logs package](https://www.elastic.co/docs/reference/integrations/unifiedlogs) current input package
Contributor guide
Research direction
Start by reading #21024 and #17644, then inspect the existing unifiedlogs input package and the linked custom macOS Unified Logs package documentation. Define the new package’s datasets, ECS fields, ingest pipelines, and Fleet installation/versioning; done means the integration provides supported, enumerable data streams that can be targeted by prebuilt detection rules.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos
- Domain
- observability, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100