Security & Sandbox¶

fuseraft-cli provides two runtime containment mechanisms: a filesystem sandbox that restricts where agents can read, write, and execute, and an HTTP allowlist that restricts which hosts agents can contact. Both are enforced in code via an IFunctionInvocationFilter that runs before plugin functions execute.

Filesystem sandbox¶

Set Security.FileSystemSandboxPath to a directory path. Every FileSystem and Shell plugin call that involves a path argument is checked before execution.

Security:
  FileSystemSandboxPath: /home/user/projects/myapp

What is checked¶

Plugin	Argument	Check type
`FileSystem`	`path`	Hard deny if resolved path is outside sandbox
`FileSystem`	`directory`	Hard deny if resolved path is outside sandbox
`Shell`	`workingDirectory`	Hard deny if resolved path is outside sandbox
`Shell`	`command`	Best-effort scan for absolute paths escaping sandbox
`Shell`	`script`	Best-effort scan for absolute paths escaping sandbox

Path resolution¶

All paths are resolved to their canonical absolute form (symlinks followed, .. removed) before checking. A path is allowed if its canonical form starts with the sandbox root.

Shell command scanning¶

The command and script arguments are scanned with a regex for tokens that look like absolute paths. Matches are resolved and checked against the sandbox. System binary prefixes are exempted so agents can invoke normal tools without being blocked:

Exempted prefixes (Unix): /usr/, /bin/, /sbin/, /lib/, /lib64/, /opt/, /nix/, /run/current-system/, /snap/

Exempted prefixes (Windows): C:\Windows\, C:\Program Files\, C:\Program Files (x86)\

This means /usr/bin/dotnet build src/ is allowed, but cat /etc/passwd is blocked.

Limitation¶

Shell command scanning is heuristic. It can be bypassed by variable interpolation, subshells, or shell escaping. For strict containment, use the CodeExecution plugin (Docker) instead of Shell. Docker containers run with --network none and are isolated from the host filesystem.

Denial response¶

When a check fails, the function is never executed and the agent receives this tool result:

[DENIED] Path '/etc/passwd' is outside the configured sandbox '/home/user/projects/myapp'.
All file operations must stay within the sandbox.

The agent sees this as a tool error and can respond accordingly (typically by staying within the sandbox).

HTTP allowlist¶

Set Security.HttpAllowedHosts to a list of permitted hostnames. If the list is non-empty, any Http plugin call to a hostname not on the list is denied.

Security:
  HttpAllowedHosts:
    - api.github.com
    - registry.npmjs.org
    - pypi.org

Private and loopback addresses are always blocked regardless of the allowlist:

Range	Blocked addresses
Loopback	`127.0.0.0/8`
Private class A	`10.0.0.0/8`
Private class B	`172.16.0.0/12`
Private class C	`192.168.0.0/16`
Link-local	`169.254.0.0/16`
IPv6 loopback	`::1`
IPv6 link-local	`fe80::/10`

This prevents SSRF-style attacks where an agent is tricked into making requests to internal infrastructure.

An empty HttpAllowedHosts list means unrestricted (but private IPs are still blocked).

Entries in HttpAllowedHosts support ${ENV_VAR} token expansion — the token is replaced with the environment variable's value at startup:

Security:
  HttpAllowedHosts:
    - "${SNOW_HOST}"       # e.g. mycompany.service-now.com
    - api.github.com

Tokens referencing unset variables expand to an empty string. See Configuration → ApiProfiles for the same expansion applied to profile header values.

AllowPrivateHosts¶

Set Security.AllowPrivateHosts: true to bypass the private/loopback IP check. This allows agents to reach locally-running servers such as a mock API or a development service.

Security:
  AllowPrivateHosts: true
  HttpAllowedHosts:
    - localhost
    - "127.0.0.1"

Do not set this in production configs. It is intended exclusively for local development and sandbox environments where agents must contact a server running on the same machine. The HttpAllowedHosts allowlist is still enforced when set — AllowPrivateHosts only disables the private-IP range check, not the host allowlist.

Combining both¶

Security:
  FileSystemSandboxPath: /home/user/projects/myapp
  HttpAllowedHosts:
    - api.github.com

Agents are now constrained to: - Reading and writing files only within /home/user/projects/myapp - Making HTTP requests only to api.github.com

Docker containment (CodeExecution plugin)¶

For the highest isolation, use the CodeExecution plugin's sandbox_run instead of Shell. Each invocation gets a fresh Docker container:

--network none — no network access
--memory 256m — memory capped
--cpus 0.5 — CPU capped
Container is removed after execution

Plugins:
  - CodeExecution

sandbox_run(language="python", code="import os; print(os.listdir('/'))")

This gives a fully isolated execution environment regardless of what the FileSystemSandboxPath is set to.

Execution rings¶

When Security.FileSystemSandboxPath is configured, each agent is placed in an execution ring based on its TrustScore. Rings layer on top of the path-level sandbox to control which operations the agent may perform within those paths.

Ring	TrustScore	Writes allowed	Shell allowed
Ring 1 (Trusted)	≥ 0.80	yes	yes
Ring 2 (Standard)	≥ 0.60	yes	yes
Ring 3 (Sandbox)	< 0.60	no	no

Ring 3 agents can read files and list directories but are blocked from writing, deleting, running shell commands, or making network requests. This is useful for review-only agents or auditors that should not be able to modify state.

- Name: Auditor
  TrustScore: 0.5
  Plugins:
    - FileSystem

See Governance — Execution rings for details.

`sudo` protection¶

sudo is unconditionally blocked in the Shell plugin. Any command or script containing sudo — including in pipe chains (cmd && sudo apt install ...), semicolon sequences, or multi-line scripts — is caught before execution and the agent receives:

[DENIED] sudo is not permitted. Prefer non-privileged alternatives: pip install --user,
python -m pip install --user, pipx, or a virtual environment
(python -m venv .venv && .venv/bin/pip install ...).
If elevated privileges are truly required, tell the user exactly which command to run
and they will run it themselves.

This keeps privilege escalation out of the automated loop. If elevated access is genuinely needed, the agent surfaces the command to the user to run manually.

Prompt injection detection¶

Tool results are scanned for adversarial instruction overrides before they are passed to the agent. If a shell_run or read_file result looks like it is trying to override the agent's instructions, the content is flagged and the event is recorded in the audit log.

Detection is automatic — no configuration required.

Security notes¶

The path sandbox and ring system are enforced at the agent middleware layer, not at the OS level. A compromised plugin bypass (e.g. a malicious MCP server) could potentially circumvent them.
For production use with untrusted tasks, run fuseraft-cli inside a container or VM rather than relying solely on the sandbox config.
Session files in ~/.fuseraft/sessions/ are written with owner-only permissions (Unix mode 0600) to prevent other users from reading session content.
See Governance for the full set of runtime safety controls.