fix: harden path sandboxing with symlink protection, safe defaults, and sensitive file guards

- Add `Filesystem.containsReal()` with `realpathSync` to prevent symlink escape attacks
  (same class of bug as Codex GHSA-w5fx-fh39-j5rw and Claude Code CVE-2025-54794)
- Add `isAbsolute(rel)` check to `Filesystem.contains()` for Windows cross-drive bypass
- Update `Instance.containsPath()` to use symlink-aware `containsReal()`
- Add safe permission defaults: deny `rm -rf`, `git push --force`, `git reset --hard`,
  `DROP DATABASE`, `TRUNCATE` out of the box
- Add `Protected.isSensitiveWrite()` to detect writes to `.git/`, `.ssh/`, `.aws/`,
  `.env*`, credential files even inside the project boundary
- Add `assertSensitiveWrite()` guard to write, edit, and apply_patch tools
- Remove resolved TODO comments from `file/index.ts`
- Update SECURITY.md, permissions docs, and security FAQ with practical guidance
- Add 94 tests including 62 e2e tests covering symlink attacks, path traversal,
  sensitive file detection, and combined attack scenarios

Closes #202

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anandgupta42

SECURITY.md

@@ -12,22 +12,29 @@ submit one that will be an automatic ban from the project.
 
 Altimate Code is an AI-powered data engineering coding assistant that runs locally on your machine. It provides an agent system with access to powerful tools including shell execution, file operations, and web access.
 
-### No Sandbox
+### Permission System
 
-Altimate Code does **not** sandbox the agent. The permission system exists as a UX feature to help users stay aware of what actions the agent is taking - it prompts for confirmation before executing commands, writing files, etc. However, it is not designed to provide security isolation.
+Altimate Code includes a permission system that prompts for confirmation before the agent executes commands, writes files, or accesses resources outside your project. You can configure each tool as `"allow"`, `"ask"`, or `"deny"` — and use pattern-based rules to fine-tune behavior (e.g., allow `dbt run` but deny `rm *`).
 
-If you need true isolation, run Altimate Code inside a Docker container or VM.
+The permission system is designed to keep you informed and in control of what the agent does. It includes:
+
+- **Per-tool and per-pattern controls** with wildcard matching
+- **Per-agent permission overrides** (e.g., restrict `analyst` to read-only)
+- **External directory detection** that prompts when the agent accesses files outside your project
+- **Path traversal protection** that blocks attempts to escape the project directory
+- **Doom loop detection** that alerts you when the agent repeats failed actions
+
+However, the permission system operates at the application level. It does not provide OS-level sandboxing — the process runs with your user permissions. For high-security environments or when working with sensitive production systems, we recommend running Altimate Code inside a Docker container or VM for additional isolation.
 
 ### Server Mode
 
-Server mode is opt-in only. When enabled, set `OPENCODE_SERVER_PASSWORD` to require HTTP Basic Auth. Without this, the server runs unauthenticated (with a warning). It is the end user's responsibility to secure the server - any functionality it provides is not a vulnerability.
+Server mode is opt-in only. When enabled, set `OPENCODE_SERVER_PASSWORD` to require HTTP Basic Auth. Without this, the server runs unauthenticated (with a warning). It is the end user's responsibility to secure the server — any functionality it provides is not a vulnerability.
 
 ### Out of Scope
 
 | Category                        | Rationale                                                               |
 | ------------------------------- | ----------------------------------------------------------------------- |
 | **Server access when opted-in** | If you enable server mode, API access is expected behavior              |
-| **Sandbox escapes**             | The permission system is not a sandbox (see above)                      |
 | **LLM provider data handling**  | Data sent to your configured LLM provider is governed by their policies |
 | **MCP server behavior**         | External MCP servers you configure are outside our trust boundary       |
 | **Malicious config files**      | Users control their own config; modifying it is not an attack vector    |

docs/docs/configure/permissions.md

@@ -49,7 +49,7 @@ For tools that accept arguments (like `bash`), use pattern matching:
 }
 ```
 
-Patterns are matched in order -- first match wins. Use `*` as a wildcard.
+Patterns are matched in order — last matching rule wins. Use `*` as a wildcard. Place your most specific rules first and your catch-all `"*"` rule last.
 
 ## Per-Agent Permissions
 
@@ -104,3 +104,125 @@ Set permissions via environment variable:
 export ALTIMATE_CLI_PERMISSION='{"bash":"deny","write":"deny"}'
 altimate
 ```
