Skip to main content
This guide covers security best practices for hardening Enclave deployments in production environments.

Security Checklist

Critical

  • Use STRICT security 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 identify hook, 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
  • 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:
What these limits are, and are not:
  • In process, timeout and memoryLimit are 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 by timeout. memoryLimit counts 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 to run()) 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:
The client’s options are 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:
With the hook a session belongs to the caller that created it: 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 SessionEncryptionContext per direction.
  • Read envelopes with openEncryptedEnvelope or context.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

  1. Detect - Automated monitoring alerts
  2. Contain - Isolate affected components
  3. Investigate - Review audit logs
  4. Remediate - Fix vulnerability
  5. Recover - Restore normal operation
  6. Learn - Post-incident review