`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

envtrap.json

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

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

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

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

Configuration Recipes

Production (Strict)
Development (Permissive)
CI / Headless Runner

Blocks all network leaks, DNS tunneling, and subprocess leaks:

{
  "channels": {
    "stdout": "warn",
    "stderr": "warn",
    "network": "block",
    "child_process": "block",
    "dns": "block"
  },
  "exclusions": {
    "domains": ["api.stripe.com", "api.openai.com"]
  },
  "logFile": "logs/envtrap.jsonl"
}

Logs all alerts and redacts output without blocking execution:

{
  "channels": {
    "stdout": "warn",
    "stderr": "warn",
    "network": "warn",
    "child_process": "warn",
    "dns": "warn"
  },
  "exclusions": {
    "paths": ["test/**", "**/*.test.ts"]
  }
}

Suppresses terminal noise and streams structured audit logs:

{
  "channels": {
    "network": "block",
    "dns": "block"
  },
  "quiet": true,
  "logFile": ".envtrap-ci.jsonl"
}

Validating Your Configuration

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

envtrap check

Output:

✅ Configuration is valid.

Getting Started

Core Architecture

Monitoring Channels

Configuration

Threat Model & Security

CLI Reference

Releases

Contributing

envtrap.json Configuration

`envtrap.json` Configuration Reference

Complete Schema & Defaults

Schema Properties

`channels`

`exclusions`

`exclusions.domains`

`exclusions.paths`

`entropy`

`quiet`

`logFile`

Configuration Recipes

Validating Your Configuration

​envtrap.json Configuration Reference

​Complete Schema & Defaults

​Schema Properties

​channels

​exclusions

​exclusions.domains

​exclusions.paths

​entropy

​quiet

​logFile

​Configuration Recipes

​Validating Your Configuration

`envtrap.json` Configuration Reference

Complete Schema & Defaults

Schema Properties

`channels`

`exclusions`

`exclusions.domains`

`exclusions.paths`

`entropy`

`quiet`

`logFile`

Configuration Recipes

Validating Your Configuration