Introduction

Mac Watcher is a macOS monitoring tool designed to capture information when your Mac wakes from sleep. It can help you track unauthorized access, monitor your Mac's location, and receive alerts when your Mac is used.

The tool integrates with sleepwatcher to detect wake events and can perform the following actions:

Capture webcam photos
Take screenshots
Record location data
Collect network information
Detect login failures
Send email alerts with the captured information

Demo

Here's a demonstration of Mac Watcher's primary commands and their output:

Basic Usage

Terminal

$user@users-MacBook ~ % mac-watcher
╔════════════════════════════════════════════════════╗
║                  MAC-WATCHER                       ║
╚════════════════════════════════════════════════════╝

USAGE:
  mac-watcher [OPTION]

OPTIONS:
  --dependencies  Check and install missing dependencies
  --setup         Setup .wakeup file and default configuration
  --config        Configure settings
  --diagnostics   Check current setup
  --test          Run the monitor script manually for testing
  --instructions  Show detailed usage instructions
  --help          Display this help message

RECOMMENDED WORKFLOW:
  1. mac-watcher --dependencies
  2. mac-watcher --setup
  3. mac-watcher --config
  4. brew services start sleepwatcher
  5. mac-watcher --test (optional, to test functionality)

For more information, run: mac-watcher --instructions

Checking Dependencies

Terminal

$user@users-MacBook ~ % mac-watcher --dependencies
╔════════════════════════════════════════════════════╗
║              DEPENDENCY CHECKER                    ║
╚════════════════════════════════════════════════════╝

◇ PACKAGE MANAGEMENT
  Homebrew      : Installed

◇ SYSTEM MONITORING
  Sleepwatcher  : Installed

◇ LOCATION SERVICES
  CoreLocationCLI: Installed

◇ DATA PROCESSING
  jq            : Installed
  coreutils     : Installed

◇ MEDIA CAPTURE
  imagesnap     : Installed

Dependency check completed.

Setup Process

Terminal

$user@users-MacBook ~ % mac-watcher --setup 

╔════════════════════════════════════════════════════╗
║                   MONITOR SETUP                    ║
╚════════════════════════════════════════════════════╝

Setting up mac-watcher monitoring system...

◇ CHECKING DEPENDENCIES
  Homebrew      : Installed
  Sleepwatcher  : Installed
  CoreLocationCLI: Installed
  jq            : Installed
  imagesnap     : Installed
  Dependency check completed

◇ CONFIGURING WAKEUP FILE
  Target location: /Users/user/.wakeup
  Status         : Created successfully
  Permissions    : Executable (755)

◇ CREATING DEFAULT CONFIGURATION
  Target location: /Users/user/.config/monitor.conf
  Status         : Configuration already exists
  Action         : Preserved existing configuration

◇ SLEEPWATCHER SERVICE
  Status         : Running

╔════════════════════════════════════════════════════╗
║                   SETUP COMPLETE                   ║
╚════════════════════════════════════════════════════╝

Next steps to complete your setup:

1. Start the sleepwatcher service:
   brew services start sleepwatcher

2. Configure mac-watcher settings:
   mac-watcher --config

3. Verify your setup:
   mac-watcher --diagnostics

Configuration

Terminal

$user@users-MacBook ~ % mac-watcher --config
╔════════════════════════════════════════════════════╗
║               MONITOR CONFIGURATION                ║
╚════════════════════════════════════════════════════╝

◇ EMAIL
  Email Status    : Enabled
  Sender email    : onboarding@resend.dev
  Recipient email : example@gmail.com
  Resend API Key  : re_3nvY9****************************************
  Initial Email   : Enabled
  Follow-up Email : Enabled
  Time Restriction: Disabled
  Day Restriction : Disabled

◇ SECURITY
  Login Detection : Disabled

◇ LOCATION & NETWORK
  Location  : Enabled
  Method    : CoreLocationCLI
  Setup     : Configured
  Network   : Enabled

◇ MEDIA CAPTURE
  Webcam    : Enabled
  Screenshot: Enabled
  Follow-up Screenshot: Enabled

◇ SCHEDULE
  Status        : Running Every Day
  Active Days   : Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday
  Active Windows: None configured

◇ AUTO-DELETE
  Status    : Disabled

