Skip to main content

​
Secret Detection & Entropy Engine

envtrap detects secrets in a two-stage lifecycle:
  1. Startup Discovery: Reads and evaluates secret candidates from process.env and .env files.
  2. Runtime Matching: Performs ultra-fast exact substring matching on live egress buffers without heavy regex runtime overhead.

​
Stage 1 — Secret Candidate Discovery

When envtrap run starts, it initializes an in-memory secret registry by merging two distinct sources:

process.env (Active Shell)

Evaluates every environment variable in the current shell. A built-in blocklist filters out non-sensitive system environment variables (PATH, HOME, USER, SHELL, PWD, LANG, TERM, NODE_ENV, NODE_OPTIONS, XDG_*, etc.).

File Secrets (.env)

Parses .env (or custom paths provided via --env-file). In v3.1, secrets explicitly declared in .env files are strictly retained and protected even if their variable name coincides with generic environment names, ensuring targeted secrets are never discarded.

​
Stage 2 — The Candidate Evaluation Gate

Every string value from the environment must pass through the candidate filter before being added to the active watch list:
1

Length Threshold Check

Strings with fewer than minLength characters (default: 12) are discarded immediately. This ensures short non-secret variables (e.g. PORT=3000, DEBUG=true, ENV=prod) never trigger false alerts.
2

Deterministic Regex Pattern Matching

If the string matches any known vendor format (Stripe, AWS, GitHub, Slack, SendGrid, or Bearer tokens), it is instantly registered as a secret, completely bypassing the entropy calculation.
3

Shannon Entropy Analysis

If the string does not match a known prefix, envtrap computes its Shannon entropy. If the score is greater than or equal to entropy.threshold (default: 3.5 bits/char), it is registered as an active secret candidate.

​
Built-In Deterministic Patterns

These high-priority patterns always match, regardless of entropy score:

​
Shannon Entropy Calculation

Shannon entropy measures the uncertainty and statistical randomness of the characters in a string: H=−∑i=1npilog⁡2(pi)H = -\sum_{i=1}^{n} p_i \log_2(p_i) Where pip_i is the frequency probability of each unique character in the string. The higher the randomness and character diversity, the higher the score (0 to 8 bits/character).
You can tune the entropy gate in envtrap.json. If your project uses many semi-random config values that cause false positives, raise entropy.threshold to 4.0 or 4.2.

​
High-Performance Runtime Scanning

During application execution, every intercepted HTTP payload, terminal output chunk, DNS query, and subprocess environment is scanned for exact substring matches of the active secrets list:
At runtime, envtrap does not evaluate expensive regular expressions on streaming buffers. Instead, it performs direct substring searches against the registered secret values. This ensures near-zero latency impact on high-throughput Node.js servers.
To protect the Node.js event loop from memory exhaustion and denial-of-service, content buffers larger than 1 MB are clamped. Only the first 1 MB of any single payload is scanned.
To prevent runaway alert storms in high-concurrency loops, duplicate detections of the same secret on the same channel within a 1.5-second TTL window are suppressed. Only the initial occurrence triggers an alert and enters the report.