sekant-intercept-js 1.0.0

package/src/peModule.mjs

@@ -0,0 +1,295 @@
+/*
+ * Copyright 2026 Rishi Kant (Sekant Security Inc.)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Browser-compatible PE parser that mirrors YARA's PE module fields.
+// Includes lightweight detection of digital signature (no PKIjs).
+
+import * as PE from "pe-library";
+import { computeEntropy, digestHex, calculateMD5, readUtf16leString, findPattern } from "./sharedUtils.mjs";
+
+/* -------------------------
+   Section processing
+------------------------- */
+async function parsePESections(exe, inputBytes) {
+  const sections = [];
+  const exeSections = exe.getAllSections?.() || exe.sections || [];
+  for (const s of exeSections) {
+    // Handle different PE library structures
+    const sectionInfo = s.info || s;
+    const data = s.data ? new Uint8Array(s.data) : (s.data ?? new Uint8Array());
+    
+    // Compute section hashes using shared utilities (browser-compatible)
+    const md5Hash = calculateMD5(data);
+    const sha1Hash = await digestHex("SHA-1", data);
+    const sha256Hash = await digestHex("SHA-256", data);
+    
+    const sectionHashes = {
+      md5: md5Hash,
+      sha1: sha1Hash,
+      sha256: sha256Hash,
+    };
+    
+    sections.push({
+      name: (sectionInfo.name || s.name || "")?.replace(/\0.*$/, ""),
+      raw_data: data,
+      entropy: computeEntropy(data),
+      virtual_address: sectionInfo.virtualAddress ?? sectionInfo.VirtualAddress ?? s.VirtualAddress ?? 0,
+      virtual_size: sectionInfo.virtualSize ?? sectionInfo.VirtualSize ?? s.VirtualSize ?? 0,
+      raw_data_offset: sectionInfo.pointerToRawData ?? sectionInfo.PointerToRawData ?? s.PointerToRawData ?? 0,
+      raw_data_size: sectionInfo.sizeOfRawData ?? sectionInfo.SizeOfRawData ?? s.SizeOfRawData ?? 0,
+      characteristics: (sectionInfo.characteristics ?? sectionInfo.Characteristics ?? s.Characteristics ?? 0) >>> 0, // Convert to unsigned 32-bit
+      ...sectionHashes,
+    });
+  }
+  return sections;
+}
+
+/* -------------------------
+   Imports / Exports
+------------------------- */
+function parseImports(exe) {
+  return (exe.imports || []).map(imp => ({
+    dll: imp.name || "",
+    functions: (imp.functions || []).map(f => ({ name: f.name || null, ordinal: f.ordinal || null })),
+  }));
+}
+
+function parseExports(exe) {
+  return (exe.exports || []).map(e => e.name || e).filter(Boolean);
+}
+
+/* -------------------------
+   ImpHash
+------------------------- */
+function computeImpHash(importsArray) {
+  const parts = [];
+  for (const imp of importsArray) {
+    const dll = (imp.dll || "").toLowerCase();
+    if (Array.isArray(imp.functions)) {
+      for (const fn of imp.functions) {
+        const name = (fn.name || `ordinal${fn.ordinal || ""}`).toLowerCase();
+        parts.push(`${dll}.${name}`);
+      }
+    }
+  }
+  // Use calculateMD5 with TextEncoder for string hashing
+  const encoder = new TextEncoder();
+  return calculateMD5(encoder.encode(parts.join(",")));
+}
+
+/* -------------------------
+   Digital Signature
+------------------------- */
+function detectAuthenticode(exe) {
+  const dirEntry = exe.optionalHeader?.dataDirectory?.[PE.Format.ImageDirectoryEntry.Security];
+  if (!dirEntry || !dirEntry.virtualAddress || !dirEntry.size) return { has_signature: false };
+  return { has_signature: true, certificate_table: { offset: dirEntry.virtualAddress, size: dirEntry.size } };
+}
+
+/* -------------------------
+   Rich Header detection
+------------------------- */
+function detectRichHeader(buf) {
+  const pattern = new Uint8Array([0x52, 0x69, 0x63, 0x68]); // "Rich"
+  const offset = findPattern(buf, pattern);
+  return offset !== -1 ? { offset } : null;
+}
+
+/* -------------------------
+   Optional Header Fields (flattened for YARA)
+------------------------- */
+function parseOptionalHeaderFlat(exe) {
+  const opt = exe.newHeader?.optionalHeader || exe.optionalHeader;
+  if (!opt) return {};
+  
+  return {
+    size_of_code: opt.sizeOfCode ?? 0,
+    size_of_initialized_data: opt.sizeOfInitializedData ?? 0,
+    size_of_uninitialized_data: opt.sizeOfUninitializedData ?? 0,
+    address_of_entry_point: opt.addressOfEntryPoint ?? 0,
+    base_of_code: opt.baseOfCode ?? 0,
+    base_of_data: opt.baseOfData ?? 0,
+    image_base: opt.imageBase ?? 0,
+    section_alignment: opt.sectionAlignment ?? 0,
+    file_alignment: opt.fileAlignment ?? 0,
+    subsystem: opt.subsystem ?? 0,
+    dll_characteristics: opt.dllCharacteristics ?? 0,
+    size_of_stack_reserve: opt.sizeOfStackReserve ?? 0,
+    size_of_stack_commit: opt.sizeOfStackCommit ?? 0,
+    size_of_heap_reserve: opt.sizeOfHeapReserve ?? 0,
+    size_of_heap_commit: opt.sizeOfHeapCommit ?? 0,
+  };
+}
+
+/* -------------------------
+   Main YARA-Compatible Parser
+------------------------- */
+export async function parsePEYara(inputBytes) {
+  if (inputBytes instanceof ArrayBuffer) inputBytes = new Uint8Array(inputBytes);
+
+  let exe;
+  try { exe = PE.NtExecutable.from(inputBytes); } 
+  catch(e) { return { error: "Failed to parse PE", message: e.message }; }
+
+  const sections = await parsePESections(exe, inputBytes);
+  const imports = parseImports(exe);
+  const exportsArr = parseExports(exe);
+  const imphash = computeImpHash(imports);
+  const digital_signature = detectAuthenticode(exe);
+  const rich_header = detectRichHeader(inputBytes);
+  const optional_header = parseOptionalHeaderFlat(exe);
+
+  // Get optional header reference (supports both old and new pe-library versions)
+  const optHeader = exe.newHeader?.optionalHeader || exe.optionalHeader;
+  const coffHeader = exe.newHeader?.fileHeader || exe.coffHeader;
+
+  // Convert entry_point from RVA to file offset (like we do for ELF)
+  const entryPointRVA = optHeader?.addressOfEntryPoint ?? 0;
+  let entryPointOffset = entryPointRVA;
+  
+  if (entryPointRVA > 0 && sections.length > 0) {
+    // Find the section containing the entry point RVA
+    for (const section of sections) {
+      const sectionStart = section.virtual_address;
+      const sectionEnd = sectionStart + section.virtual_size;
+      
+      if (entryPointRVA >= sectionStart && entryPointRVA < sectionEnd) {
+        // Convert RVA to file offset: file_offset = RVA - virtual_address + raw_data_offset
+        entryPointOffset = entryPointRVA - section.virtual_address + section.raw_data_offset;
+        break;
+      }
+    }
+  }
+
+  const peObj = {
+    machine: coffHeader?.machine ?? 0,
+    entry_point: entryPointOffset,
+    image_base: optHeader?.imageBase ?? 0,
+    number_of_sections: sections.length,
+    sections,
+    imports,
+    exports: exportsArr,
+    imphash,
+    digital_signature,
+    rich_signature: rich_header, // matches YARA field name
+    // Flatten optional header fields at top-level for YARA
+    ...optional_header,
+    file_size: inputBytes.length,
+  };
+
+  // Add YARA-compatible helper methods
+  peObj.is_dll = () => {
+    const characteristics = coffHeader?.characteristics ?? 0;
+    return (characteristics & 0x2000) !== 0; // IMAGE_FILE_DLL
+  };
+
+  peObj.is_32bit = () => {
+    const magic = optHeader?.magic ?? 0;
+    return magic === 0x010b; // PE32
+  };
+
+  peObj.is_64bit = () => {
+    const magic = optHeader?.magic ?? 0;
+    return magic === 0x020b; // PE32+
+  };
+
+  return peObj;
+}
+
+/* -------------------------
+   PE Module for YARA Conditions
+   This wraps the parsed PE with YARA-compatible methods
+------------------------- */
+export function createPEModule(parsedPE) {
+  if (!parsedPE || parsedPE.error) {
+    return null;
+  }
+
+  return {
+    // Direct properties
+    machine: parsedPE.machine,
+    entry_point: parsedPE.entry_point,
+    image_base: parsedPE.image_base,
+    number_of_sections: parsedPE.number_of_sections,
+    sections: parsedPE.sections,
+    imports: parsedPE.imports,
+    exports: parsedPE.exports,
+    imphash: parsedPE.imphash,
+    rich_signature: parsedPE.rich_signature,
+    digital_signature: parsedPE.digital_signature,
+    
+    // Optional header fields
+    size_of_code: parsedPE.size_of_code,
+    size_of_initialized_data: parsedPE.size_of_initialized_data,
+    size_of_uninitialized_data: parsedPE.size_of_uninitialized_data,
+    address_of_entry_point: parsedPE.address_of_entry_point,
+    base_of_code: parsedPE.base_of_code,
+    base_of_data: parsedPE.base_of_data,
+    section_alignment: parsedPE.section_alignment,
+    file_alignment: parsedPE.file_alignment,
+    subsystem: parsedPE.subsystem,
+    dll_characteristics: parsedPE.dll_characteristics,
+    
+    // YARA-compatible methods
+    is_dll: parsedPE.is_dll,
+    is_32bit: parsedPE.is_32bit,
+    is_64bit: parsedPE.is_64bit,
+    
+    // Helper to check if a DLL is imported
+    imports_dll: (dllName) => {
+      const lower = dllName.toLowerCase();
+      return parsedPE.imports.some(imp => imp.dll.toLowerCase() === lower);
+    },
+    
+    // Helper to check if a specific function is imported from a DLL
+    // Usage: pe.imports("kernel32.dll", "CreateProcess") or pe.imports("kernel32.dll")
+    importsFunction: (dllName, functionName) => {
+      const lower = dllName.toLowerCase();
+      const imp = parsedPE.imports.find(imp => imp.dll.toLowerCase() === lower);
+      if (!imp) return false;
+      
+      if (!functionName) return true; // Just check if DLL is imported
+      
+      const lowerFunc = functionName.toLowerCase();
+      return imp.functions.some(fn => 
+        fn.name && fn.name.toLowerCase() === lowerFunc
+      );
+    },
+    
+    // Helper to check if a function is exported
+    exports_function: (functionName) => {
+      const lower = functionName.toLowerCase();
+      return parsedPE.exports.some(exp => exp.toLowerCase() === lower);
+    },
+    
+    // PE constants (common values used in YARA rules)
+    MACHINE_I386: 0x014c,
+    MACHINE_AMD64: 0x8664,
+    MACHINE_ARM: 0x01c0,
+    MACHINE_ARM64: 0xaa64,
+    
+    SUBSYSTEM_NATIVE: 1,
+    SUBSYSTEM_WINDOWS_GUI: 2,
+    SUBSYSTEM_WINDOWS_CUI: 3,
+    
+    SECTION_CNT_CODE: 0x00000020,
+    SECTION_CNT_INITIALIZED_DATA: 0x00000040,
+    SECTION_CNT_UNINITIALIZED_DATA: 0x00000080,
+    SECTION_MEM_EXECUTE: 0x20000000,
+    SECTION_MEM_READ: 0x40000000,
+    SECTION_MEM_WRITE: 0x80000000,
+  };
+}

