Runtime Module Hooks

1. ES Modules (module.register)

Node.js 18+ provides module customization hooks that intercept module resolution and loading:

Module Resolution (resolve hook)

When application code or an npm package imports node:child_process or node:dns, the resolve() hook intercepts the specifier and redirects it to an internal virtual URL protocol:

export async function resolve(specifier, context, nextResolve) {
  if (specifier === 'child_process' || specifier === 'node:child_process') {
    return { url: 'envtrap:child_process', shortCircuit: true };
  }
  if (specifier === 'dns' || specifier === 'node:dns') {
    return { url: 'envtrap:dns', shortCircuit: true };
  }
  return nextResolve(specifier, context);
}

Module Loading (load hook)

When Node.js attempts to load an envtrap:* URL, the load() hook serves our specialized virtual wrapper module (src/hooks/virtual/child-process.mjs or src/hooks/virtual/dns.mjs) directly from memory:

export async function load(url, context, nextLoad) {
  if (url === 'envtrap:dns') {
    const source = fs.readFileSync(join(__hooksDir, 'virtual', 'dns.mjs'), 'utf-8')
      .replaceAll('__HOOKS_SHARED_URL__', sharedUrl);
    return { format: 'module', shortCircuit: true, source };
  }
  return nextLoad(url, context);
}

2. CommonJS (Module.prototype.require)

Because older packages still use CommonJS require(), hooks.mjs patches Module.prototype.require in the main application thread:

const originalRequire = Module.prototype.require;

Module.prototype.require = function (id) {
  if (id === 'child_process' || id === 'node:child_process') {
    return wrapChildProcess(originalRequire.call(this, id));
  }
  if (id === 'dns' || id === 'node:dns') {
    return wrapDns(originalRequire.call(this, id));
  }
  return originalRequire.call(this, id);
};

This guarantees that both ESM import statements and CommonJS require() calls receive identical security enforcement.

3. Call-Stack Path Exclusions

Before triggering an alert or throwing an error, virtual hooks inspect the execution call stack:

An Error object is instantiated to capture the active call stack.

The calling file path is evaluated against glob patterns configured in exclusions.paths.

If the calling file is excluded (such as test suites or database seeders), the operation is permitted without raising an alert.

Getting Started

Core Architecture

Monitoring Channels

Configuration

Threat Model & Security

CLI Reference

Releases

Contributing

Runtime Module Hooks

Runtime Module Hooks

1. ES Modules (`module.register`)

2. CommonJS (`Module.prototype.require`)

3. Call-Stack Path Exclusions

​Runtime Module Hooks

​1. ES Modules (module.register)

​2. CommonJS (Module.prototype.require)

​3. Call-Stack Path Exclusions

Runtime Module Hooks

1. ES Modules (`module.register`)

2. CommonJS (`Module.prototype.require`)

3. Call-Stack Path Exclusions