◇ DELAY TIMING
  Initial   : 0 seconds
  Follow-up : 25 seconds

◇ STORAGE
  Path      : /Users/User/Pictures/.access

──────────────────────────────────────────────────────

CONFIGURATION MENU
  [1] Email Settings
  [2] Location & Network Settings
  [3] Media Capture Settings
  [4] Schedule Settings
  [5] Storage Path Settings
  [6] Timing Settings
  [7] Auto-Delete Settings
  [8] Login Detection Settings (Beta)
  [9] Save & Exit

Select option (1-9):

Diagnostics

Terminal

$user@users-MacBook ~ % mac-watcher --diagnostics
╔════════════════════════════════════════════════════╗
║              SYSTEM DIAGNOSTICS                    ║
╚════════════════════════════════════════════════════╝

◇ SLEEPWATCHER SERVICE
  Status: Running

◇ WAKEUP FILE
  Existence: File exists
  Configuration: Correct
  Permissions: Correct (755)

◇ REQUIRED DEPENDENCIES
  CoreLocationCLI: Installed
  jq            : Installed
  coreutils     : Installed
  imagesnap     : Installed

◇ CONFIGURATION
  Status: Found
  Location: /Users/User/.config/monitor.conf
  Email Setup: Complete
  Location Setup: Complete

Diagnostics completed.

Instructions

Terminal

$user@users-MacBook ~ % mac-watcher --instructions
╔════════════════════════════════════════════════════╗
║             MAC-WATCHER INSTRUCTIONS               ║
╚════════════════════════════════════════════════════╝

OVERVIEW:
  Mac-Watcher is a security tool that monitors Mac usage and sends alerts
  when your Mac wakes from sleep.

SETUP PROCESS:
  1. Run 'mac-watcher --dependencies' to ensure all dependencies are installed
  2. Run 'mac-watcher --setup' to create the necessary .wakeup file and default configuration
  3. Run 'mac-watcher --config' to customize email alerts, location tracking,
     screenshots, and other options
  4. Start the sleepwatcher service with 'brew services start sleepwatcher'
  5. Test functionality with 'mac-watcher --test' (optional)

CONFIGURATION FILES:
  • ~/.wakeup: Script executed when your Mac wakes from sleep
  • ~/.config/monitor.conf: Configuration settings

VIEWING CAPTURED DATA:
  The monitoring data is stored in the configured directory (default: ~/Pictures/.access)
  organized by year/month/day/time.

TROUBLESHOOTING:
  Run 'mac-watcher --diagnostics' to check your setup for common issues
  Run 'mac-watcher --test' to manually trigger monitoring and test functionality

MORE INFORMATION:
  Visit: https://github.com/ramanaraj7/mac-watcher

Example

You specify configuration options in a configuration file:

Terminal

$# ~/.config/monitor.conf

# Basic configuration
WEBCAM_ENABLED="yes"
SCREENSHOT_ENABLED="yes"
LOCATION_ENABLED="yes"
NETWORK_INFO_ENABLED="yes"

# Email configuration
EMAIL_ENABLED="yes"
EMAIL_FROM="onboarding@resend.dev"
EMAIL_TO="your.email@example.com"
RESEND_API_KEY="re_123456789"
INITIAL_EMAIL_ENABLED="yes"
FOLLOWUP_EMAIL_ENABLED="yes"

# Storage configuration
BASE_DIR="$HOME/Pictures/.access/"
AUTO_DELETE_ENABLED="no"
AUTO_DELETE_DAYS=365

Run mac-watcher --setup to set up the monitoring:

Terminal

$$ mac-watcher --setup
✓ Configuration file created
✓ Dependencies installed
✓ Wake detection script created
✓ Service installed

Mac Watcher is now running and will monitor wake events.

Installation

Mac Watcher can be installed using Homebrew or manual installation.

Using Homebrew (Recommended)

Terminal

$# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Mac Watcher
brew install ramanaraj7/tap/mac-watcher

# Run the setup

Manual Installation

You can also install Mac Watcher manually by cloning the repository and running the installation script:

Terminal

$# Clone the repository
git clone https://github.com/ramanaraj7/mac-watcher.git

# Change to the directory
cd mac-watcher

# Run the install script
./install.sh

# Run the setup
./mac-watcher --setup

