Security Checklist
Critical
- Use
STRICTsecurity level for untrusted code - Set memory limits, on the sandbox and on the process or container around it
- Configure timeouts
- Validate all tool inputs
- Authenticate callers in front of every endpoint that accepts code, and in front of every session route of the broker: the routes that list, read, replay and end sessions have no authentication of their own either
- Give the broker’s session routes an
identifyhook, so that a session belongs to the caller that created it. Authentication alone does not do that. Only a broker whose routes a single trusted backend calls can go without the hook (see Client Connections) - Run as non-root user
Recommended
- Use HTTPS for client connections: the client and the broker exchange plain JSON
- Run the sandbox in the worker pool for a hard stop of a script that runs past its timeout and a heap limit per worker. A worker thread shares the host’s process: the pool does not guarantee that the host survives
- Run the enclave in a child process or a container with limits of the operating system when the host must survive any script
- Consider the AI Scoring Gate as an additional, heuristic signal
- Implement rate limiting
- Use network segmentation
- Enable audit logging
- Set up intrusion detection
- Regular security updates
Security Levels
Always use the appropriate security level:Defense in Depth
Layer 1: Input Validation
Validate code before it reaches Enclave:Layer 2: Pre-Scanner
Enclave runs the pre-scanner on the script as it was written, before anything parses it, with the pre-scanner preset named like the AST preset. With the default agentscript preset that is the strictest one: 100 KB of code in at most 1,000 lines of at most 2,000 characters, string literals of at most 10 KB, no regular-expression literal, and no bidirectional or invisible control character.
Loosen single limits only where your scripts need it, and keep the Unicode checks:
preScan: { preset: 'standard' } gives the limits enclaves had before 2.19.2 (5 MB, 10,000 lines, regular-expression literals analyzed, no check for bidirectional or invisible characters).
Layer 3: AST Validation
Strict AST validation:Layer 4: AI Scoring Gate
An optional heuristic: it scores a script by its tool calls and refuses it at a threshold. It flags patterns that look risky; a low score does not show that a script is safe.Layer 5: Runtime Isolation
Limits, and the worker pool around the sandbox:- In process,
timeoutandmemoryLimitare 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; it does not count copies, objects, Maps or Sets. - The worker pool adds the engine’s heap limit and terminates a script that is still running five seconds after its timeout. A worker thread shares the process with the host: it is not process isolation, and the heap limit is a backstop, not a guarantee that the process survives.
- A host that must survive whatever a script does runs the enclave in a child process or a container with limits of the operating system.
Layer 6: Output Sanitization
Sanitize all outputs:Tool Security
Input Validation
Always validate tool inputs:Permission Control
Implement tool permissions per user. A tool handler receives the tool name and the arguments, nothing about the caller, so create the enclave (or pass the handler torun()) for the user the script runs for:
Data Filtering
Filter sensitive data from tool responses:Network Security
Isolation
Run the process that executes scripts (your application with@enclave-vm/core, or the broker) on an internal network, behind the gateway that authenticates callers. A script has no network access of its own; what reaches the network are your tool handlers, so give that process only the routes its tools need:
TLS Configuration
Client Connections
@enclave-vm/client sends requests and receives events as plain JSON. It does not encrypt and has no encryption option, so the transport is what protects a session: use an https: base URL. Credentials go in headers:
baseUrl, headers, timeout, autoReconnect, maxReconnectAttempts, reconnectDelay, maxEventLength and fetch. Any other key, such as encryption or auth, makes the constructor throw.
The broker’s session routes have no authentication of their own. The application has to put authentication in front of all of them (the route that creates a session, and the routes that list, read, replay and end sessions) and check the credentials the client sends.
Authentication does not tell the routes whose session is whose: without an identify hook they answer every caller for every session. Give the session handler the hook, and let it return the caller your authentication found:
GET /sessions lists the caller’s own sessions, a request for another caller’s session is answered with 404, and a request without an identity with 401. The hook can be left out only where a single trusted backend is the one caller of the routes; that backend then has to keep the sessions of its own users apart. See Who may see a session.
Payload Encryption
No EnclaveJS package encrypts payloads. An application that wants payload encryption on top of TLS has to wire the primitives of@enclave-vm/stream (ECDH P-256, HKDF-SHA-256, AES-256-GCM) into its own endpoints, on both ends. See the Encrypted Sessions example. What such an application has to take care of:
- The key exchange is not authenticated: it protects against a party that can only read the connection, not against one that can change messages. Authenticate the hello messages yourself (for example by signing them with a key the client pins) or rely on TLS for the identity of the server.
- There are two keys, one per direction. Use one
SessionEncryptionContextper direction. - Read envelopes with
openEncryptedEnvelopeorcontext.openEnvelope, which fail when the ciphertext or the envelope’s header was changed. Whether a sequence number was seen before is for the receiver to check. - The server that receives the code decrypts it to run it. Payload encryption does not hide anything from that server.
Rate Limiting
Per-User Limits
Per-Tool Limits
Audit Logging
Comprehensive Logging
Log Retention
Container Security
Dockerfile Best Practices
Security Context
Secrets Management
Environment Variables
Never hardcode secrets:Kubernetes Secrets
Incident Response
Detection
Monitor for anomalies:Response Plan
- Detect - Automated monitoring alerts
- Contain - Isolate affected components
- Investigate - Review audit logs
- Remediate - Fix vulnerability
- Recover - Restore normal operation
- Learn - Post-incident review
Related
- Security Model - Architecture overview
- AI Scoring - Semantic analysis
- Production Deployment - Deployment guide