aletheia-firewall 0.3.0

package/src/detector.js

@@ -0,0 +1,245 @@
+// packages/fw-agent/src/detector.js
+const { AhoCorasick } = require('./aho-corasick');
+const { BehaviorTracker } = require('./behavior-tracker');
+
+// Extended signature set covers crypto-miners, dynamic code execution, network abuse,
+// and supply-chain worm patterns (postinstall fetchers, credential harvesters).
+// High-confidence malicious signatures — trigger QUARANTINE/BLOCK on match.
+const BLOCK_SIGNATURES = [
+  '/dev/tcp/',
+  // Reverse-shell redirect idiom (F-29): bare 'bash -i' / 'sh -i' also match ordinary
+  // interactive-shell invocations of unrelated tools (push -i, fish -i, wash -i, ...).
+  // Real reverse shells redirect stdio via '>&' — require that too.
+  'bash -i >&',
+  'sh -i >&',
+  // Crypto-miner pool identifiers. F-29: bare 'stratum' matches the mining-protocol word
+  // wherever it occurs in English prose (e.g. dictionary/word-list packages containing
+  // "stratum", "substratum", "stratus"), so match the pool-URL scheme instead — that's
+  // what real miner configs actually contain.
+  'stratum+tcp',
+  'stratum://',
+  'pool.hashvault',
+  'coin-hive',
+  'xmr-stak',
+  'nicehash',
+  'coinhive',
+  'cryptonight',
+  // Additional browser/pool miner brands with no stratum literal (red-team group B). These
+  // are distinctive product names that do not occur in ordinary prose or legitimate code.
+  'coinimp',
+  'jsecoin',
+  'webminepool',
+  'deepminer',
+  // Supply-chain worm indicators
+  '//pastebin',
+  '//paste.ee',
+  '| bash',
+];
+
+// Regex-tier block signatures for idioms that must be anchored beyond a literal substring.
+// A bare '| sh' literal in the Aho-Corasick set would false-match '| shorten', '| sha256sum',
+// '| ssh', etc.; the \b after the shell name prevents that. Covers the sh/dash/zsh stagers the
+// literal '| bash' above misses (revsh-wget-pipe-sh, sc-preinstall-curl-sh): piping a
+// downloaded payload straight into a shell is a high-confidence stager.
+const BLOCK_REGEXES = [
+  // Require whitespace after the pipe (`| sh`, not `|sh`): a `|word|word|` token list — e.g.
+  // he.js's HTML-entity table `|dArr|dash|Sqrt|` — otherwise matches `|dash` as `| da + sh`.
+  // All real stagers in the corpus (`curl … | sh`, `wget … | sh`) space the pipe. `|sh` without
+  // a space is a documented residual gap (see THREAT-COVERAGE.md).
+  { re: /\|\s+(?:ba|da|z)?sh\b/i, type: 'dynamic-code-exec', severity: 'HIGH', label: 'pipe-to-shell-stager' },
+  // Reverse-shell tooling beyond /dev/tcp (red-team group E). Each is anchored to the exact
+  // exploit idiom (a flag, a scheme, or an API path) so it cannot match ordinary prose or
+  // legitimate command strings — none of these occur in benign npm module source.
+  { re: /\bnc\s+-e\b/i,                          type: 'reverse-shell', severity: 'HIGH', label: 'netcat-exec' },
+  { re: /\bncat\s+(?:--exec|-e)\b/i,             type: 'reverse-shell', severity: 'HIGH', label: 'ncat-exec' },
+  { re: /\bsocat\b[^\n]{0,120}EXEC:/i,           type: 'reverse-shell', severity: 'HIGH', label: 'socat-exec' },
+  { re: /\bmkfifo\b[^\n]{0,120}\bnc\b/i,         type: 'reverse-shell', severity: 'HIGH', label: 'mkfifo-backpipe' },
+  { re: /\bfsockopen\s*\(/i,                      type: 'reverse-shell', severity: 'HIGH', label: 'php-fsockopen' },
+  { re: /Net\s*\.\s*Sockets\s*\.\s*TCPClient/i,  type: 'reverse-shell', severity: 'HIGH', label: 'powershell-tcpclient' },
+  { re: /\bruby\s+-r\s*socket\b/i,               type: 'reverse-shell', severity: 'HIGH', label: 'ruby-socket' },
+  { re: /\blua\s+-e\b[^\n]{0,120}os\s*\.\s*execute/i, type: 'reverse-shell', severity: 'HIGH', label: 'lua-socket' },
+];
+
+// Crypto-miner signal hints — any BLOCK_SIGNATURES hit containing one of these is labeled a
+// crypto-miner (CRITICAL) rather than the generic dynamic-code-exec (HIGH). Previously only
+// stratum/pool/nicehash/cryptonight were treated as crypto, so coinhive/xmr-stak/coin-hive and
+// the brands above were mislabeled dynamic-code-exec. Cosmetic (both still block) but correct.
+const CRYPTO_SIGNAL_HINTS = ['stratum', 'pool', 'nicehash', 'cryptonight', 'coinhive', 'coin-hive', 'xmr-stak', 'coinimp', 'jsecoin', 'webminepool', 'deepminer'];
+
+// Indicative patterns common in legitimate code — emit WARN/OBSERVE only, never block.
+// Also includes patterns (exec, eval) that are caught by the behavioral DYNAMIC_CODE_EXEC_CHAIN
+// rule when used dangerously — so static-only matches on these produce WARN, not hard block.
+const WARN_SIGNATURES = [
+  'buffer.from',
+  'atob(',
+  'btoa(',
+  'https.request',
+  'http.request',
+  'net.createconnection',
+  'socket.connect',
+  // Broad exec/eval literals — moved from BLOCK (F-20): appear in legitimate build tools
+  // and test frameworks. Behavioral DYNAMIC_CODE_EXEC_CHAIN still hard-blocks the
+  // dangerous eval+exec combination.
+  'eval(',
+  'child_process.exec',
+  'execsync',
+  // Legitimate capabilities that false-positive on lodash/axios/express — warn, don't block.
+  'new function',
+  'process.binding',
+  // Legitimate capabilities in bundlers/process libs (esbuild, execa, cross-spawn, ws, undici) — F-26
+  'child_process.spawn',
+  'spawnsync',
+  'vm.runinnewcontext',
+  'vm.runinthiscontext',
+  // Bare words that also match prose/comments — F-26
+  'curl ',
+  'wget ',
+];
+
+class Detector {
+  constructor(/** @reserved - future policy integration */ policyEngine) {
+    this.policyEngine = policyEngine;
+    this.blockMatcher = new AhoCorasick(BLOCK_SIGNATURES);
+    this.warnMatcher = new AhoCorasick(WARN_SIGNATURES);
+    this.behaviorTracker = new BehaviorTracker();
+
+    this.stats = {
+      calls: 0,
+      automatonScans: 0,
+      behaviorViolations: 0,
+      warnOnlyDetections: 0,
+    };
+  }
+
+  async scanModule(packageName, moduleContent) {
+    return this.scanModuleSync(packageName, moduleContent);
+  }
+
+  /**
+   * Synchronous O(N) compilation screening combining signature matching and behavioral analysis.
+   */
+  scanModuleSync(packageName, moduleContent, filename, packageKey) {
+    this.stats.calls++;
+
+    if (!moduleContent || typeof moduleContent !== 'string') {
+      return { action: 'OBSERVE', detections: [], packageName, scanTime: Date.now() };
+    }
+
+    // Full-content scan: Aho-Corasick is O(N) so scanning the entire module is safe.
+    const searchContent = moduleContent;
+
+    this.stats.automatonScans++;
+    const detections = [];
+
+    // BLOCK-tier: high-confidence malicious patterns — always quarantine on match
+    const blockMatch = this.blockMatcher.searchInsensitive(searchContent);
+    if (blockMatch) {
+      const isCrypto = CRYPTO_SIGNAL_HINTS.some(h => blockMatch.includes(h));
+      detections.push({
+        type: isCrypto ? 'crypto-miner' : 'dynamic-code-exec',
+        severity: isCrypto ? 'CRITICAL' : 'HIGH',
+        matched: blockMatch,
+        timestamp: Date.now(),
+      });
+    }
+
+    // Regex-tier block signatures (anchored idioms that literals can't express safely).
+    for (const { re, type, severity, label } of BLOCK_REGEXES) {
+      if (re.test(searchContent)) {
+        detections.push({ type, severity, matched: label, timestamp: Date.now() });
+      }
+    }
+
+    // WARN-tier: common in benign code — log for visibility but never block on these alone
+    const warnMatch = this.warnMatcher.searchInsensitive(searchContent);
+    if (warnMatch) {
+      this.stats.warnOnlyDetections++;
+      detections.push({
+        type: 'indicative-pattern',
+        severity: 'WARN',
+        matched: warnMatch,
+        timestamp: Date.now(),
+        warnOnly: true,
+      });
+    }
+
+    // Behavioral sequence analysis on full content (skipped when FW_ENABLE_BEHAVIORAL=0)
+    const behaviorEnabled = process.env.FW_ENABLE_BEHAVIORAL !== '0';
+    const behaviorViolations = behaviorEnabled
+      ? this.behaviorTracker.analyzeModule(filename || packageName, moduleContent, packageKey)
+      : [];
+
+    // Cross-file correlation, scoped to this file's package. OPT-IN (FW_ENABLE_CROSSFILE=1,
+    // default OFF): soak validation showed it false-positives on large legitimate packages that
+    // legitimately split capabilities across files — mongodb reads AWS credentials and hits the
+    // instance-metadata endpoint (indistinguishable from exfil), babel/knex generate code in one
+    // file and spawn processes in another. Static co-occurrence cannot separate these from a real
+    // split attack; that needs Phase 3 taint analysis. Left available for curated dependency sets
+    // and mirrored by the registry batch scanner's finalizePackage() (which applies human review).
+    const crossFileEnabled = behaviorEnabled && process.env.FW_ENABLE_CROSSFILE === '1';
+    if (crossFileEnabled && packageKey !== undefined && packageKey !== null) {
+      for (const v of this.behaviorTracker.analyzePackage(packageKey)) {
+        behaviorViolations.push(v);
+      }
+    }
+    if (behaviorViolations.length > 0) {
+      this.stats.behaviorViolations++;
+      for (const v of behaviorViolations) {
+        // CRITICAL/HIGH behavioral violations are block-tier — escalate to quarantine
+        if (v.severity === 'CRITICAL' || v.severity === 'HIGH') {
+          detections.push({
+            type: 'behavioral',
+            severity: v.severity,
+            rule: v.rule,
+            description: v.description,
+            timestamp: Date.now(),
+          });
+        } else {
+          // WARN/MEDIUM violations are surfaced for logging and telemetry but never trigger QUARANTINE
+          detections.push({
+            type: 'behavioral',
+            severity: v.severity,
+            rule: v.rule,
+            description: v.description,
+            timestamp: Date.now(),
+            warnOnly: true,
+          });
+        }
+      }
+    }
+
+    // Only escalate to QUARANTINE if at least one non-WARN detection exists
+    const hasBlockDetection = detections.some(d => !d.warnOnly);
+    const action = hasBlockDetection ? 'QUARANTINE' : 'OBSERVE';
+    return { action, detections, packageName, scanTime: Date.now(), behaviorViolations };
+  }
+
+  /**
+   * Batch cross-file finalizer. Call once after scanModuleSync() has run over every file in a
+   * package (with reset() between packages). Used by the registry's whole-package scanner
+   * (scan-registry.js / watch-changes.js); the runtime firewall does not need it because it runs
+   * scoped cross-file inline in scanModuleSync(). With no packageKey, analyzePackage() correlates
+   * the whole moduleSignals map — which, given the caller resets per package, is exactly one
+   * package's files.
+   */
+  finalizePackage() {
+    const violations = this.behaviorTracker.analyzePackage();
+    if (violations.length > 0) {
+      this.stats.behaviorViolations++;
+    }
+    return violations.map(v => ({
+      type: 'behavioral',
+      severity: v.severity,
+      rule: v.rule,
+      description: v.description,
+      files: v.files,
+      timestamp: Date.now(),
+    }));
+  }
+
+  static isSuspicious(content) {
+    return content && typeof content === 'string' && content.length > 0;
+  }
+}
+
+module.exports = { Detector };

package/src/policy-watcher.js

@@ -0,0 +1,233 @@
+// packages/fw-agent/src/policy-watcher.js
+// Continuous policy integrity verification using Ed25519 asymmetric signatures.
+//
+// policy.signed.json format:
+//   { "version": 1, "rules": {...}, "signedAt": "ISO-8601", "signature": "base64url" }
+//
+// The signature covers the canonical JSON of { version, rules (keys sorted), signedAt }.
+// An invalid or missing signature immediately triggers emergency lockdown.
+// A valid signature with changed rules triggers hot-reload via onValidChange().
+//
+// To sign a policy file:
+//   node scripts/sign-policy.js scripts/dev-private-key.pem rules.json policy.signed.json
+//
+// To generate a production key pair:
+//   node scripts/generate-policy-key.js
+
+const fs = require('fs');
+const crypto = require('crypto');
+
+const WATCH_INTERVAL_MS = 60_000;
+
+// ── Dev/CI public key ─────────────────────────────────────────────────────────
+// Generated with: node scripts/generate-policy-key.js
+// PRODUCTION: replace with your own key and regenerate .helios-baseline.
+// The private key is in scripts/dev-private-key.pem — DO NOT deploy that file.
+const DEV_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEANejKx1KxfXVk5B0UzI2Cp3XO9hmy6nIXTAhsW0bhlFo=
+-----END PUBLIC KEY-----`;
+
+// Allow the public key to be overridden via environment variable for production deployments.
+// FW_POLICY_PUBKEY must be a PEM-encoded Ed25519 SPKI public key.
+const PUBLIC_KEY_PEM = process.env.FW_POLICY_PUBKEY || DEV_PUBLIC_KEY_PEM;
+
+// F-02a: true when we're verifying with the bundled dev key (fallback, or explicitly set).
+// The matching private key (scripts/dev-private-key.pem) is committed to the public repo,
+// so any policy file signed with it is trivially forgeable.
+// Fail loud in start() unless explicitly opted in via FW_ALLOW_DEV_POLICY_KEY=1.
+const USING_DEV_POLICY_KEY = PUBLIC_KEY_PEM.trim() === DEV_PUBLIC_KEY_PEM.trim();
+
+/**
+ * Build the canonical signed payload buffer from a policy object.
+ * Keys in rules are sorted alphabetically so the byte sequence is deterministic.
+ */
+function canonicalPayload(version, rules, signedAt) {
+  const sorted = {};
+  for (const k of Object.keys(rules).sort()) sorted[k] = rules[k];
+  return Buffer.from(JSON.stringify({ version, rules: sorted, signedAt }));
+}
+
+/**
+ * F-33: production dev-key guard that does NOT depend on a policy file being present.
+ *
+ * The in-`start()` guard below only fires when a policy.signed.json exists (start() returns
+ * early otherwise), so a production deploy running the bundled dev key with no policy file on
+ * disk got zero signal — even though a policy file could be dropped in later and hot-loaded,
+ * and even though shipping the public dev key at all in production is a misconfiguration worth
+ * failing loud on. Call this from agent startup, before the watcher, so the check runs
+ * regardless of policy-file presence.
+ *
+ * Refuses to start (process.exit(1)) when running in production against the bundled dev key
+ * without an explicit acknowledgement. Local/dev/CI is unaffected: NODE_ENV is not 'production'
+ * there, and operators can still opt in with FW_ALLOW_DEV_POLICY_KEY=1.
+ *
+ * @param {object} [env]  - injectable for tests; defaults to process.env
+ * @param {function} [exit] - injectable for tests; defaults to process.exit
+ * @returns {boolean} true if a refusal was triggered (tests), false otherwise
+ */
+function assertProductionKeyConfig(env = process.env, exit = process.exit) {
+  if (env.NODE_ENV === 'production' && USING_DEV_POLICY_KEY && env.FW_ALLOW_DEV_POLICY_KEY !== '1') {
+    console.error(
+      '[CRITICAL] Running in production (NODE_ENV=production) with the bundled development ' +
+      'policy key. The matching private key is public, so any attacker can forge a policy ' +
+      'signature. Set FW_POLICY_PUBKEY to your production public key. Refusing to start.'
+    );
+    exit(1);
+    return true;
+  }
+  return false;
+}
+
+class PolicyWatcher {
+  /**
+   * @param {string} policyPath   - Absolute path to policy.signed.json
+   * @param {object} callbacks    - { onTamperDetected(), onValidChange(rules) }
+   * @param {object} [options]    - { intervalMs }
+   */
+  constructor(policyPath, callbacks, options = {}) {
+    this.policyPath = policyPath;
+    this.onTamperDetected = (callbacks && callbacks.onTamperDetected) || (() => {});
+    this.onValidChange = (callbacks && callbacks.onValidChange) || (() => {});
+    this.locked = false;
+    this.timer = null;
+    this._intervalMs = (options && options.intervalMs) || WATCH_INTERVAL_MS;
+    this._lastRulesHash = null;
+  }
+
+  /**
+   * Attempt to read, parse, and cryptographically verify the policy file.
+   * Returns { version, rules, signedAt } on success, or null on any failure.
+   * Fail-closed: unsigned, malformed, or tampered policies return null.
+   */
+  _loadAndVerify() {
+    let content;
+    try {
+      content = fs.readFileSync(this.policyPath, 'utf8');
+    } catch (e) {
+      console.error('[PolicyWatcher] Cannot read policy file:', e.message);
+      return null;
+    }
+
+    let policy;
+    try {
+      policy = JSON.parse(content);
+    } catch (e) {
+      console.error('[PolicyWatcher] Policy file is not valid JSON:', e.message);
+      return null;
+    }
+
+    const { version, rules, signedAt, signature } = policy;
+
+    if (version !== 1 || !rules || typeof rules !== 'object' || !signedAt || !signature) {
+      console.error('[PolicyWatcher] Policy file is missing required fields (version, rules, signedAt, signature).');
+      return null;
+    }
+
+    const payload = canonicalPayload(version, rules, signedAt);
+    let sigBuffer;
+    try {
+      sigBuffer = Buffer.from(signature, 'base64url');
+    } catch (e) {
+      console.error('[PolicyWatcher] Policy signature is not valid base64url.');
+      return null;
+    }
+
+    let valid = false;
+    try {
+      valid = crypto.verify(null, payload, { key: PUBLIC_KEY_PEM, format: 'pem', type: 'spki' }, sigBuffer);
+    } catch (e) {
+      console.error('[PolicyWatcher] Signature verification error:', e.message);
+      return null;
+    }
+
+    if (!valid) {
+      console.error('[PolicyWatcher] Policy signature is INVALID.');
+      return null;
+    }
+
+    return { version, rules, signedAt };
+  }
+
+  /**
+   * Verify the policy file cryptographically.
+   * Returns true if valid, false otherwise. Safe to call directly in tests.
+   */
+  verify() {
+    return this._loadAndVerify() !== null;
+  }
+
+  /**
+   * Hash the rules for change detection (not security-critical — just diffing).
+   */
+  _hashRules(rules) {
+    return crypto.createHash('sha256').update(JSON.stringify(rules)).digest('hex');
+  }
+
+  /**
+   * Start the periodic integrity check.
+   * Verifies the policy on startup; calls onTamperDetected() if verification fails.
+   * Calls onValidChange(rules) with the initial rules on startup, then on every verified change.
+   */
+  start() {
+    if (!fs.existsSync(this.policyPath)) return;
+
+    // F-02a: refuse to verify a policy file against the bundled dev key in production.
+    // The dev private key is public (committed to the repo), so any attacker can forge
+    // a valid signature. Only allow the dev key when FW_ALLOW_DEV_POLICY_KEY=1.
+    if (USING_DEV_POLICY_KEY && process.env.FW_ALLOW_DEV_POLICY_KEY !== '1') {
+      console.error(
+        '[CRITICAL] Policy file found but FW_POLICY_PUBKEY is missing or set to the bundled ' +
+        'development key. The matching private key is public, making this unsafe. Set ' +
+        'FW_POLICY_PUBKEY to your production public key, or set FW_ALLOW_DEV_POLICY_KEY=1 ' +
+        'for local/dev/CI use. Refusing to run.'
+      );
+      process.exit(1);
+    }
+
+    const initial = this._loadAndVerify();
+    if (!initial) {
+      this.locked = true;
+      console.error('\n[CRITICAL] Policy file failed signature verification on startup. EMERGENCY LOCKDOWN ACTIVE.');
+      this.onTamperDetected();
+      return;
+    }
+
+    this._lastRulesHash = this._hashRules(initial.rules);
+    this.onValidChange(initial.rules);
+
+    this.timer = setInterval(() => {
+      if (this.locked) return;
+
+      const result = this._loadAndVerify();
+      if (!result) {
+        this.locked = true;
+        console.error('\n[CRITICAL] Policy integrity violation detected. EMERGENCY LOCKDOWN ACTIVE.');
+        this.onTamperDetected();
+        return;
+      }
+
+      const newHash = this._hashRules(result.rules);
+      if (newHash !== this._lastRulesHash) {
+        this._lastRulesHash = newHash;
+        console.log('[PolicyWatcher] Valid policy update detected \u2014 hot-reloading rules.');
+        this.onValidChange(result.rules);
+      }
+    }, this._intervalMs);
+
+    if (this.timer.unref) this.timer.unref();
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  get isLocked() {
+    return this.locked;
+  }
+}
+
+module.exports = { PolicyWatcher, canonicalPayload, assertProductionKeyConfig };
+

package/src/policy.js

@@ -0,0 +1,83 @@
+// packages/fw-agent/src/policy.js
+const crypto = require('crypto');
+
+/**
+ * Canonical Helios object structure for tamper-evident hashing
+ */
+function createCanonicalObject(data, objectType = 'security_policy') {
+  return {
+    category: objectType,
+    created_at: data.created_at || new Date().toISOString(),
+    key: data.key || 'active_policy',
+    relationships: data.relationships || [],
+    source: data.source || 'fw-control-plane',
+    value: data.value || data.rules || {}
+  };
+}
+
+/**
+ * Hash a memory object using SHA-256 (Helios-compatible format)
+ */
+function hashMemoryObject(obj) {
+  // Canonical JSON serialization (sorted keys, no whitespace)
+  const canonical = JSON.stringify(obj, Object.keys(obj).sort());
+  return crypto.createHash('sha256').update(canonical).digest('hex');
+}
+
+/**
+ * Verify policy integrity against Helios hash
+ */
+async function verifyPolicyIntegrity(policyObject) {
+  if (!policyObject || !policyObject.rules) {
+    console.warn('[Policy Verification] Missing or empty policy object');
+    return false;
+  }
+
+  // Construct the canonical object as it was signed
+  const canonicalObject = createCanonicalObject(policyObject, 'security_policy');
+  
+  // Calculate the hash locally
+  const calculatedHash = hashMemoryObject(canonicalObject);
+  
+  // Verify against the provided hash
+  if (policyObject.helios_hash) {
+    if (calculatedHash !== policyObject.helios_hash) {
+      console.error('[CRITICAL] Policy tampering detected! Hash mismatch.');
+      console.error(`Expected: ${policyObject.helios_hash}`);
+      console.error(`Calculated: ${calculatedHash}`);
+      return false;
+    }
+    console.log('[Policy Verification] ✅ Policy integrity verified');
+    return true;
+  }
+  
+  // If no hash provided, log warning but allow (graceful degradation)
+  console.warn('[Policy Verification] ⚠️ No integrity hash provided (unsigned policy)');
+  return true;
+}
+
+/**
+ * Create a forensic object for a security event
+ */
+function createForensicObject(eventType, packageName, operation, details) {
+  return {
+    category: 'quarantine_event',
+    created_at: new Date().toISOString(),
+    key: `ev_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+    relationships: [packageName],
+    source: 'fw-agent-proxy',
+    value: {
+      eventType,
+      operation,
+      details,
+      timestamp: Date.now()
+    }
+  };
+}
+
+module.exports = {
+  createCanonicalObject,
+  hashMemoryObject,
+  verifyPolicyIntegrity,
+  createForensicObject
+};