After installation, you can configure Mac Watcher to suit your needs. The configuration file is located at ~/.config/monitor.conf.

You can edit this file manually or use the configuration utility:

Terminal

$# Open the configuration utility
mac-watcher --config

Configuration

After installation, you can configure Mac Watcher to suit your needs. The configuration file is located at ~/.config/monitor.conf.

Configuration Options

Option	Description
CAPTURE_WEBCAM	Enable webcam capture (true/false)
CAPTURE_SCREENSHOT	Enable screenshot capture (true/false)
TRACK_LOCATION	Enable location tracking (true/false)
COLLECT_NETWORK_INFO	Enable network information collection (true/false)
SEND_EMAIL	Enable email notifications (true/false)
STORAGE_PATH	Path to store captured data

Diagnostic Tool

Mac Watcher includes a diagnostic tool to help troubleshoot issues:

Terminal

$# Run the diagnostic tool
mac-watcher --diagnostics

# Output should look like this:
✓ Configuration file found
✓ Wake detection script installed
✓ Service running
✓ Camera access permitted
✓ Location access permitted
✓ Storage directory exists
✓ All dependencies installed

Usage

Once installed and configured, Mac Watcher runs automatically in the background. It will activate whenever your Mac wakes from sleep and perform the actions you've configured.

To test Mac Watcher without waiting for your Mac to sleep and wake:

Terminal

$# Test Mac Watcher functionality
mac-watcher --test

Commands

Mac Watcher provides several commands to help you manage and use the tool:

Command	Description
mac-watcher --setup	Run the initial setup process
mac-watcher --config	Open the configuration utility
mac-watcher --test	Test the monitoring functionality
mac-watcher --diagnostics	Run diagnostics to check the installation
mac-watcher --dependencies	Check and install dependencies
mac-watcher --help	Display help information

File Locations

Mac Watcher uses several files and directories for its operation:

File/Directory	Description
~/.config/monitor.conf	Configuration file
~/.wakeup	Wake detection script used by sleepwatcher
~/Pictures/.access/	Default storage location for captured media (configurable)
~/.config/mac-watcher.log	Log file

Email Notifications

Mac Watcher can send email notifications when your Mac wakes from sleep. To configure email notifications:

Edit your configuration file (~/.config/monitor.conf)
Set SEND_EMAIL=true
Configure the email settings (Email and API key from Resend)
Run mac-watcher --test to test your email configuration

Location Tracking

Mac Watcher can track your Mac's location when it wakes from sleep. To enable location tracking:

Edit your configuration file (~/.config/monitor.conf)
Set TRACK_LOCATION=true
Make sure your Mac has location services enabled
Grant Mac Watcher permission to access your location when prompted

Mac Watcher includes a login failure detection feature that allows you to only trigger monitoring actions when a login failure is detected. This helps reduce unnecessary alerts and focuses on potential security incidents.

Beta Feature: Login Failure Detection is currently in beta and may have some limitations.

How It Works

When login failure detection is enabled, Mac Watcher will:

Monitor both Touch ID and password authentication attempts
Distinguish between successful and failed login attempts
Only trigger monitoring actions (screenshots, webcam, location tracking) when login failures occur
Provide detailed logs of authentication events

Configuration

To enable or disable login failure detection:

Run mac-watcher --config
Select "Security Settings" from the menu
Toggle the login failure detection option
Save your changes

Example Configuration

Terminal

$◇ SECURITY
  Login Detection : Enabled

This setting will only trigger monitoring when login failures are detected.

When login failure detection is enabled, Mac Watcher will still run on every wake event but will only capture data and send alerts if it detects that a login attempt failed.

Error Handling

Mac Watcher includes robust error handling to ensure it continues to function even when certain features fail:

If webcam capture fails, Mac Watcher will continue with other enabled features
If email sending fails, Mac Watcher will store the alert data locally
If location services are unavailable, Mac Watcher will skip location tracking
All errors are logged to ~/.config/mac-watcher.log

Troubleshooting

Common Issues

Issue	Solution
Mac Watcher doesn't capture on wake	Run `mac-watcher --diagnostics` to check if all components are working
Email notifications aren't being sent	Verify your API key and email settings and check your spam folder
Webcam capture not working	Make sure your Mac has camera permissions enabled for terminal applications
Location data missing	Check if location services are enabled for terminal applications