THREAT_MODEL.md

Threat Model & Security Boundaries for localagent

Document Status: Production Reference
Last Updated: July 2026
Enforcement Boundary: Application-Level Policy Engine + Optional Process Isolation (bwrap)

---

1. System Overview & Security Philosophy

localagent is an autonomous CLI tool orchestrator that executes tools (via Model Context Protocol - MCP) based on local LLM outputs (Ollama).

Because LLMs are non-deterministic, susceptible to hallucination, and vulnerable to indirect prompt injection, localagent operates under a Zero-Trust Model Inference stance: outputs from the LLM are treated as untrusted user input.

---

2. In-Scope Defenses (What localagent Protects Against)

localagent explicitly mitigates the following categories of threats when tool proposals are processed:

2.1 Path Traversal & Unbounded File Operations

• Threat: The LLM or an injected prompt attempts to read, write, or delete files outside the configured workspace directory (e.g., ../../etc/passwd, C:\Windows, ~/.ssh/id_rsa).
• Mitigation:
  • Path canonicalization using filepath.Abs and filepath.EvalSymlinks.
  • Prefix containment checking (strings.HasPrefix(canonicalTarget, canonicalWorkspace)).
  • Rejection of unresolved symlinks pointing outside the workspace.

2.2 Shell Injection & Unbounded Command Execution

• Threat: The LLM attempts to chain commands or execute shell sub-processes via raw string interpolation (e.g., git status; rm -rf /, echo hello && whoami, cat $(secret)).
• Mitigation:
  • Direct binary execution via exec.Command (passing distinct argument arrays rather than invoking shell interpreters like sh -c or cmd.exe /c).
  • Explicit AST token sanitization rejecting shell meta-characters (;&|><$ and backticks) and working directory escape flags (git -C /etc, --git-dir=/etc).
  • Whitelisting allowed executable binaries.

2.3 Network Data Exfiltration & Unrestricted Sockets (Strict Mode Default)

• Threat: A compromised tool or prompt injection payload attempts to open network connections or send host data to external command-and-control servers.
• Mitigation:
  • In --sandbox-mode=strict, network namespace access is disabled by default (--unshare-all without --share-net).
  • Outbound socket creation and network calls are blocked at the OS kernel boundary unless the user explicitly passes the --allow-network CLI flag.

2.4 Unauthorized Writes & Unintended Modifications

• Threat: The LLM executes write/overwrite/delete operations without explicit user awareness or consent.
• Mitigation:
  • Capability-based policy engine categorizing operations into READ, WRITE, and EXECUTE.
  • Mandatory interactive confirmation gates displaying target parameters and file diff previews prior to execution.

---

3. Explicit Non-Protections & Security Limits (What it Does NOT Protect Against)

Warning

localagent is NOT a hypervisor or OS-level security boundary by default. You must understand the following explicit limitations:

3.1 Bugs or Logic Flaws in the Application Policy Engine Itself

• Limitation: Security enforcement (path evaluation, regex sanitization, whitelist checking) is implemented at the application level in Go.
• Risk: Any bug, parsing oversight, encoding mismatch (e.g. Unicode path normalization, OS-specific path separators on Windows vs Linux), or logic flaw in internal/sandbox directly invalidates the security boundary. Application-level enforcement cannot protect against implementation errors within itself.

3.2 Malicious or Compromised MCP Tool Servers

• Limitation: MCP servers are spawned as child processes running under the host user account privileges.
• Risk: If an MCP server binary is malicious, compromised, or contains its own vulnerabilities, it inherits the full permissions of the user running localagent. Unless executed inside OS-level containers (bwrap on Linux with unshared namespaces), the application policy engine cannot prevent a rogue MCP process from accessing the host filesystem directly.

3.3 Indirect Prompt Injection via Untrusted Content

• Limitation: Reading external files, git repositories, or web pages into the LLM context allows untrusted input to influence LLM reasoning.
• Risk: While localagent blocks unauthorized tool calls resulting from prompt injection, it cannot prevent the LLM from being tricked into outputting misleading text, corrupting summaries, or proposing malicious tool arguments (which then rely entirely on the user or policy gate to catch).

3.4 Human Confirmation Fatigue & Blind Approvals

• Limitation: Interactive confirmation gates rely on human judgment.
• Risk: If a user blindly approves tool proposals (-y flag or habituated y responses) without reviewing the target path or diff preview, localagent will execute the action as requested.

3.5 Host OS Kernel Exploits & Hardware Vulnerabilities

• Limitation: localagent operates entirely in user space.
• Risk: Kernel 0-day privilege escalations, hardware side-channel attacks (Spectre/Meltdown), memory corruption in underlying dependencies, or compromised host OS binaries are completely outside the scope of this security architecture.

---

4. Threat Matrix Summary

Threat Category	Protected?	Enforcement Mechanism	Failure Mode / Residual Risk
Path Traversal (../)	YES	EvalSymlinks + Workspace Prefix Match	Bug in Go path normalization logic
Shell Injection (;&|)	YES	Direct exec.Command + Argument Regex	Invocation of a binary that itself interprets flags dangerous
Directory Flag Escape (git -C)	YES	Path Flag Parser Validation	Unrecognized custom flag syntax
Network Data Exfiltration	YES	Unshared Network Namespace (Strict Mode)	Passing --allow-network opt-in flag
Unauthorized File Write	YES	Interactive User Confirmation Gate	User confirmation fatigue / -y flag
Bugs in localagent Code	NO	N/A (Self-enforced in user space)	Full bypass of application security rules
Malicious MCP Server	PARTIAL	Depends on bwrap process sandbox	Unisolated child process inherits host user permissions
Kernel 0-Day / OS Escapes	NO	Out of Scope	Host compromise