desktop-guardian

# Desktop Guardian Full macOS GUI access and desktop automation for OpenClaw, powered by **Hammerspoon**. ## What It Does ### 🖥️ GUI Access - **Query** all open windows, apps, and dialogs with full detail (titles, buttons, states) - **Close** specific windows or tabs — not just kill entire apps - **Click buttons** in system dialogs and popups (with safety guardrails) - **Send keypresses** to any app - **Quit or force-quit** apps programmatically - **Chrome DevTools Protocol** integration for tab-level browser control ### 🛡️ Active Desktop Monitoring - **Watches** for system dialogs, permission prompts, error popups, and alerts in real-time - **Auto-dismisses** known-safe dialogs (e.g., "app downloaded from internet") - **Alerts you** via Telegram/chat when human input is needed (e.g., security prompts) - **Detects and closes** unauthorized apps and excess browser windows/tabs - **Enforces** configurable desktop policies via YAML rules - **Logs** every action for full audit trail ## Requirements - macOS (Tahoe or later) - Hammerspoon (installed automatically) + Accessibility permission - Python 3 + PyYAML (installed automatically) - Optional: Chrome with `--remote-debugging-port=9222` for tab-level control ## Installation ```bash bash scripts/install.sh ``` This will: 1. Install Hammerspoon if needed 2. Install the DesktopGuardian Spoon 3. Guide you through Accessibility permission 4. Compile the Swift fallback for degraded mode 5. Set up config, logs, and LaunchAgent ## Configuration Config file: `~/.openclaw/skills/desktop-guardian/policy.yaml` See `assets/config.example.yaml` for all options. Key settings: - **cleanup.enabled**: Master switch for auto-cleanup (default: true) - **cleanup.apps.whitelist**: Apps allowed to run; others get closed - **browsers.chrome.max_windows/max_tabs**: Limits before auto-close - **dialogs.auto_dismiss**: Apps whose dialogs are safe to dismiss - **dialogs.ignore**: Apps whose dialogs should be silently ignored - **alerts.notify_on_actions**: Send notification for every auto-action ## Chrome Tab Monitoring For tab-level granularity, Chrome must run with CDP enabled: ```bash open -a "Google Chrome" --args --remote-debugging-port=9222 ``` Without CDP, only window counts are available. ## Kill Switch Instantly disable all actions: ```bash touch ~/.openclaw/skills/desktop-guardian/KILL_SWITCH ``` Remove to re-enable: ```bash rm ~/.openclaw/skills/desktop-guardian/KILL_SWITCH ``` ## Graceful Degradation Without Hammerspoon, the skill runs in **monitor-only mode** using a Swift fallback binary. It can detect violations but cannot auto-close or dismiss anything. ## helpers.py Subcommands ``` parse_config — Output config as key=value pairs validate_config — Validate config (exit 0/1) check_quiet — Exit 0 if NOT in quiet hours evaluate_snapshot — Apply policy to snapshot JSON → violations + actions parse_query — Convert snapshot to key=value pairs safe_hs_command — Generate safe hs -c command string update_state — Update alert cooldown state log_violation — Append to violation log daily_summary — Generate daily summary list_apps — List apps from last snapshot check_cooldown — Check if alert cooldown has expired ``` ## Security - **Never** interpolates shell variables into `hs -c` commands - Hardcoded button blacklist: won't click Allow, Delete, Install, etc. - Hardcoded app blacklist: won't dismiss SecurityAgent, Keychain Access, etc. - All app names validated against `^[a-zA-Z0-9 ._-]+$` - Config file mode 600, state uses atomic writes - Full audit log of every action taken ## Uninstall ```bash bash scripts/uninstall.sh ``` Removes LaunchAgent, Spoon, and init.lua entries. Preserves config/logs unless you choose to remove them. Does NOT uninstall Hammerspoon.