Develop macOS Unified Logging System (ULS) Reader for Logcollector

[vikman90]

Description

The goal is to implement a Logcollector Reader that interfaces with macOS's Unified Logging System (ULS) using the OSLog framework. This Reader will allow querying and filtering logs based on specific predicates, log levels, and types.

Given that OSLog is designed for Objective-C, while the Wazuh Agent is implemented in C++, a wrapper will need to be developed or integrated to bridge the two languages.

Requirements

Configuration Options

The macOS Reader will support the following options:

• macos: Defines a macOS-specific reader with the following sub-options:
  • query: Predicate to filter logs.
  • level: Log verbosity level: default, info, or debug.
  • type: Limits the log type; possible values (combinable): activity, log, trace.
• file_wait: Defines the log polling interval (e.g., 500ms).
• reload_interval: Interval for detecting log rotation (if applicable).

Example Configuration

logcollector:
  enabled: true

  macos:
  - query: process == "sshd" OR message CONTAINS "invalid"
    level: info
    type: trace,activity,log
  - query: process == "wazuh-agent"
    level: default
    type: log

  reload_interval: 1m
  file_wait: 500ms

Tasks

Spike

1. Review Configuration Options
   • Validate the proposed options and identify potential additional configurations if needed.
2. Investigate OSLog Framework Integration
   • Analyze the OSLog API and available Objective-C/C++ bridging options.
   • Determine the best approach to create or use a wrapper for integrating OSLog with C++.
3. Define Runner Behavior
   • Design the macOS Reader's behavior in alignment with the specification of issue Support Platform-Specific Logging Systems in Logcollector #424.
   • Determine whether ULS manages log rotation internally or if the Reader must periodically reload logs.

Development

1. Extend Logcollector's Setup Function
   • Parse and validate the macOS-specific configuration options.
2. Integrate OSLog API
   • Develop or utilize a wrapper to interact with the OSLog framework from C++.
   • Ensure synchronous retrieval and filtering of logs based on queries, levels, and types.
3. Implement macOS Reader
   • Develop the Reader to process and transmit logs in the standard format.
   • Handle log rotation detection if it is not natively managed by ULS.
4. Testing
   • Write unit tests and integration tests to validate the Reader's behavior with different queries, log levels, and types.
   • Test the Reader's behavior with multiple configuration entries.
5. Documentation
   • Prepare detailed documentation for the macOS Reader, including configuration examples, usage instructions, and limitations.

Deliverables

• Fully implemented macOS Reader for Logcollector.
• Comprehensive test suite covering functionality and edge cases.
• Documentation for configuration and usage.

[jr0me]

Update

I’ve started working on the macOS Reader for Logcollector. Reviewed the configuration options and began investigating OSLog API integration and Objective-C/C++ bridging. Next steps will include coming up with an approach for the wrapper, draft a Reader design, and validate ULS log rotation handling.