Hostwatch / docs
Docs · Chapter 08

#Threat model and attack coverage

What Hostwatch defends against, what it doesn't, how it protects itself, and which attack techniques it sees, mapped to MITRE ATT&CK. Where Hostwatch is weak, this page says so.

#What Hostwatch is for

Hostwatch watches one Mac for an attacker who got code running as you: a malicious download, a poisoned package, an infostealer, a backdoor that wants to start again after a reboot, or an AI coding agent tricked into running something harmful. It learns what is normal, flags what isn't, joins small steps into one story, and can stop launches, file access and connections you didn't allow.

What it protects

  • your secrets: SSH and GPG keys, keychains, cloud and developer credentials, browser passwords and cookies
  • what starts by itself: launch agents and daemons, login items, shell startup files, cron
  • your network: which programs talk to which servers
  • its own record of what happened: the history, patterns and decisions, encrypted on disk

Who it defends against

AttackerIn scope
Malware running as you (dropper, infostealer, backdoor, persistence)Yes the main case
A program you were tricked into openingYes
An AI coding agent following malicious instructionsYes with the Claude Code guard for Claude Code
Known malware servers and filesYes through public threat lists
Another user account on the same MacPartly it can't read Hostwatch's socket or data, but its processes aren't stopped
Malware that already has root, or a kernel exploitNo
Someone with physical access to your unlocked MacNo
Attacks on other devices on your networkNo

#What Hostwatch assumes

  • System Integrity Protection is on. Hostwatch relies on macOS protecting Endpoint Security and its own tools (pfctl, tcpdump) and the code signing checks.
  • The app is somewhere only an administrator can write, such as /Applications. The collector is the app's own binary, run as root. Anything that can replace the app gains root at its next start.
  • Full Disk Access is granted to the collector. Without it, Endpoint Security tells it nothing.
  • macOS itself is not compromised. Hostwatch reads what macOS reports. A rootkit can lie to both.

#Trust boundaries

Each line where data crosses from a less trusted side to a more trusted one, and what guards it.

BoundaryWhat crossesGuard
Your account → root collectorcommands and firewall answers over /var/run/hostwatch/collector.sockUnix socket only, no network port. The kernel names the peer (audit token), and the collector accepts only code that satisfies its own designated requirement: same Team ID and bundle id. Socket 0600, folder root-owned.
Root collector → appthe event streamThe app connects only to a socket owned by you, mode 0600, not a link, in a root-owned folder.
App → diskhistory, patterns, decisions, logsAES-256-GCM, for every file Hostwatch writes. The key is in a keychain item only Hostwatch's code may read, or wrapped by the Secure Enclave.
Events → AIcommand lines, paths, evidenceEvery prompt is masked for secrets right before it's sent. An AI can't mark a shell, interpreter or system tool Safe beyond an exact folder in your own projects. Your decisions always win over any AI.
Internet → appthreat lists, the update checkHTTPS, no cookies. A list must be text in the right shape and size, can never make anything trusted, and can't flag the big platforms by their own domain. The update check only tells you, nothing is downloaded or installed.
Claude Code → its toolseach command before it runsA hook that runs before each tool use. It can only make Claude Code stricter, never answers allow.
MCP client → historyread-only questionsA random token you register once, kept only as a SHA-256 hash, compared in constant time. Every tool is read-only.
Your programs → the networkconnectionsWith the firewall on Ask or Strict, the packet filter sends your programs' new connections through a relay that waits for your decision. Root's connections pass.

#How Hostwatch protects itself

PartThreatProtectionWhat remains
Root collectorAnother program talks to it, reads the stream or answers firewall questionsPeer audit token checked against Hostwatch's designated requirement on every connectionA process with root can do anything, as always
Root collectorCode injection into itHardened runtime: macOS ignores DYLD_INSERT_LIBRARIES and loads only Apple-signed libraries. Verified with a test library.None known
Root collectorCommands from the clientClient config is only used as filters. The collector runs no command a client sends.None known
The appReplaced by malwareSigned and notarized. macOS checks the signature at launch. Keep it in /Applications.An app in a folder you can write can be replaced
Data on diskRead by another program running as youEncrypted. The key needs Hostwatch's code signature, or your keychain password in a dialog.Settings (the preferences file) are plain
Secrets in command linesStored in history or sent to an AIMasked by one rule set: headers, tokens, passwords, URL credentials, known token formats, private keysA secret in a shape no rule knows can slip through
Threat listsA poisoned list flags a popular domain, or a list carries codeShape, size and growth checks. Big platforms can't be flagged by their own domain. A malicious file on a platform anyone can publish to (GitHub, Telegram, Dropbox…) doesn't flag the platform. Lists only raise alerts.A list provider can still miss things or be late. Malware calling home through such a platform isn't a list match, only its behaviour is judged.
Your exceptions and rulesAn Allow opens a place or a server to more than you meantA place's exceptions name one program each, never "any program". Destinations: the most specific decides, Block when a program is on both lists.A program you always allow in a place can read it, by your choice.
AI check of paused programsA crafted command line talks the AI into letting a program go onOnly a sure Safe lets it go on, once. Never a shell, interpreter, high-risk program or sensitive file. A warning sign Hostwatch found blocks it. The decision stays yoursOne launch of an ordinary program could get through on a wrong verdict. Turn the check off in Settings ▸ AI.
AI triageA command line written to fool the AI ("this is safe")The AI never decides alone for shells and interpreters. Precedence: you, then your rules, then AI, then automatic. Risk only goes up by itself.The AI can still be wrong about ordinary programs. Its verdict is shown as the AI's, and you can reopen it.
Hold and protectionA process frozen forever, or the wrong process signalledA watchdog resumes every held process after 65 s. The path is checked before every signal, so a reused pid is left alone.Stopping happens just after the start, see below
ReleaseA tampered downloadDeveloper ID signature, Apple notarization, a stapled ticket, a published SHA-256Trust in Apple and GitHub

