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

# envtrap.json Reference

> Complete reference for every field in the envtrap.json configuration file — exact types, defaults, and validation rules.

## Overview

Create an `envtrap.json` file in your **project root** (next to `package.json`) to customise envtrap's behaviour. All fields are **optional** — envtrap ships with safe, production-ready defaults.

envtrap validates this file on every `envtrap run` and prints warnings for any invalid fields. You can also validate it manually with `envtrap check`.

***

## Full Schema with Defaults

```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
}
```

***

## `channels`

**Type**: `object`\
**Default**: see above

Sets the enforcement mode for each interception channel independently. Each key accepts one of three string values:

| Mode      | Meaning                                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"block"` | Detected leak is **prevented**. For network: connection is terminated. For dns/child\_process: a synchronous Error is thrown. For stdout/stderr: child process is killed via SIGTERM. |
| `"warn"`  | Detected leak is **logged** and secret is **redacted** in output, but execution continues.                                                                                            |
| `"off"`   | Channel monitoring is **completely disabled** — no scanning, no alerts.                                                                                                               |

### Channel Keys

| Key             | Default   | What it intercepts                                                                                  |
| --------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `stdout`        | `"warn"`  | Every write to `process.stdout` from the child process                                              |
| `stderr`        | `"warn"`  | Every write to `process.stderr` from the child process                                              |
| `network`       | `"block"` | All outbound HTTP and HTTPS connections via the MITM proxy                                          |
| `child_process` | `"warn"`  | `spawn`, `exec`, `fork`, `execFile`, `spawnSync`, `execSync`, `execFileSync` — checks `options.env` |
| `dns`           | `"block"` | All `node:dns` resolution calls — `lookup`, `resolve*`, and `dns.promises.*`                        |

**Example — set all channels to warn-only for development:**

```json theme={null}
{
  "channels": {
    "stdout": "warn",
    "stderr": "warn",
    "network": "warn",
    "child_process": "warn",
    "dns": "warn"
  }
}
```

**Example — disable a specific channel:**

```json theme={null}
{ "channels": { "child_process": "off" } }
```

<Warning>
  Setting a channel to `"off"` fully disables monitoring for that attack surface. Only use this if you are certain no leaks are possible through that channel.
</Warning>

***

## `exclusions`

**Type**: `object`

### `exclusions.domains`

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

A list of **fully-qualified domain names** that are allowed to bypass network scanning entirely. Requests to these domains are forwarded directly through the MITM proxy without inspecting headers, body, or URL.

Use this for your own known API endpoints where you intentionally send credentials:

```json theme={null}
{
  "exclusions": {
    "domains": [
      "api.stripe.com",
      "api.openai.com",
      "api.anthropic.com",
      "o123456.ingest.sentry.io"
    ]
  }
}
```

<Warning>
  Only add domains you explicitly own or fully trust. envtrap matches the exact hostname — subdomains like `evil.api.stripe.com` are **not** covered by adding `api.stripe.com`.
</Warning>

### `exclusions.paths`

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

A list of **glob patterns** for source file paths. If an intercepted operation (dns lookup, subprocess spawn, stdout write) originates from a file that matches one of these patterns — resolved via call stack inspection — the detection is suppressed.

Common use case: suppress alerts from your own test files that intentionally use mock secrets:

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

**Glob matching rules**:

* `*` matches any sequence of characters except `/`
* `**` matches any sequence of characters including `/`
* Patterns without a leading `/` or `**/` are automatically prefixed with `**/` to match anywhere in the path

<Note>
  Path exclusions apply to `stdout`, `stderr`, `child_process`, and `dns` channels. They do **not** apply to the `network` channel (the MITM proxy has no access to call stack information).
</Note>

***

## `entropy`

**Type**: `object`

Controls the Shannon entropy threshold used to screen `process.env` and `.env` values as secret candidates at startup.

### `entropy.threshold`

**Type**: `number`\
**Default**: `3.5`\
**Range**: 0 to 8

Minimum Shannon entropy score a string must have to be registered as an active secret. Higher values are stricter (fewer false positives, might miss low-entropy secrets).

### `entropy.minLength`

**Type**: `number`\
**Default**: `12`

Minimum character length a value must have before entropy is evaluated. Values shorter than this are always dropped, regardless of entropy score.

```json theme={null}
{
  "entropy": {
    "threshold": 4.0,
    "minLength": 16
  }
}
```

<Note>
  These settings also control the high-entropy DNS tunneling detection threshold inside `hooks.mjs`.
</Note>

***

## `quiet`

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

When `true`, suppresses all real-time output from envtrap:

* No startup banner
* No per-leak alert blocks
* No `warn()` / `info()` lines

Only the **run summary** (printed after child exits) and **`.envtrap-report.json`** are still produced.

Can also be set via the `--quiet` CLI flag.

```json theme={null}
{ "quiet": true }
```

***

## `logFile`

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

Path (relative to the current working directory, or absolute) to a file where envtrap appends **structured JSONL events** as each leak is detected — one JSON object per line.

The log directory is created automatically if it does not exist.

Can also be set via the `--log-file <path>` CLI flag.

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

Each JSONL line has the following shape:

```json theme={null}
{"secretName":"STRIPE_SECRET_KEY","source":"env","channel":"network","context":"...","sha256":"baf2ae56...","timestamp":1781335024545}
```

***

## Validation

envtrap validates `envtrap.json` on every startup and prints warnings for any issues without crashing. Run `envtrap check` to validate explicitly:

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

**Valid output:**

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

**Invalid output:**

```text theme={null}
Configuration Validation Failed:
  - [$.channels.network] Invalid mode "fast". Valid modes: block, warn, off
  - [$.entropy.threshold] Must be a number (e.g. 3.5)
```