#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
| Attacker | In scope |
|---|---|
| Malware running as you (dropper, infostealer, backdoor, persistence) | Yes the main case |
| A program you were tricked into opening | Yes |
| An AI coding agent following malicious instructions | Yes with the Claude Code guard for Claude Code |
| Known malware servers and files | Yes through public threat lists |
| Another user account on the same Mac | Partly it can't read Hostwatch's socket or data, but its processes aren't stopped |
| Malware that already has root, or a kernel exploit | No |
| Someone with physical access to your unlocked Mac | No |
| Attacks on other devices on your network | No |
#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.
| Boundary | What crosses | Guard |
|---|---|---|
| Your account → root collector | commands and firewall answers over /var/run/hostwatch/collector.sock | Unix 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 → app | the event stream | The app connects only to a socket owned by you, mode 0600, not a link, in a root-owned folder. |
| App → disk | history, patterns, decisions, logs | AES-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 → AI | command lines, paths, evidence | Every 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 → app | threat lists, the update check | HTTPS, 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 tools | each command before it runs | A hook that runs before each tool use. It can only make Claude Code stricter, never answers allow. |
| MCP client → history | read-only questions | A random token you register once, kept only as a SHA-256 hash, compared in constant time. Every tool is read-only. |
| Your programs → the network | connections | With 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
| Part | Threat | Protection | What remains |
|---|---|---|---|
| Root collector | Another program talks to it, reads the stream or answers firewall questions | Peer audit token checked against Hostwatch's designated requirement on every connection | A process with root can do anything, as always |
| Root collector | Code injection into it | Hardened runtime: macOS ignores DYLD_INSERT_LIBRARIES and loads only Apple-signed libraries. Verified with a test library. | None known |
| Root collector | Commands from the client | Client config is only used as filters. The collector runs no command a client sends. | None known |
| The app | Replaced by malware | Signed 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 disk | Read by another program running as you | Encrypted. The key needs Hostwatch's code signature, or your keychain password in a dialog. | Settings (the preferences file) are plain |
| Secrets in command lines | Stored in history or sent to an AI | Masked by one rule set: headers, tokens, passwords, URL credentials, known token formats, private keys | A secret in a shape no rule knows can slip through |
| Threat lists | A poisoned list flags a popular domain, or a list carries code | Shape, 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 rules | An Allow opens a place or a server to more than you meant | A 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 programs | A crafted command line talks the AI into letting a program go on | Only 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 yours | One launch of an ordinary program could get through on a wrong verdict. Turn the check off in Settings ▸ AI. |
| AI triage | A 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 protection | A process frozen forever, or the wrong process signalled | A 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 |
| Release | A tampered download | Developer ID signature, Apple notarization, a stapled ticket, a published SHA-256 | Trust 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 BADtag 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
| Technique | Coverage | How | ||
|---|---|---|---|---|
| T1204.002 User Execution: Malicious File | AlertsCan stop | Ran 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 Shell | AlertsCan stop | App spawned shell (a browser or Office starting sh), Encoded/piped command (`curl … \ | sh). The Claude Code guard asks before curl \ | sh`. |
| T1059.002 AppleScript | Alerts | osascript is a watched tool. osascript -e is an encoded command. | ||
| T1059.006 Python, T1059.007 JavaScript | FlagsAlerts | Interpreters are judged by the script they run, never trusted broadly. python -c is an encoded command. | ||
| T1105 Ingress Tool Transfer | Alerts | Download stage (writes into Downloads, /Users/Shared), curl and wget are watched tools. | ||
| T1553.001 Gatekeeper Bypass | Alerts | Quarantine removed (xattr -d com.apple.quarantine, xattr -c). With running the file, the story is Dangerous. | ||
| T1027 Obfuscated Files, T1140 Deobfuscate/Decode | Alerts | Encoded/piped command (base64 -d, piped shells). | ||
| T1569.001 Launchctl | Flags | launchctl is a watched tool. The Claude Code guard asks before launchctl load. |
#Staying on the Mac
| Technique | Coverage | How |
|---|---|---|
| T1543.001 Launch Agent | AlertsCan stop | Autostart write, the strongest single stage. Files on Ask or Strict stop programs writing autostart places. |
| T1543.004 Launch Daemon | Alerts | Autostart write. Writers are usually root, which protection can't stop. |
| T1547.015 Login Items | AlertsCan stop | Background task and login item databases are autostart places. |
| T1546.004 Unix Shell Configuration | AlertsCan stop | .zshrc, .bashrc, .profile, fish config and /etc shell files are autostart places. |
| T1053.003 Cron | Alerts | Cron and at folders and periodic are autostart places. crontab is a watched tool. |
| T1037.005 Startup Items | Alerts | /Library/StartupItems is an autostart place. |
| T1554 Compromise Host Software Binary | Alerts | Binary replaced: a known path whose signer changed. It also reopens a Safe decision. |
| T1647 Plist File Modification | Alerts | For plists in autostart places. Elsewhere it's a gap. |
#Defence evasion and privilege
| Technique | Coverage | How |
|---|---|---|
| T1562.001 Disable or Modify Tools | Partial | The 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 Modification | Flags | csrutil and spctl are watched tools. The Claude Code guard blocks turning them off. |
| T1562.004 Disable or Modify System Firewall | Flags | pfctl is a watched tool. |
| T1548.003 Sudo and Sudo Caching | FlagsCan stop | sudoers and PAM config are protected places. The Claude Code guard asks before sudo. |
| T1222.002 File Permissions Modification | Recorded | chmod, chown and chflags are kept as their own patterns. |
| T1055 Process Injection | Partial | Watch Closely flags task ports, debugging and thread injection, while it records one program. Always-on: gap. |
| T1564.001 Hidden Files and Directories | Gap | |
| T1070.004 File Deletion | Gap | Watch Closely shows deletes while it records. |
#Stealing credentials and data
| Technique | Coverage | How |
|---|---|---|
| T1555.001 Keychain | AlertsCan stop | Credential access for keychain files and security find-generic-password. Keychains are a protected group. |
| T1555.003 Credentials from Web Browsers | AlertsCan stop | Browser password and cookie stores are a protected group. |
| T1539 Steal Web Session Cookie | AlertsCan stop | ~/Library/Cookies and browser cookie stores. |
| T1552.004 Private Keys | AlertsCan stop | ~/.ssh, ~/.gnupg, /etc/ssh. |
| T1552.001 Credentials In Files | AlertsCan stop | AWS, Azure, Google Cloud, GitHub, Docker, Kubernetes, .netrc, .npmrc, .pypirc, .git-credentials, pass. |
| T1005 Data from Local System | PartialCan stop | Messages and Mail are a protected group, and you can add your own folders and files. Other files: recorded. |
| T1056.002 GUI Input Capture | Flags | A fake password dialog needs osascript, a watched tool. |
| T1113 Screen Capture | Flags | screencapture is a watched tool. Capture through system frameworks: gap. |
| T1082 System Information Discovery, T1057 Process Discovery | Recorded | |
| T1046 Network Service Discovery | Alerts | Port 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 Poisoning | Alerts | Router changed: the router's address now answers from a different hardware address. |
#Calling home and sending data out
| Technique | Coverage | How |
|---|---|---|
| T1071.001 Web Protocols | AlertsCan stop | New domain, Beaconing (steady interval, low jitter), known command servers from threat lists. The firewall on Ask or Strict blocks new destinations. |
| T1571 Non-Standard Port | AlertsCan stop | Raw-IP connection: a public IP, an unusual port, no DNS answer before it, an untrusted program. |
| T1095 Non-Application Layer Protocol | Partial | Raw-IP connections. The Claude Code guard blocks /dev/tcp and nc -e. UDP sent without connecting: gap. |
| T1568.002 Domain Generation Algorithms | Partial | Every never-seen domain is New domain after the learning period. No dedicated DGA check. |
| T1071.004 DNS | Partial | Known bad domains are caught. Data hidden inside DNS queries: gap. |
| T1041 Exfiltration Over C2 Channel | AlertsCan stop | Large 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 Service | Partial | The Claude Code guard blocks secrets sent to paste and webhook sites. Elsewhere: new domains and the firewall only. |
| T1048 Exfiltration Over Alternative Protocol | Partial | scp, sftp, ftp are watched tools. |
| T1090 Proxy | Gap | Traffic through a proxy shows only the proxy. |
#Damage
| Technique | Coverage | How |
|---|---|---|
| T1486 Data Encrypted for Impact | Gap | Watch Closely flags mass renames while it records. Always-on ransomware detection: gap. |
| T1485 Data Destruction | Partial | The Claude Code guard blocks rm -rf ~, diskutil eraseDisk and similar. Other programs: gap. |
| T1490 Inhibit System Recovery | Flags | tmutil 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.