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

# envtrap.json Configuration

> Complete schema specification, default values, and validation rules for envtrap.json.

# `envtrap.json` Configuration Reference

Configure `envtrap` by placing an `envtrap.json` file in your **project root** (adjacent to `package.json`).

All configuration options are **optional**. When a field is omitted, `envtrap` applies safe, production-grade defaults automatically.

***

## Complete Schema & Defaults

```json envtrap.json theme={null}
{
  "channels": {
    "stdout":        "warn",
    "stderr":        "warn",
    "network":       "block",
    "child_process": "warn",
    "dns":           "block"
  },
  "exclusions": {
    "domains": [],
    "paths":   []
  },
  "entropy": {
    "threshold": 3.5,
    "minLength": 12
  },
  "quiet":   false,
  "logFile": null
}
```

***

## Schema Properties

### `channels`

* **Type**: `object`
* **Default**: See schema above

Controls the enforcement mode for each of the five runtime egress channels. Each channel accepts one of three valid modes:

* `"block"`: Prevent the leak. Network sockets are severed, DNS and child process calls throw errors, and stdout/stderr leaks kill the process with `SIGTERM`.
* `"warn"`: Log the alert box, redact the secret value with its SHA-256 fingerprint, and allow execution to continue.
* `"off"`: Completely disable monitoring for this channel.

| Channel Key | Default | Monitored Target |
| :- | :- | :- |
| `network` | `"block"` | Outbound HTTP and HTTPS traffic via local MITM TLS proxy |
| `dns` | `"block"` | `node:dns` and `dns.promises` resolution and lookups |
| `child_process` | `"warn"` | Subprocess invocations (`spawn`, `exec`, `fork`) with `options.env` |
| `stdout` | `"warn"` | Standard output stream writes from the child process |
| `stderr` | `"warn"` | Standard error stream writes from the child process |

***

### `exclusions`

* **Type**: `object`

Bypasses monitoring for trusted third-party endpoints or specific source files.

#### `exclusions.domains`

* **Type**: `string[]`
* **Default**: `[]`

A list of trusted domain names that are permitted to receive outbound traffic containing credentials. Connections to these domains bypass proxy inspection and are automatically appended to `NO_PROXY`.

```json theme={null}
{
  "exclusions": {
    "domains": [
      "api.stripe.com",
      "api.openai.com",
      "api.github.com"
    ]
  }
}
```

#### `exclusions.paths`

* **Type**: `string[]`
* **Default**: `[]`

A list of file glob patterns. Output originating from matching source files is pre-redacted inside the child process, suppressing alerts in the parent scanner. Ideal for test runners or seed scripts.

```json theme={null}
{
  "exclusions": {
    "paths": [
      "test/**",
      "**/*.spec.ts",
      "scripts/seed.ts"
    ]
  }
}
```

***

### `entropy`

* **Type**: `object`

Configures the statistical threshold for the candidate secret filter.

| Property | Type | Default | Description |
| :- | :- | :- | :- |
| `threshold` | `number` | `3.5` | Minimum Shannon entropy score (0 to 8 bits/character) required to track an environment variable. |
| `minLength` | `number` | `12` | Minimum string length required to be considered a secret candidate. |

***

### `quiet`

* **Type**: `boolean`
* **Default**: `false`

When set to `true`, suppresses the startup banner and immediate per-leak terminal alerts. The final exit summary and report files are still generated.

***

### `logFile`

* **Type**: `string | null`
* **Default**: `null`

A file path where `envtrap` streams structured JSONL events as leaks occur. Can be relative to CWD or an absolute path.

```json theme={null}
{
  "logFile": "logs/envtrap-audit.jsonl"
}
```

***

## Configuration Recipes

<Tabs>
  <Tab title="Production (Strict)">
    Blocks all network leaks, DNS tunneling, and subprocess leaks:

    ```json theme={null}
    {
      "channels": {
        "stdout": "warn",
        "stderr": "warn",
        "network": "block",
        "child_process": "block",
        "dns": "block"
      },
      "exclusions": {
        "domains": ["api.stripe.com", "api.openai.com"]
      },
      "logFile": "logs/envtrap.jsonl"
    }
    ```
  </Tab>

  <Tab title="Development (Permissive)">
    Logs all alerts and redacts output without blocking execution:

    ```json theme={null}
    {
      "channels": {
        "stdout": "warn",
        "stderr": "warn",
        "network": "warn",
        "child_process": "warn",
        "dns": "warn"
      },
      "exclusions": {
        "paths": ["test/**", "**/*.test.ts"]
      }
    }
    ```
  </Tab>

  <Tab title="CI / Headless Runner">
    Suppresses terminal noise and streams structured audit logs:

    ```json theme={null}
    {
      "channels": {
        "network": "block",
        "dns": "block"
      },
      "quiet": true,
      "logFile": ".envtrap-ci.jsonl"
    }
    ```
  </Tab>
</Tabs>

***

## Validating Your Configuration

Run `envtrap check` to validate your `envtrap.json` file against the schema before running your application:

```bash theme={null}
envtrap check
```

Output:

```text theme={null}
✅ Configuration is valid.
```


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