Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/docs/configure/permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,14 @@ When working near production systems. Blocks destructive operations entirely and
}
```

With `external_directory: "deny"`, the bash tool refuses a command whose literal text names a path outside the project. It checks arguments and option values (`--out=/x`, `-o/x`, `key=/x`), programs run by path, redirection targets and the words after them, heredoc arguments, assignment and array values, `for`/`[[ ]]`/`case` words, `cd`/`pushd`/`popd` and `env -C` directories, and literal `sh -c`, `eval`, `env -S` and `find -exec` strings. Each path is resolved in the directory its command runs in, through symlinks, with `..` applied after the symlink the way the kernel does (`lnk/../x`). Directories you allow under `external_directory` keep working. A `"*": "deny"` also removes the default allow for skill directories, reference directories and the CLI temp directory, so bundled skill scripts and reference files stored there are refused unless you allow those directories again. The tool-output directory stays allowed.

Some forms are refused because the guard cannot follow them: a loop or function body that changes directory, more than 32 possible working directories, a directory-stack rotation (`pushd +1`), `~-`, another user's `~name`, and `sh -c`/`eval` nested more than three levels deep.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor, not a blocker (docs; safe once behaviour settles): the docs still state forms as refused or checked that are not.

This line and security-faq.md:308 say a loop or function body that changes directory is refused, and so is another user's ~name. They also say env -S and find -exec strings are checked. At head, builtin cd in a function, A=(~root/x), env -S sh -c '…' and find -exec sh -c '…' {} \; all get through (see the inline majors). bash <<< 'head <outside>/s.txt' read the outside file. That is the here-string form of the heredoc-body limit, and it is not listed. Please make both pages match what the guard refuses at merge time.


Deliberate exceptions: character devices (`/dev/null`, `/dev/fd/N`), programs in system binary directories run by full path (`/usr/bin/env`), the pattern or program operand of `grep`/`sed`/`awk`/`rg` (`grep /etc/ f`), separator values (`cut -d/`, `IFS=/`, `tr` operands), and text below a top-level entry that does not exist (`echo /api/v1`) unless a parent-creating program (`mkdir`, `install`, `cp`, `rsync`, …) is given it.

This is a guard rail, not a sandbox. It sees only literal command text. Paths built at run time (`$HOME/x`, `$(pwd)/..`, globs, `cd "$dir"`), files a program opens on its own (`python -c "open('/etc/hosts')"`, an awk program that reads a file, a script that writes to `/tmp`), heredoc bodies and directories from `CDPATH` are not checked. Use a container or VM when you need isolation.

### Per-Agent Lockdown

Give each agent only the permissions it needs:
Expand Down
1 change: 1 addition & 0 deletions docs/docs/reference/security-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,7 @@ Altimate Code includes several layers of protection to keep the agent within you
- **Path traversal blocking.** Paths containing `../` sequences that would escape the project are rejected with an "Access denied" error.
- **Sensitive file protection.** Writing to credential files (`.env`, `.ssh/`, `.aws/`, private keys) triggers a confirmation prompt, even inside the project. See [below](#why-am-i-being-prompted-to-edit-env-files) for details.
- **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.
- **Bash path guard under `external_directory: "deny"`.** With the default (`"ask"`) or `"allow"`, the bash tool checks only the file operations above. When `external_directory` is `"deny"` for `*`, it also refuses a command whose literal text names a path outside the project: arguments (including `--opt=/x`, `-o/x` and `key=/x` values), a program run by path, redirection targets and the words after them, heredoc arguments, assignment and array values (`PY=/x`, `A=(/x)`, `export PATH=/x:$PATH`), `for`/`[[ ]]`/`case` words, `cd`/`pushd`/`popd` and `env -C` directories, and literal `sh -c '…'`, `eval "…"`, `env -S` and `find -exec` strings. Each path is resolved in the directory its command runs in and through symlinks, applying `..` after the symlink as the kernel does, so `lnk/s.txt` and `lnk/../s.txt` through an in-project symlink that points outside are caught. It refuses what it cannot follow: a loop or function body that changes directory, more than 32 possible working directories, `pushd +N`, `~-`, another user's `~name`, and `sh -c`/`eval` nested more than three levels deep. Deliberate exceptions: character devices (`/dev/null`), programs in system binary directories run by full path, the pattern or program operand of `grep`/`sed`/`awk`/`rg`, separator values (`cut -d/`, `IFS=/`, `tr` operands), and text below a missing top-level entry (`echo /api/v1`) unless it is given to a parent-creating program such as `mkdir` or `install`. Directories allowed in `external_directory` (and the tool-output directory) stay usable. Under a `"*": "deny"` rule, skill and reference directories and the CLI temp directory lose their default allow unless you allow them again, so bundled skill scripts that live there are refused too. This is a guard rail over literal command text, not a sandbox: paths built at run time (`$HOME/x`, `$(pwd)/..`, globs, `cd "$dir"`, variables set outside the command), paths a program opens itself (`python -c "open('/etc/hosts')"`, an awk program that reads a file, a script that writes to `/tmp`), heredoc bodies and `CDPATH` lookups are not seen.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This bullet is too long to scan and repeats the full rule list from permissions.md, where the two copies already disagree (the device exemption and the parent-creating program examples differ). Shorten it to the summary and link to Permissions for the complete list of exceptions and limits, so the rule is maintained in one place.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/docs/reference/security-faq.md, line 308:

<comment>This bullet is too long to scan and repeats the full rule list from permissions.md, where the two copies already disagree (the device exemption and the parent-creating program examples differ). Shorten it to the summary and link to Permissions for the complete list of exceptions and limits, so the rule is maintained in one place.</comment>

<file context>
@@ -305,7 +305,7 @@ Altimate Code includes several layers of protection to keep the agent within you
 - **Sensitive file protection.** Writing to credential files (`.env`, `.ssh/`, `.aws/`, private keys) triggers a confirmation prompt, even inside the project. See [below](#why-am-i-being-prompted-to-edit-env-files) for details.
 - **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.
-- **Bash path guard under `external_directory: "deny"`.** With the default (`"ask"`) or `"allow"`, the bash tool checks only the file operations above. When `external_directory` is `"deny"` for `*`, it also refuses any command whose text names a path outside the project: arguments (including `--opt=/x`, `-o/x` and `key=/x` values), a program run by path, redirection targets, assignment values (`PY=/x`, `export PATH=/x:$PATH`), `for`/`[[ ]]`/`case` words, `cd`/`pushd` targets, and literal `sh -c '…'`/`eval "…"` strings. Each path is resolved in the directory its command runs in and through symlinks, so a symlink inside the project that points outside is caught. Directories allowed in `external_directory` (and the tool-output directory) stay usable. Under a `"*": "deny"` rule, skill and reference directories and the CLI temp directory lose their default allow unless you allow them again, so bundled skill scripts that live there are refused too. This is a guard rail over literal command text, not a sandbox: paths built at run time (`$HOME/x`, `$(pwd)/..`, globs, variables set outside the command), paths a program opens itself (`python -c "open('/etc/hosts')"`, a script that writes to `/tmp`) and heredoc bodies are not seen. A command with `sh -c`/`eval` strings nested more than three levels deep is refused rather than checked.
+- **Bash path guard under `external_directory: "deny"`.** With the default (`"ask"`) or `"allow"`, the bash tool checks only the file operations above. When `external_directory` is `"deny"` for `*`, it also refuses a command whose literal text names a path outside the project: arguments (including `--opt=/x`, `-o/x` and `key=/x` values), a program run by path, redirection targets and the words after them, heredoc arguments, assignment and array values (`PY=/x`, `A=(/x)`, `export PATH=/x:$PATH`), `for`/`[[ ]]`/`case` words, `cd`/`pushd`/`popd` and `env -C` directories, and literal `sh -c '…'`, `eval "…"`, `env -S` and `find -exec` strings. Each path is resolved in the directory its command runs in and through symlinks, applying `..` after the symlink as the kernel does, so `lnk/s.txt` and `lnk/../s.txt` through an in-project symlink that points outside are caught. It refuses what it cannot follow: a loop or function body that changes directory, more than 32 possible working directories, `pushd +N`, `~-`, another user's `~name`, and `sh -c`/`eval` nested more than three levels deep. Deliberate exceptions: character devices (`/dev/null`), programs in system binary directories run by full path, the pattern or program operand of `grep`/`sed`/`awk`/`rg`, separator values (`cut -d/`, `IFS=/`, `tr` operands), and text below a missing top-level entry (`echo /api/v1`) unless it is given to a parent-creating program such as `mkdir` or `install`. Directories allowed in `external_directory` (and the tool-output directory) stay usable. Under a `"*": "deny"` rule, skill and reference directories and the CLI temp directory lose their default allow unless you allow them again, so bundled skill scripts that live there are refused too. This is a guard rail over literal command text, not a sandbox: paths built at run time (`$HOME/x`, `$(pwd)/..`, globs, `cd "$dir"`, variables set outside the command), paths a program opens itself (`python -c "open('/etc/hosts')"`, an awk program that reads a file, a script that writes to `/tmp`), heredoc bodies and `CDPATH` lookups are not seen.
 - **Non-git project safety.** For projects outside a git repository, the boundary is strictly the working directory (not the entire filesystem).
 
</file context>
Suggested change
- **Bash path guard under `external_directory: "deny"`.** With the default (`"ask"`) or `"allow"`, the bash tool checks only the file operations above. When `external_directory` is `"deny"` for `*`, it also refuses a command whose literal text names a path outside the project: arguments (including `--opt=/x`, `-o/x` and `key=/x` values), a program run by path, redirection targets and the words after them, heredoc arguments, assignment and array values (`PY=/x`, `A=(/x)`, `export PATH=/x:$PATH`), `for`/`[[ ]]`/`case` words, `cd`/`pushd`/`popd` and `env -C` directories, and literal `sh -c '…'`, `eval "…"`, `env -S` and `find -exec` strings. Each path is resolved in the directory its command runs in and through symlinks, applying `..` after the symlink as the kernel does, so `lnk/s.txt` and `lnk/../s.txt` through an in-project symlink that points outside are caught. It refuses what it cannot follow: a loop or function body that changes directory, more than 32 possible working directories, `pushd +N`, `~-`, another user's `~name`, and `sh -c`/`eval` nested more than three levels deep. Deliberate exceptions: character devices (`/dev/null`), programs in system binary directories run by full path, the pattern or program operand of `grep`/`sed`/`awk`/`rg`, separator values (`cut -d/`, `IFS=/`, `tr` operands), and text below a missing top-level entry (`echo /api/v1`) unless it is given to a parent-creating program such as `mkdir` or `install`. Directories allowed in `external_directory` (and the tool-output directory) stay usable. Under a `"*": "deny"` rule, skill and reference directories and the CLI temp directory lose their default allow unless you allow them again, so bundled skill scripts that live there are refused too. This is a guard rail over literal command text, not a sandbox: paths built at run time (`$HOME/x`, `$(pwd)/..`, globs, `cd "$dir"`, variables set outside the command), paths a program opens itself (`python -c "open('/etc/hosts')"`, an awk program that reads a file, a script that writes to `/tmp`), heredoc bodies and `CDPATH` lookups are not seen.
- **Bash path guard under `external_directory: "deny"`.** With the default (`"ask"`) or `"allow"`, the bash tool checks only the file operations above. When `external_directory` is `"deny"` for `*`, it also refuses a command whose literal text names a path outside the project, following symlinks and `..` the way the kernel does. Directories allowed in `external_directory` (and the tool-output directory) stay usable. The guard is not a sandbox: it does not see run-time-built paths, files a program opens itself, heredoc bodies or `CDPATH` lookups. See [Permissions](../configure/permissions.md) for the forms it refuses, its deliberate exceptions and the full list of limits.

- **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.
Expand Down
Loading
Loading