ferret-scan 2.1.2 → 2.3.0

package/dist/utils/baseline.js

@@ -2,10 +2,10 @@
  * Baseline Management - Track and ignore accepted findings
  * Allows users to create baselines of known/accepted security findings
  */
-import { writeFileSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { statSync } from 'node:fs';
+import { writeFile, readFile, mkdir, access } from 'node:fs/promises';
 import { resolve, dirname, extname } from 'node:path';
 import { createHash } from 'node:crypto';
-import { mkdirSync } from 'node:fs';
 import logger from './logger.js';
 /**
  * Generate a hash for a finding to uniquely identify it
@@ -14,20 +14,51 @@ function generateFindingHash(finding) {
     const content = `${finding.ruleId}:${finding.relativePath}:${finding.line}:${finding.match}`;
     return createHash('sha256').update(content).digest('hex');
 }
+/**
+ * Compute integrity hash of a baseline (excluding the integrity field itself)
+ */
+export function computeBaselineIntegrity(baseline) {
+    const payload = JSON.stringify({
+        version: baseline.version,
+        createdDate: baseline.createdDate,
+        lastUpdated: baseline.lastUpdated,
+        description: baseline.description,
+        findings: baseline.findings,
+    });
+    return {
+        algorithm: 'sha256',
+        hash: createHash('sha256').update(payload).digest('hex'),
+    };
+}
+/**
+ * Verify that a loaded baseline has not been tampered with
+ */
+export function verifyBaselineIntegrity(baseline) {
+    if (!baseline.integrity) {
+        return true; // Old baselines without integrity field are accepted
+    }
+    const expected = computeBaselineIntegrity(baseline);
+    return expected.hash === baseline.integrity.hash;
+}
 /**
  * Load baseline from file
  */
-export function loadBaseline(baselinePath) {
+export async function loadBaseline(baselinePath) {
     try {
-        if (!existsSync(baselinePath)) {
-            return null;
-        }
-        const content = readFileSync(baselinePath, 'utf-8');
+        await access(baselinePath);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const content = await readFile(baselinePath, 'utf-8');
         const baseline = JSON.parse(content);
-        // Validate baseline structure
         if (!baseline.version || !baseline.findings || !Array.isArray(baseline.findings)) {
             throw new Error('Invalid baseline format');
         }
+        if (baseline.integrity && !verifyBaselineIntegrity(baseline)) {
+            logger.warn(`Baseline integrity check failed for ${baselinePath} — file may have been tampered with`);
+        }
         logger.debug(`Loaded baseline with ${baseline.findings.length} accepted findings`);
         return baseline;
     }
@@ -39,17 +70,17 @@ export function loadBaseline(baselinePath) {
 /**
  * Save baseline to file
  */
-export function saveBaseline(baseline, baselinePath) {
+export async function saveBaseline(baseline, baselinePath) {
     try {
-        // Ensure directory exists
-        const dir = dirname(baselinePath);
-        mkdirSync(dir, { recursive: true });
-        // Update lastUpdated timestamp
-        baseline.lastUpdated = new Date().toISOString();
-        // Write baseline file
-        const content = JSON.stringify(baseline, null, 2);
-        writeFileSync(baselinePath, content, 'utf-8');
-        logger.info(`Baseline saved to ${baselinePath} with ${baseline.findings.length} findings`);
+        await mkdir(dirname(baselinePath), { recursive: true });
+        const updated = { ...baseline, lastUpdated: new Date().toISOString() };
+        const baselineWithIntegrity = {
+            ...updated,
+            integrity: computeBaselineIntegrity(updated),
+        };
+        const content = JSON.stringify(baselineWithIntegrity, null, 2);
+        await writeFile(baselinePath, content, 'utf-8');
+        logger.info(`Baseline saved to ${baselinePath} with ${baselineWithIntegrity.findings.length} findings`);
     }
     catch (error) {
         logger.error(`Failed to save baseline to ${baselinePath}:`, error);
@@ -227,7 +258,7 @@ export function getDefaultBaselinePath(scanPaths) {
     // Try to find a good location for baseline file
     const firstPath = scanPaths[0] ?? process.cwd();
     try {
-        if (existsSync(firstPath) && statSync(firstPath).isFile()) {
+        if (statSync(firstPath).isFile()) {
             return resolve(dirname(firstPath), '.ferret-baseline.json');
         }
     }

package/dist/utils/contentCache.d.ts

@@ -0,0 +1,39 @@
+/**
+ * LRU-bounded in-memory cache for file content.
+ *
+ * Prevents unbounded memory growth when the scanner reads thousands of files:
+ * - Per-file cap: individual files larger than `maxFileSize` bytes are never cached.
+ * - Aggregate cap: once `totalBytes` would exceed `maxBytes`, the least-recently-used
+ *   entry is evicted first. Same policy applies to the `maxEntries` cap.
+ *
+ * Insertion order of a Map mirrors access order after each get() refresh,
+ * giving us O(1) LRU with the iteration-based eviction below.
+ */
+export interface BoundedContentCacheOpts {
+    /** Maximum total cached bytes. Default: 256 MB. */
+    maxBytes?: number;
+    /** Maximum number of cached entries. Default: 10 000. */
+    maxEntries?: number;
+    /** Maximum size of a single file to admit into the cache. Default: 1 MB. */
+    maxFileSize?: number;
+}
+export declare class BoundedContentCache {
+    private readonly map;
+    private totalBytes;
+    private readonly maxBytes;
+    private readonly maxEntries;
+    private readonly maxFileSize;
+    constructor(opts?: BoundedContentCacheOpts);
+    set(path: string, content: string): void;
+    get(path: string): string | undefined;
+    has(path: string): boolean;
+    /** Number of cached entries. */
+    size(): number;
+    /** Total cached bytes (UTF-8 encoded). */
+    bytes(): number;
+    /** Expose for CorrelationAnalyzer compatibility (read-only iteration). */
+    entries(): IterableIterator<[string, string]>;
+    /** Allow spread / array-from for compatibility with Map-based consumers. */
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+//# sourceMappingURL=contentCache.d.ts.map

package/dist/utils/contentCache.js

@@ -0,0 +1,77 @@
+/**
+ * LRU-bounded in-memory cache for file content.
+ *
+ * Prevents unbounded memory growth when the scanner reads thousands of files:
+ * - Per-file cap: individual files larger than `maxFileSize` bytes are never cached.
+ * - Aggregate cap: once `totalBytes` would exceed `maxBytes`, the least-recently-used
+ *   entry is evicted first. Same policy applies to the `maxEntries` cap.
+ *
+ * Insertion order of a Map mirrors access order after each get() refresh,
+ * giving us O(1) LRU with the iteration-based eviction below.
+ */
+const DEFAULT_MAX_BYTES = 256 * 1024 * 1024; // 256 MB
+const DEFAULT_MAX_ENTRIES = 10_000;
+const DEFAULT_MAX_FILE = 1_000_000; // 1 MB
+export class BoundedContentCache {
+    map = new Map();
+    totalBytes = 0;
+    maxBytes;
+    maxEntries;
+    maxFileSize;
+    constructor(opts = {}) {
+        this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.maxFileSize = opts.maxFileSize ?? DEFAULT_MAX_FILE;
+    }
+    set(path, content) {
+        const incoming = Buffer.byteLength(content, 'utf-8');
+        // Refuse files that exceed the per-file cap.
+        if (incoming > this.maxFileSize)
+            return;
+        // If the key already exists, remove its contribution before re-inserting.
+        const existing = this.map.get(path);
+        if (existing !== undefined) {
+            this.map.delete(path);
+            this.totalBytes -= Buffer.byteLength(existing, 'utf-8');
+        }
+        // Evict the oldest (first-in-map) entries until this one fits.
+        while (this.map.size > 0 &&
+            (this.totalBytes + incoming > this.maxBytes || this.map.size >= this.maxEntries)) {
+            const oldestKey = this.map.keys().next().value;
+            const oldestVal = this.map.get(oldestKey);
+            this.map.delete(oldestKey);
+            this.totalBytes -= Buffer.byteLength(oldestVal, 'utf-8');
+        }
+        this.map.set(path, content);
+        this.totalBytes += incoming;
+    }
+    get(path) {
+        const val = this.map.get(path);
+        if (val === undefined)
+            return undefined;
+        // Refresh to most-recently-used position (LRU via Map insertion order).
+        this.map.delete(path);
+        this.map.set(path, val);
+        return val;
+    }
+    has(path) {
+        return this.map.has(path);
+    }
+    /** Number of cached entries. */
+    size() {
+        return this.map.size;
+    }
+    /** Total cached bytes (UTF-8 encoded). */
+    bytes() {
+        return this.totalBytes;
+    }
+    /** Expose for CorrelationAnalyzer compatibility (read-only iteration). */
+    entries() {
+        return this.map.entries();
+    }
+    /** Allow spread / array-from for compatibility with Map-based consumers. */
+    [Symbol.iterator]() {
+        return this.map.entries();
+    }
+}
+//# sourceMappingURL=contentCache.js.map

package/dist/utils/glob.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Safe glob-to-regex conversion utility
+ *
+ * Prevents regex injection attacks and ReDoS by escaping metacharacters
+ * and bounding wildcard replacements.
+ */
+export interface GlobOptions {
+    /** Whether to anchor with ^$ (default: true) */
+    anchored?: boolean;
+    /** Whether this is a file path (affects wildcard replacement) */
+    pathLike?: boolean;
+}
+/**
+ * Convert a glob pattern to a safe RegExp with bounded wildcards.
+ *
+ * - Escapes all regex metacharacters except `*`
+ * - Replaces `*` with bounded character classes to prevent ReDoS
+ * - Anchors patterns to prevent unintended substring matches
+ * - Caches compiled patterns for performance
+ *
+ * @param glob The glob pattern (e.g. "*.env", "CRED-*")
+ * @param opts Configuration options
+ * @returns A safe RegExp that won't cause ReDoS or over-match
+ *
+ * @example
+ * ```typescript
+ * // File pattern matching
+ * const filePattern = globToRegex("*.env", { pathLike: true });
+ * filePattern.test("/path/to/file.env");  // true
+ * filePattern.test("file.env.backup");   // false (anchored)
+ *
+ * // Rule ID pattern matching
+ * const rulePattern = globToRegex("CRED-*");
+ * rulePattern.test("CRED-001");          // true
+ * rulePattern.test("CREDENTIAL-001");    // false (literal dot required)
+ * ```
+ */
+export declare function globToRegex(glob: string, opts?: GlobOptions): RegExp;
+/**
+ * Clear the compiled pattern cache (useful for testing)
+ */
+export declare function clearCache(): void;
+/**
+ * Get cache statistics (useful for debugging)
+ */
+export declare function getCacheStats(): {
+    size: number;
+    keys: string[];
+};
+//# sourceMappingURL=glob.d.ts.map

package/dist/utils/glob.js

@@ -0,0 +1,84 @@
+/**
+ * Safe glob-to-regex conversion utility
+ *
+ * Prevents regex injection attacks and ReDoS by escaping metacharacters
+ * and bounding wildcard replacements.
+ */
+// Regex metacharacters that need escaping (all except asterisk)
+const REGEX_META = /[.+?^${}()|[\]\\]/g;
+// Cache compiled regexes to avoid recompilation in hot paths
+const cache = new Map();
+/**
+ * Convert a glob pattern to a safe RegExp with bounded wildcards.
+ *
+ * - Escapes all regex metacharacters except `*`
+ * - Replaces `*` with bounded character classes to prevent ReDoS
+ * - Anchors patterns to prevent unintended substring matches
+ * - Caches compiled patterns for performance
+ *
+ * @param glob The glob pattern (e.g. "*.env", "CRED-*")
+ * @param opts Configuration options
+ * @returns A safe RegExp that won't cause ReDoS or over-match
+ *
+ * @example
+ * ```typescript
+ * // File pattern matching
+ * const filePattern = globToRegex("*.env", { pathLike: true });
+ * filePattern.test("/path/to/file.env");  // true
+ * filePattern.test("file.env.backup");   // false (anchored)
+ *
+ * // Rule ID pattern matching
+ * const rulePattern = globToRegex("CRED-*");
+ * rulePattern.test("CRED-001");          // true
+ * rulePattern.test("CREDENTIAL-001");    // false (literal dot required)
+ * ```
+ */
+export function globToRegex(glob, opts = {}) {
+    const anchored = opts.anchored !== false;
+    const pathLike = opts.pathLike ?? false;
+    // Create cache key including options
+    const key = `${glob}::${anchored}::${pathLike}`;
+    // Return cached pattern if available
+    const hit = cache.get(key);
+    if (hit) {
+        return hit;
+    }
+    // Escape all regex metacharacters except asterisk
+    const escaped = glob.replace(REGEX_META, '\\$&');
+    // Replace asterisk with bounded character class
+    // Path-like: match non-newlines (for file paths)
+    // Rule-like: match non-whitespace (for rule IDs)
+    const wildcard = pathLike
+        ? '[^\\n]{0,200}' // File paths: no newlines, bound to 200 chars
+        : '[^\\s]{0,200}'; // Rule IDs: no whitespace, bound to 200 chars
+    const body = escaped.replace(/\*/g, wildcard);
+    // Anchor pattern if requested (default)
+    const pattern = anchored ? `^${body}$` : body;
+    try {
+        const compiled = new RegExp(pattern);
+        cache.set(key, compiled);
+        return compiled;
+    }
+    catch {
+        // Fallback to never-matching pattern if compilation fails
+        const fallback = /(?!)/; // Negative lookahead - never matches
+        cache.set(key, fallback);
+        return fallback;
+    }
+}
+/**
+ * Clear the compiled pattern cache (useful for testing)
+ */
+export function clearCache() {
+    cache.clear();
+}
+/**
+ * Get cache statistics (useful for debugging)
+ */
+export function getCacheStats() {
+    return {
+        size: cache.size,
+        keys: Array.from(cache.keys())
+    };
+}
+//# sourceMappingURL=glob.js.map

package/dist/utils/pathSecurity.js

@@ -36,6 +36,7 @@ export function sanitizeFilename(filename) {
         .replace(/[\/\\]/g, '_') // Replace path separators
         .replace(/\.\./g, '_') // Replace parent directory references
         .replace(/[<>:"|?*]/g, '_') // Remove invalid filename characters
+        .replace(/\0/g, '_') // Replace null bytes
         .replace(/^\.+/, '_'); // Remove leading dots
 }
 /**

package/dist/utils/safeRegex.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Safe regex runtime utilities with bounded runtime and match limits.
+ *
+ * Uses Google RE2 (linear-time engine) when available for categorically
+ * safe pattern execution. Falls back to the screened native JS engine.
+ * Prevents ReDoS attacks and runaway regex matching in user-controlled patterns.
+ */
+export interface BoundedOptions {
+    /** Maximum runtime in milliseconds (default: 1000) */
+    maxMs?: number;
+    /** Maximum number of matches to collect (default: 500) */
+    maxMatches?: number;
+}
+export interface BoundedResult {
+    /** Array of captured matches */
+    matches: RegExpExecArray[];
+    /** Whether runtime was truncated due to time/count limits */
+    truncated: boolean;
+}
+/**
+ * Compile a pattern string into a RegExp (or RE2 instance when available).
+ *
+ * Tries RE2 first — it is a linear-time engine that categorically eliminates
+ * ReDoS. If RE2 is unavailable or rejects the pattern (e.g. lookaheads), falls
+ * back to the static ReDoS screener + native RegExp.
+ *
+ * @param raw The raw pattern string
+ * @param flags Regex flags (default: 'gi')
+ * @returns Compiled RegExp/RE2 or null if pattern is unsafe/invalid
+ *
+ * @example
+ * ```typescript
+ * const safe = compileSafePattern('test\\d+');   // OK
+ * const invalid = compileSafePattern('[unclosed'); // null - syntax error
+ * ```
+ */
+export declare function compileSafePattern(raw: string, flags?: string): RegExp | null;
+/**
+ * Run a regex against content with bounded runtime and match limits.
+ *
+ * When RE2 is active the time budget is largely redundant (RE2 is linear),
+ * but the match-count ceiling still prevents unbounded result arrays.
+ */
+export declare function runBounded(pattern: RegExp, content: string, options?: BoundedOptions): BoundedResult;
+/**
+ * Safe pattern matching that combines compilation and bounded runtime.
+ */
+export declare function safeMatch(rawPattern: string, content: string, flags?: string, options?: BoundedOptions): BoundedResult | null;
+/**
+ * Test if a pattern matches content safely, returning boolean result.
+ */
+export declare function safeTest(rawPattern: string, content: string, flags?: string): boolean;
+/** Returns true when RE2 is active (linear-time engine). */
+export declare function isRE2Active(): boolean;
+//# sourceMappingURL=safeRegex.d.ts.map

package/dist/utils/safeRegex.js

@@ -0,0 +1,130 @@
+/**
+ * Safe regex runtime utilities with bounded runtime and match limits.
+ *
+ * Uses Google RE2 (linear-time engine) when available for categorically
+ * safe pattern execution. Falls back to the screened native JS engine.
+ * Prevents ReDoS attacks and runaway regex matching in user-controlled patterns.
+ */
+// Lazy-load RE2 so the module is still usable when re2 is not installed.
+let RE2 = null;
+let re2Attempted = false;
+function getRE2() {
+    if (re2Attempted)
+        return RE2;
+    re2Attempted = true;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        RE2 = require('re2');
+    }
+    catch {
+        RE2 = null;
+    }
+    return RE2;
+}
+/**
+ * Compile a pattern string into a RegExp (or RE2 instance when available).
+ *
+ * Tries RE2 first — it is a linear-time engine that categorically eliminates
+ * ReDoS. If RE2 is unavailable or rejects the pattern (e.g. lookaheads), falls
+ * back to the static ReDoS screener + native RegExp.
+ *
+ * @param raw The raw pattern string
+ * @param flags Regex flags (default: 'gi')
+ * @returns Compiled RegExp/RE2 or null if pattern is unsafe/invalid
+ *
+ * @example
+ * ```typescript
+ * const safe = compileSafePattern('test\\d+');   // OK
+ * const invalid = compileSafePattern('[unclosed'); // null - syntax error
+ * ```
+ */
+export function compileSafePattern(raw, flags = 'gi') {
+    const RE2Ctor = getRE2();
+    if (RE2Ctor !== null) {
+        // RE2 is linear-time — no static ReDoS screening needed.
+        // If RE2 rejects the pattern (lookaheads, backreferences) it throws;
+        // we fall through to the native screener below.
+        try {
+            return new RE2Ctor(raw, flags);
+        }
+        catch {
+            // Pattern uses features RE2 does not support — fall through.
+        }
+    }
+    // Fallback: static screen for exponential-backtracking structures before
+    // handing the pattern to the native JS engine.
+    const redosPatterns = [
+        /(\?\+)/, // Possessive quantifier abuse: a+?+
+        /(\+\+)/, // Double plus: a++
+        /(\*\*)/, // Double star: a**
+        /(\(.*\+\)\+)/, // Nested quantifiers: (a+)+
+        /(\(.*\*\)\*)/, // Nested quantifiers: (a*)*
+        /(\(.*\+\)\{)/, // Quantified groups: (a+){2,}
+        /(\(.*\|.*\)\+)/, // Alternation inside quantified group: (a|b)+
+        /(\(.*\|.*\)\*)/, // Alternation inside quantified group: (a|b)*
+        /(\(.*\|.*\)\{)/, // Alternation inside bounded group: (a|b){2,}
+    ];
+    for (const redos of redosPatterns) {
+        if (redos.test(raw)) {
+            return null;
+        }
+    }
+    try {
+        return new RegExp(raw, flags);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run a regex against content with bounded runtime and match limits.
+ *
+ * When RE2 is active the time budget is largely redundant (RE2 is linear),
+ * but the match-count ceiling still prevents unbounded result arrays.
+ */
+export function runBounded(pattern, content, options = {}) {
+    const maxMs = options.maxMs ?? 1000;
+    const maxMatches = options.maxMatches ?? 500;
+    const deadline = Date.now() + maxMs;
+    const matches = [];
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        if (Date.now() > deadline) {
+            return { matches, truncated: true };
+        }
+        if (matches.length >= maxMatches) {
+            return { matches, truncated: true };
+        }
+        matches.push(match);
+        if (!pattern.global) {
+            break;
+        }
+        if (match[0].length === 0) {
+            pattern.lastIndex++;
+        }
+    }
+    return { matches, truncated: false };
+}
+/**
+ * Safe pattern matching that combines compilation and bounded runtime.
+ */
+export function safeMatch(rawPattern, content, flags = 'gi', options = {}) {
+    const pattern = compileSafePattern(rawPattern, flags);
+    if (pattern === null) {
+        return null;
+    }
+    return runBounded(pattern, content, options);
+}
+/**
+ * Test if a pattern matches content safely, returning boolean result.
+ */
+export function safeTest(rawPattern, content, flags = 'i') {
+    const testFlags = flags.replace(/g/g, '');
+    const result = safeMatch(rawPattern, content, testFlags, { maxMatches: 1 });
+    return result !== null && result.matches.length > 0 && !result.truncated;
+}
+/** Returns true when RE2 is active (linear-time engine). */
+export function isRE2Active() {
+    return getRE2() !== null;
+}
+//# sourceMappingURL=safeRegex.js.map