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

{
  "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:

{
  "channels": {
    "stdout": "warn",
    "stderr": "warn",
    "network": "warn",
    "child_process": "warn",
    "dns": "warn"
  }
}

Example — disable a specific channel:

{ "channels": { "child_process": "off" } }

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.

---

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:

{
  "exclusions": {
    "domains": [
      "api.stripe.com",
      "api.openai.com",
      "api.anthropic.com",
      "o123456.ingest.sentry.io"
    ]
  }
}

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.

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:

{
  "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

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

---

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.

{
  "entropy": {
    "threshold": 4.0,
    "minLength": 16
  }
}

These settings also control the high-entropy DNS tunneling detection threshold inside hooks.mjs.

---

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.

{ "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.

{ "logFile": "logs/envtrap-events.jsonl" }

Each JSONL line has the following shape:

{"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:

envtrap check

Valid output:

✅ Configuration is valid.

Invalid output:

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