#Known weaknesses

These are real, and listed so you can judge Hostwatch fairly.

  • Malware running as you can quit Hostwatch. The app runs as you, so a process of yours can end it. The collector then stops watching after 15 seconds without a client, and nothing records what happens next. Restarting the app resumes everything. Raising an alert when the app goes away unexpectedly is planned.
  • It decides before a launch or a protected file's open, not after. In Ask and Strict, Endpoint Security holds them until Hostwatch answers. Two things still slip past: what macOS's own programs do (they pass without a question, unless you marked their pattern, which is then enforced right after it starts), and anything while the app is too busy to answer within a moment (it goes on, and is paused right after).
  • Only your own processes can be stopped. Launch and file protection and holds act on processes of your user. A root process, or another user's, is reported but not stopped. The firewall judges your programs' connections too: root's connections and macOS's DNS service pass without being asked about.
  • Detection judges behaviour and text. Well-hidden code, an unknown way to persist, or a secret in an unusual format can get through. The always-on monitor records launches, file opens and connections, not every file write or rename. Watch Closely records about 60 kinds of event, but only for the program you point it at.
  • Containers, virtual machines and some network traffic aren't fully covered: see Known limitations in Privacy, security and limits.
  • The AI can be wrong. It suggests, you decide. An explicit Apply the Verdicts is your decision, recorded as yours.

#Attack coverage (MITRE ATT&CK)

MITRE ATT&CK is the public catalogue of how attackers work, used to compare security tools. This table maps the macOS techniques Hostwatch sees. What each level means:

  • Alerts raises a story, a KNOWN BAD tag or a badge by itself or together with other steps.
  • Flags a new pattern you're asked to review, and a weak step in stories. Not an alert on its own.
  • Can stop stopped or blocked when the named feature is on. Off by default unless the table says so.
  • Recorded kept in the history and searchable, without a signal.
  • Gap not covered today.

#Execution and getting in

