Day-One Guardrails: Sandboxes, Secret Hygiene, and Safe Agent Permissions
From Agentic Software Development · 10 articles · latest
Every small engineering team hits the same temptation the week it adopts an AI coding agent: install the CLI, drop it into an engineer's daily shell, and ask it to fix a flaky integration test. Twenty minutes later, that engineer realizes the agent runs with the same OS permissions as their login user—meaning it can read .env, inspect ~/.aws/credentials, touch a live kubectl context, or run git push --force before anyone finishes reading the terminal scrollback.
In Beyond Vibe Coding: The 5-Stage Roadmap to Agentic Software Engineering, we mapped the path from ad-hoc chat loops to repeatable engineering workflows. Before you even write your first AGENTS.md, you need structural rails that hold even when the model misunderstands a prompt or encounters hostile text in a dependency log. The OWASP Top 10 for LLM Applications highlights Excessive Agency and Sensitive Information Disclosure as top failure modes for tool-using models (see also our catalog of agentic coding failure modes)—and for a 3-to-10-person team without a dedicated AppSec group, following a Stage 0 agent containment and baseline checklist eliminates both risks in fifteen minutes.
Why Prompt Rules Alone Fail on Day One
Telling an agent "please do not read .env or run destructive shell commands" in natural language is a polite request, not an access control. Models follow probabilities, not POSIX permissions. When a test fails because a database URL is missing, a helpful agent will instinctively search the repo for configuration files—or grep your environment variables—to diagnose the error.
Prompt rules also fail under indirect prompt injection. An issue comment, a third-party README, or a malformed log line can nudge an agent into running unexpected shell commands or exfiltrating workspace contents if your runtime environment places zero hard barriers in the way. The fix is straightforward: move safety boundaries out of the prompt and into the filesystem, container, and tool runner.
The Three-Ring Permission Model
Most teams fail at agent permissions in one of two opposite ways. Either they prompt the human for approval on every single cat, rg, and pytest call—causing acute approval fatigue until everyone toggles "auto-approve all" by lunchtime—or they leave the agent completely unrestricted from minute one.
Split every tool and shell command into three concentric rings:
Ring 1: Auto-Allowed Read and Verification Loops
Give the agent friction-free autonomy over read-only inspection and fast local checks. These actions have zero external blast radius:
- Searching and reading source files (
rg,grep,git status,git diff,git log). - Running unit tests, type checkers, and linters (
pytest,npm test,ruff,mypy,mvn test -Dtest=...). - Querying read-only MCP tools (documentation search, schema inspection, local retrieval).
Ring 2: Workspace-Scoped Edits
Allow file modifications and branch-local Git operations strictly inside the active repository or dedicated Git worktree:
- Creating, editing, and deleting source or test files under the project root.
- Staging and committing work onto disposable feature branches (
agent/<ticket>). - Running local builds against ephemeral test containers or local SQLite/Docker test databases.
Ring 3: Human-Gated High-Blast-Radius Actions
Require an explicit human confirmation prompt—or block the agent outright—for anything that crosses out of the local workspace or cannot be cleanly undone with git reset:
- Reading or modifying
.env, cloud credential directories, SSH keys, or Kubernetes contexts. - Running destructive or privileged commands (
rm -rf,sudo,chmod -R,git push --force, database migrations against shared environments). - Making arbitrary outbound network requests (
curl | sh, unpinned package installs, external webhooks).
Tip
Eliminate approval fatigue by keeping Ring 1 silent. If your team has to click "Approve" forty times while an agent iterates on unit tests, engineers will disable prompts entirely. Auto-approve safe read/test commands so human attention stays sharp for Ring 3 boundaries.
Secret Hygiene: Keep Credentials Out of Agent Context
Once an agent reads a secret value—whether from .env, a shell dump, or a stack trace—that credential enters the model's context window. From there it is transmitted to the inference provider, stored in session logs, and occasionally echoed into generated test fixtures or commit messages.
Protect credentials with three concrete controls on Day One:
- Block credential paths at the tool layer. Configure your agent runner's permission policy to deny file reads and shell access to secret locations, while keeping a sanitized
.env.examplechecked into Git so the agent still knows which variable names the app expects. - Inject short-lived, scoped tokens at runtime. When integration tests genuinely need an API key or staging database password, issue a low-privilege, expiring credential injected only into the test runner subprocess—never a long-lived personal admin token.
- Turn on automated leak detection. Enable GitHub Secret Scanning and Push Protection on every team repository, and pair it with a local pre-commit check (
gitleaksordetect-secrets) so accidental credentials fail before leaving the laptop.
Here is a practical starter permission policy you can adapt for CLI coding agents:
{
"permissions": {
"allow": [
"Bash(git status)",
"Bash(git diff *)",
"Bash(pytest *)",
"Bash(ruff check *)"
],
"ask": [
"Bash(git commit *)",
"Bash(pip install *)",
"Bash(npm install *)"
],
"deny": [
"Read(.env*)",
"Read(**/.ssh/**)",
"Read(**/.aws/**)",
"Read(**/terraform.tfstate*)",
"Bash(rm -rf *)",
"Bash(sudo *)",
"Bash(curl *)",
"Bash(git push --force*)"
]
}
}
Warning
Never share your daily-driver personal access token or production .env with an agent session. Even well-intentioned debugging prompts ("check why staging auth fails") can cause an agent to print os.environ or paste headers into a markdown summary.
Sandboxing the Workspace Without Slowing Down
Permission globs inside an agent CLI are a great first layer, but shell commands are notoriously slippery (python -c "open('.env').read()" bypasses naive Read(.env*) rules if bash is unrestricted). For real blast-radius containment, isolate the process itself.
A lightweight, reproducible option for small teams is running coding agents inside a non-root container built to the Development Containers specification on top of Docker's namespace and cgroup isolation. Mount only the repository directory—never $HOME, ~/.ssh, ~/.aws, or the host Docker socket:
{
"name": "sandboxed-agent-workspace",
"image": "mcr.microsoft.com/devcontainers/python:3.12",
"remoteUser": "vscode",
"runArgs": [
"--cap-drop=ALL",
"--security-opt=no-new-privileges:true",
"--memory=4g",
"--cpus=2"
],
"mounts": []
}
Two details matter here:
- Never mount
/var/run/docker.sockinside an agent container. Access to the Docker daemon socket is effectively root access to the host machine, because any process inside the sandbox can launch a privileged container mounting/. - Understand what containers do and do not protect. As devcontainer security guidance emphasizes, dev containers are designed for environment consistency and OS-level isolation—not as a hardened hypervisor against untrusted repositories whose
postCreateCommandruns automatically on startup. Always inspectdevcontainer.jsonbefore opening an unfamiliar repo.
If your workflow makes full containers awkward (for example, macOS native builds or heavy GPU toolchains), combine a dedicated low-privilege OS user or isolated Git worktree with strict Ring 1–3 command allowlists and empty credential environment variables.
Git and CI Backstops: Make Mistakes Cheap to Revert
Even a tightly sandboxed agent will occasionally wander down a bad architectural path and rewrite twelve files it had no business touching. Your final safety layer is ensuring bad agent runs cost thirty seconds to discard, not three hours to untangle.
Configure GitHub branch protection rules on main (and any release branches) before merging your first agent-authored PR:
- Require a pull request before merging with at least one human engineer approval.
- Require status checks to pass (unit tests, linter, type check, secret scan) before the merge button unlocks.
- Block force pushes and branch deletions, including for repository administrators if your team is prone to quick "hotfix" overrides.
- Isolate each task on a fresh branch (
agent/fix-invoice-rounding), so wiping out a failed experiment is a singlegit checkout main && git branch -D ....
A 15-Minute Day-One Checklist for Small Teams
You do not need enterprise IAM machinery to adopt coding agents responsibly. Run through this five-step baseline once across your team repositories:
| Guardrail Layer | What to Put in Place | Blast Radius Prevented |
|---|---|---|
| Git & CI | Protect main; require PR + human review + CI checks | Direct pushes or broken builds landing in prod |
| Secret Hygiene | Deny .env* & ~/.ssh reads; enable GitHub Push Protection | API keys entering context windows or git history |
| Permission Rings | Auto-allow read/test loops; gate installs & network egress | Approval fatigue and silent destructive shell commands |
| Process Sandbox | Non-root devcontainer or isolated worktree; no docker.sock | Accidental host filesystem damage or privilege escalation |
| Branch Discipline | One disposable feature branch per agent session | Cross-task contamination and painful rollbacks |
With these guardrails locked down, your team can let agents run fast inside Ring 1 and Ring 2 without hovering over every keystroke. Next up in this series, we put that safe workspace to work by onboarding the codebase itself in Writing Your First AGENTS.md (Without Triggering Context Rot).
References
- OWASP Top 10 for Large Language Model Applications — Covers Excessive Agency (LLM06) and Sensitive Information Disclosure (LLM02).
- GitHub Secret Scanning & Push Protection Documentation — Automated detection and commit-time blocking for leaked credentials.
- GitHub Managing a Branch Protection Rule — Enforcing PR reviews, required CI checks, and push restrictions on
main. - Development Containers Specification & Docker Documentation — Containerized workspace configuration, non-root execution, and namespace/cgroup isolation primitives.
- Wikantik Reference: Agent Containment and Baseline & Tool Use & Agent Sandboxing — Stage 0 team containment playbooks and sandboxed tool-execution boundaries.
Comments