+
+## Recommended Configurations
+
+### Data Engineering (Default — Balanced)
+
+A good starting point for most data engineering workflows. Allows safe read operations, prompts for writes and commands:
+
+```json
+{
+  "permission": {
+    "read": "allow",
+    "glob": "allow",
+    "grep": "allow",
+    "list": "allow",
+    "edit": "ask",
+    "write": "ask",
+    "bash": {
+      "dbt *": "allow",
+      "git status": "allow",
+      "git diff *": "allow",
+      "git log *": "allow",
+      "ls *": "allow",
+      "cat *": "allow",
+      "rm *": "deny",
+      "DROP *": "deny",
+      "DELETE *": "deny",
+      "TRUNCATE *": "deny",
+      "*": "ask"
+    },
+    "external_directory": "ask"
+  }
+}
+```
+
+### Strict (Production-Adjacent Work)
+
+When working near production systems. Blocks destructive operations entirely and requires confirmation for everything else:
+
+```json
+{
+  "permission": {
+    "read": "allow",
+    "glob": "allow",
+    "grep": "allow",
+    "list": "allow",
+    "edit": "ask",
+    "write": "ask",
+    "bash": {
+      "dbt *": "ask",
+      "git status": "allow",
+      "rm *": "deny",
+      "DROP *": "deny",
+      "DELETE *": "deny",
+      "TRUNCATE *": "deny",
+      "ALTER *": "deny",
+      "git push *": "deny",
+      "git reset *": "deny",
+      "*": "ask"
+    },
+    "external_directory": "deny"
+  }
+}
+```
+
+### Per-Agent Lockdown
+
+Give each agent only the permissions it needs:
+
+```json
+{
+  "agent": {
+    "analyst": {
+      "permission": {
+        "write": "deny",
+        "edit": "deny",
+        "bash": {
+          "SELECT *": "allow",
+          "dbt docs *": "allow",
+          "*": "deny"
+        }
+      }
+    },
+    "builder": {
+      "permission": {
+        "bash": {
+          "dbt *": "allow",
+          "git *": "ask",
+          "DROP *": "deny",
+          "*": "ask"
+        }
+      }
+    }
+  }
+}
+```
+
+## How Permissions Work
+
+When the agent wants to use a tool, the permission system evaluates your rules in order:
+
+1. **Config rules** — from `altimate-code.json`
+2. **Agent-level rules** — per-agent overrides
+3. **Session approvals** — patterns you've approved with "Allow always" during the current session
+
+If a rule matches, it applies. If no rule matches, the default is `"ask"` — you'll be prompted.
+
+When prompted, you have three choices:
+
+| Choice | Effect |
+|--------|--------|
+| **Allow once** | Approves this single action |
+| **Allow always** | Approves this pattern for the rest of the session |
+| **Reject** | Blocks the action (optionally with feedback for the agent) |
+
+"Allow always" approvals persist for your current session only. They reset when you restart Altimate Code.
+
+## Tips
+
+- **Start with `"ask"` and relax as you build confidence.** You can always approve patterns with "Allow always" during a session.
+- **Use `"deny"` for truly dangerous commands** like `rm *`, `DROP *`, `git push --force *`, and `git reset --hard *`. These are blocked even if other rules would allow them.
+- **Use per-agent permissions** to enforce least-privilege. An analyst doesn't need write access. A builder doesn't need `DROP`.
+- **Review the prompt before approving.** The TUI shows you exactly what will run — including diffs for file edits and the full command for bash operations.

docs/docs/security-faq.md

@@ -198,6 +198,48 @@ For additional safety:
 - Run against a **staging environment** before production
 - Use the `analyst` agent with restricted permissions for ad-hoc queries
 
