aletheia-firewall 0.3.0 → 0.4.0

package/.helios-baseline

@@ -1 +1 @@
-800c13e8709801a5cd30d832a05d9e1fe0fd51780af348860c35a430d92957c4
+7f88b7011cdf41ed82ce047932b27fee86e36aca3cc010845acdcea0253c5e5b

package/README.md

@@ -20,6 +20,28 @@ For Bun:
 FW_ENABLE_DETECTION=1 BUN_PRELOAD=aletheia-firewall bun app.js
 ```
 
+## Coverage & Limitations
+
+Aletheia hooks `Module.prototype._compile`, Node's CommonJS compilation step. This means:
+
+| Load path | Covered |
+|---|---|
+| `require()` of `.js` / `.cjs` | ✅ |
+| `import` / `import()` (ESM, `.mjs`) | ❌ separate Node loader, not hooked |
+| `.json` requires | ❌ handled by Node core, bypasses `_compile` |
+| Native addons (`.node`) | ❌ not JS, not scanned |
+| Dependency npm lifecycle scripts (preinstall/postinstall) | ❌ run before the firewall loads |
+
+Aletheia is a **runtime enforcement layer**: it watches what a dependency does once it's
+already in your CommonJS require graph, after `npm install` has finished. It is not an
+install-time scanner and does not intercept package installation.
+
+Detection is signature + behavioral, not AST-based, so payloads can evade static matching
+through string-splitting, encoding, or indirection. Our adversarial corpus documents this
+honestly: **95/125 (76%) of malicious payloads caught, 30 known bypasses, 0 false positives**
+on the current corpus — run it yourself from the repository root with `npm run redteam`. Every bypass class is listed
+in [`red-team/README.md`](../../red-team/README.md).
+
 ## Environment Variables
 
 | Variable | Default | Description |
@@ -66,18 +88,18 @@ own key (`scripts/generate-policy-key.js`) and set `FW_POLICY_PUBKEY`.
 
 ## Performance
 
-The firewall's cost is a **one-time per-module compile scan** — the `Module._compile` hook runs once per file on first load, then a compilation cache short-circuits it. There is **zero overhead when `FW_ENABLE_DETECTION` is unset** (`index.js` returns immediately and installs no hook).
+The firewall's cost is a **one-time per-module compile scan** — the `Module._compile` hook runs once per file on first load, then a compilation cache short-circuits repeat compilations. There is **zero overhead when `FW_ENABLE_DETECTION` is unset** (`index.js` returns immediately and installs no hook).
 
-Measured on a 900-module cold load (methodology: `packages/fw-control/test/bench.js` in the monorepo), AMD EPYC, Node v22 (CI: 18, 20, 22), Linux x64:
+The repo maintains a 25% median compilation-overhead gate budget, but this is a regression threshold, not a published release guarantee. Current v0.3.0 evidence shows the runtime `Module._compile` interception path is the dominant steady-state cost; `Detector.scanModuleSync` is a secondary contributor in the verified 900-module workload.
 
-| Metric | Measured | Gate budget | Enforced? |
-|--------|----------|-------------|-----------|
-| Median module-compile overhead | ~17–21% (varies by host) | 25% | **Yes** |
-| P95 overhead | ~25–37% across hosts | 30% (reference) | No — informational |
+| Metric | Budget | Enforced? |
+|--------|--------|-----------|
+| Median module-compile overhead | 25% | **Yes** |
+| P95 overhead | 30% (informational only) | No |
 
-Environment: measured on two AMD EPYC Codespaces — 9V74 (80-core) and 7763 (64-core), Node v22. The median is host-dependent (7763 ~17%, 9V74 ~20–21%); after the v0.1.0 sub-512B scan-skip fix the measured range is ~17–21%.
+The gate is a **regression guard**, not a performance target. If the median exceeds 25%, the change needs review.
 
-The gate **enforces median only** (budget 25%). P95 (~25–37%) is informational and **not stable across hardware** — it reflects shared-CPU scheduler contention on multi-tenant Codespaces, not firewall algorithmic cost — so it is reported but never gated.
+For the v0.3.0 frozen baseline and diagnostic evidence, see `PERFORMANCE.md` and `results/benchmarks/steady-state-compile-attr-*.json`.
 
 To reproduce, run the 900-module gate from the GitHub repo: `npm run gate`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aletheia-firewall",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Zero-dependency runtime firewall that blocks malicious npm modules at require-time.",
   "main": "index.js",
   "license": "MIT",

package/src/behavior-tracker.js

@@ -2,6 +2,8 @@
 // Behavioral analyzer for sequence-based threat detection.
 // Tracks dangerous action sequences within a single module.
 
+const { AhoCorasick } = require('./aho-corasick');
+
 // Signal detection patterns for each behavioral category
 const SIGNAL_PATTERNS = {
   // Reads sensitive credential files (fs-based). process.env is tracked separately
@@ -155,6 +157,47 @@ function matchesAny(content, patterns) {
   return patterns.some(p => p.test(content));
 }
 
+// Literal substrings that are a superset of all SIGNAL_PATTERN regexes.
+// Used as a fast pre-screener: if none appear in content, all signal checks are
+// guaranteed false and the expensive scanSrc normalization + regex loop can be
+// skipped. A false positive (keyword present but regex doesn't match) is safe;
+// a false negative would miss a detection and is prevented by the superset property.
+const BEHAVIOR_PRESCREENER_KEYWORDS = [
+  // SENSITIVE_READ
+  'readfile', 'fs.open',
+  // ENV_READ
+  'process.env',
+  // SENSITIVE_PATH
+  '.env', 'credentials', '.ssh', 'id_rsa', '.netrc', '.aws', 'secret', 'passwd', 'shadow',
+  // SENSITIVE_CONFIG_PATH
+  '.kube', '.docker', 'login data',
+  // NPMRC_READ / NPMRC_TOKEN
+  '.npmrc', '_authtoken', '_auth', '_password', 'authtoken',
+  // HOST_OPTION
+  'host:',
+  // NETWORK_EGRESS
+  'http.request', 'https.request', 'http.get', 'https.get',
+  'fetch(', 'net.connect', 'net.createconnection', 'socket.connect',
+  'websocket', 'xmlhttprequest', 'tls.connect', 'dgram.createsocket',
+  'dns.resolve', 'sendbeacon',
+  // inline require("http"|"https"|"net"|"tls"|"dgram").method() forms
+  'require("http', "require('http", 'require("https', "require('https",
+  'require("net', "require('net", 'require("tls', "require('tls",
+  'require("dgram', "require('dgram", 'require("vm', "require('vm",
+  // DYNAMIC_CODE
+  'eval(', 'new function', 'function(', 'vm.runincontext', 'vm.runinnewcontext',
+  'vm.runinthiscontext', 'runinnewcontext', 'vm.script(', 'settimeout(', 'setinterval(', '(0,eval)',
+  // CODE_DECODE
+  'atob(', 'buffer.from',
+  // PROCESS_EXEC
+  'child_process', 'execsync(', 'spawnsync(', 'execfile(', 'execfilesync(', 'shellstring',
+  'process.binding(',
+  // DYNAMIC_REQUIRE (unambiguous forms; bare require(var) is checked separately)
+  'require.resolve(', 'module._load',
+];
+
+const BEHAVIOR_PRESCREENER_KEYWORDS_NO_WS = BEHAVIOR_PRESCREENER_KEYWORDS.map(kw => kw.replace(/\s+/g, ''));
+
 // A quoted absolute URL passed directly as the argument of an actual network-call site --
 // distinguishes theft (hardcodes the destination) from legit npm tooling (builds the URL
 // from config, e.g. `fetch(`${registry}/${name}`)`). Anchored to the call site itself (not
@@ -183,6 +226,10 @@ class BehaviorTracker {
     this.filePackage = new Map();
     // Accumulated violations for telemetry
     this.violations = [];
+    // Fast-path pre-screener: single Aho-Corasick over all signal literal substrings.
+    this._prescreener = new AhoCorasick(BEHAVIOR_PRESCREENER_KEYWORDS);
+    // Whitespace-normalized pre-screener catches spaced variants like `fetch (...)`.
+    this._prescreenerNoWs = new AhoCorasick(BEHAVIOR_PRESCREENER_KEYWORDS_NO_WS);
   }
 
   /**
@@ -193,6 +240,36 @@ class BehaviorTracker {
   analyzeModule(filename, content, packageKey) {
     if (!content) return [];
 
+    const contentNoWs = content.replace(/\s+/g, '');
+
+    // Fast-path: if no signal keyword is present in either the raw content or a
+    // whitespace-collapsed variant, all regex-based signal checks are guaranteed to be false
+    // (the pre-screener is a superset of all SIGNAL_PATTERN regexes). Skip the expensive
+    // scanSrc normalization chain and 60+ regex tests. DYNAMIC_REQUIRE is the one signal
+    // without an unambiguous literal keyword (require(var) vs require('literal')), so it is
+    // checked separately.
+    if (!this._prescreener.searchInsensitive(content) &&
+        !this._prescreenerNoWs.searchInsensitive(contentNoWs)) {
+      const dynamicRequire = matchesAny(content, SIGNAL_PATTERNS.DYNAMIC_REQUIRE);
+      const signals = {
+        sensitiveRead: false, sensitivePath: false, sensitiveConfigPath: false,
+        npmrcRead: false, npmrcToken: false, hostOption: false,
+        hardcodedEgress: false, hardcodedEgressNonRegistry: false,
+        envRead: false, networkEgress: false, dynamicCode: false,
+        codeDecode: false, processExec: false, dynamicRequire,
+      };
+      this.moduleSignals.set(filename, signals);
+      if (packageKey !== undefined && packageKey !== null) this.filePackage.set(filename, packageKey);
+      if (!dynamicRequire) return [];
+      const found = [{
+        rule: 'DYNAMIC_MODULE_LOAD',
+        severity: 'MEDIUM',
+        description: 'Module uses dynamic require() or module._load with a non-literal path',
+      }];
+      this.violations.push({ filename, violations: found, timestamp: Date.now() });
+      return found;
+    }
+
     // SENSITIVE_PATH / SENSITIVE_READ must only fire on genuine filesystem access, not on
     // import/require module specifiers (e.g. "@memberjunction/credentials") or URL paths
     // (e.g. "https://api.example.com/totpSecret"). Blank just the specifier STRING in place
@@ -452,4 +529,4 @@ class BehaviorTracker {
 
 // SIGNAL_PATTERNS is exported so downstream tooling can iterate the raw signal regexes for
 // evidence reconstruction (the registry's watch-changes.js). Keeps this engine a drop-in copy.
-module.exports = { BehaviorTracker, SIGNAL_PATTERNS };
+module.exports = { BehaviorTracker, SIGNAL_PATTERNS, BEHAVIOR_PRESCREENER_KEYWORDS };