Quickstart

Get envtrap v2.1 protecting your Node.js app in under 60 seconds.

Prerequisites

• Node.js 18.0.0 or later (ESM customization hooks require Node 18+)
• npm or pnpm

Step 1 — Install

Install envtrap globally:

npm install -g envtrap

Or use via npx without installing:

npx envtrap run node app.js

Or install as a dev dependency:

npm install --save-dev envtrap

Step 2 — Run your app through envtrap

Prefix your existing start command with envtrap run:

# Before
node app.js

# After — fully monitored
envtrap run node app.js

That’s it. envtrap now:

• Starts a native-RSA in-memory MITM TLS proxy and routes all outbound HTTP/HTTPS through it
• Automatically sets NO_PROXY for loopback addresses so local Redis, Docker, and sidecar services are never proxied
• Scans stdout and stderr streams for secrets in real time
• Intercepts all child_process spawns to check if secrets are passed via options.env
• Intercepts all DNS lookups for exact secret matches and high-entropy subdomain patterns
• Wraps process.env to detect and broadcast runtime-rotated credentials to the ESM loader thread

Step 3 — Read the startup output

On every run, envtrap prints a startup banner and configuration summary to stderr:

  ℹ  [envtrap] Configuration loaded: envtrap.json
  ℹ  [envtrap] Active monitoring channels:
  ℹ  [envtrap]   - stdout: [WARN]
  ℹ  [envtrap]   - stderr: [WARN]
  ℹ  [envtrap]   - network: [BLOCK]
  ℹ  [envtrap]   - child_process: [WARN]
  ℹ  [envtrap]   - dns: [BLOCK]

 ⚠  envtrap v2.1.0
    Monitoring: node app.js
    Channels: stdout/stderr · HTTPS MITM · child_process · ESM hooks

When a leak is detected:

 🌐 SECRET LEAK DETECTED   2026-06-29T14:05:32.203Z
────────────────────────────────────────────────────────────
  Secret:  STRIPE_SECRET_KEY  (source: env)
  Value:   [SHA256:56018fa55485...]
  Channel: 🌐  NETWORK
  Context:
    Outbound HTTPS Request Audited:
      Destination Host: attacker.com
      Request Line:     POST /collect
      Headers:
        Authorization: Bearer [REDACTED: SHA256:56018fa5]
────────────────────────────────────────────────────────────
  ⚠  [envtrap] Network leak blocked: closing connection to attacker.com

After your app exits, envtrap prints a summary:

════════════════════════════════════════════════════════════
  envtrap — Run Summary
────────────────────────────────────────────────────────────
  🚨  1 leak event(s) detected!

  🌐  NETWORK: 1 leak(s)
       → STRIPE_SECRET_KEY
════════════════════════════════════════════════════════════

Step 4 — (Optional) Create a config file

Create envtrap.json in your project root for fine-grained control:

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

Domains listed in exclusions.domains are automatically added to NO_PROXY so they also bypass the MITM proxy without any extra configuration.

Validate your config:

envtrap check

Use "warn" on all channels during development to observe traffic patterns. Switch network and dns to "block" before deploying to production.

Step 5 — Add to package.json scripts

{
  "scripts": {
    "start": "envtrap run node app.js",
    "dev":   "envtrap run node --watch app.js"
  }
}

What Happens on Detection?

Channel	"warn" mode	"block" mode
network	Leak logged, request forwarded	Leak logged, connection terminated (socket destroy)
stdout	Secret redacted in output, child continues	Child process killed via SIGTERM
stderr	Secret redacted in output, child continues	Child process killed via SIGTERM
child_process	Leak logged via stderr, spawn proceeds	Synchronous Error thrown, no OS fork
dns	Leak logged, lookup proceeds	Synchronous Error thrown, no DNS packet sent

Framework Compatibility

envtrap hooks Node.js core modules, not your application layer — so it works with any framework:

Framework	Command
Express / Fastify	envtrap run node server.js
NestJS	envtrap run node dist/main.js
Next.js (server)	envtrap run npm run start
Bare Node.js	envtrap run node script.js

Next.js and other frameworks that compile or bundle client-side code are covered only for server-side execution. Browser runtime code is not in scope.

Next Steps

How It Works

Deep-dive into MITM proxy, ESM hooks, and CJS patching.

Configuration

Full reference for every envtrap.json field.

Attack Surfaces

Understand the five channels envtrap monitors.

CLI Reference

All CLI commands and flags.