package/src/performanceInstrumentation.mjs

@@ -0,0 +1,172 @@
+/*
+ * Copyright 2026 Rishi Kant (Sekant Security Inc.)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const defaultLogger = typeof console !== "undefined" && typeof console.log === "function" ? (...args) => console.log(...args) : () => {};
+
+const hasPerformance = typeof globalThis !== "undefined" && globalThis.performance && typeof globalThis.performance.now === "function";
+
+function now() {
+  return hasPerformance ? globalThis.performance.now() : Date.now();
+}
+
+function cloneDeep(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+export class PerformanceTracker {
+  constructor(options = {}) {
+    const enabled = options.enabled ?? options.enableTiming ?? false;
+    const logger = options.logger ?? defaultLogger;
+    const autoPrint = options.autoPrint ?? false;
+
+    this.options = {
+      enabled: Boolean(enabled),
+      logger,
+      autoPrint: Boolean(autoPrint),
+    };
+
+    this.lastTiming = {
+      compile: null,
+      scan: null,
+    };
+  }
+
+  isEnabled() {
+    return Boolean(this.options.enabled);
+  }
+
+  now() {
+    return now();
+  }
+
+  updateOptions(options = {}) {
+    if (Object.prototype.hasOwnProperty.call(options, "enabled") || Object.prototype.hasOwnProperty.call(options, "enableTiming")) {
+      this.options.enabled = Boolean(options.enabled ?? options.enableTiming);
+    }
+    if (Object.prototype.hasOwnProperty.call(options, "logger")) {
+      this.options.logger = options.logger ?? defaultLogger;
+    }
+    if (Object.prototype.hasOwnProperty.call(options, "autoPrint")) {
+      this.options.autoPrint = Boolean(options.autoPrint);
+    }
+  }
+
+  enable(enable = true, logger) {
+    this.updateOptions({ enabled: enable, logger });
+  }
+
+  clearCompile() {
+    this.lastTiming.compile = null;
+  }
+
+  clearScan() {
+    this.lastTiming.scan = null;
+  }
+
+  recordCompile(duration) {
+    const entry = { total: duration };
+    this.lastTiming.compile = entry;
+    this.printTiming("compile", entry);
+  }
+
+  createScanTiming() {
+    return {
+      total: 0,
+      steps: {
+        buildAutomaton: 0,
+        acSearch: 0,
+        deduplicate: 0,
+        verifyCandidates: 0,
+        buildMatches: 0,
+        evaluateConditions: 0,
+        filterStrings: 0,
+      },
+      modules: {
+        total: 0,
+        pe: 0,
+        elf: 0,
+        math: 0,
+        hash: 0,
+      },
+      conditionParsing: {
+        total: 0,
+        byRule: {},
+      },
+      matchCount: 0,
+    };
+  }
+
+  finalizeScan(scanTiming) {
+    this.lastTiming.scan = scanTiming;
+    this.printTiming("scan", scanTiming);
+  }
+
+  accumulateStep(steps, key, duration) {
+    if (!steps || !Number.isFinite(duration)) return;
+    steps[key] = (steps[key] || 0) + duration;
+  }
+
+  accumulateModule(modules, key, duration) {
+    if (!modules || !Number.isFinite(duration)) return;
+    modules.total = (modules.total || 0) + duration;
+    modules[key] = (modules[key] || 0) + duration;
+  }
+
+  accumulateCondition(conditionTiming, ruleName, duration) {
+    if (!conditionTiming || !Number.isFinite(duration)) return;
+    conditionTiming.total = (conditionTiming.total || 0) + duration;
+    if (!conditionTiming.byRule) {
+      conditionTiming.byRule = {};
+    }
+    conditionTiming.byRule[ruleName] = (conditionTiming.byRule[ruleName] || 0) + duration;
+  }
+
+  getSnapshot() {
+    return cloneDeep(this.lastTiming);
+  }
+
+  printTiming(phase, data) {
+    if (!this.options.enabled || !this.options.autoPrint || !this.options.logger || !data) {
+      return;
+    }
+    const logger = this.options.logger;
+    if (phase === "compile") {
+      logger(`[InterceptScanner] Compile completed in ${data.total.toFixed(3)}ms`);
+      return;
+    }
+
+    if (phase === "scan") {
+      const matchCount = data.matchCount ?? "n/a";
+      logger(`[InterceptScanner] Scan completed in ${data.total.toFixed(3)}ms (matches: ${matchCount})`);
+      if (data.steps) {
+        Object.entries(data.steps).forEach(([step, value]) => {
+          if (value == null) return;
+          logger(`  • ${step}: ${value.toFixed(3)}ms`);
+        });
+      }
+      if (data.modules && data.modules.total) {
+        logger(`  • moduleCreation.total: ${data.modules.total.toFixed(3)}ms`);
+      }
+      if (data.conditionParsing && data.conditionParsing.total) {
+        logger(`  • conditionParsing.total: ${data.conditionParsing.total.toFixed(3)}ms`);
+      }
+    }
+  }
+}
+
+export function createPerformanceTracker(options = {}) {
+  return new PerformanceTracker(options);
+}

package/src/sharedUtils.mjs

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2026 Rishi Kant (Sekant Security Inc.)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import SparkMD5 from 'spark-md5';
+
+/**
+ * Detect runtime environment
+ */
+const isBrowser = typeof crypto !== 'undefined';
+const isNode = typeof globalThis.process !== 'undefined' && globalThis.process.versions && globalThis.process.versions.node;
+
+/**
+ * Get crypto object based on environment
+ * In browser: window.crypto or self.crypto
+ * In Node.js: assumes crypto is available in global namespace
+ */
+function getCrypto() {
+  if (isBrowser) {
+    return crypto;
+  } else if (isNode) {
+    // In Node.js, assume crypto has been imported and is available globally
+    return globalThis.crypto;
+  }
+  throw new Error('Crypto API not available in this environment');
+}
+
+export function computeEntropy(u8) {
+  const counts = new Uint32Array(256);
+  for (let i = 0; i < u8.length; i++) counts[u8[i]]++;
+  let entropy = 0;
+  const len = u8.length;
+  if (len === 0) return 0;
+  for (let i = 0; i < 256; i++) {
+    if (counts[i] === 0) continue;
+    const p = counts[i] / len;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+export function toHex(u8) {
+  return Array.from(u8).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Calculate hash digest and return as hex string
+ * @param {string} algo - Algorithm name (e.g., 'SHA-1', 'SHA-256')
+ * @param {Uint8Array} buf - Data to hash
+ * @returns {Promise<string>} Hex string
+ */
+export async function digestHex(algo, buf) {
+  const crypto = getCrypto();
+  const hash = await crypto.subtle.digest(algo, buf);
+  return toHex(new Uint8Array(hash));
+}
+
+/**
+ * Calculate MD5 hash using SparkMD5
+ * @param {Uint8Array} data - Data to hash
+ * @returns {string} Hex string
+ */
+export function calculateMD5(data) {
+  const spark = new SparkMD5.ArrayBuffer();
+  spark.append(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+  return spark.end();
+}
+
+/* Endianness-aware readers */
+export function readUint16(view, offset, littleEndian) {
+  return view.getUint16(offset, littleEndian);
+}
+
+export function readUint32(view, offset, littleEndian) {
+  return view.getUint32(offset, littleEndian);
+}
+
+export function readUint64(view, offset, littleEndian) {
+  const lo = view.getUint32(offset + (littleEndian ? 0 : 4), littleEndian);
+  const hi = view.getUint32(offset + (littleEndian ? 4 : 0), littleEndian);
+  return hi * 2 ** 32 + lo;
+}
+
+/* Null-terminated UTF-8 string */
+export function readString(buf, offset, maxLength = 1024) {
+  const end = Math.min(buf.length, offset + maxLength);
+  let str = "";
+  for (let i = offset; i < end; i++) {
+    if (buf[i] === 0) break;
+    str += String.fromCharCode(buf[i]);
+  }
+  return str;
+}
+
+/* Null-terminated UTF-16 LE string */
+export function readUtf16leString(view, offset, maxBytes = 2048) {
+  let str = "";
+  for (let i = 0; i + 1 < maxBytes; i += 2) {
+    const code = view.getUint16(offset + i, true);
+    if (code === 0) break;
+    str += String.fromCharCode(code);
+  }
+  return str;
+}
+
+/* Find a pattern in Uint8Array */
+export function findPattern(buf, pattern) {
+  const len = buf.length, plen = pattern.length;
+  for (let i = 0; i <= len - plen; i++) {
+    let ok = true;
+    for (let j = 0; j < plen; j++) if (buf[i + j] !== pattern[j]) { ok = false; break; }
+    if (ok) return i;
+  }
+  return -1;
+}

package/src/stringModule.mjs

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2026 Rishi Kant (Sekant Security Inc.)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const string = {
+  to_int: (s, base = 10) => {
+    if (typeof s !== "string" && !(s instanceof String)) {
+      throw new Error("to_int() first argument must be a string");
+      // return 0; // Match YARA behavior
+    }
+    if (s.startsWith("0x") || s.startsWith("0X")) {
+      base = 16;
+      s = s.slice(2);
+    } else if (s.startsWith("O") || s.startsWith("o")) {
+      base = 8;
+      s = s.slice(1);
+    }
+    const result = parseInt(s, base);
+    if (isNaN(result)) {
+      throw new Error(`to_int() could not convert string '${s}' to integer`);
+      // return 0; // Match YARA behavior
+    }
+    return result;
+  },
+  length: (s) => {
+    if (typeof s === "string" || s instanceof String) {
+      return s.length;
+    }
+    return 0;
+  },
+};

package/src/timeModule.mjs

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2026 Rishi Kant (Sekant Security Inc.)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const time = {
+    now: () => Date.now()
+}