Quickstart Guide

This guide walks you through installing envtrap, running it against your application, understanding its output, and integrating it into your deployment workflow.

Prerequisites

Node.js: 18.0.0 or higher (ESM customization hooks require Node.js 18+).
Package Manager: npm, pnpm, or yarn.

Getting Started

Install envtrap

Install envtrap globally, locally as a dev dependency, or execute it on-demand via npx:

Global (Recommended)
pnpm
npm (Dev Dependency)
npx (No Install)

npm install -g envtrap

pnpm add -D envtrap

npm install --save-dev envtrap

npx envtrap run node app.js

Run your application with envtrap

Simply prefix your standard startup command with envtrap run:

envtrap run node app.js

envtrap run node server.js

envtrap run node dist/main.js

envtrap run npm run start

envtrap forwards all process arguments, environment variables, exit codes, and signals (SIGINT, SIGTERM) directly to and from your application.

Review the startup banner

When envtrap starts, it reads available secrets from process.env and your .env file, spins up the in-memory MITM proxy, and outputs a configuration overview to standard error:

  ℹ  [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 v3.0.0
     Monitoring: node app.js
     Channels: stdout/stderr · HTTPS MITM · child_process · DNS hooks

Simulate or observe an interception

If any dependency or script attempts to transmit credentials over an unapproved channel, envtrap immediately intercepts the operation and logs a structured alert box:

 🌐 SECRET LEAK DETECTED   2026-09-05T14: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

Notice that the actual secret value is never printed in plain text. It is automatically replaced with a non-reversible SHA-256 fingerprint prefix, protecting your credentials even if logs are ingested into public CI/CD pipelines or cloud dashboards.

Inspect the exit summary

When your application terminates, envtrap prints a grouped summary of all monitored events and writes an incident audit report to .envtrap-report.json:

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

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

Adding to `package.json`

To make envtrap a standard part of your development and production lifecycle, wrap your npm scripts in package.json:

package.json

{
  "scripts": {
    "start": "envtrap run node dist/main.js",
    "dev": "envtrap run node --watch src/index.js"
  }
}

Next Steps

Configuration Reference

Learn how to configure channel modes, exclude trusted domains, and set custom entropy levels.

CLI Reference

Explore all CLI flags including --env-file, --no-mitm, --verbose, and --log-file.

Getting Started

Core Architecture

Monitoring Channels

Configuration

Threat Model & Security

CLI Reference

Releases

Contributing

Quickstart

Quickstart Guide

Prerequisites

Getting Started

Adding to `package.json`

Next Steps

Configuration Reference

CLI Reference

​Quickstart Guide

​Prerequisites

​Getting Started

​Adding to package.json

​Next Steps

Configuration Reference

CLI Reference

Quickstart Guide

Prerequisites

Getting Started

Adding to `package.json`

Next Steps