MacOS Security Monitor - Complete Setup Guide

This guide will help you set up the MacOS Security Monitor project correctly after the compilation issues have been fixed.

Prerequisites

• macOS 12.0 or later
• Xcode 13.0 or later
• Swift 5.5 or later
• Root access for running the monitor
• For production use: Apple Developer account with the EndpointSecurity entitlement

Project Setup

1. Create the Project Structure

mkdir -p MacOSSecurityMonitor/Sources/MacOSSecurityMonitor
mkdir -p MacOSSecurityMonitor/Resources
cd MacOSSecurityMonitor

2. Create the Package.swift File

Create a file named Package.swift in the root directory with the fixed content provided.

3. Add the Entitlements File

Create Resources/MacOSSecurityMonitor.entitlements using the fixed entitlements file content.

4. Add the Source Files

Create the following files in the Sources/MacOSSecurityMonitor directory:

• Models.swift - Fixed version
• Utilities.swift - Fixed version
• ESClient.swift - Fixed version
• EventHandler.swift - Original version
• Logger.swift - Original version
• main.swift - Original version

5. Add the Makefile

Create a Makefile in the root directory using the fixed Makefile content.

Explanation of Fixes

Fixed Package.swift

• Added AppKit to the frameworks list
• Simplified the linker settings section
• Removed the custom entitlements section since we'll handle it differently

Fixed Models.swift

• Added missing CS_* constants to handle code signing flags
• Modified the event structure access to handle API limitations
• Added placeholder implementation for events we can't directly access

Fixed Utilities.swift

• Added import AppKit for NSWorkspace
• Fixed the plain text file detection logic
• Corrected the type conformance check

Fixed ESClient.swift

• Fixed the event subscription method to safely unwrap optionals
• Converted Int to UInt32 for proper API usage
• Improved error handling

Fixed Makefile

• Fixed the syntax issues that caused "missing separator" errors
• Improved the plist creation method for the LaunchDaemon

Building and Running

Build the Project

cd MacOSSecurityMonitor
swift build

Run the Monitor

The monitor requires root privileges to access EndpointSecurity:

sudo swift run MacOSSecurityMonitor

With command-line options:

sudo swift run MacOSSecurityMonitor --verbose --summary --interval 60

Using the Makefile

The Makefile provides several useful commands:

• Build the project: make
• Run the monitor: sudo make run
• Run with verbose logging: sudo make run-verbose
• Install as a system service: sudo make install
• Start the service: sudo make start-service
• Stop the service: sudo make stop-service
• Uninstall: sudo make uninstall

Entitlements and Signing

For production use, you need the EndpointSecurity entitlement from Apple:

1. Request the com.apple.developer.endpoint-security.client entitlement from Apple
2. Create a properly signed application with this entitlement
3. Grant Full Disk Access to the application in System Preferences

For testing on a VM with SIP disabled, you can test without the official entitlement.

Monitoring Capabilities

The monitor currently tracks:

1. XProtect Events:

   • Malware detection (ES_EVENT_TYPE_NOTIFY_XP_MALWARE_DETECTED)
   • Malware remediation (ES_EVENT_TYPE_NOTIFY_XP_MALWARE_REMEDIATED)

2. Gatekeeper Events:

   • User overrides (ES_EVENT_TYPE_NOTIFY_GATEKEEPER_USER_OVERRIDE) on macOS 15.0+

Due to API limitations, some event details are currently placeholders. The code is structured to be easily updated when fuller API access becomes available.

Troubleshooting

Common Issues

1. Entitlement Error: "Missing 'com.apple.developer.endpoint-security.client' entitlement"

   • Solution: Run on a VM with SIP disabled for testing, or get the proper entitlement from Apple

2. TCC Approval Error: "Missing TCC approval"

   • Solution: Grant Full Disk Access in System Preferences

3. Privilege Error: "Must run as root"

   • Solution: Run with sudo

4. Missing Frameworks: Compilation errors about missing frameworks

   • Solution: Make sure Xcode command line tools are installed with xcode-select --install

5. Runtime API Errors: If new macOS versions change the API

   • Solution: Update the code to match the latest EndpointSecurity API documentation