+## What protections does Altimate Code have for file access?
+
+Altimate Code includes several layers of protection to keep the agent within your project:
+
+- **Project boundary enforcement** — File operations check that paths stay within your project directory (or git worktree for monorepos). Attempts to read or write outside the project trigger an `external_directory` permission prompt.
+- **Path traversal blocking** — Paths containing `../` sequences that would escape the project are rejected with an "Access denied" error.
+- **Bash command analysis** — The bash tool parses commands with tree-sitter to detect file operations (`rm`, `cp`, `mv`, etc.) targeting paths outside your project, and prompts for permission.
+- **Non-git project safety** — For projects outside a git repository, the boundary is strictly the working directory (not the entire filesystem).
+
+These protections operate at the application level. For additional isolation, you can run Altimate Code inside a Docker container or VM.
+
+## Best practices for staying safe
+
+1. **Review before approving.** The permission prompt shows you exactly what will happen — diffs for file edits, the full command for bash. Take a moment to read it.
+
+2. **Deny destructive commands.** Add these to your `altimate-code.json` to block the most dangerous operations regardless of other rules:
+
+    ```json
+    {
+      "permission": {
+        "bash": {
+          "rm -rf *": "deny",
+          "DROP *": "deny",
+          "DELETE *": "deny",
+          "git push --force *": "deny",
+          "git reset --hard *": "deny",
+          "*": "ask"
+        }
+      }
+    }
+    ```
+
+3. **Use per-agent permissions.** Give each agent only what it needs. The `analyst` agent doesn't need write access. See [Permissions](configure/permissions.md) for examples.
+
+4. **Use read-only database credentials for exploration.** When using the agent for analysis or ad-hoc queries, connect with a read-only database user.
+
+5. **Work on a branch.** Let the agent work on a feature branch so you can review changes before merging. Git gives you a full safety net.
+
+6. **Back up before large operations.** If the agent is about to make sweeping changes, commit your current state first. You can always `git stash` or revert.
+
+7. **Use Docker for sensitive environments.** If you're working with production systems or sensitive data, running Altimate Code in a container provides OS-level isolation on top of the permission system.
+
 ## Where should I report security vulnerabilities?
 
 **Do not open public GitHub issues for security vulnerabilities.** Instead, email **security@altimate.ai** with a description, reproduction steps, and your severity assessment. You'll receive acknowledgment within 48 hours. See the full [Security Policy](https://github.com/AltimateAI/altimate-code/blob/main/SECURITY.md) for details.

packages/opencode/src/agent/agent.ts

@@ -80,6 +80,23 @@ export namespace Agent {
         "*.env.*": "ask",
         "*.env.example": "allow",
       },
+      // Safety defaults: deny destructive commands that are rarely intentional.
+      // Users can override these in altimate-code.json if needed.
+      bash: {
+        "rm -rf *": "deny",
+        "rm -fr *": "deny",
+        "rmdir /s *": "deny",
+        "git push --force *": "deny",
+        "git push -f *": "deny",
+        "git reset --hard *": "deny",
+        "git clean -fd *": "deny",
+        "git clean -f *": "deny",
+        "git checkout -- .": "deny",
+        "DROP DATABASE *": "deny",
+        "DROP SCHEMA *": "deny",
+        "TRUNCATE *": "deny",
+        "*": "ask",
+      },
     })
     const user = PermissionNext.fromConfig(cfg.permission ?? {})
 

packages/opencode/src/file/index.ts

