Double VM Layer

The Double VM layer provides enhanced security through nested VM isolation. A parent VM acts as a security barrier that validates all operations before they reach the host system.

Architecture

Parent VM: Security barrier with operation validation
Inner VM: Isolated execution environment for user code
Tool call flow: Inner VM → Parent VM validation → Host handler

Basic Configuration

import { Enclave } from '@enclave-vm/core';

const enclave = new Enclave({
  securityLevel: 'SECURE',
  doubleVm: {
    enabled: true, // Default: true
    parentTimeoutBuffer: 1000, // Extra timeout for parent VM (ms)
    parentValidation: {
      validateOperationNames: true,
      maxOperationsPerSecond: 100, // Rate limiting
      blockSuspiciousSequences: true, // Detect attack patterns
    },
  },
});

Parent Validation Options

interface ParentValidationOptions {
  // Name validation
  validateOperationNames: boolean;
  allowedOperationPattern?: RegExp;    // Whitelist pattern
  blockedOperationPatterns?: RegExp[]; // Blacklist patterns

  // Rate limiting
  maxOperationsPerSecond: number;

  // Pattern detection
  blockSuspiciousSequences: boolean;
  suspiciousPatterns?: SuspiciousPattern[];
}

Operation Name Filtering

Control which tool names are allowed:

const enclave = new Enclave({
  doubleVm: {
    parentValidation: {
      validateOperationNames: true,

      // Only allow specific patterns
      allowedOperationPattern: /^[a-z]+:[a-z]+$/i,

      // Block admin operations
      blockedOperationPatterns: [
        /^admin:/i,
        /^system:/i,
        /delete/i,
      ],
    },
  },
});

Built-in Suspicious Pattern Detection

The Double VM detects these attack patterns automatically:

Pattern	Description
`EXFIL_LIST_SEND`	List/query followed by send/export
`RAPID_ENUMERATION`	Same operation called >10 times in 5s
`CREDENTIAL_EXFIL`	Credential access + external operation
`BULK_OPERATION`	Bulk/batch/mass operation names
`DELETE_AFTER_ACCESS`	Delete operation after data access

const enclave = new Enclave({
  doubleVm: {
    parentValidation: {
      blockSuspiciousSequences: true,
      // All built-in patterns are enabled by default
    },
  },
});

Custom Suspicious Patterns

Define your own detection logic:

const enclave = new Enclave({
  doubleVm: {
    parentValidation: {
      suspiciousPatterns: [
        {
          id: 'CUSTOM_PATTERN',
          description: 'Custom detection logic',
          detect: (operationName, args, history) => {
            // Check if operation is suspicious based on context
            if (operationName.includes('dangerous')) {
              return true;
            }

            // Check operation history
            const recentOps = history.slice(-5);
            if (recentOps.some(op => op.name === 'sensitive:read')) {
              return operationName.includes('send');
            }

            return false;
          },
        },
        {
          id: 'RATE_SPIKE',
          description: 'Sudden increase in operation rate',
          detect: (operationName, args, history) => {
            const last10 = history.slice(-10);
            const timeSpan = Date.now() - (last10[0]?.timestamp || 0);
            return timeSpan < 1000; // 10 ops in <1s
          },
        },
      ],
    },
  },
});

Detection Pattern Interface

interface SuspiciousPattern {
  id: string;              // Unique identifier
  description: string;     // Human-readable description
  detect: (
    operationName: string,
    args: unknown,
    history: OperationHistoryEntry[]
  ) => boolean;
}

interface OperationHistoryEntry {
  name: string;
  args: unknown;
  timestamp: number;
}

Rate Limiting

Prevent rapid-fire tool calls:

const enclave = new Enclave({
  doubleVm: {
    parentValidation: {
      maxOperationsPerSecond: 50, // Allow max 50 ops/sec
    },
  },
});

When the rate limit is exceeded, subsequent calls are blocked until the rate drops.

Security Benefits

Operation Isolation - Tool calls pass through validation layer
Pattern Detection - Detect multi-step attack sequences
Rate Limiting - Prevent denial-of-service via tool flooding
Audit Trail - Operation history for forensics
Defense in Depth - Additional layer beyond AST validation

Host Value Boundary

Custom globals, and everything reachable from what they return, are wrapped in a membrane that blocks constructor, prototype, and __proto__. One descriptor shape cannot be wrapped: a JavaScript get trap is required to report the exact value of a non-configurable, non-writable own data property, so such a property can be neither wrapped nor hidden. For host-owned values the membrane therefore refuses that read with a SecurityError whenever the pinned value is an object or a function — returning the reference would place an unwrapped host object graph within reach of sandboxed code, and that graph’s prototype chain leads to the host Function constructor. Pinned primitives are still reported as-is, so numeric constants and slots pinned to undefined read normally. Values owned by the sandbox’s own realms keep the exact-value behavior. Their intrinsics run with code generation from strings disabled, and new Array() and instanceof both depend on reading a pinned prototype. The practical consequence for embedders: sandboxed code should receive only plain serialized data, never live host objects. A structurally cloned or JSON-projected value has no pinned members and reads normally, whereas a Zod schema pins _zod and every class pins prototype. The exported createSecureProxy() helper applies the same rule and always treats its target as host-owned.

Performance Considerations

The Double VM adds minimal overhead:

Latency: ~1-2ms per tool call for validation
Memory: ~10MB additional for parent VM context
CPU: Negligible for pattern matching

For performance-critical applications, you can disable specific features:

const enclave = new Enclave({
  doubleVm: {
    enabled: true,
    parentValidation: {
      validateOperationNames: true,
      blockSuspiciousSequences: false, // Disable pattern detection
    },
  },
});

Security Levels - Security presets
AI Scoring Gate - Semantic security analysis
Worker Pool - OS-level isolation

Get Started

Concepts

@enclave-vm/core

@enclave-vm/browser

@enclave-vm/ast

EnclaveJS Streaming

Guides

Examples

Troubleshooting

Architecture

Basic Configuration

Parent Validation Options

Operation Name Filtering

Built-in Suspicious Pattern Detection

Custom Suspicious Patterns

Detection Pattern Interface

Rate Limiting

Security Benefits

Host Value Boundary

Performance Considerations

​Architecture

​Basic Configuration

​Parent Validation Options

​Operation Name Filtering

​Built-in Suspicious Pattern Detection

​Custom Suspicious Patterns

​Detection Pattern Interface

​Rate Limiting

​Security Benefits

​Host Value Boundary

​Performance Considerations

​Related

Architecture

Basic Configuration

Parent Validation Options

Operation Name Filtering

Built-in Suspicious Pattern Detection

Custom Suspicious Patterns

Detection Pattern Interface

Rate Limiting

Security Benefits

Host Value Boundary

Performance Considerations

Related