agent-workspace-guard-sdk

Agent Workspace Guard SDK

Filesystem confinement and command-policy guardrails for autonomous coding agents.

---

1. WHAT IS THIS?

The Agent Workspace Guard SDK is a lightweight, zero-dependency Node.js developer security library that prevents autonomous AI coding agents (such as tool-calling LLMs, Cursor extensions, Claude Code tools, or custom agents) from escaping their designated working directory or running dangerous host commands.

2. WHO IS IT FOR?

• Developers building autonomous coding agent workflows.
• DevSecOps engineers integrating AI agent tools into developer machines.
• SaaS platforms allowing AI agents to read and modify project files locally.

3. WHAT PROBLEM DOES IT SOLVE?

AI agents given shell and file-access tools can be tricked via prompt injection or unexpected planning into reading .env credentials, following symlinks outside the workspace, escaping with ../../, or executing destructive commands like rm -rf / or sudo. Heavy cloud microVMs (E2B, Modal) introduce 200ms+ network latency and $50–$200/mo cloud bills. This SDK provides in-process, sub-millisecond confinement directly in your Node.js runtime.

4. WHY PAY FOR IT INSTEAD OF BUILDING IT?

Writing ad-hoc regex or path checks fails on real-world edge cases: symlink race conditions (TOCTOU), Windows backslash traversal evasion (..\..\), multi-dot evasion (....//), shell chaining metacharacters (;, &&, |, $()), and command redirection (<, >). This SDK includes an independently verified, 110-case adversarial red-team test suite covering these exact attack vectors.

5. WHAT IS VERIFIED?

• 110 / 110 Adversarial Attack Cases Passed: Covering path traversal, symlink escapes, secret files, command chaining, and destructive command patterns.
• Zero External Runtime Dependencies: Built strictly on Node.js standard library (node:fs, node:path, node:crypto).
• Cryptographic Audit Log: Every command evaluation is chained using SHA-256 digests.

6. HOW DO I RUN IT?

# 1. Run the 110-case adversarial security test suite
node --test tests/adversarial-red-team.test.mjs

# 2. Run the interactive agent runner demonstration
node examples/agent-runner-example.mjs