waggle-os/THREAT_MODEL.md

Waggle OS — Threat Model

Waggle OS is a workspace-native AI agent platform with persistent memory, shipped as a Tauri desktop binary (Windows/macOS) with a bundled Node.js sidecar. This document states the trust boundary and the controls that enforce it, so contributors can reason about security without reading the full agent + connector stack.

Status: living document. The controls below are implemented and cited to source. Known gaps are open and honestly listed.

Trust Boundary

Waggle runs on the user's own machine, for that single user. The human operator is trusted: they own the workspace, the vault, the filesystem, and the connector credentials. The threat model does not try to stop the operator from doing what they are entitled to do on their own device.

The boundary Waggle defends is between the trusted operator + Waggle's own code and untrusted external content that flows into the agent's context:

• conversation/file imports (Harvest: ChatGPT/Claude/Gemini/PDF/markdown/URL adapters)
• connector auto-fetch + tool reads (calendar, email, GitHub, web, files)
• tool output sourced from outside the process
• MCP server output
• saved memory frames derived from any of the above

The core risk is prompt injection: untrusted content carrying instructions that try to hijack the agent ("ignore previous instructions", fake SYSTEM: authority, role override, prompt-extraction) and make it act against the operator's intent.

Controls (implemented)

1. Injection scanning at every ingress — scanForInjection

packages/hive-mind-core/src/injection-scanner.ts (re-exported via packages/agent/src/injection-scanner.ts). Three pattern sets — role-override, prompt-extraction, instruction-injection — produce a score; safe = score < 0.3 (instruction-injection is weighted higher, 0.6, for tool_output context). It gates the three untrusted chokepoints:

• Harvest ingestion (external conversation exports).
• Recall: orchestrator.ts scans the joined recalled block and drops the entire recall on a flag (orchestrator.ts:777-786) — a poisoned memory frame never silently re-enters context on a later turn.
• Tool output: tool-executor.ts scans every executed-tool result and replaces flagged content with a [SECURITY] … sanitized placeholder before any observer or the model sees it.

2. Structural untrusted-content fence — untrustedContextWrapper

packages/agent/src/untrusted-context.ts. Tool output that passes the scan is still external data. Before it enters the model's next-turn context it is wrapped in a delimiter-guarded block with a "this is DATA, not instructions" header, applied in tool-executor.ts (after scan + compression). Embedded guard markers in the body are escaped so untrusted content cannot break out of the fence to forge a close-marker. This is defense-in-depth on top of the scanner: the scanner blocks known attack phrasings; the fence makes all external tool output structurally non-authoritative.

Maintained invariant (taint preservation): tool output is delivered as a discrete role:'tool' message (agent-loop.ts) / Anthropic tool_result content block (anthropic-proxy.ts) and is never string-concatenated into the user turn. Waggle's provider adapters do no lossy role-alternation merge (openai-compat.ts), so the data/instruction boundary is preserved natively. Follow-up guard: if a provider adapter that merges consecutive same-role turns is ever added, it MUST insert a boundary rather than concatenate an untrusted block into the operator's real request — re-audit at that time.

3. Human-in-the-loop confirmation — confirmation.ts

packages/agent/src/confirmation.ts. State-changing tools require explicit approval: an ALWAYS_CONFIRM set (write_file, edit_file, git_push, install_capability, create_skill/delete_skill, cross-workspace reads, …) plus a CONNECTOR_WRITE_PATTERNS regex that gates connector write actions (_create_/_update_/_delete_/_send_/…). Read-only/informational calls flow freely; destructive ops do not inherit autonomy.

4. Capability install audit trail — install-audit.ts

packages/core/src/install-audit.ts. Every install-relevant action (proposed, approved, installed, rejected, failed, uninstalled) is persisted to the .mind DB with risk, approval class, initiator, and trust source — a verifiable history of what was installed, when, why, and by whom. Backs the EU-AI-Act capability-provenance story.

5. Local secret storage — vault.ts

packages/core/src/vault.ts. Secrets are encrypted with AES-256-GCM under a machine-local key file; each entry is independently encrypted. API keys live in the vault or .env (never committed; .env.example carries key names only). No secret is ever written to a prompt, a log, or a memory frame.

6. MCP tool scope gate — scope.ts

packages/memory-mcp/src/scope.ts + packages/hive-mind-mcp-server/src/scope.ts. An external agent (Claude Code/Codex) granted stdio access to the memory substrate can be scoped read-only via WAGGLE_MCP_SCOPES / HIVE_MIND_SCOPES: a memory:read scope registers only the read tools, so a read-only client literally cannot call save/cleanup/ingest. Default (unset) stays full read+write for backward-compat; memory:write implies memory:read. This keeps a poisoned or buggy external agent from writing junk into the substrate.

7. Workspace filesystem boundary + secret deny — file-store.ts