package/src/quarantine.js

@@ -0,0 +1,123 @@
+// packages/fw-agent/src/quarantine.js
+const { hashMemoryObject, createForensicObject } = require('./policy');
+
+/**
+ * QuarantineStub - A Proxy that intercepts all method calls on quarantined modules
+ * Every intercept is hashed and logged for forensic analysis
+ */
+class QuarantineStub {
+  constructor(packageName, telemetry) {
+    this.packageName = packageName;
+    this.telemetry = telemetry;
+    this.interceptCount = 0;
+    this.rateLimitCount = 0;
+    this.initTime = BigInt(process.hrtime.bigint());
+  }
+
+  /**
+   * Record a quarantine event with tamper-evident hashing
+   */
+  record(operation, details = {}) {
+    this.interceptCount++;
+    
+    // Detect rapid-fire intercepts (>100 calls in <1ms) as a potential exhaustion attack.
+    // Do NOT kill the host process — rate-limit logs and return to preserve availability.
+    const currentDelta = Number(process.hrtime.bigint() - this.initTime) / 1e6;
+    if (this.interceptCount > 100 && currentDelta < 1.0) {
+      this.rateLimitCount++;
+      if (this.rateLimitCount % 10 === 1) {
+        console.warn(
+          `[Quarantine] Rapid-fire intercepts on "${this.packageName}" ` +
+          `(${this.interceptCount} calls in ${currentDelta.toFixed(3)}ms). ` +
+          `Rate-limiting (suppressed ${this.rateLimitCount - 1} events).`
+        );
+      }
+      return; // Inert return — preserve host availability
+    }
+
+    // Create the forensic object
+    const forensicObject = createForensicObject(
+      'QUARANTINE_BREACH',
+      this.packageName,
+      operation,
+      {
+        ...details,
+        interceptCount: this.interceptCount
+      }
+    );
+
+    // Calculate the forensic hash (SHA-256 of canonical JSON)
+    const eventHash = hashMemoryObject(forensicObject);
+
+    // Only emit telemetry if it exists (may be disabled during benchmarks)
+    if (this.telemetry && this.telemetry.emit) {
+      // Emit telemetry with the hash for immutable audit trail
+      this.telemetry.emit('quarantine_event', {
+        ...forensicObject,
+        hash: eventHash  // Tamper-evident anchor
+      });
+    }
+
+    // Also log to console for real-time observability (only first breach)
+    if (this.interceptCount === 1) {
+      console.warn(
+        `[Quarantine Intercept] Package: ${this.packageName} | Operation: ${operation} | Hash: ${eventHash.substring(0, 16)}...`
+      );
+    }
+  }
+
+  /**
+   * Create a Proxy that intercepts all property accesses and method calls
+   */
+  createProxy() {
+    return new Proxy({}, {
+      get: (target, prop) => {
+        // F-17: Prevent the proxy from being treated as a thenable/iterable.
+        // If `then`, Symbol.toPrimitive, or Symbol.iterator resolve to a function,
+        // Promise.resolve() / await / for..of will hang or throw unexpectedly.
+        if (prop === 'then' || prop === Symbol.toPrimitive || prop === Symbol.iterator) {
+          return undefined;
+        }
+
+        // Record the interception
+        this.record(`property_access`, { property: String(prop) });
+
+        // Return a function that logs further calls
+        return (...args) => {
+          this.record(`method_call`, {
+            property: String(prop),
+            args: args.length
+          });
+          return null; // Graceful degradation
+        };
+      },
+
+      set: (target, prop, value) => {
+        this.record(`property_write`, { property: String(prop) });
+        return true; // Pretend success
+      },
+
+      has: (target, prop) => {
+        this.record(`property_check`, { property: String(prop) });
+        return false; // Pretend property doesn't exist
+      },
+
+      deleteProperty: (target, prop) => {
+        this.record(`property_delete`, { property: String(prop) });
+        return true; // Pretend deletion succeeded
+      },
+
+      ownKeys: (target) => {
+        this.record(`enumerate_keys`, {});
+        return [];
+      },
+
+      getOwnPropertyDescriptor: (target, prop) => {
+        this.record(`descriptor_query`, { property: String(prop) });
+        return undefined;
+      }
+    });
+  }
+}
+
+module.exports = { QuarantineStub };