@enclave-vm/core 2.17.0 → 2.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +265 -38
- package/SECURITY-AUDIT.md +85 -77
- package/adapters/interpreter-adapter.d.ts +27 -0
- package/adapters/worker-pool/config.d.ts +4 -2
- package/adapters/worker-pool/memory-monitor.d.ts +16 -2
- package/adapters/worker-pool/protocol.d.ts +63 -11
- package/adapters/worker-pool/worker-pool-adapter.d.ts +45 -2
- package/adapters/worker-pool/worker-script.d.ts +14 -4
- package/adapters/worker-pool/worker-slot.d.ts +99 -2
- package/console-handler.d.ts +33 -0
- package/deadline-guard.d.ts +65 -0
- package/double-vm/double-vm-wrapper.d.ts +11 -2
- package/double-vm/parent-vm-bootstrap.d.ts +118 -0
- package/enclave.d.ts +31 -0
- package/esm/index.mjs +12581 -8226
- package/esm/worker.mjs +2935 -212
- package/execution-deadline.d.ts +69 -0
- package/global-function-gate.d.ts +22 -1
- package/globals-validator.d.ts +12 -0
- package/index.d.ts +2 -1
- package/index.js +12604 -8250
- package/interpreter/interpreter.d.ts +149 -5
- package/interpreter/safe-globals.d.ts +14 -0
- package/package.json +4 -4
- package/realm-airlock.d.ts +51 -0
- package/safe-error.d.ts +6 -0
- package/safe-runtime.d.ts +16 -0
- package/sandbox-console.d.ts +26 -0
- package/sandbox-rejections.d.ts +67 -0
- package/sandbox-script.d.ts +156 -0
- package/secure-proxy.d.ts +21 -0
- package/src/adapters/worker-pool/package.json +4 -4
- package/src/adapters/worker-pool/worker-script.js +8738 -625
- package/stack-reserve.d.ts +46 -0
- package/tool-bridge.d.ts +34 -2
- package/types.d.ts +105 -5
- package/worker.js +2935 -212
package/SECURITY-AUDIT.md
CHANGED
|
@@ -5,9 +5,11 @@
|
|
|
5
5
|
**Test Suite:** 1255 security tests
|
|
6
6
|
**Pass Rate:** 1255/1255 passing (100%)
|
|
7
7
|
|
|
8
|
+
> **How to read this report.** It was written for v2.4.0 and is kept as a record of what was tested then. A pass rate describes the tests that existed, not the absence of weaknesses: several were found and fixed afterwards, and tests were added for each. Statements below that no longer described the implementation have been corrected in place and are marked _Updated_. The maintained index of security properties and their tests is `SECURITY-TESTS.md` in the repository root; the runtime behaviour is described in `README.md` ("What the Script's Realm Holds", "Worker Pool Adapter", "How `timeout` Is Enforced"). The test files it names are no longer in this repository: the security tests live in a private repository, mounted here as the git submodule `security-tests` (see `SECURITY-TESTS.md`).
|
|
9
|
+
|
|
8
10
|
## Executive Summary
|
|
9
11
|
|
|
10
|
-
The enclave-vm package provides a **defense-in-depth security architecture** for safe AgentScript execution
|
|
12
|
+
The enclave-vm package provides a **defense-in-depth security architecture** for safe AgentScript execution: static validation, a reduced realm, a membrane between the script and the host, sanitized results and enforced limits, with an **AI Scoring Gate** for semantic analysis and an optional **Worker Pool Adapter** that adds a heap limit per worker and a hard stop. Each layer is tested on its own, with the other layers switched off.
|
|
11
13
|
|
|
12
14
|
## Security Test Results
|
|
13
15
|
|
|
@@ -138,18 +140,20 @@ The enclave-vm package provides a **defense-in-depth security architecture** for
|
|
|
138
140
|
|
|
139
141
|
**Verdict:** AI Scoring Gate successfully detects semantic attack patterns with 8 detection rules.
|
|
140
142
|
|
|
141
|
-
### ✅ Worker Pool Adapter
|
|
143
|
+
### ✅ Worker Pool Adapter (_Updated_)
|
|
142
144
|
|
|
143
|
-
When enabled with `adapter: 'worker_threads'`,
|
|
145
|
+
When enabled with `adapter: 'worker_threads'`, each script runs in a worker thread. A worker thread is not a sandbox and not process isolation (it has the Node.js API and shares the process), so inside the worker the script runs in the same sandbox as in process:
|
|
144
146
|
|
|
145
|
-
- **
|
|
146
|
-
- **Memory limit enforcement**: ✅
|
|
147
|
-
- **
|
|
148
|
-
- **
|
|
147
|
+
- **Sandbox inside the worker**: ✅ the double VM by default (a single VM when the double VM is disabled)
|
|
148
|
+
- **Memory limit enforcement**: ✅ a heap limit per worker (`resourceLimits`); a worker that exceeds it is terminated and replaced. When the process runs with `--max-old-space-size`, which replaces the limit of every worker thread, the pool enforces it from the host. ⚠️ Not a guarantee that the host process survives memory exhaustion in a worker (README, "The Worker Heap Limit")
|
|
149
|
+
- **Pool size and shutdown**: ✅ `maxWorkers` holds under concurrent executions; a disposed pool leaves no worker thread or timer behind
|
|
150
|
+
- **Hard halt capability**: ✅ `worker.terminate()` for a script nothing else can interrupt
|
|
151
|
+
- **Tool calls**: ✅ answered by the host's tool bridge, as for in-process execution
|
|
152
|
+
- **Untrusted worker messages**: ✅ every message is checked against the protocol schema on the host
|
|
149
153
|
- **Message flood protection**: ✅ ENFORCED (rate limiting)
|
|
150
154
|
- **Prototype-safe deserialization**: ✅ ENFORCED (JSON-only, no structured clone)
|
|
151
155
|
|
|
152
|
-
**Verdict:** Worker Pool Adapter
|
|
156
|
+
**Verdict:** The Worker Pool Adapter adds a heap limit and a stop that does not depend on the script, around the same sandbox as in-process execution. Tests: `enclave.worker-isolation` and `enclave.worker-resources` (ATK-WORKER).
|
|
153
157
|
|
|
154
158
|
### ✅ Side Channel Attack Prevention (Documented Limitations)
|
|
155
159
|
|
|
@@ -177,12 +181,12 @@ Since all these prerequisites are blocked in the Enclave sandbox, Spectre-class
|
|
|
177
181
|
|
|
178
182
|
**Verdict:** Most inputs handled safely, parser limitations noted.
|
|
179
183
|
|
|
180
|
-
### ✅ Multiple Execution Isolation (
|
|
184
|
+
### ✅ Multiple Execution Isolation (_Updated_)
|
|
181
185
|
|
|
182
|
-
- **Cross-execution isolation**:
|
|
186
|
+
- **Cross-execution isolation**: ✅ ISOLATED. Every `enclave.run()` gets new VM contexts and discards them afterwards; no realm state is shared between executions (see "VM Context State Sharing" below)
|
|
183
187
|
- **Cross-instance isolation**: ✅ ISOLATED (separate enclaves)
|
|
184
188
|
|
|
185
|
-
**Verdict:** Instances are isolated
|
|
189
|
+
**Verdict:** Instances and executions are isolated.
|
|
186
190
|
|
|
187
191
|
## Known Limitations
|
|
188
192
|
|
|
@@ -200,12 +204,9 @@ Since all these prerequisites are blocked in the Enclave sandbox, Spectre-class
|
|
|
200
204
|
**Mitigation:** Consider sanitizing stack traces before returning.
|
|
201
205
|
**Priority:** Low
|
|
202
206
|
|
|
203
|
-
### 3. VM Context State Sharing
|
|
207
|
+
### 3. VM Context State Sharing (_Updated: no longer applies_)
|
|
204
208
|
|
|
205
|
-
|
|
206
|
-
**Impact:** Potential state leakage between executions in same enclave instance.
|
|
207
|
-
**Mitigation:** Create new VM context for each execution or properly reset context.
|
|
208
|
-
**Priority:** Medium
|
|
209
|
+
Every `enclave.run()` creates new VM contexts (parent and inner realm, or the single VM's context) and discards them afterwards. Nothing a script leaves in its realm is visible to a later execution. Scripts also run in strict mode, so a script can only write to its realm's global object when both static layers are switched off.
|
|
209
210
|
|
|
210
211
|
## Security Architecture
|
|
211
212
|
|
|
@@ -512,6 +513,19 @@ All security mechanisms are functioning correctly with zero failures or skipped
|
|
|
512
513
|
|
|
513
514
|
## Version History
|
|
514
515
|
|
|
516
|
+
- **Unreleased** (2026-11): Runtime hardening
|
|
517
|
+
- The script's realm holds only the globals its validator allows (`realmGlobals: 'allowlist'`, the default for validated AgentScript); no name resolves through a prototype of the global object (ATK-GLOBALS)
|
|
518
|
+
- Scripts run in strict mode at every security level (ATK-THIS)
|
|
519
|
+
- Regular expressions cannot be executed in a realm with the allowlist (ATK-RXRT)
|
|
520
|
+
- The parent realm's intrinsics are frozen while a script runs, and the host console object is no longer in it (ATK-PLOCK)
|
|
521
|
+
- The worker adapter runs the double VM inside the worker, enforces a heap limit per worker, validates worker messages and recovers from dead workers (ATK-WORKER)
|
|
522
|
+
- The size check of returned values no longer calls into the value and counts unpaired surrogates at their serialized size (ATK-SIZE)
|
|
523
|
+
- Compiled sandbox code is not shared between realms on V8 13.x (Node.js 24), where that could crash the process (ATK-ENGINE)
|
|
524
|
+
- Execution time no longer grows with the number of earlier scripts of the same length: the script is the first thing in the double VM bootstrap, and the bootstrap is ASCII whatever the script contains (ATK-ENGINE, Sustained Load in the performance suite)
|
|
525
|
+
- Nothing a script can reach is a raw object of another realm, checked by a crawler that runs inside the sandbox (ATK-REACH)
|
|
526
|
+
- With composite handles disabled, a handle written by the script is refused like the operator that would have built it (ATK-SIDECAR)
|
|
527
|
+
- Static rules: syntax allowlist, lexical scope analysis, write and reflection rules (see `SECURITY-TESTS.md`, layer 1)
|
|
528
|
+
|
|
515
529
|
- **v2.4.0** (2026-01-06): Attack Prevention Test Suite
|
|
516
530
|
- Added comprehensive attack prevention tests (71 new tests)
|
|
517
531
|
- New test categories with consistent ATK-XXX naming scheme:
|
|
@@ -624,12 +638,6 @@ The enclave-vm uses a **three-layer security approach**:
|
|
|
624
638
|
|
|
625
639
|
**Issue:** When user-provided objects were passed as globals without wrapping, prototype chain attacks could access real `process.env`.
|
|
626
640
|
|
|
627
|
-
**Attack Pattern:**
|
|
628
|
-
|
|
629
|
-
```javascript
|
|
630
|
-
process.env['__p' + 'roto__']['con' + 'structor']['con' + 'structor']('return process.env.PATH')();
|
|
631
|
-
```
|
|
632
|
-
|
|
633
641
|
**Fix:** All custom globals are now recursively wrapped with SecureProxy in both vm-adapter.ts and parent-vm-bootstrap.ts.
|
|
634
642
|
|
|
635
643
|
#### 2. Constructor Functions as Globals (KNOWN LIMITATION)
|
|
@@ -709,63 +717,63 @@ The critical finding is that **even when attackers access the Function construct
|
|
|
709
717
|
|
|
710
718
|
### Attack Categories Tested (50 Tests)
|
|
711
719
|
|
|
712
|
-
| Category | Vectors | Security Level
|
|
713
|
-
| -------------------------------------- | ------------------------------ |
|
|
714
|
-
| **1. Primitive Constructor Chains** | |
|
|
715
|
-
| String constructor chain | `"".constructor.constructor` | VM Isolation
|
|
716
|
-
| Number constructor chain | `(0).constructor.constructor` | VM Isolation
|
|
717
|
-
| Boolean constructor chain | `true.constructor.constructor` | VM Isolation
|
|
718
|
-
| Array constructor chain | `[].constructor.constructor` | VM Isolation
|
|
719
|
-
| Object constructor chain | `{}.constructor.constructor` | VM Isolation
|
|
720
|
-
| RegExp constructor chain | `/x/.constructor.constructor` | VM Isolation
|
|
721
|
-
| **2. Callback Injection Attacks** | |
|
|
722
|
-
| Array.prototype.map | Callback `this.constructor` | VM Isolation
|
|
723
|
-
| Array.prototype.filter | `arguments.callee` access |
|
|
724
|
-
| Array.prototype.reduce | Accumulator constructor | VM Isolation
|
|
725
|
-
| Array.prototype.sort | Comparator globals | VM Isolation
|
|
726
|
-
| Array.prototype.forEach | Prototype access | VM Isolation
|
|
727
|
-
| **3. Type Coercion Gadgets** | |
|
|
728
|
-
| `valueOf` exploitation | Coercion callback | VM Isolation
|
|
729
|
-
| `toString` exploitation | Coercion callback | VM Isolation
|
|
730
|
-
| `toJSON` exploitation | Stringify callback | VM Isolation
|
|
731
|
-
| `Symbol.toPrimitive` | Custom coercion | AST Blocked
|
|
732
|
-
| **4. Function.prototype Exploitation** | |
|
|
733
|
-
| `Function.prototype.call` | Context injection | VM Isolation
|
|
734
|
-
| `Function.prototype.apply` | Arguments injection | VM Isolation
|
|
735
|
-
| `Function.prototype.bind` | Context binding | VM Isolation
|
|
736
|
-
| **5. Tagged Template Attacks** | |
|
|
737
|
-
| `String.raw` exploitation | Constructor access | SecureProxy
|
|
738
|
-
| Custom tag functions | `strings.raw.constructor` | VM Isolation
|
|
739
|
-
| **6. JSON Reviver/Replacer** | |
|
|
740
|
-
| `JSON.parse` reviver | `this.constructor` access | VM Isolation
|
|
741
|
-
| `JSON.stringify` replacer | Value transformation | VM Isolation
|
|
742
|
-
| **7. Implicit Coercion** | |
|
|
743
|
-
| Addition operator | `+` triggers valueOf | VM Isolation
|
|
744
|
-
| Comparison operator | `==` triggers valueOf | VM Isolation
|
|
745
|
-
| Property key coercion | `obj[key]` triggers toString | VM Isolation
|
|
746
|
-
| **8. Getter/Setter Attacks** | |
|
|
747
|
-
| Getter exploitation | `get prop()` context | PERMISSIVE
|
|
748
|
-
| Setter exploitation | `set prop()` context | PERMISSIVE
|
|
749
|
-
| `Object.defineProperty` | Dynamic getter/setter | PERMISSIVE
|
|
750
|
-
| **9. Prototype Pollution** | |
|
|
751
|
-
| `Object.prototype` pollution | Host isolation | VM Isolation
|
|
752
|
-
| `Array.prototype` pollution | Host isolation | VM Isolation
|
|
753
|
-
| Constructor prototype pollution | Host isolation | VM Isolation
|
|
754
|
-
| **10. Chained/Combined Attacks** | |
|
|
755
|
-
| Coercion + Constructor chain | Multi-step attack | VM Isolation
|
|
756
|
-
| Callback + Constructor chain | Multi-step attack | VM Isolation
|
|
757
|
-
| JSON.parse + Constructor chain | Multi-step attack | VM Isolation
|
|
720
|
+
| Category | Vectors | Security Level | Result |
|
|
721
|
+
| -------------------------------------- | ------------------------------ | -------------- | ------------------------------------- |
|
|
722
|
+
| **1. Primitive Constructor Chains** | | | |
|
|
723
|
+
| String constructor chain | `"".constructor.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
724
|
+
| Number constructor chain | `(0).constructor.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
725
|
+
| Boolean constructor chain | `true.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
726
|
+
| Array constructor chain | `[].constructor.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
727
|
+
| Object constructor chain | `{}.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
728
|
+
| RegExp constructor chain | `/x/.constructor.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
729
|
+
| **2. Callback Injection Attacks** | | | |
|
|
730
|
+
| Array.prototype.map | Callback `this.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
731
|
+
| Array.prototype.filter | `arguments.callee` access | Strict mode | ✅ Blocked at every level (_Updated_) |
|
|
732
|
+
| Array.prototype.reduce | Accumulator constructor | VM Isolation | ✅ Sandbox context |
|
|
733
|
+
| Array.prototype.sort | Comparator globals | VM Isolation | ✅ Sandbox context |
|
|
734
|
+
| Array.prototype.forEach | Prototype access | VM Isolation | ✅ Sandbox context |
|
|
735
|
+
| **3. Type Coercion Gadgets** | | | |
|
|
736
|
+
| `valueOf` exploitation | Coercion callback | VM Isolation | ✅ Sandbox Function |
|
|
737
|
+
| `toString` exploitation | Coercion callback | VM Isolation | ✅ Sandbox context |
|
|
738
|
+
| `toJSON` exploitation | Stringify callback | VM Isolation | ✅ Sandbox context |
|
|
739
|
+
| `Symbol.toPrimitive` | Custom coercion | AST Blocked | ✅ Symbol blocked |
|
|
740
|
+
| **4. Function.prototype Exploitation** | | | |
|
|
741
|
+
| `Function.prototype.call` | Context injection | VM Isolation | ✅ Sandbox global |
|
|
742
|
+
| `Function.prototype.apply` | Arguments injection | VM Isolation | ✅ Sandbox context |
|
|
743
|
+
| `Function.prototype.bind` | Context binding | VM Isolation | ✅ Sandbox context |
|
|
744
|
+
| **5. Tagged Template Attacks** | | | |
|
|
745
|
+
| `String.raw` exploitation | Constructor access | SecureProxy | ✅ Blocked |
|
|
746
|
+
| Custom tag functions | `strings.raw.constructor` | VM Isolation | ✅ Sandbox Function |
|
|
747
|
+
| **6. JSON Reviver/Replacer** | | | |
|
|
748
|
+
| `JSON.parse` reviver | `this.constructor` access | VM Isolation | ✅ Sandbox Function |
|
|
749
|
+
| `JSON.stringify` replacer | Value transformation | VM Isolation | ✅ Sandbox context |
|
|
750
|
+
| **7. Implicit Coercion** | | | |
|
|
751
|
+
| Addition operator | `+` triggers valueOf | VM Isolation | ✅ Sandbox context |
|
|
752
|
+
| Comparison operator | `==` triggers valueOf | VM Isolation | ✅ Sandbox context |
|
|
753
|
+
| Property key coercion | `obj[key]` triggers toString | VM Isolation | ✅ Sandbox context |
|
|
754
|
+
| **8. Getter/Setter Attacks** | | | |
|
|
755
|
+
| Getter exploitation | `get prop()` context | PERMISSIVE | ✅ Sandbox context |
|
|
756
|
+
| Setter exploitation | `set prop()` context | PERMISSIVE | ✅ Sandbox context |
|
|
757
|
+
| `Object.defineProperty` | Dynamic getter/setter | PERMISSIVE | ✅ Sandbox context |
|
|
758
|
+
| **9. Prototype Pollution** | | | |
|
|
759
|
+
| `Object.prototype` pollution | Host isolation | VM Isolation | ✅ Host protected |
|
|
760
|
+
| `Array.prototype` pollution | Host isolation | VM Isolation | ✅ Host protected |
|
|
761
|
+
| Constructor prototype pollution | Host isolation | VM Isolation | ✅ Host protected |
|
|
762
|
+
| **10. Chained/Combined Attacks** | | | |
|
|
763
|
+
| Coercion + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
|
|
764
|
+
| Callback + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
|
|
765
|
+
| JSON.parse + Constructor chain | Multi-step attack | VM Isolation | ✅ Sandbox Function |
|
|
758
766
|
|
|
759
767
|
### Security Mode Differences
|
|
760
768
|
|
|
761
|
-
| Feature | AgentScript (Default) | PERMISSIVE
|
|
762
|
-
| ------------------------------------- | --------------------- |
|
|
763
|
-
| Function expressions | ❌ Blocked | ✅ Allowed
|
|
764
|
-
| Getter/Setter syntax | ❌ Blocked | ✅ Allowed
|
|
765
|
-
| `arguments.callee` | ❌ Blocked (strict) |
|
|
766
|
-
| `function.call(null)` |
|
|
767
|
-
| Constructor access on wrapped globals | ❌ Blocked | ✅ Allowed
|
|
768
|
-
| Prototype pollution in sandbox | ✅ Host isolated | ✅ Host isolated
|
|
769
|
+
| Feature | AgentScript (Default) | PERMISSIVE |
|
|
770
|
+
| ------------------------------------- | --------------------- | ------------------- |
|
|
771
|
+
| Function expressions | ❌ Blocked | ✅ Allowed |
|
|
772
|
+
| Getter/Setter syntax | ❌ Blocked | ✅ Allowed |
|
|
773
|
+
| `arguments.callee` | ❌ Blocked (strict) | ❌ Blocked (strict) |
|
|
774
|
+
| `function.call(null)` | `this` is `null` | `this` is `null` |
|
|
775
|
+
| Constructor access on wrapped globals | ❌ Blocked | ✅ Allowed |
|
|
776
|
+
| Prototype pollution in sandbox | ✅ Host isolated | ✅ Host isolated |
|
|
769
777
|
|
|
770
778
|
### Key Takeaways
|
|
771
779
|
|
|
@@ -773,7 +781,7 @@ The critical finding is that **even when attackers access the Function construct
|
|
|
773
781
|
|
|
774
782
|
2. **AgentScript preset provides strong protection** - Blocks function expressions, getters/setters, and dangerous patterns statically
|
|
775
783
|
|
|
776
|
-
3. **PERMISSIVE mode trades security for flexibility** - Allows more JavaScript features but still maintains host isolation
|
|
784
|
+
3. **PERMISSIVE mode trades security for flexibility** - Allows more JavaScript features but still maintains host isolation. (_Updated_: scripts run in strict mode at every level, so `this` is never the realm's global object and `arguments.callee` is never available.)
|
|
777
785
|
|
|
778
786
|
4. **Constructor access through primitives works but is contained** - The constructed functions run in sandbox context with no host access
|
|
779
787
|
|
|
@@ -4,12 +4,39 @@ export interface InterpreterAdapterOptions {
|
|
|
4
4
|
maxSteps?: number;
|
|
5
5
|
/** Override the max interpreter call depth (default 256). */
|
|
6
6
|
maxCallDepth?: number;
|
|
7
|
+
/**
|
|
8
|
+
* The most a script may allocate, in bytes, as the interpreter estimates it (default 64 MB).
|
|
9
|
+
* An execution's own `memoryLimit` applies when it is lower.
|
|
10
|
+
*/
|
|
11
|
+
maxAllocationBytes?: number;
|
|
7
12
|
}
|
|
8
13
|
export declare class InterpreterAdapter implements SandboxAdapter {
|
|
9
14
|
private readonly options;
|
|
10
15
|
constructor(options?: InterpreterAdapterOptions);
|
|
11
16
|
execute<T = unknown>(code: string, context: ExecutionContext): Promise<ExecutionResult<T>>;
|
|
12
17
|
dispose(): void;
|
|
18
|
+
/**
|
|
19
|
+
* What transformed AgentScript refers to beyond the standard globals: the helpers the
|
|
20
|
+
* transformer emits, and the console, tool namespaces and custom globals of this execution.
|
|
21
|
+
*/
|
|
22
|
+
private runtimeGlobals;
|
|
23
|
+
/**
|
|
24
|
+
* `callTool(name, args, options)` for the script, through the host tool bridge: the request
|
|
25
|
+
* and the response cross as JSON, so the handler never receives a value of the script and the
|
|
26
|
+
* script never receives an object of the handler.
|
|
27
|
+
*/
|
|
28
|
+
private createCallTool;
|
|
29
|
+
/**
|
|
30
|
+
* The value a script returned, as the caller gets it: plain host data, like from every other
|
|
31
|
+
* adapter. A function, or a result that would serialize to more than the memory limit, fails
|
|
32
|
+
* the execution.
|
|
33
|
+
*/
|
|
34
|
+
private succeed;
|
|
13
35
|
private stats;
|
|
36
|
+
/**
|
|
37
|
+
* What ended an execution, as a name and a message. A script can throw any value: a string is
|
|
38
|
+
* the message, an object contributes its `name`, `message` and `code` when they are strings.
|
|
39
|
+
*/
|
|
40
|
+
private describe;
|
|
14
41
|
private fail;
|
|
15
42
|
}
|
|
@@ -21,8 +21,10 @@ export interface WorkerPoolConfig {
|
|
|
21
21
|
*/
|
|
22
22
|
maxWorkers: number;
|
|
23
23
|
/**
|
|
24
|
-
*
|
|
25
|
-
*
|
|
24
|
+
* Heap limit of each worker in bytes (its old generation); 0 for none.
|
|
25
|
+
* Enforced by the engine, or by the pool when the process runs with `--max-old-space-size`,
|
|
26
|
+
* which replaces the heap limit of every worker thread. A worker over its limit is terminated
|
|
27
|
+
* and replaced.
|
|
26
28
|
* @default 128 * 1024 * 1024 (128MB)
|
|
27
29
|
*/
|
|
28
30
|
memoryLimitPerWorker: number;
|
|
@@ -40,13 +40,22 @@ export interface MemoryMonitorStats {
|
|
|
40
40
|
memoryExceededCount: number;
|
|
41
41
|
/** Number of check failures */
|
|
42
42
|
checkFailureCount: number;
|
|
43
|
-
/**
|
|
43
|
+
/** Most that one worker held in any report (its heap plus its external memory, in bytes) */
|
|
44
44
|
peakMemoryBytes: number;
|
|
45
|
-
/** Average
|
|
45
|
+
/** Average of what a worker held over all reports (bytes) */
|
|
46
46
|
avgMemoryBytes: number;
|
|
47
47
|
/** Total samples collected */
|
|
48
48
|
totalSamples: number;
|
|
49
49
|
}
|
|
50
|
+
/**
|
|
51
|
+
* What a worker itself holds, from its memory report: its heap plus its external memory.
|
|
52
|
+
*
|
|
53
|
+
* Not `rss`: inside a worker thread `process.memoryUsage().rss` is the resident size of the
|
|
54
|
+
* whole process. Compared with a per-worker limit, it made every worker of a host larger than
|
|
55
|
+
* the limit look over it, at every check: idle workers were recycled, and an execution that was
|
|
56
|
+
* running (waiting for a tool call, say) lost its worker.
|
|
57
|
+
*/
|
|
58
|
+
export declare function workerMemoryBytes(usage: ResourceUsage): number;
|
|
50
59
|
/**
|
|
51
60
|
* Monitors worker memory usage and enforces limits
|
|
52
61
|
*/
|
|
@@ -98,9 +107,14 @@ export declare class MemoryMonitor extends EventEmitter {
|
|
|
98
107
|
* Get current memory usage summary
|
|
99
108
|
*/
|
|
100
109
|
getCurrentUsageSummary(): {
|
|
110
|
+
/** Sum of the `rss` every worker reported: each report is the size of the WHOLE process */
|
|
101
111
|
totalRss: number;
|
|
102
112
|
avgRss: number;
|
|
103
113
|
maxRss: number;
|
|
114
|
+
/** Sum of what the workers themselves hold (heap plus external memory) */
|
|
115
|
+
totalWorkerBytes: number;
|
|
116
|
+
avgWorkerBytes: number;
|
|
117
|
+
maxWorkerBytes: number;
|
|
104
118
|
slotCount: number;
|
|
105
119
|
};
|
|
106
120
|
}
|
|
@@ -10,6 +10,10 @@ import { z } from 'zod';
|
|
|
10
10
|
import { type NormalizedToolNamespace } from '@enclave-vm/ast';
|
|
11
11
|
import type { ResourceUsage } from './config';
|
|
12
12
|
import type { SpecialResultValue } from './result-encoding';
|
|
13
|
+
import type { ConsoleLevel } from '../../console-handler';
|
|
14
|
+
import type { SerializableSuspiciousPattern } from '../../double-vm/types';
|
|
15
|
+
import type { SecureProxyLevelConfig } from '../../types';
|
|
16
|
+
import type { ReferenceConfig } from '../../sidecar/reference-config';
|
|
13
17
|
/**
|
|
14
18
|
* Serialized error format for cross-thread communication
|
|
15
19
|
* Errors are serialized to prevent prototype pollution
|
|
@@ -23,6 +27,33 @@ export interface SerializedError {
|
|
|
23
27
|
code?: string;
|
|
24
28
|
/** Sanitized stack trace (only if sanitizeStackTraces is false) */
|
|
25
29
|
stack?: string;
|
|
30
|
+
/** Structured details of the error (JSON data), as `ExecutionError.data` */
|
|
31
|
+
data?: Record<string, unknown>;
|
|
32
|
+
}
|
|
33
|
+
/** A regular expression as it crosses the thread boundary. */
|
|
34
|
+
export interface SerializedPattern {
|
|
35
|
+
source: string;
|
|
36
|
+
flags: string;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* The double VM configuration as it crosses the thread boundary: regular expressions as source
|
|
40
|
+
* and flags, custom suspicious patterns as serialized detectors.
|
|
41
|
+
*/
|
|
42
|
+
export interface SerializedDoubleVmConfig {
|
|
43
|
+
/** false runs the script in a single VM inside the worker (not recommended) */
|
|
44
|
+
enabled: boolean;
|
|
45
|
+
parentTimeoutBuffer: number;
|
|
46
|
+
parentValidation: {
|
|
47
|
+
validateOperationNames: boolean;
|
|
48
|
+
allowedOperationPattern?: SerializedPattern;
|
|
49
|
+
blockedOperationPatterns?: SerializedPattern[];
|
|
50
|
+
maxOperationsPerSecond: number;
|
|
51
|
+
blockSuspiciousSequences: boolean;
|
|
52
|
+
rapidEnumerationThreshold: number;
|
|
53
|
+
rapidEnumerationOverrides: Record<string, number>;
|
|
54
|
+
/** The host's custom suspicious patterns (the default ones are added inside the worker) */
|
|
55
|
+
suspiciousPatterns: SerializableSuspiciousPattern[];
|
|
56
|
+
};
|
|
26
57
|
}
|
|
27
58
|
/**
|
|
28
59
|
* Execution statistics from the worker
|
|
@@ -72,6 +103,27 @@ export interface SerializedConfig {
|
|
|
72
103
|
* `mail.list` through the worker's callTool)
|
|
73
104
|
*/
|
|
74
105
|
toolNamespaces?: NormalizedToolNamespace[];
|
|
106
|
+
/**
|
|
107
|
+
* Whether the host has a consoleHandler: the sandbox then gets the handler console at every
|
|
108
|
+
* security level, and each console message carries one formatted line as its only argument
|
|
109
|
+
*/
|
|
110
|
+
hasConsoleHandler?: boolean;
|
|
111
|
+
/** Memory limit for the in-sandbox allocation tracking, in bytes (0 = no tracking) */
|
|
112
|
+
memoryLimit?: number;
|
|
113
|
+
/** Maximum size of a tool request or response, in bytes */
|
|
114
|
+
toolBridgeMaxPayloadBytes?: number;
|
|
115
|
+
/** Secure proxy (membrane) configuration of the enclave */
|
|
116
|
+
secureProxyConfig?: SecureProxyLevelConfig;
|
|
117
|
+
/** Cap on calls into host functions passed in `globals` */
|
|
118
|
+
maxGlobalFunctionCalls?: number;
|
|
119
|
+
/** Global names the script's realm may hold (`realmGlobals: 'allowlist'`); absent otherwise */
|
|
120
|
+
realmGlobalAllowlist?: string[];
|
|
121
|
+
/** Reference (sidecar) configuration: the worker needs it to treat reference ids correctly */
|
|
122
|
+
referenceConfig?: ReferenceConfig;
|
|
123
|
+
/**
|
|
124
|
+
* How the script is isolated inside the worker. Absent means the double VM with its defaults.
|
|
125
|
+
*/
|
|
126
|
+
doubleVm?: SerializedDoubleVmConfig;
|
|
75
127
|
}
|
|
76
128
|
/**
|
|
77
129
|
* Execute code in the worker
|
|
@@ -94,16 +146,12 @@ export interface ToolResponseMessage {
|
|
|
94
146
|
requestId: string;
|
|
95
147
|
/** Tool call identifier */
|
|
96
148
|
callId: string;
|
|
97
|
-
/** Tool result (if successful) */
|
|
98
|
-
result?: unknown;
|
|
99
|
-
/** Error (if failed) */
|
|
100
|
-
error?: SerializedError;
|
|
101
149
|
/**
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
150
|
+
* The host's answer in the string tool-bridge format (see ../../tool-bridge): the sanitized
|
|
151
|
+
* result, or an error that says whether the tool itself failed or the host refused the call.
|
|
152
|
+
* It is produced by the same bridge as for an in-process execution.
|
|
105
153
|
*/
|
|
106
|
-
|
|
154
|
+
response: string;
|
|
107
155
|
}
|
|
108
156
|
/**
|
|
109
157
|
* Request memory usage report from worker
|
|
@@ -185,7 +233,7 @@ export interface ConsoleMessage {
|
|
|
185
233
|
/** Execution request identifier */
|
|
186
234
|
requestId: string;
|
|
187
235
|
/** Console level */
|
|
188
|
-
level:
|
|
236
|
+
level: ConsoleLevel;
|
|
189
237
|
/** Console arguments */
|
|
190
238
|
args: unknown[];
|
|
191
239
|
}
|
|
@@ -227,6 +275,7 @@ export declare const executionResultMessageSchema: z.ZodObject<{
|
|
|
227
275
|
message: z.ZodString;
|
|
228
276
|
code: z.ZodOptional<z.ZodString>;
|
|
229
277
|
stack: z.ZodOptional<z.ZodString>;
|
|
278
|
+
data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
230
279
|
}, z.core.$strip>>;
|
|
231
280
|
stats: z.ZodObject<{
|
|
232
281
|
duration: z.ZodNumber;
|
|
@@ -257,9 +306,10 @@ export declare const consoleMessageSchema: z.ZodObject<{
|
|
|
257
306
|
requestId: z.ZodString;
|
|
258
307
|
level: z.ZodEnum<{
|
|
259
308
|
log: "log";
|
|
309
|
+
info: "info";
|
|
260
310
|
warn: "warn";
|
|
261
311
|
error: "error";
|
|
262
|
-
|
|
312
|
+
debug: "debug";
|
|
263
313
|
}>;
|
|
264
314
|
args: z.ZodArray<z.ZodUnknown>;
|
|
265
315
|
}, z.core.$strict>;
|
|
@@ -301,6 +351,7 @@ export declare const workerToMainMessageSchema: z.ZodDiscriminatedUnion<[z.ZodOb
|
|
|
301
351
|
message: z.ZodString;
|
|
302
352
|
code: z.ZodOptional<z.ZodString>;
|
|
303
353
|
stack: z.ZodOptional<z.ZodString>;
|
|
354
|
+
data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
304
355
|
}, z.core.$strip>>;
|
|
305
356
|
stats: z.ZodObject<{
|
|
306
357
|
duration: z.ZodNumber;
|
|
@@ -323,9 +374,10 @@ export declare const workerToMainMessageSchema: z.ZodDiscriminatedUnion<[z.ZodOb
|
|
|
323
374
|
requestId: z.ZodString;
|
|
324
375
|
level: z.ZodEnum<{
|
|
325
376
|
log: "log";
|
|
377
|
+
info: "info";
|
|
326
378
|
warn: "warn";
|
|
327
379
|
error: "error";
|
|
328
|
-
|
|
380
|
+
debug: "debug";
|
|
329
381
|
}>;
|
|
330
382
|
args: z.ZodArray<z.ZodUnknown>;
|
|
331
383
|
}, z.core.$strict>], "type">;
|
|
@@ -8,25 +8,41 @@
|
|
|
8
8
|
*/
|
|
9
9
|
import type { SandboxAdapter, ExecutionContext, ExecutionResult, SecurityLevel } from '../../types';
|
|
10
10
|
import type { WorkerPoolConfig, WorkerPoolMetrics } from './config';
|
|
11
|
+
import type { DoubleVmConfig } from '../../double-vm/types';
|
|
11
12
|
/**
|
|
12
13
|
* Worker Pool Adapter
|
|
13
14
|
*
|
|
14
15
|
* Provides a worker thread-based sandbox adapter with:
|
|
15
|
-
* -
|
|
16
|
+
* - A heap limit per worker, enforced by the engine (by the pool when a heap flag of the process
|
|
17
|
+
* overrides it, see WorkerSlot)
|
|
16
18
|
* - Hard halt capability via worker.terminate()
|
|
17
19
|
* - Pool management with min/max workers
|
|
18
20
|
* - Memory monitoring and enforcement
|
|
19
21
|
* - Rate limiting for message flood protection
|
|
22
|
+
*
|
|
23
|
+
* Inside the worker the script runs in the same sandbox as an in-process execution: the double VM
|
|
24
|
+
* by default (or a single VM when the double VM is disabled). The worker thread is an additional
|
|
25
|
+
* layer around that sandbox, not a replacement for it. Tool calls come back to this thread and
|
|
26
|
+
* go through the same tool bridge as in-process tool calls.
|
|
20
27
|
*/
|
|
21
28
|
export declare class WorkerPoolAdapter implements SandboxAdapter {
|
|
22
29
|
private readonly config;
|
|
23
30
|
private readonly securityLevel;
|
|
31
|
+
private readonly doubleVm;
|
|
24
32
|
private readonly slots;
|
|
33
|
+
/**
|
|
34
|
+
* Workers that are starting. A worker is in `slots` only once it is ready, so everything that
|
|
35
|
+
* compares the pool with its size has to count these as well: a burst of executions that each
|
|
36
|
+
* found "room" started a worker each, however small `maxWorkers` was.
|
|
37
|
+
*/
|
|
38
|
+
private startingWorkers;
|
|
25
39
|
private readonly executionQueue;
|
|
26
40
|
private readonly memoryMonitor;
|
|
27
41
|
private readonly rateLimiter;
|
|
28
42
|
private disposed;
|
|
29
43
|
private initialized;
|
|
44
|
+
/** The initialization in progress: concurrent callers share it */
|
|
45
|
+
private initialization;
|
|
30
46
|
private readonly boundMemoryExceededHandler;
|
|
31
47
|
private _totalExecutions;
|
|
32
48
|
private _successfulExecutions;
|
|
@@ -34,12 +50,22 @@ export declare class WorkerPoolAdapter implements SandboxAdapter {
|
|
|
34
50
|
private _timeoutExecutions;
|
|
35
51
|
private _workerRecycles;
|
|
36
52
|
private _forcedTerminations;
|
|
37
|
-
|
|
53
|
+
private _heapLimitKills;
|
|
54
|
+
/** Workers already counted as a memory kill (by the memory monitor or as a heap-limit kill) */
|
|
55
|
+
private readonly memoryKilledSlots;
|
|
56
|
+
/**
|
|
57
|
+
* @param config Worker pool configuration
|
|
58
|
+
* @param securityLevel Security level of the enclave
|
|
59
|
+
* @param doubleVmConfig How the script is isolated inside each worker. Default: the double VM
|
|
60
|
+
* with its default validation.
|
|
61
|
+
*/
|
|
62
|
+
constructor(config?: Partial<WorkerPoolConfig>, securityLevel?: SecurityLevel, doubleVmConfig?: DoubleVmConfig);
|
|
38
63
|
/**
|
|
39
64
|
* Initialize the worker pool
|
|
40
65
|
* Must be called before execute()
|
|
41
66
|
*/
|
|
42
67
|
initialize(): Promise<void>;
|
|
68
|
+
private warmUp;
|
|
43
69
|
/**
|
|
44
70
|
* Execute code in a worker
|
|
45
71
|
*/
|
|
@@ -48,8 +74,25 @@ export declare class WorkerPoolAdapter implements SandboxAdapter {
|
|
|
48
74
|
* Dispose the adapter and all workers
|
|
49
75
|
*/
|
|
50
76
|
dispose(): void;
|
|
77
|
+
/** Workers the pool has, or is about to have */
|
|
78
|
+
private get workerCount();
|
|
79
|
+
/**
|
|
80
|
+
* Start a worker and add it to the pool.
|
|
81
|
+
*
|
|
82
|
+
* @param executionId When given, the new worker is acquired for this execution before anyone
|
|
83
|
+
* else can see it idle (the caller asked for a worker because none was free).
|
|
84
|
+
*/
|
|
51
85
|
private createAndAddSlot;
|
|
86
|
+
/** One worker ended at its memory limit is one memory kill, whichever check saw it */
|
|
87
|
+
private countHeapLimitKill;
|
|
52
88
|
private acquireSlot;
|
|
89
|
+
/**
|
|
90
|
+
* Take a worker that is gone (terminated by the watchdog, by the memory monitor, or by itself)
|
|
91
|
+
* out of the pool, and let a queued execution proceed: it finds the pool below its size and
|
|
92
|
+
* gets a new worker. A dead slot that stayed in the pool would count against `maxWorkers`
|
|
93
|
+
* forever, and with one worker every later execution would wait in the queue until it timed out.
|
|
94
|
+
*/
|
|
95
|
+
private removeDeadSlot;
|
|
53
96
|
private releaseSlot;
|
|
54
97
|
private handleSlotRecycling;
|
|
55
98
|
private handleMemoryExceeded;
|
|
@@ -1,11 +1,21 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Worker Script
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
* 1. Worker thread isolation (OS-level)
|
|
6
|
-
* 2. VM context isolation (prototype isolation)
|
|
4
|
+
* Runs inside a worker thread of the pool.
|
|
7
5
|
*
|
|
8
|
-
*
|
|
6
|
+
* What a worker adds to an execution: a heap limit that the engine enforces, and a way for the
|
|
7
|
+
* host to stop the execution whatever the script is doing (`worker.terminate()`).
|
|
8
|
+
*
|
|
9
|
+
* What it does NOT add is a sandbox. A worker thread has the whole Node.js API (`process`,
|
|
10
|
+
* `require`, the file system), and a `vm` context created here from this thread's own objects
|
|
11
|
+
* hands the script this thread's `Function` constructor one property read away. So the script
|
|
12
|
+
* runs here in the SAME sandbox as an in-process execution: the double VM (parent realm with the
|
|
13
|
+
* membrane and the tool gate, inner realm for the script), or a single VM when the double VM is
|
|
14
|
+
* disabled. The worker is a layer around that sandbox.
|
|
15
|
+
*
|
|
16
|
+
* Tool calls leave the sandbox through the string tool bridge, are sent to the host thread as
|
|
17
|
+
* messages, and are answered there by the host's tool bridge (see ../../tool-bridge): the same
|
|
18
|
+
* checks, sidecar handling and sanitization as for an in-process tool call.
|
|
9
19
|
*
|
|
10
20
|
* @packageDocumentation
|
|
11
21
|
*/
|