TechniqueCoverageHow
T1204.002 User Execution: Malicious FileAlertsCan stopRan downloaded/temp file and Unsigned download ran stages. A file known to malware lists is Known malware. Launches on Ask or Strict stop unknown launches.
T1059.004 Unix ShellAlertsCan stopApp spawned shell (a browser or Office starting sh), Encoded/piped command (`curl … \sh). The Claude Code guard asks before curl \sh`.
T1059.002 AppleScriptAlertsosascript is a watched tool. osascript -e is an encoded command.
T1059.006 Python, T1059.007 JavaScriptFlagsAlertsInterpreters are judged by the script they run, never trusted broadly. python -c is an encoded command.
T1105 Ingress Tool TransferAlertsDownload stage (writes into Downloads, /Users/Shared), curl and wget are watched tools.
T1553.001 Gatekeeper BypassAlertsQuarantine removed (xattr -d com.apple.quarantine, xattr -c). With running the file, the story is Dangerous.
T1027 Obfuscated Files, T1140 Deobfuscate/DecodeAlertsEncoded/piped command (base64 -d, piped shells).
T1569.001 LaunchctlFlagslaunchctl is a watched tool. The Claude Code guard asks before launchctl load.

#Staying on the Mac

TechniqueCoverageHow
T1543.001 Launch AgentAlertsCan stopAutostart write, the strongest single stage. Files on Ask or Strict stop programs writing autostart places.
T1543.004 Launch DaemonAlertsAutostart write. Writers are usually root, which protection can't stop.
T1547.015 Login ItemsAlertsCan stopBackground task and login item databases are autostart places.
T1546.004 Unix Shell ConfigurationAlertsCan stop.zshrc, .bashrc, .profile, fish config and /etc shell files are autostart places.
T1053.003 CronAlertsCron and at folders and periodic are autostart places. crontab is a watched tool.
T1037.005 Startup ItemsAlerts/Library/StartupItems is an autostart place.
T1554 Compromise Host Software BinaryAlertsBinary replaced: a known path whose signer changed. It also reopens a Safe decision.
T1647 Plist File ModificationAlertsFor plists in autostart places. Elsewhere it's a gap.

#Defence evasion and privilege

TechniqueCoverageHow
T1562.001 Disable or Modify ToolsPartialThe Claude Code guard blocks spctl --master-disable and changing Hostwatch's files, and asks before pkill Hostwatch. Other programs quitting Hostwatch is a gap (see Known weaknesses).
T1553.006 Code Signing Policy ModificationFlagscsrutil and spctl are watched tools. The Claude Code guard blocks turning them off.
T1562.004 Disable or Modify System FirewallFlagspfctl is a watched tool.
T1548.003 Sudo and Sudo CachingFlagsCan stopsudoers and PAM config are protected places. The Claude Code guard asks before sudo.
T1222.002 File Permissions ModificationRecordedchmod, chown and chflags are kept as their own patterns.
T1055 Process InjectionPartialWatch Closely flags task ports, debugging and thread injection, while it records one program. Always-on: gap.
T1564.001 Hidden Files and DirectoriesGap
T1070.004 File DeletionGapWatch Closely shows deletes while it records.

#Stealing credentials and data

TechniqueCoverageHow
T1555.001 KeychainAlertsCan stopCredential access for keychain files and security find-generic-password. Keychains are a protected group.
T1555.003 Credentials from Web BrowsersAlertsCan stopBrowser password and cookie stores are a protected group.
T1539 Steal Web Session CookieAlertsCan stop~/Library/Cookies and browser cookie stores.
T1552.004 Private KeysAlertsCan stop~/.ssh, ~/.gnupg, /etc/ssh.
T1552.001 Credentials In FilesAlertsCan stopAWS, Azure, Google Cloud, GitHub, Docker, Kubernetes, .netrc, .npmrc, .pypirc, .git-credentials, pass.
T1005 Data from Local SystemPartialCan stopMessages and Mail are a protected group, and you can add your own folders and files. Other files: recorded.
T1056.002 GUI Input CaptureFlagsA fake password dialog needs osascript, a watched tool.
T1113 Screen CaptureFlagsscreencapture is a watched tool. Capture through system frameworks: gap.
T1082 System Information Discovery, T1057 Process DiscoveryRecorded
T1046 Network Service DiscoveryAlertsPort scan: one address on your network trying ten ports on this Mac within a minute. Scans from the internet are shown on the network map.
T1557.002 ARP Cache PoisoningAlertsRouter changed: the router's address now answers from a different hardware address.

#Calling home and sending data out

TechniqueCoverageHow
T1071.001 Web ProtocolsAlertsCan stopNew domain, Beaconing (steady interval, low jitter), known command servers from threat lists. The firewall on Ask or Strict blocks new destinations.
T1571 Non-Standard PortAlertsCan stopRaw-IP connection: a public IP, an unusual port, no DNS answer before it, an untrusted program.
T1095 Non-Application Layer ProtocolPartialRaw-IP connections. The Claude Code guard blocks /dev/tcp and nc -e. UDP sent without connecting: gap.
T1568.002 Domain Generation AlgorithmsPartialEvery never-seen domain is New domain after the learning period. No dedicated DGA check.
T1071.004 DNSPartialKnown bad domains are caught. Data hidden inside DNS queries: gap.
T1041 Exfiltration Over C2 ChannelAlertsCan stopLarge upload: 100 MB or more sent within an hour to a destination the program first reached today. The firewall blocks destinations you didn't allow.
T1567 Exfiltration Over Web ServicePartialThe Claude Code guard blocks secrets sent to paste and webhook sites. Elsewhere: new domains and the firewall only.
T1048 Exfiltration Over Alternative ProtocolPartialscp, sftp, ftp are watched tools.
T1090 ProxyGapTraffic through a proxy shows only the proxy.

#Damage

TechniqueCoverageHow
T1486 Data Encrypted for ImpactGapWatch Closely flags mass renames while it records. Always-on ransomware detection: gap.
T1485 Data DestructionPartialThe Claude Code guard blocks rm -rf ~, diskutil eraseDisk and similar. Other programs: gap.
T1490 Inhibit System RecoveryFlagstmutil and diskutil are watched tools.

#Beyond ATT&CK: AI agents

Prompt injection against coding agents isn't an ATT&CK technique yet (it is in MITRE ATLAS). For Claude Code, the guard checks every shell command, file write and read of a secret before it happens, and blocks or asks. AI sessions show what each agent session did, grouped.

#Checking these claims yourself

# The release is signed, notarized and unchanged
codesign --verify --deep --strict --verbose=2 /Applications/Hostwatch.app
spctl --assess --type execute --verbose=2 /Applications/Hostwatch.app

# Hardened runtime is on (flags=0x10000(runtime))
codesign -dv /Applications/Hostwatch.app 2>&1 | grep flags

# The collector's socket: root-owned folder, socket 0600 and yours
ls -ld /var/run/hostwatch /var/run/hostwatch/collector.sock

# Data on disk is sealed (starts with HWV1)
head -c 4 ~/Library/Application\ Support/Hostwatch/stories.json && echo

The source is public. To report a way around any of these protections, see SECURITY.md.

↑