Exclusions & Allowlisting

In production applications, certain outbound operations are legitimate — such as sending your Stripe API key to api.stripe.com or printing mock test tokens in unit test suites. envtrap provides two powerful exclusion mechanisms in envtrap.json:

Domain Allowlisting (exclusions.domains): Bypasses network proxy inspection for trusted hosts.
Path Glob Exclusions (exclusions.paths): Suppresses alerts from designated source files or directories.

1. Domain Exclusions (`exclusions.domains`)

Applies To: The network channel.
Mechanism: Exact hostname matching and automatic NO_PROXY inclusion.

Domains added to exclusions.domains are granted direct pass-through status:

HTTPS/HTTP requests to these hosts are not decrypted or scanned.
Hosts are automatically appended to the child process’s NO_PROXY environment variable, avoiding unnecessary proxy hops.

envtrap.json

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

Domain matching is based on exact hostname verification."api.stripe.com" will not allow "evil.api.stripe.com" or "api.stripe.com.attacker.com". Each unique subdomain must be explicitly enumerated in your configuration.

2. Path Glob Exclusions (`exclusions.paths`)

Applies To: stdout, stderr, child_process, and dns.
Mechanism: Call stack frame inspection and child-level pre-redaction.

When a leak occurs on a local channel, envtrap analyzes the originating call stack. If the calling source file matches any glob pattern in exclusions.paths, the alert is suppressed.

envtrap.json

{
  "exclusions": {
    "paths": [
      "test/**",
      "**/__tests__/**",
      "**/*.spec.ts",
      "**/*.test.js",
      "scripts/seed.ts"
    ]
  }
}

Glob Matching Syntax:

Pattern	Scope of Match	Example Match
`test/**`	Any file located within a `test/` directory at any hierarchy level	`test/auth.test.js`
`/__tests__/`	Any file inside any `__tests__` folder	`src/api/__tests__/user.spec.ts`
`*.test.js`	Any test file matching the suffix anywhere in the codebase	`src/client.test.js`
`/var/app/seed.js`	Exact absolute file path	`/var/app/seed.js`

Patterns that do not begin with / or ** are automatically prepended with **/ so they match files anywhere in your project tree.

Combined Production Configuration

Here is a recommended setup for an Express or Next.js application that integrates with external payment and AI APIs while running automated test suites:

envtrap.json

{
  "channels": {
    "stdout": "warn",
    "stderr": "warn",
    "network": "block",
    "child_process": "block",
    "dns": "block"
  },
  "exclusions": {
    "domains": [
      "api.stripe.com",
      "api.openai.com",
      "api.resend.com"
    ],
    "paths": [
      "test/**",
      "**/*.spec.ts"
    ]
  },
  "logFile": "logs/envtrap-audit.jsonl"
}

Getting Started

Core Architecture

Monitoring Channels

Configuration

Threat Model & Security

CLI Reference

Releases

Contributing

Exclusions & Whitelisting

Exclusions & Allowlisting

1. Domain Exclusions (`exclusions.domains`)

2. Path Glob Exclusions (`exclusions.paths`)

Glob Matching Syntax:

Combined Production Configuration

​Exclusions & Allowlisting

​1. Domain Exclusions (exclusions.domains)

​2. Path Glob Exclusions (exclusions.paths)

​Glob Matching Syntax:

​Combined Production Configuration

Exclusions & Allowlisting

1. Domain Exclusions (`exclusions.domains`)

2. Path Glob Exclusions (`exclusions.paths`)

Glob Matching Syntax:

Combined Production Configuration