87 lines
8.0 KiB
Markdown
87 lines
8.0 KiB
Markdown
# Execution & Security
|
|
|
|
This chapter covers how Astrion executes AI-initiated actions safely: the actual behavior of sandbox execution, path authorization, and the approval mechanism. For the four conceptual switches (deployment / permission / execution environment / work mode), see the "Core Concepts" chapter first; this chapter focuses on concrete behavior and day-to-day management.
|
|
|
|
> Scope note: the "live terminal" is just an observation panel and is unrelated to the security mechanisms; see the "Conversation" chapter.
|
|
|
|
---
|
|
|
|
## 1. How Commands Are Executed
|
|
|
|
### run_command: two-phase execution
|
|
|
|
Take the default recommended `approval` mode as an example. The actual journey of a shell command initiated by the AI is:
|
|
|
|
1. **It executes first with read-only identity**—can read but not write (host mode relies on the OS sandbox; docker mode relies on a non-privileged user inside the container);
|
|
2. If the command does not touch any write operation, the result is returned directly, fully transparent;
|
|
3. If it triggers a permission denial (writing files, modifying the system), **it automatically escalates into an approval request to you**;
|
|
4. After you approve, **only this one command** is retried with writable identity; if you reject it or the request times out, it is not executed at all;
|
|
5. The AI receives only the final result; the intermediate process never disturbs its reasoning.
|
|
|
|
`auto_approval` mode replaces the approver in step 3 with an auto-approval agent; `unrestricted` mode skips approval and executes directly; in `readonly` mode, write requests are rejected outright. Note that approval **only escalates this one write—it does not expand the read scope**—the only way to read files outside the workspace is path authorization (see section 2).
|
|
|
|
### Terminal sessions: identity pinned, switching closes them
|
|
|
|
The read/write identity of persistent terminal sessions (terminal family of tools) is **pinned** at startup according to the current permission tier, execution environment, and sandbox policy: under restricted tiers (readonly/approval/auto_approval) the terminal runs with read-only identity and writes inside the terminal are denied directly by the system (EPERM); only under `unrestricted` is the identity writable. When you **switch the execution environment (sandbox ⇄ direct), switch the permission tier between restricted and unrestricted, or switch workspace or container**, existing terminal sessions are **closed immediately**—they never keep running with the old identity, and subsequent operations run in a freshly spawned session under the new policy. This also means: don't switch these toggles while running long tasks, because the task terminates together with the session.
|
|
|
|
### Sub agents and background commands
|
|
|
|
Sub agent terminal processes also go through the execution environment policy: under sandbox they are launched via the host sandbox; under direct they launch directly on the host; in docker mode they execute inside the container. Background commands (`run_in_background`) go through the same read-only/writable sandbox determination as foreground commands—**going to the background does not bypass permissions**.
|
|
|
|
## 2. Day-to-Day Management of Path Authorization
|
|
|
|
Entry point: input bar `+` menu → "Path authorization".
|
|
|
|
- **Readable and writable paths**: the AI's full working scope, typically your project directory;
|
|
- **Read-only paths**: allow the AI to consult but not modify, e.g., reference docs, online config samples, and other projects' source code.
|
|
|
|
Suggested practices:
|
|
|
|
1. Keep authorization minimal—only add the directories the current task needs;
|
|
2. Never add sensitive directories (`~/.ssh`, key stores, system directories) under any category;
|
|
3. Adjust promptly when the nature of a task changes. Authorization takes effect immediately (except for new terminal sessions, see above).
|
|
|
|
## 3. Network Permission
|
|
|
|
An independent group in the input bar permission menu:
|
|
|
|
- **Restricted** (default): loopback only; the AI cannot reach the external network—suited for purely local tasks and prevents data exfiltration;
|
|
- **Fully open**: allows outbound/inbound connections—enable it when the AI needs to search the web, call external APIs, or install dependencies.
|
|
|
|
Network permission is independent of the file sandbox and can also be adjusted in plan mode.
|
|
|
|
## 4. Approval Panel
|
|
|
|
Entry point: `+` menu → "Approval panel". Here you can see the approval history: which commands/writes were submitted for approval, who approved them (human or the auto-approval agent), and the outcome. In `auto_approval` mode, if you don't want the panel to pop up automatically, there is a toggle in Personal Space (not auto-opened by default).
|
|
|
|
## 5. Forbidden Command List
|
|
|
|
The deployment-level config `forbidden_commands.json` (placed in `<data root>/config/`) can define **command patterns that are absolutely forbidden to execute**. Any match is rejected regardless of permission mode. This is the last line of defense—suitable for locking down commands like `rm -rf /` and `shutdown` on server deployments.
|
|
|
|
## 6. A Word of Caution About direct Mode
|
|
|
|
`direct` = commands execute directly on the host, **with no sandbox at all**. It is hard-mutually-exclusive with the restricted tiers (readonly/approval/auto_approval)—only `unrestricted` can select direct, and switching from direct into a restricted tier automatically pushes you back to sandbox. There is exactly one legitimate use case: a command genuinely cannot run inside the sandbox (requires system-level permissions) and there is no alternative. In that case:
|
|
|
|
1. First switch the permission tier to `unrestricted`, then temporarily switch to direct;
|
|
2. Switch back to sandbox (and the original permission tier) as soon as the command is done;
|
|
3. Note that after direct is switched on, it **persists and does not revert automatically**—forgetting to switch back means running unprotected long-term.
|
|
|
|
## 7. Current Security State of docker Mode
|
|
|
|
In docker mode, the isolation boundary between users is the container itself: each user's terminal runs in an independent container, invisible to each other. The permission constraints **inside** the container are also truly enforced:
|
|
|
|
- Under restricted tiers (readonly/approval/auto_approval), run_command, background commands, and persistent terminals all execute as a **non-privileged user (uid 10001)** inside the container—the workspace is owned by root, and writes are denied directly by kernel file permissions, without relying on recognizing command text; after approval, only that one command is retried as root;
|
|
- Prerequisites: the workspace is owned by root, there are no globally writable files, and the container does not mount docker.sock (all satisfied by following the official deployment docs);
|
|
- This enforcement holds only on **Linux hosts**—Docker Desktop on a local macOS machine does not enforce uid file permissions, so don't treat container-internal permissions as a security boundary during local development;
|
|
- Multi-user deployments should combine container resource limits, image minimization, and other standard container security practices.
|
|
|
|
## 8. Security Posture by Platform
|
|
|
|
Reiterating the conclusion from the "Core Concepts" chapter, because it directly affects how much you should trust the sandbox:
|
|
|
|
- **Windows (WSL2)**: full data isolation is achievable, but WSL2 must be installed first;
|
|
- **macOS (sandbox-exec)**: whitelist read model; both writes and reads can be restricted—processes can by default only read system directories, the workspace, and authorized paths; the trade-off is that top-level file names in the ancestor directories of authorized paths can be listed (file contents remain unreadable);
|
|
- **Linux (bwrap+seccomp)**: writes can be restricted, but the read side is still globally readable, not yet aligned to a whitelist, and **not yet tested in practice**—don't rely on its isolation.
|
|
|
|
On any platform, the primary value of the sandbox is **preventing accidental operations**; for genuinely sensitive data, layer path authorization minimization, restricted network, and readonly permissions together for comprehensive protection.
|