MacSentry
Security alerts for your Mac, delivered to Telegram.
English · Tiếng Việt
MacSentry watches a Mac for remote access, persistence, tampering and security posture changes, and sends
each finding to Telegram as it happens, so the record leaves the machine before anyone can clean it up.
It is built for people who look after their own Mac, or a few machines, and want to know when something
changes without running a full EDR stack.
[!NOTE]
The app is available in English and Vietnamese (it follows the system language, or pick one in Settings).
Telegram alerts from the daemon are still in Vietnamese; help translating them is welcome (see
Contributing).
Highlights
- Remote access: SSH, Screen Sharing/VNC, Remote Desktop, SMB, AFP and Remote Apple Events sessions, with
a popup for unknown IPs, reverse DNS and whois details, plus TeamViewer, AnyDesk, RustDesk, Chrome Remote
Desktop and tunnels such as ngrok and cloudflared.
- Persistence: LaunchAgents/Daemons (including binaries swapped under an existing plist), Login and
Background Items, configuration profiles, system extensions, kexts, authorization plugins, login hooks,
trusted root CAs, browser extensions, cron,
sudoers, PAM, authorized_keys, shell rc files, with diffs of
what changed and secrets masked.
- Endpoint Security: failed authentication with the exact calling process, TCC grants (screen
recording, accessibility, Full Disk Access, camera, microphone...), XProtect detections, Gatekeeper bypass,
new users and admins, and dangerous commands such as reverse shells, keychain dumps,
curl | sh and
disabling SIP, Gatekeeper or the firewall.
- Posture: firewall, Gatekeeper, SIP, FileVault, automatic security updates, auto-login, Guest, screen
lock, Find My, MDM, outdated XProtect.
- Agents you rely on: Wazuh (process, manager connection, configuration, active responses) and a built-in
catalog of EDR, MDM, VPN and firewall agents, extendable through
/etc/macsentry.agents.
- Hard to silence: a root daemon starts at boot, the menu bar app and the daemon watch each other,
kill -9 is reported, the log is append-only, and an optional heartbeat lets an outside service tell you
when the Mac goes quiet.
- Light on resources: event driven (FSEvents, IOKit, DiskArbitration, SCDynamicStore, Endpoint Security),
roughly 1-3% of one core in total, running at background priority. See Performance.
See docs/detections.md for the full list.
Screenshots
| Events | Connection history |
|---|
| |
| Trusted IPs | Settings |
| |
Screenshots use sample data and documentation IP ranges.
How it works
flowchart LR
ES["macsentry-es<br/>(root, Endpoint Security<br/>via eslogger)"] -- spool --> D
D["macsentryd<br/>(root LaunchDaemon)"] --> LOG[("/var/log/macsentry.log<br/>append-only")]
D -- shared scan --> APP["MacSentry.app<br/>(menu bar, per user)"]
APP -. watches .-> D
D --> TG(["Telegram bot"])
APP --> TG
D -. heartbeat .-> HC(["Healthchecks-style<br/>monitor (optional)"])
| Component | Runs as | Role |
|---|
MacSentry.app | user (LaunchAgent, restarted if killed) | Remote access popups, screen lock/unlock, camera and microphone, sleep; history, trusted IPs, event viewer and settings. |
macsentryd | root (LaunchDaemon, from boot) | Most detections, the append-only log, Telegram delivery, the daily report and the heartbeat. |
macsentry-es | root (LaunchDaemon, needs Full Disk Access) | Reads Endpoint Security events through /usr/bin/eslogger and hands them to the daemon. It never holds the Telegram token. |
More detail is in docs/architecture.md.
Requirements
- macOS 26 (Tahoe) or later, on Apple silicon or Intel
- Xcode 26 or later, or the matching Command Line Tools (Swift 6)
- A Telegram bot token from @BotFather and your chat ID
Installation
MacSentry is built from source.
git clone https://github.com/vuminhhoa/macsentry.git
cd MacSentry
./build.sh # builds and installs ~/Applications/MacSentry.app, then starts it
- On first launch the app installs the daemon and helper itself (
daemon/install.sh --auto): macOS asks for an
administrator password once, no Terminal needed. If you cancel, click Install Now under
Monitoring Components.
- Open MacSentry → Settings, enter the bot token and chat ID, and send a test message. If the daemon was
installed before Telegram was set up, the app reinstalls it so the daemon shares the app's bot (one more password prompt).
- Grant Full Disk Access to
/usr/local/libexec/macsentry-es and /usr/local/libexec/macsentryd:
System Settings → Privacy & Security → Full Disk Access → + → press ⌘⇧G
and paste the path. The daemon reminds you on Telegram until this is done.
For a separate daemon bot (recommended, see Security model), a heartbeat URL, or to turn off
process execution monitoring, run sudo ./daemon/install.sh --reconfigure.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
