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

# Subprocess Channel

> How envtrap monitors node:child_process to prevent credential leakage into subprocess environments.

# Subprocess Channel (`child_process`)

* **Default Mode**: `"warn"`
* **Target**: `node:child_process` API invocations across ESM and CommonJS.

The `child_process` channel monitors subprocess invocations to ensure that malicious dependencies or utility scripts do not pass sensitive environment variables to system binaries (`curl`, `wget`, `bash`, `python`).

***

## Intercepted APIs

`envtrap` wraps the following Node.js subprocess methods:

* `child_process.spawn` & `spawnSync`
* `child_process.exec` & `execSync`
* `child_process.execFile` & `execFileSync`
* `child_process.fork`

***

## Detection Logic

When an application invokes an intercepted method:

1. `envtrap` inspects the environment passed to the child process. If `options.env` is explicitly provided, it inspects that object. If `options.env` is undefined (the default in Node.js subprocesses), `envtrap` evaluates the calling process's `process.env` since the child process inherits it by default.
2. For each key in the inspected environment, it checks whether the key exists in the active secret registry and the assigned value matches the secret value.
3. If a match is found, an alert or block is triggered before the operating system process is spawned.
4. Asynchronous and synchronous method signatures—including `(error, stdout, stderr)` callback handlers on `child_process.exec` and `child_process.execFile`—are strictly preserved with standard error objects and exit status parity.

***

## Enforcement Modes

<Tabs>
  <Tab title="warn (Default)">
    Writes an alert to `stderr`, logs the incident in `.envtrap-report.json`, and allows the subprocess to execute with inherited options.
  </Tab>

  <Tab title="block">
    Throws a synchronous `Error` immediately before any OS fork occurs:

    ```text theme={null}
    Error: [envtrap] child_process block: env key "STRIPE_SECRET_KEY" passed to child process
    ```
  </Tab>

  <Tab title="off">
    Disables subprocess environment inspection.
  </Tab>
</Tabs>

***

## Configuration Example

```json envtrap.json theme={null}
{
  "channels": {
    "child_process": "block"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.