elastic / elastic/integrations

[New Integration] macOS Unified Logs

Open
#21,060 1 comment 0 reactions 0 assignees View on GitHub
needs:triage Team:Security-Service-Integrations
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.