The 6 Layers
Layer 0: Pre-Scanner
Runs on the script as it was written, before anything parses it, so that no parser is handed input it cannot cope with.Enclave runs the pre-scanner with the preset named like the AST preset:
Every preset except
permissive also refuses a null byte and a fixed list of look-alike letters (Cyrillic, Greek and full-width forms of letters such as a, e and o), anywhere in the script. The bidirectional control characters are the characters of Trojan Source (CVE-2021-42574). The preScan option picks another pre-scanner preset or changes single limits; with validate: false the pre-scanner does not run.
A script is also limited to 5,242,880 characters, checked before anything parses it.
Layer 1: AST Validation
Static analysis of the parsed AST to block dangerous patterns:Blocked Categories
Enforcement
Layer 2: Code Transformation
Valid code is transformed for safe execution:- Main wrapper - Entry point for execution
- Safe callTool - Proxied through host with counting
- Safe loops - Iteration limits enforced
- Safe console - Rate-limited with output capture
Layer 3: AI Scoring Gate
An optional heuristic: it scores a script by its tool calls (names, argument names, literal values, order, loops) and refuses it at a threshold. It flags patterns that look risky; a low score does not show that a script is safe.Layer 4: Runtime Sandbox
Code executes in an isolated Node.js vm context:- Fresh context - No access to host scope
- Controlled globals - Only whitelisted APIs available
- Resource limits - Timeout, memory accounting, iterations, tool calls
- Optional worker pool - A heap limit per worker thread and a stop that does not depend on the script
What’s Available in the Sandbox
Layer 5: Output Sanitization
Results are sanitized before returning to the caller:- Plain data - The returned value is copied into plain host data; functions, symbols and prototype keys are dropped
- Size check - A value larger than the memory limit allows is refused
- Errors as text -
result.errorholds anameand amessageof bounded length. An error made inside the sandbox has no stack; for the errors that have one,sanitizeStackTracesremoves paths and frames
Security Level Presets
Enclave provides preset configurations:What Enclave Protects Against
- Code injection - Blocked by AST validation
- Infinite loops - Limited by maxIterations
- Resource exhaustion - Limited by the timeout, the memory accounting and the other limits (see below for what they cover)
- Prototype pollution - Blocked by AST validation and by the runtime
- Sandbox escape - Blocked by controlled globals
- Information leakage - Errors made in the sandbox carry no stack; host stacks can be sanitized
- ReDoS attacks - AgentScript has no regular expressions, and with the default preset the script’s realm cannot run one
What Enclave Does NOT Protect Against
- Tool abuse - Scripts can call allowed tools; limit what’s available
- Algorithmic complexity - O(n²) algorithms run within limits
- Business logic attacks - Tool-level validation required
- Side effects - Tool calls have real effects
- A hard time or memory bound in process - In process, the timeout and
memoryLimitare the enclave’s own accounting, not the engine’s. The deadline is checked between the steps of the script’s own code, so one call into a built-in is not bounded bytimeout;memoryLimitcounts the operations that make text and arrays grow, not copies, objects, Maps or Sets. For the engine’s own bounds, use the worker pool, or a child process or container with limits of the operating system - A host process that survives whatever a worker allocates - A worker thread shares the process; its heap limit is a backstop, not a guarantee
- Misleading text in a script, with the looser pre-scanner presets - The
agentscript(default) andstrictpresets refuse bidirectional control characters and invisible characters in a script.securedoes not refuse invisible characters, andstandard(also what thebabelAST preset runs with) andpermissiverefuse neither
Best Practices
- Use STRICT for untrusted code - AI-generated, user-submitted
- Limit available tools - Only expose what’s needed
- Validate tool inputs - Check arguments before execution
- Monitor execution - Log tool calls and durations
- Set appropriate limits - Tune for your use case
- Keep updated - Security improvements in new versions
Related
- Architecture - System overview
- AgentScript - Language definition
- Security Levels - Preset details