@chatbotaurus/nodevm

Secure Node.js VM for Chatbotaurus - Execute user code in isolated sandbox environments.

Overview

@chatbotaurus/nodevm provides a secure virtual machine environment for executing untrusted JavaScript code in Node.js. It creates an isolated sandbox that prevents malicious code from accessing the host system while allowing controlled access to specific modules and resources.

Installation

npm install @chatbotaurus/nodevm

or with pnpm:

pnpm add @chatbotaurus/nodevm

Basic Usage

import { NodeVM } from '@chatbotaurus/nodevm';

// Create a new VM instance
const vm = new NodeVM({
  console: 'inherit',
  sandbox: {},
  require: {
    external: true,
    builtin: ['fs', 'path'],
    root: './'
  }
});

// Execute code in the sandbox
const result = vm.run(`
  const message = 'Hello from the sandbox!';
  module.exports = message;
`);

console.log(result); // Output: Hello from the sandbox!

Configuration Options

NodeVMOptions

• console: Control console output behavior

  • 'inherit' - Pass through to host console
  • 'redirect' - Capture console output
  • 'off' - Disable console

• sandbox: Object containing variables accessible in the sandbox

  const vm = new NodeVM({
    sandbox: {
      customVar: 'Available in sandbox'
    }
  });

• require: Configure module loading

  • external: Allow external npm packages (boolean or string array)
  • builtin: Whitelist of built-in Node.js modules
  • root: Root directory for module resolution
  • mock: Mock specific modules

• wrapper: Code wrapping strategy

  • 'commonjs' - Wrap in CommonJS module format (default)
  • 'none' - No wrapping

• sourceExtensions: File extensions to process (default: ['js'])

Advanced Examples

Restricting Module Access

const vm = new NodeVM({
  require: {
    external: false, // Disable external packages
    builtin: ['path'], // Only allow 'path' module
    root: './'
  }
});

Running Files

const vm = new NodeVM();
const result = vm.runFile('./user-script.js');

Custom Sandbox Variables

const vm = new NodeVM({
  sandbox: {
    apiKey: process.env.API_KEY,
    fetch: customFetchImplementation
  }
});

Security Considerations

• Always validate and sanitize user input before execution
• Limit access to built-in modules based on your security requirements
• Set appropriate timeouts for code execution
• Monitor resource usage (CPU, memory) when executing untrusted code
• Consider using additional security layers (containers, process isolation)

Use Cases

• Execute user-provided workflow scripts in Chatbotaurus
• Run custom transformations and data processing
• Implement plugin systems with sandboxed code
• Test and validate JavaScript code safely

License

MIT

Links

• npm Package
• GitHub Repository
• Documentation

Support

For issues and questions, please visit our GitHub Issues page.