@@ -500,8 +500,6 @@ export namespace File {
     const project = Instance.project
     const full = path.join(Instance.directory, file)
 
-    // TODO: Filesystem.contains is lexical only - symlinks inside the project can escape.
-    // TODO: On Windows, cross-drive paths bypass this check. Consider realpath canonicalization.
     if (!Instance.containsPath(full)) {
       throw new Error(`Access denied: path escapes project directory`)
     }
@@ -580,8 +578,6 @@ export namespace File {
     }
     const resolved = dir ? path.join(Instance.directory, dir) : Instance.directory
 
-    // TODO: Filesystem.contains is lexical only - symlinks inside the project can escape.
-    // TODO: On Windows, cross-drive paths bypass this check. Consider realpath canonicalization.
     if (!Instance.containsPath(resolved)) {
       throw new Error(`Access denied: path escapes project directory`)
     }

packages/opencode/src/file/protected.ts

@@ -37,6 +37,38 @@ const DARWIN_ROOT = ["/.DocumentRevisions-V100", "/.Spotlight-V100", "/.Trashes"
 
 const WIN32_HOME = ["AppData", "Downloads", "Desktop", "Documents", "Pictures", "Music", "Videos", "OneDrive"]
 
+/**
+ * Directories and file patterns that should require explicit permission before
+ * write operations, even when they are located inside the project boundary.
+ * These contain credentials, version control state, or configuration that
+ * should not be modified without the user's awareness.
+ */
+const SENSITIVE_DIRS = [
+  ".git",
+  ".ssh",
+  ".gnupg",
+  ".aws",
+  ".azure",
+  ".gcloud",
+  ".kube",
+  ".docker",
+]
+
+const SENSITIVE_FILES = [
+  ".env",
+  ".env.local",
+  ".env.production",
+  ".env.staging",
+  ".env.development",
+  ".npmrc",
+  ".pypirc",
+  ".netrc",
+  "credentials.json",
+  "service-account.json",
+  "id_rsa",
+  "id_ed25519",
+]
+
 export namespace Protected {
   /** Directory basenames to skip when scanning the home directory. */
   export function names(): ReadonlySet<string> {
@@ -56,4 +88,30 @@ export namespace Protected {
     if (process.platform === "win32") return WIN32_HOME.map((n) => path.join(home, n))
     return []
   }
+
+  /**
+   * Check if a file path targets a sensitive directory or file that should
+   * require explicit user permission before modification, even inside the project.
+   * Returns the name of the matched sensitive pattern, or undefined if not sensitive.
+   */
+  export function isSensitiveWrite(filepath: string): string | undefined {
+    const segments = filepath.split(path.sep)
+    const filename = segments[segments.length - 1] ?? ""
+
+    // Check if any path segment is a sensitive directory
+    for (const segment of segments) {
+      if (SENSITIVE_DIRS.includes(segment)) {
+        return segment
+      }
+    }
+
+    // Check if the filename matches a sensitive file pattern
+    for (const pattern of SENSITIVE_FILES) {
+      if (filename === pattern) return pattern
+      // Match .env.* variants (e.g., .env.local.bak)
+      if (pattern === ".env" && filename.startsWith(".env.")) return filename
+    }
+
+    return undefined
+  }
 }

packages/opencode/src/project/instance.ts

@@ -93,14 +93,15 @@ export const Instance = {
   /**
    * Check if a path is within the project boundary.
    * Returns true if path is inside Instance.directory OR Instance.worktree.
+   * Uses symlink-aware resolution to prevent symlink escape attacks.
    * Paths within the worktree but outside the working directory should not trigger external_directory permission.
    */
   containsPath(filepath: string) {
-    if (Filesystem.contains(Instance.directory, filepath)) return true
+    if (Filesystem.containsReal(Instance.directory, filepath)) return true
     // Non-git projects set worktree to "/" which would match ANY absolute path.
     // Skip worktree check in this case to preserve external_directory permissions.
     if (Instance.worktree === "/") return false
-    return Filesystem.contains(Instance.worktree, filepath)
+    return Filesystem.containsReal(Instance.worktree, filepath)
   },
   state<S>(init: () => S, dispose?: (state: Awaited<S>) => Promise<void>): () => S {
     return State.create(() => Instance.directory, init, dispose)

packages/opencode/src/tool/apply_patch.ts

@@ -7,7 +7,7 @@ import { FileWatcher } from "../file/watcher"
 import { Instance } from "../project/instance"
 import { Patch } from "../patch"
 import { createTwoFilesPatch, diffLines } from "diff"
-import { assertExternalDirectory } from "./external-directory"
+import { assertExternalDirectory, assertSensitiveWrite } from "./external-directory"
 import { trimDiff } from "./edit"
 import { LSP } from "../lsp"
 import { Filesystem } from "../util/filesystem"
@@ -60,6 +60,7 @@ export const ApplyPatchTool = Tool.define("apply_patch", {
     for (const hunk of hunks) {
       const filePath = path.resolve(Instance.directory, hunk.path)
       await assertExternalDirectory(ctx, filePath)
+      await assertSensitiveWrite(ctx, filePath)
 
       switch (hunk.type) {
         case "add": {

packages/opencode/src/tool/edit.ts

@@ -16,7 +16,7 @@ import { FileTime } from "../file/time"
 import { Filesystem } from "../util/filesystem"
 import { Instance } from "../project/instance"
 import { Snapshot } from "@/snapshot"
-import { assertExternalDirectory } from "./external-directory"
+import { assertExternalDirectory, assertSensitiveWrite } from "./external-directory"
 
 const MAX_DIAGNOSTICS_PER_FILE = 20
 
@@ -52,6 +52,7 @@ export const EditTool = Tool.define("edit", {
 
     const filePath = path.isAbsolute(params.filePath) ? params.filePath : path.join(Instance.directory, params.filePath)
     await assertExternalDirectory(ctx, filePath)
+    await assertSensitiveWrite(ctx, filePath)
 
     let diff = ""
     let contentOld = ""