packages/core/src/file-store.ts. Every FileStore op resolves the caller path and asserts it cannot escape the workspace root: a segment-boundary containment check (not a string prefix — ${root}-evil is rejected) plus symlink-aware containment (the realpath'd target must stay under the realpath'd root, so a benign-named symlink/junction pointing at ~/.ssh or /etc is denied, while in-root monorepo links still work). For LINKED external folders, isSensitiveFilePath additionally denies reads/writes/listing of well-known secret material (SSH/GPG keys, cloud + terraform credentials, .env, id_rsa, authorized_keys, backup copies, *.pem), normalized against Windows ADS (::$DATA) and trailing-dot/space tricks. searchFiles/listFiles filter the same set so search never even discloses a secret's existence. This is real containment + a defense-in-depth BLOCKLIST — not a sandbox: the deny is a curated list (it cannot enumerate every secret a home dir holds) and is deny-by-default with no per-workspace override yet.

8. SSRF egress guard — url-egress-guard.ts

packages/agent/src/url-egress-guard.ts (guarding web_fetch in system-tools.ts) and the structurally-identical packages/hive-mind-core/src/harvest/url-egress-guard.ts (guarding UrlAdapter.fetchAndParse, reached by the MCP ingest_source url path in packages/{memory-mcp,hive-mind-mcp-server}/src/tools/ingest.ts). A URL named by untrusted content or a user is resolved to concrete IP(s); the fetch is refused if any resolved address is loopback / private (RFC1918 + CGNAT) / link-local / unique-local / multicast / reserved / unspecified. This closes the cloud instance-metadata exfiltration path — 169.254.169.254 (link-local) reaching IAM credentials — which matters because the cloud/TEAMS sidecar binds 0.0.0.0 (docker-compose.production.yml, render.yaml). Coverage:

• Scheme allowlist: only http:/https: (blocks file:/gopher:/ftp: redirect tricks).
• Obfuscated literals (octal 0177.0.0.1, decimal 2130706433, hex 0x7f000001) are normalized by the OS resolver — net.isIP rejects them as literals, so they route through dns.lookup (getaddrinfo) which returns the canonical dotted form the classifier blocks.
• IPv6 including ::1, fe80::/10, fc00::/7, ff00::/8, and IPv4-mapped (::ffff:169.254.169.254) which is unwrapped and classified as its embedded v4.
• Redirects are followed manually (redirect: 'manual') and the target is re-validated at every hop, so a public URL cannot 30x-bounce into a private address; a hop cap bounds it.
• Desktop localhost: loopback is blocked by default; a legitimate local-dev fetch is permitted only when WAGGLE_ALLOW_LOCAL_FETCH=1 (loopback only — private/link-local stay blocked even then). Fail-closed: an unclassifiable/malformed address is treated as blocked.

Known Gaps (open, honest)

1. Pattern-based scanner. scanForInjection is regex/heuristic — novel phrasings, heavy obfuscation, or non-English attacks outside the small multilingual set can evade it. The structural fence (control 2) is the backstop, but the fence is advisory: a sufficiently capable model can still be jailbroken from inside a correctly-fenced block. Both controls reduce, not eliminate, injection risk.
2. No filesystem/shell sandbox. File and command tools run as the app-process user. Control 7 now confines FileStore ops to the workspace boundary and blocks well-known secrets in linked dirs, but it is a path-level guard + blocklist, not OS-level confinement; shell/command tools remain bounded only by the confirmation gate (control 3). The linked-dir secret deny is also a curated blocklist (whole secret classes — e.g. browser profiles, shell history, .config/gh|gcloud tokens — are out of scope) and has no per-workspace override, so legitimate .env/.npmrc edits in a linked project are denied by default. (S3FileStore — the TEAMS/cloud backend — now rejects .. traversal in keys and uses a ReDoS-safe glob matcher for search, but it has no secret-deny blocklist; its bucket prefix is the isolation boundary.)
3. Fence scope is tool output only. Recalled memory carries an equivalent prose preamble (orchestrator.ts) but is not yet wrapped in the same structural fence; harvest content is scanned at ingest but not re-fenced per frame. Extending the fence to recall is a low-marginal-value follow-up.
4. isReadOnly persona gating is fail-open. Read-only personas filter write tools by denylist rather than an inverse allowlist; a tool missing from the denylist is not blocked. Flip to allowlist + static mutator backstop when persona governance is next touched.
5. Connector endpoint URLs are not redacted before logging. userinfo/query/fragment on LiteLLM/connector URLs can leak credentials into logs — fold a redactUrl pass into the next compliance/logging pass.
6. Connector auto-harvest persists external content durably. Opt-in PRO connector harvest writes external data (e.g. inbox metadata + message previews) into the personal mind, where it is recalled into model context on later turns. Content is injection-scanned per frame but NOT scanned for secrets/PII; the email harvest pins $select to subject/from/preview (not full bodies) to bound exposure. A secret-pattern redaction pass before writeFrame is a follow-up.
7. SSRF guard has a residual DNS-rebind TOCTOU window. The egress guard (control 8) resolves + validates the hostname, then hands the URL to fetch, which resolves it a second time — a hostname whose DNS flips to a private IP between the two lookups could slip through on the fetch's own resolution. The window is re-validated on every redirect hop, but full closure needs IP-pinning (connect to the validated address) which fetch+HTTPS can't do portably without breaking TLS SNI/cert validation. Also out of scope: the guard bounds the target address, not response size/content, and does not defend a genuinely public-but-malicious endpoint. The duplicated agent/hive-mind-core guard copies share one spec and must be kept in sync (they cannot share a module — hive-mind-core is OSS-mirrored and must not import @waggle/agent).