envtrap

Important

Repository Discontinued: This repository has been discontinued and migrated to the EnvTrap organization at https://github.com/EnvTrap. Component repositories (such as the core package and website) now reside there in separate dedicated repositories.

A zero-configuration, air-gapped runtime secret leak detector and egress firewall for Node.js.

envtrap sits at the lowest boundary of your Node.js process — hooking module loaders and socket interfaces — to intercept, block, and log accidental secret exposure before a single byte leaves your machine.

---

Interception Channels

envtrap intercepts leaks across five distinct runtime vectors:

• HTTPS/HTTP MITM Proxy (network channel): Routes outbound TCP connections through an ephemeral, in-memory loopback proxy. Intercepts request headers, URLs, and payloads, verifying them before forwarding. Ephemeral TLS certificates are generated on-the-fly and trusted by injecting a temporary Root CA into NODE_EXTRA_CA_CERTS.
• Standard Output Scanning (stdout / stderr channels): Hooks standard output streams to search for registered credentials. Matches are redacted using a secure SHA-256 fingerprint placeholder.
• Subprocess Environment Check (child_process channel): Hooks Node.js process creation modules (child_process.spawn, exec, fork, and their synchronous equivalents) at the binding layer to prevent sensitive credentials from being inherited by child processes.
• DNS Resolution Auditing (dns channel): Hooks the core node:dns module to detect secrets encoded directly inside hostname resolution queries.
• High-Entropy Label Detection: Uses Shannon entropy analysis on subdomain labels to automatically flag potential base64/hex DNS tunneling vectors.

---

Installation

# Global install
npm install -g envtrap

# Dev dependency
npm install --save-dev envtrap

# One-off, no install
npx envtrap run node app.js

---

Usage

Prefix your Node.js startup command with envtrap run:

envtrap run node app.js

# Express / Fastify
envtrap run node server.js

# NestJS
envtrap run node dist/main.js

# Next.js (server-side protection)
envtrap run npm run start

CLI Flags

# Custom .env file path
envtrap run --env-file .env.production node app.js

# Disable HTTPS MITM proxy (bypasses network interception)
envtrap run --no-mitm node app.js

# Verbose output (logs cert issuance and network handshake information)
envtrap run --verbose node app.js

# Quiet mode (suppress terminal alerts, prints exit summary only)
envtrap run --quiet node app.js

# Append JSONL events to a custom file
envtrap run --log-file logs/envtrap.jsonl node app.js

# Verify the syntax of envtrap.json
envtrap check

---

Configuration (envtrap.json)

You can customize rules by creating an envtrap.json file in your project root:

{
  "channels": {
    "stdout":        "warn",
    "stderr":        "warn",
    "network":       "block",
    "child_process": "warn",
    "dns":           "block"
  },
  "exclusions": {
    "domains": ["api.stripe.com", "api.openai.com"],
    "paths":   ["test/**", "**/__tests__/**"]
  },
  "entropy": {
    "threshold": 3.5,
    "minLength": 12
  },
  "quiet":   false,
  "logFile": null
}

Channel Modes

• block: Halts execution, closes the network stream, or interrupts the system command immediately when a secret leak is detected.
• warn: Emits a warning log detailing the leak event, redacts the matched content, and allows the operation to proceed.
• off: Disables the corresponding interception channel entirely.

Exclusions & Subdomain Bypasses

• domains: Bypasses network interception for specific target hosts. These domains are automatically appended to the environment's NO_PROXY parameters.
• paths: Glob patterns targeting source files. Detections originating from source code inside these paths are ignored.

---

Security & Implementation Details

• 100% Local Execution: Completely self-contained runtime with zero external telemetry or outbound API reporting.
• In-Memory Root CA: Ephemeral Root CA key material is generated entirely in RAM on application bootstrap. The private key never touches the disk and is wiped from memory upon process termination.