# watchcheck 🔍

**English** | [简体中文](README.zh-CN.md)

**See what's actually running on your Mac — and who's watching.**

watchcheck reads the processes on your Mac (read-only) and turns cryptic names
into plain language: what each one is, who makes it, and — its specialty —
whether it's **endpoint-monitoring software** (EDR / DLP / MDM / network & print
auditing). It has **first-class coverage of Chinese enterprise monitoring agents**
(深信服 Sangfor, 亿赛通 ESafeNet, IP-Guard, 奇安信, 360, 联软, 天空卫士, 北信源, and
other domestic EDR/DLP/MDM tools) that Western tools — Little Snitch, KnockKnock,
even general-purpose LLMs — consistently misidentify or don't know at all.

## Two ways to use it

One read-only engine, two front-ends — pick either or both:

| | 🖥️ Live panel | 🤖 MCP server |
|---|---|---|
| **What** | A local, auto-refreshing dashboard that reads your **current** processes — like Activity Monitor, but it explains each one and flags monitoring software | Plugs into your AI assistant (Claude, Cursor, …) so the **LLM can read your live processes** and answer questions about them |
| **For** | Anyone — no AI, no account, no setup beyond install | People who live in an AI client and want to *ask* in their own words |
| **Run** | `watchcheck panel` | add to your MCP config, then ask Claude |
| **Network** | none — binds `127.0.0.1` only | none — local stdio |

> [!IMPORTANT]
> **watchcheck is read-only and honest by design.** It identifies software and
> describes what that *class* of software is *capable* of per vendor docs. It does
> **not** prove any tool is actively capturing you right now, and it **cannot** see
> the *content* of any data being sent. It is a transparency tool, not a way to
> evade legitimate corporate policy. On a company-managed device, removing or
> tampering with required software may violate your employment agreement.

## Install

Requires Python 3.10+ and macOS.

```bash
# with uv (recommended)
uv tool install watchcheck          # once published
# or from source
git clone https://github.com/derkcc/watchcheck && cd watchcheck
uv venv --python 3.12 && uv pip install -e .
```

## 🖥️ The live panel

A local, read-only dashboard that re-collects your processes / CPU / memory / GPU
every couple of seconds and explains them. Binds `127.0.0.1` only — never touches
the network, never modifies anything.

```bash
watchcheck panel                       # opens http://127.0.0.1:8787/
watchcheck panel --lang en --interval 2 --port 8787
```

Activity-Monitor-style tabs — **Monitoring / CPU / Memory / GPU / All processes** —
where every process row carries an inline plain-language explanation and a 🟢/🔴/⚪
marker; monitoring software is flagged with its capabilities and evidence.

Prefer a static, shareable file instead of a live server?

```bash
watchcheck report            # one-shot HTML snapshot → ~/watchcheck-report.html
watchcheck report --lang en  # English (~/watchcheck-report.en.html)
```

Both are bilingual (`--lang zh|en`). GPU is reported system-wide — macOS exposes
no per-process GPU without `sudo`.

## 🤖 The MCP server

Let your AI assistant read and explain your live processes. Add to your MCP client
config — **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "watchcheck": { "command": "watchcheck" }
  }
}
```

From source (no install):

```json
{
  "mcpServers": {
    "watchcheck": {
      "command": "uv",
      "args": ["--directory", "/path/to/watchcheck", "run", "watchcheck"]
    }
  }
}
```

Then just ask:

> "Scan my Mac — is my company monitoring me, and what can they see?"
> "What is `acnvmagent`?"
> "What monitoring tools does watchcheck know about?"

### How it works (no screenshots needed)

You never copy process names or paste screenshots. The server runs on your Mac
and reads the live process list itself; Claude calls it and explains the result.

```mermaid
flowchart TD
    A["You — ask in plain language<br/>(no screenshots, no copy-paste)"] --> B["Claude picks a tool:<br/>scan / overview / explain_process"]
    B --> C["watchcheck runs locally on your Mac<br/>reads processes via ps / launchd / certs<br/>read-only · no network · nothing modified"]
    C --> D["Returns structured facts:<br/>vendor / type / capabilities / CPU · memory<br/>(things it doesn't know are marked 'unknown')"]
    D --> E["Claude explains in plain language<br/>and answers follow-ups"]
    E --> A
```

Division of labor: **watchcheck** reads the processes and supplies the facts
(from its signature DB); **Claude** orchestrates the calls, turns the facts into
plain language, and fills in anything marked `unknown` from its own knowledge.

### Tools exposed

| Tool | What it does |
|---|---|
| `scan` | Read-only scan → identified **monitoring** software with evidence, capabilities, privacy impact |
| `overview` | Typed breakdown of **everything** running (Apple system / browser / cloud / your own VPN / monitoring / unknown …), duplicates collapsed, with CPU/memory/GPU |
| `explain_process` | Explain one process / label / bundle id in plain language |
| `list_signatures` | The full catalog of what watchcheck can identify (transparency) |
| `raw_inventory` | Raw collected artifacts, no matching (for investigating unknowns / contributing) |

## How it works

watchcheck reads only what macOS already exposes — nothing is modified, no files
are read for content, no network calls:

| Source | Command | What it reveals |
|---|---|---|
| Processes | `ps` | Running agents + CPU / memory |
| Persistence | LaunchDaemons/Agents plists | What auto-starts |
| System extensions | `systemextensionsctl list` | Network / endpoint-security filters |
| Kernel extensions | `kextstat` | Kernel-level agents (highest privilege) |
| MDM | `profiles status` | DEP / MDM enrollment |
| Certificates | `security find-certificate` | Corporate root CAs (HTTPS interception) |
| GPU | `ioreg` | System-wide GPU utilization |

It then matches these against two data files: a curated, community-maintained
**monitoring signature DB**
([`signatures.yaml`](src/watchcheck/data/signatures.yaml) — the part that knows
Chinese enterprise tools) and a **common-process catalog**
([`common_processes.yaml`](src/watchcheck/data/common_processes.yaml) — everyday
macOS processes), so it can reassure you that *most* of what's running is normal
and clearly flag what isn't. The signature DB is the whole point; everything else
is a thin, replaceable shell.

## Contributing signatures (the important part)

Coverage of Chinese enterprise tools on macOS is the gap, and it's where you can
help most. If `raw_inventory` (or the panel's "unknown" rows) shows something
watchcheck doesn't recognize:

1. Find the artifact (process name, launchd label, bundle id, kext id, cert CN, path).
2. Add an entry to [`signatures.yaml`](src/watchcheck/data/signatures.yaml)
   following the schema and the **honesty rules** at the top of that file.
3. Set `verified: true` only if you confirmed it on a real machine.
4. Open a PR. See [CONTRIBUTING.md](CONTRIBUTING.md).

Signatures are facts about software, contributed by people who see it in the wild.
That's the moat — and it only grows with help.

## Roadmap

- [ ] Windows + Linux collectors
- [ ] Optional `outbound_activity` (which monitoring processes have live connections — volume/destination only, never content)
- [ ] Wider Chinese-vendor macOS signatures
- [ ] Per-process CPU sparklines in the live panel

## License

MIT. See [LICENSE](LICENSE).

Vendor and product names are used nominatively to identify software. No affiliation
with or endorsement by any vendor is implied.