> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Double VM Layer

> Enhanced security through nested VM isolation with operation validation

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

```mermaid theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8a045', 'primaryTextColor': '#fff', 'primaryBorderColor': '#c78935', 'lineColor': '#c78935', 'secondaryColor': '#f0b865', 'tertiaryColor': '#fff5e6'}}}%%
flowchart TB
    subgraph host["Host Process"]
        subgraph parent["Parent VM (Security Validation)"]
            subgraph inner["Inner VM (Code Execution)"]
                code["User Code"]
            end
        end
    end
    style host fill:#fff5e6,stroke:#c78935,color:#333
    style parent fill:#f0b865,stroke:#c78935,color:#333
    style inner fill:#e8a045,stroke:#c78935,color:#fff
    style code fill:#c78935,stroke:#c78935,color:#fff
```

* **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

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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     |

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  doubleVm: {
    parentValidation: {
      blockSuspiciousSequences: true,
      // All built-in patterns are enabled by default
    },
  },
});
```

## Custom Suspicious Patterns

Define your own detection logic:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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

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

## 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:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  doubleVm: {
    enabled: true,
    parentValidation: {
      validateOperationNames: true,
      blockSuspiciousSequences: false, // Disable pattern detection
    },
  },
});
```

## Related

* [Security Levels](/enclave/core-libraries/enclave-vm/security-levels) - Security presets
* [AI Scoring Gate](/enclave/core-libraries/enclave-vm/ai-scoring) - Semantic security analysis
* [Worker Pool](/enclave/core-libraries/enclave-vm/worker-pool) - OS-level isolation