No input content was provided for translation. Please supply the chunk text to translate.```js
import { VM } from 'vm2';

new VM().run('this.constructor.constructor("return process")().exit()');
// Throws ReferenceError: process is not defined

## Exemplos rápidos```js
import { VM } from 'vm2';

const vm = new VM();
vm.run(`process.exit()`); // TypeError: process.exit is not a function

## Documentação

-   [VM](#vm)
-   [NodeVM](#nodevm)
-   [VMScript](#vmscript)
-   [Tratamento de erros](#error-handling)
-   [Depuração de código em sandbox](#debugging-a-sandboxed-code)
-   [Objetos somente leitura](#read-only-objects-experimental)
-   [Objetos protegidos](#protected-objects-experimental)
-   [Relações entre sandboxes](#cross-sandbox-relationships)
-   [CLI](#cli)
-   [Mudanças da 2.x para 3.x](https://github.com/patriksimek/vm2/wiki/2.x-to-3.x-changes)
-   [Documentação da 1.x e 2.x](https://github.com/patriksimek/vm2/wiki/1.x-and-2.x-docs)
-   [Contribuindo](https://github.com/patriksimek/vm2/wiki/Contributing)

## VM

VM é um sandbox simples para executar código não confiável de forma síncrona sem o recurso `require`. Apenas objetos internos do JavaScript e `Buffer` do Node estão disponíveis. Funções de agendamento (`setInterval`, `setTimeout` e `setImmediate`) não estão disponíveis por padrão.

**Opções:**

-   `timeout` - Tempo limite do script em milissegundos. **ATENÇÃO**: Talvez você queira usar esta opção junto com `allowAsync=false`. Além disso, operar em objetos retornados do sandbox pode executar código arbitrário e contornar o tempo limite. Deve-se testar se o objeto retornado é um primitivo com `typeof` e descartá-lo completamente (fazer log ou criar mensagens de erro com esse objeto também pode executar código arbitrário novamente) caso contrário.
-   `sandbox` - Objeto global da VM.
-   `compiler` - `javascript` (padrão), `typescript`, `coffeescript` ou função de compilador personalizada. A biblioteca espera que você tenha o compilador pré-instalado se o valor for definido como `typescript` ou `coffeescript`.
-   `eval` - Se definido como `false`, qualquer chamada a `eval` ou construtores de função (`Function`, `GeneratorFunction`, etc.) lançará um `EvalError` (padrão: `true`).
-   `wasm` - Se definido como `false`, qualquer tentativa de compilar um módulo WebAssembly lançará um `WebAssembly.CompileError` (padrão: `true`). Observação: `WebAssembly.JSTag` é removido dentro do sandbox por motivos de segurança, portanto o código wasm não pode capturar exceções JavaScript.
-   `allowAsync` - Se definido como `false`, qualquer tentativa de executar código usando `async` lançará um `VMError` (padrão: `true`).
-   `bufferAllocLimit` - Tamanho máximo em bytes para uma única solicitação `Buffer.alloc` / `Buffer.allocUnsafe` / `Buffer.allocUnsafeSlow` / `Buffer(N)` / `new Buffer(N)` de dentro do sandbox. Solicitações que excedem esse limite lançam um `RangeError` de forma síncrona sem realizar a alocação no host. Padrão: `Infinity` (sem limite, totalmente compatível com versões anteriores). Incorporadores que executam código não confiável em ambientes com memória limitada (Docker / Kubernetes / Lambda / serverless) devem optar por um limite finito (ex.: `32 * 1024 * 1024`) como parte da defesa em camadas contra DoS, da mesma forma que optam por `timeout`. Consulte [Recomendações de endurecimento](#hardening-recommendations) abaixo.

**IMPORTANTE**: O tempo limite só é eficaz em código síncrono executado por meio de `run`. O tempo limite **NÃO** funciona em nenhum método retornado pela VM. Existem algumas situações em que o tempo limite não funciona - consulte [#244](https://github.com/patriksimek/vm2/pull/244).```js
import { VM } from 'vm2';

const vm = new VM({
	timeout: 1000,
	allowAsync: false,
	sandbox: {},
});

vm.run('process.exit()'); // throws ReferenceError: process is not defined

**DICA**: Consulte os testes para mais exemplos de uso.

## NodeVM

Ao contrário de `VM`, o `NodeVM` permite que você utilize módulos da mesma forma que faria no contexto normal do Node.

**Opções:**

-   `console` - `inherit` para habilitar o console, `redirect` para redirecionar para eventos, `off` para desabilitar o console (padrão: `inherit`).
-   `sandbox` - Objeto global da VM.
-   `compiler` - `javascript` (padrão), `typescript`, `coffeescript` ou uma função de compilador personalizada (que recebe o código e o caminho do arquivo dele). A biblioteca espera que você tenha o compilador pré-instalado se o valor for definido como `typescript` ou `coffeescript`.
-   `eval` - Se definido como `false`, qualquer chamada a `eval` ou construtores de função (`Function`, `GeneratorFunction`, etc.) lançará um `EvalError` (padrão: `true`).
-   `wasm` - Se definido como `false`, qualquer tentativa de compilar um módulo WebAssembly lançará um `WebAssembly.CompileError` (padrão: `true`). Observação: `WebAssembly.JSTag` é removido dentro da sandbox por motivos de segurança, portanto, o código wasm não pode capturar exceções JavaScript.
-   `bufferAllocLimit` - Mesma semântica do `VM` — tamanho máximo em bytes para uma única solicitação da família `Buffer.alloc` de dentro da sandbox. Padrão: `Infinity`. Consulte [Recomendações de endurecimento](#hardening-recommendations).
-   `sourceExtensions` - Matriz de extensões de arquivo a serem tratadas como código-fonte (padrão: `['js']`).
-   `require` - `true`, um objeto ou um Resolver para habilitar o método `require` (padrão: `false`).
-   `require.external` - Os valores podem ser `true`, uma matriz de módulos externos permitidos ou um objeto (padrão: `false`). Todos os caminhos que correspondem a `/node_modules/${any_allowed_external_module}/(?!/node_modules/)` são permitidos para require.
-   `require.external.modules` - Matriz de módulos externos permitidos. Também suporta curingas, então especificar `['@scope/*-ver-??]`, por exemplo, permitirá usar todos os módulos com um nome da forma `@scope/something-ver-aa`, `@scope/other-ver-11`, etc. O curinga `*` não corresponde a separadores de caminho.
-   `require.external.transitive` - Booleano que indica se dependências transitivas de módulos externos são permitidas (padrão: `false`). **ATENÇÃO**: Quando um módulo é exigido transitivamente, qualquer módulo pode então exigi-lo normalmente, mesmo que isso não fosse possível antes de ser carregado.
-   `require.builtin` - Matriz de módulos integrados permitidos, aceita ["\*"] para todos (padrão: nenhum). **ATENÇÃO**: "\*" pode ser perigoso, pois novos módulos integrados podem ser adicionados.
-   `require.root` - Caminho(s) restrito(s) onde módulos locais podem ser exigidos (padrão: todos os caminhos).
-   `require.mock` - Coleção de módulos simulados (tanto externos quanto integrados).
-   `require.context` - `host` (padrão) para exigir módulos no host e fazer proxy deles para a sandbox. `sandbox` para carregar, compilar e exigir módulos na sandbox. `callback(moduleFilename, ext)` para escolher dinamicamente um contexto por módulo. O padrão será sandbox se nada for especificado. Exceto para `events`, os módulos integrados são sempre exigidos no host e encapsulados por proxy na sandbox.
-   `require.import` - Uma matriz de módulos a serem carregados no NodeVM na inicialização.
-   `require.resolve` - Uma função de consulta adicional caso um módulo não seja encontrado em um dos caminhos tradicionais de consulta do node.
-   `require.customRequire` - Use em vez da função `require` para carregar módulos do host.
-   `require.strict` - `false` para não forçar o modo estrito nos módulos carregados por require (padrão: `true`).
-   `require.fs` - Implementação personalizada do sistema de arquivos.
-   `nesting` - **ATENÇÃO**: Permitir isso é um risco de segurança, pois scripts podem criar uma NodeVM que pode exigir qualquer módulo do host. `true` para habilitar aninhamento de VMs (padrão: `false`).
-   `wrapper` - `commonjs` (padrão) para envolver o script no wrapper CommonJS, `none` para recuperar o valor retornado pelo script.
-   `argv` - Matriz a ser passada para `process.argv`.
-   `env` - Objeto a ser passado para `process.env`.
-   `strict` - `true` para módulos carregados em modo estrito (padrão: `false`).

**IMPORTANTE**: O timeout não é eficaz para o NodeVM, portanto ele não é imune a `while (true) {}` ou a outros códigos maliciosos semelhantes.

**LEMBRE-SE**: Quanto mais módulos você permitir, mais frágil sua sandbox se torna.```js
import { NodeVM } from 'vm2';

const vm = new NodeVM({
	console: 'inherit',
	sandbox: {},
	require: {
		external: true,
		builtin: ['fs', 'path'],
		root: './',
		mock: {
			fs: {
				readFileSync: () => 'Nice try!',
			},
		},
	},
});

// Sync

let functionInSandbox = vm.run('module.exports = function(who) { console.log("hello "+ who); }');
functionInSandbox('world');

// Async

let functionWithCallbackInSandbox = vm.run('module.exports = function(who, callback) { callback("hello "+ who); }');
functionWithCallbackInSandbox('world', greeting => {
	console.log(greeting);
});

**DICA**: Veja os testes para mais exemplos de uso.

### Carregando módulos por caminho relativo

Para carregar módulos por caminho relativo, você deve passar o caminho completo do script que está executando como segundo argumento para o método `run` do vm se o script for uma string. O nome do arquivo é então exibido em quaisquer stack traces geradas pelo script.```js
vm.run('require("foobar")', '/data/myvmscript.js');

### Resolver

Um resolver pode ser criado via `makeResolverFromLegacyOptions` e usado para múltiplas instâncias de `NodeVM`, permitindo compartilhar código de módulo compilado e potencialmente acelerando os tempos de carregamento. O primeiro exemplo de `NodeVM` pode ser reescrito usando `makeResolverFromLegacyOptions` da seguinte forma.```js
const resolver = makeResolverFromLegacyOptions({
	external: true,
	builtin: ['fs', 'path'],
	root: './',
	mock: {
		fs: {
			readFileSync: () => 'Nice try!',
		},
	},
});
const vm = new NodeVM({
	console: 'inherit',
	sandbox: {},
	require: resolver,
});

Funciona para ambos `VM` e `NodeVM`.```js
import { NodeVM, VMScript } from 'vm2';

const vm = new NodeVM();
const script = new VMScript('module.exports = Math.random()');
console.log(vm.run(script));
console.log(vm.run(script));

## Depurando um código em sandbox

Você pode depurar ou inspecionar código em execução na sandbox como se estivesse em um processo normal.

-   Você pode usar pontos de interrupção (o que exige especificar um nome de arquivo de script)
-   Você pode usar a palavra-chave `debugger`.
-   Você pode usar step-in para entrar no código em execução na sandbox.

### Exemplo

/tmp/main.js:```js
import { VM, VMScript } from 'vm2';
import { readFileSync } from 'node:fs';

const file = `${__dirname}/sandbox.js`;

// By providing a file name as second argument you enable breakpoints
const script = new VMScript(readFileSync(file), file);

new VM().run(script);

## Objetos somente leitura (experimental)

Para impedir que scripts em sandbox adicionem, alterem ou excluam propriedades dos objetos com proxy, você pode usar métodos `freeze` para tornar o objeto somente leitura. Isso só é eficaz dentro da VM. Objetos congelados são afetados profundamente. Tipos primitivos não podem ser congelados.

**Exemplo sem usar `freeze`:**```js
const util = {
	add: (a, b) => a + b,
};

const vm = new VM({
	sandbox: { util },
});

vm.run('util.add = (a, b) => a - b');
console.log(util.add(1, 1)); // returns 0

**IMPORTANTE:** Não é possível congelar objetos que já foram passados por proxy para a VM.

## Objetos protegidos (experimental)

Ao contrário de `freeze`, este método permite que scripts em sandbox adicionem, alterem ou excluam propriedades em objetos, com uma exceção – não é possível anexar funções. Portanto, scripts em sandbox não conseguem modificar métodos como `toJSON`, `toString` ou `inspect`.

**IMPORTANTE:** Não é possível proteger objetos que já foram passados por proxy para a VM.

## Relações entre sandboxes```js
const assert = require('assert');
const { VM } = require('vm2');

const sandbox = {
	object: new Object(),
	func: new Function(),
	buffer: new Buffer([0x01, 0x05]),
};

const vm = new VM({ sandbox });

assert.ok(vm.run(`object`) === sandbox.object);
assert.ok(vm.run(`object instanceof Object`));
assert.ok(vm.run(`object`) instanceof Object);
assert.ok(vm.run(`object.__proto__ === Object.prototype`));
assert.ok(vm.run(`object`).__proto__ === Object.prototype);

assert.ok(vm.run(`func`) === sandbox.func);
assert.ok(vm.run(`func instanceof Function`));
assert.ok(vm.run(`func`) instanceof Function);
assert.ok(vm.run(`func.__proto__ === Function.prototype`));
assert.ok(vm.run(`func`).__proto__ === Function.prototype);

assert.ok(vm.run(`new func() instanceof func`));
assert.ok(vm.run(`new func()`) instanceof sandbox.func);
assert.ok(vm.run(`new func().__proto__ === func.prototype`));
assert.ok(vm.run(`new func()`).__proto__ === sandbox.func.prototype);

assert.ok(vm.run(`buffer`) === sandbox.buffer);
assert.ok(vm.run(`buffer instanceof Buffer`));
assert.ok(vm.run(`buffer`) instanceof Buffer);
assert.ok(vm.run(`buffer.__proto__ === Buffer.prototype`));
assert.ok(vm.run(`buffer`).__proto__ === Buffer.prototype);
assert.ok(vm.run(`buffer.slice(0, 1) instanceof Buffer`));
assert.ok(vm.run(`buffer.slice(0, 1)`) instanceof Buffer);

## Recomendações de endurecimento

O vm2 evita escapes de sandbox (código não confiável obtendo acesso ao realm do host). Ele **não** impede, por si só, todas as formas de esgotamento de recursos ou negação de serviço. Integradores que executam código não confiável devem adicionar as seguintes defesas em camadas ao redor da sandbox.

### 1. Limite a alocação de memória com `bufferAllocLimit`

Uma única chamada `Buffer.alloc(N)` com `N` controlado pelo atacante é executada como uma alocação síncrona em C++ do host que o `timeout` do V8 não pode interromper. Em ambientes com memória restrita, uma carga útil de sandbox de ~100 bytes pode causar um salto de RSS do host de 100 MB+ e derrubar o processo do host via OOM. Defina `bufferAllocLimit` (ex.: `32 * 1024 * 1024`) para limitar alocações individuais:```js
const vm = new VM({
	timeout: 1000,
	bufferAllocLimit: 32 * 1024 * 1024,
	allowAsync: false,
});

Se a sua aplicação não tiver nenhuma outra fonte de rejeições não tratadas, uma captura geral + registro é aceitável:```js
process.on('unhandledRejection', reason => {
	yourLogger.warn('swallowed sandbox rejection', reason);
});

Se você definir `nesting: true`, você efetivamente concedeu à sandbox o mesmo nível de confiança que você tem. **Não habilite `nesting: true` para código não confiável.** Use-o apenas quando você confia no código da sandbox em si, mas deseja semântica de execução estilo VM (global novo, timeouts controlados) por motivos não relacionados à segurança.

`nesting: true` **exige um objeto de configuração `require` explícito** (ex.: `require: { builtin: [] }` ou `require: {}`). Qualquer outra forma — `require: false`, `require: undefined`, `require: null`, ou omitir `require` completamente — lança `VMError` na construção (GHSA-m4wx-m65x-ghrr, substitui GHSA-8hg8-63c5-gwmx). Todas essas formas produzem um resolvedor somente-NESTING_OVERRIDE: a sandbox pode usar `require('vm2')` mas nada mais, o que é uma primitiva de escape pura sem uso legítimo. Para negar todos os requires, remova `nesting: true`. Para permitir VMs aninhadas, forneça um objeto de configuração `require` explícito para que o trade-off fique visível no local da chamada.

## Problemas Conhecidos

-   Não é possível definir uma classe que estenda uma classe com proxy. Isso inclui usar uma classe com proxy em `Object.create`.
-   O eval direto não funciona.
-   Registrar arrays da sandbox fará com que a parte do array se repita nas propriedades.
-   As transformações de código-fonte podem resultar em uma string de origem diferente para uma função.
-   Existem maneiras de derrubar o processo node de dentro da sandbox. Consulte [Recomendações de endurecimento](#hardening-recommendations).

[npm-image]: https://img.shields.io/npm/v/vm2.svg
[npm-url]: https://www.npmjs.com/package/vm2
[license-image]: https://img.shields.io/npm/l/vm2.svg
[license-url]: https://raw.githubusercontent.com/patriksimek/vm2/resurrection/LICENSE.md
[downloads-image]: https://img.shields.io/npm/dm/vm2.svg
[downloads-url]: https://www.npmjs.com/package/vm2
[snyk-image]: https://snyk.io/test/github/patriksimek/vm2/badge.svg
[snyk-url]: https://snyk.io/test/github/patriksimek/vm2