ferret-scan 2.2.0 → 2.3.0

package/dist/utils/safeRegex.js

@@ -1,29 +1,58 @@
 /**
- * Safe regex runtime utilities with bounded runtime and match limits
+ * 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, rejecting obviously dangerous patterns.
+ * Compile a pattern string into a RegExp (or RE2 instance when available).
  *
- * This function screens for common ReDoS patterns and syntax errors before
- * compilation, returning null for unsafe inputs.
+ * 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 or null if pattern is unsafe
+ * @returns Compiled RegExp/RE2 or null if pattern is unsafe/invalid
  *
  * @example
  * ```typescript
  * const safe = compileSafePattern('test\\d+');   // OK
- * const unsafe = compileSafePattern('(a+)+b');   // null - ReDoS risk
  * const invalid = compileSafePattern('[unclosed'); // null - syntax error
  * ```
  */
 export function compileSafePattern(raw, flags = 'gi') {
-    // Screen for obvious ReDoS triggers.
-    // We only block patterns where the quantifier structure can cause exponential
-    // backtracking — simple multi-alternative strings like (foo|bar|baz) are safe.
+    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++
@@ -40,34 +69,18 @@ export function compileSafePattern(raw, flags = 'gi') {
             return null;
         }
     }
-    // Attempt compilation
     try {
         return new RegExp(raw, flags);
     }
     catch {
-        // Invalid syntax
         return null;
     }
 }
 /**
  * Run a regex against content with bounded runtime and match limits.
  *
- * This function wraps RegExp for each step with timeout and match count protection
- * to prevent runaway regex operations from hanging the application.
- *
- * @param pattern The compiled RegExp to run
- * @param content The content to search
- * @param options Runtime limits
- * @returns Result containing matches and truncation status
- *
- * @example
- * ```typescript
- * const pattern = /test\d+/g;
- * const { matches, truncated } = runBounded(pattern, content, { maxMs: 500 });
- * if (truncated) {
- *   console.warn('Regex operation was truncated');
- * }
- * ```
+ * 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;
@@ -76,20 +89,16 @@ export function runBounded(pattern, content, options = {}) {
     const matches = [];
     let match;
     while ((match = pattern.exec(content)) !== null) {
-        // Check time limit
         if (Date.now() > deadline) {
             return { matches, truncated: true };
         }
-        // Check match count limit
         if (matches.length >= maxMatches) {
             return { matches, truncated: true };
         }
         matches.push(match);
-        // For non-global patterns, break after first match to avoid infinite loop
         if (!pattern.global) {
             break;
         }
-        // Prevent infinite loop on zero-length matches for global patterns
         if (match[0].length === 0) {
             pattern.lastIndex++;
         }
@@ -98,27 +107,6 @@ export function runBounded(pattern, content, options = {}) {
 }
 /**
  * Safe pattern matching that combines compilation and bounded runtime.
- *
- * This is a convenience wrapper that safely compiles a pattern and runs
- * it with bounds, handling both compilation failures and runtime limits.
- *
- * @param rawPattern The raw pattern string
- * @param content The content to search
- * @param flags Regex flags (default: 'gi')
- * @param options Runtime limits
- * @returns Match result or null if pattern is unsafe
- *
- * @example
- * ```typescript
- * const result = safeMatch('test\\d+', content);
- * if (result === null) {
- *   console.warn('Unsafe or invalid pattern');
- * } else if (result.truncated) {
- *   console.warn('Pattern operation was bounded');
- * } else {
- *   console.log(`Found ${result.matches.length} matches`);
- * }
- * ```
  */
 export function safeMatch(rawPattern, content, flags = 'gi', options = {}) {
     const pattern = compileSafePattern(rawPattern, flags);
@@ -129,19 +117,14 @@ export function safeMatch(rawPattern, content, flags = 'gi', options = {}) {
 }
 /**
  * Test if a pattern matches content safely, returning boolean result.
- *
- * This is equivalent to RegExp.test() but with safety checks and bounds.
- * Returns false for unsafe patterns or bounded operations.
- *
- * @param rawPattern The raw pattern string
- * @param content The content to test
- * @param flags Regex flags (default: 'i')
- * @returns True if pattern matches safely, false otherwise
  */
 export function safeTest(rawPattern, content, flags = 'i') {
-    // For test, we want to check if there's ANY match, so use non-global flags
-    const testFlags = flags.replace(/g/g, ''); // Remove global flag for test behavior
+    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

package/dist/utils/schemas.d.ts

@@ -18,8 +18,8 @@ export declare const ThreatIndicatorSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     category: string;
     value: string;
-    type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-    severity: "critical" | "high" | "medium" | "low";
+    type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+    severity: "high" | "medium" | "low" | "critical";
     description: string;
     confidence: number;
     source: string;
@@ -30,8 +30,8 @@ export declare const ThreatIndicatorSchema: z.ZodObject<{
 }, {
     category: string;
     value: string;
-    type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-    severity: "critical" | "high" | "medium" | "low";
+    type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+    severity: "high" | "medium" | "low" | "critical";
     description: string;
     confidence: number;
     source: string;
@@ -102,8 +102,8 @@ export declare const ThreatDatabaseSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         category: string;
         value: string;
-        type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-        severity: "critical" | "high" | "medium" | "low";
+        type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+        severity: "high" | "medium" | "low" | "critical";
         description: string;
         confidence: number;
         source: string;
@@ -114,8 +114,8 @@ export declare const ThreatDatabaseSchema: z.ZodObject<{
     }, {
         category: string;
         value: string;
-        type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-        severity: "critical" | "high" | "medium" | "low";
+        type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+        severity: "high" | "medium" | "low" | "critical";
         description: string;
         confidence: number;
         source: string;
@@ -154,8 +154,8 @@ export declare const ThreatDatabaseSchema: z.ZodObject<{
     indicators: {
         category: string;
         value: string;
-        type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-        severity: "critical" | "high" | "medium" | "low";
+        type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+        severity: "high" | "medium" | "low" | "critical";
         description: string;
         confidence: number;
         source: string;
@@ -184,8 +184,8 @@ export declare const ThreatDatabaseSchema: z.ZodObject<{
     indicators: {
         category: string;
         value: string;
-        type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-        severity: "critical" | "high" | "medium" | "low";
+        type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+        severity: "high" | "medium" | "low" | "critical";
         description: string;
         confidence: number;
         source: string;
@@ -246,16 +246,16 @@ export declare const QuarantineEntrySchema: z.ZodObject<{
     }>;
 }, "strip", z.ZodTypeAny, {
     id: string;
+    reason: string;
     metadata: {
         category: string;
         severity: string;
         riskScore: number;
         originalPermissions?: string | undefined;
     };
+    findings: any[];
     originalPath: string;
     quarantinePath: string;
-    reason: string;
-    findings: any[];
     quarantineDate: string;
     fileSize: number;
     fileHash: string;
@@ -263,16 +263,16 @@ export declare const QuarantineEntrySchema: z.ZodObject<{
     restoredDate?: string | undefined;
 }, {
     id: string;
+    reason: string;
     metadata: {
         category: string;
         severity: string;
         riskScore: number;
         originalPermissions?: string | undefined;
     };
+    findings: any[];
     originalPath: string;
     quarantinePath: string;
-    reason: string;
-    findings: any[];
     quarantineDate: string;
     fileSize: number;
     fileHash: string;
@@ -312,16 +312,16 @@ export declare const QuarantineDatabaseSchema: z.ZodObject<{
         }>;
     }, "strip", z.ZodTypeAny, {
         id: string;
+        reason: string;
         metadata: {
             category: string;
             severity: string;
             riskScore: number;
             originalPermissions?: string | undefined;
         };
+        findings: any[];
         originalPath: string;
         quarantinePath: string;
-        reason: string;
-        findings: any[];
         quarantineDate: string;
         fileSize: number;
         fileHash: string;
@@ -329,16 +329,16 @@ export declare const QuarantineDatabaseSchema: z.ZodObject<{
         restoredDate?: string | undefined;
     }, {
         id: string;
+        reason: string;
         metadata: {
             category: string;
             severity: string;
             riskScore: number;
             originalPermissions?: string | undefined;
         };
+        findings: any[];
         originalPath: string;
         quarantinePath: string;
-        reason: string;
-        findings: any[];
         quarantineDate: string;
         fileSize: number;
         fileHash: string;
@@ -364,16 +364,16 @@ export declare const QuarantineDatabaseSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     entries: {
         id: string;
+        reason: string;
         metadata: {
             category: string;
             severity: string;
             riskScore: number;
             originalPermissions?: string | undefined;
         };
+        findings: any[];
         originalPath: string;
         quarantinePath: string;
-        reason: string;
-        findings: any[];
         quarantineDate: string;
         fileSize: number;
         fileHash: string;
@@ -392,16 +392,16 @@ export declare const QuarantineDatabaseSchema: z.ZodObject<{
 }, {
     entries: {
         id: string;
+        reason: string;
         metadata: {
             category: string;
             severity: string;
             riskScore: number;
             originalPermissions?: string | undefined;
         };
+        findings: any[];
         originalPath: string;
         quarantinePath: string;
-        reason: string;
-        findings: any[];
         quarantineDate: string;
         fileSize: number;
         fileHash: string;
@@ -968,18 +968,18 @@ export declare const BaselineFindingSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     match: string;
     line: number;
-    hash: string;
     ruleId: string;
     file: string;
+    hash: string;
     acceptedDate: string;
     reason?: string | undefined;
     expiresDate?: string | undefined;
 }, {
     match: string;
     line: number;
-    hash: string;
     ruleId: string;
     file: string;
+    hash: string;
     acceptedDate: string;
     reason?: string | undefined;
     expiresDate?: string | undefined;
@@ -1001,18 +1001,18 @@ export declare const BaselineSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         match: string;
         line: number;
-        hash: string;
         ruleId: string;
         file: string;
+        hash: string;
         acceptedDate: string;
         reason?: string | undefined;
         expiresDate?: string | undefined;
     }, {
         match: string;
         line: number;
-        hash: string;
         ruleId: string;
         file: string;
+        hash: string;
         acceptedDate: string;
         reason?: string | undefined;
         expiresDate?: string | undefined;
@@ -1020,33 +1020,33 @@ export declare const BaselineSchema: z.ZodObject<{
     checksum: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     version: string;
-    lastUpdated: string;
     findings: {
         match: string;
         line: number;
-        hash: string;
         ruleId: string;
         file: string;
+        hash: string;
         acceptedDate: string;
         reason?: string | undefined;
         expiresDate?: string | undefined;
     }[];
+    lastUpdated: string;
     createdDate: string;
     description?: string | undefined;
     checksum?: string | undefined;
 }, {
     version: string;
-    lastUpdated: string;
     findings: {
         match: string;
         line: number;
-        hash: string;
         ruleId: string;
         file: string;
+        hash: string;
         acceptedDate: string;
         reason?: string | undefined;
         expiresDate?: string | undefined;
     }[];
+    lastUpdated: string;
     createdDate: string;
     description?: string | undefined;
     checksum?: string | undefined;
@@ -1091,8 +1091,8 @@ declare const _default: {
     }, "strip", z.ZodTypeAny, {
         category: string;
         value: string;
-        type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-        severity: "critical" | "high" | "medium" | "low";
+        type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+        severity: "high" | "medium" | "low" | "critical";
         description: string;
         confidence: number;
         source: string;
@@ -1103,8 +1103,8 @@ declare const _default: {
     }, {
         category: string;
         value: string;
-        type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-        severity: "critical" | "high" | "medium" | "low";
+        type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+        severity: "high" | "medium" | "low" | "critical";
         description: string;
         confidence: number;
         source: string;
@@ -1175,8 +1175,8 @@ declare const _default: {
         }, "strip", z.ZodTypeAny, {
             category: string;
             value: string;
-            type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-            severity: "critical" | "high" | "medium" | "low";
+            type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+            severity: "high" | "medium" | "low" | "critical";
             description: string;
             confidence: number;
             source: string;
@@ -1187,8 +1187,8 @@ declare const _default: {
         }, {
             category: string;
             value: string;
-            type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-            severity: "critical" | "high" | "medium" | "low";
+            type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+            severity: "high" | "medium" | "low" | "critical";
             description: string;
             confidence: number;
             source: string;
@@ -1227,8 +1227,8 @@ declare const _default: {
         indicators: {
             category: string;
             value: string;
-            type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-            severity: "critical" | "high" | "medium" | "low";
+            type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+            severity: "high" | "medium" | "low" | "critical";
             description: string;
             confidence: number;
             source: string;
@@ -1257,8 +1257,8 @@ declare const _default: {
         indicators: {
             category: string;
             value: string;
-            type: "domain" | "url" | "ip" | "hash" | "email" | "filename" | "package" | "pattern" | "signature";
-            severity: "critical" | "high" | "medium" | "low";
+            type: "url" | "pattern" | "domain" | "ip" | "hash" | "email" | "filename" | "package" | "signature";
+            severity: "high" | "medium" | "low" | "critical";
             description: string;
             confidence: number;
             source: string;
@@ -1303,16 +1303,16 @@ declare const _default: {
         }>;
     }, "strip", z.ZodTypeAny, {
         id: string;
+        reason: string;
         metadata: {
             category: string;
             severity: string;
             riskScore: number;
             originalPermissions?: string | undefined;
         };
+        findings: any[];
         originalPath: string;
         quarantinePath: string;
-        reason: string;
-        findings: any[];
         quarantineDate: string;
         fileSize: number;
         fileHash: string;
@@ -1320,16 +1320,16 @@ declare const _default: {
         restoredDate?: string | undefined;
     }, {
         id: string;
+        reason: string;
         metadata: {
             category: string;
             severity: string;
             riskScore: number;
             originalPermissions?: string | undefined;
         };
+        findings: any[];
         originalPath: string;
         quarantinePath: string;
-        reason: string;
-        findings: any[];
         quarantineDate: string;
         fileSize: number;
         fileHash: string;
@@ -1369,16 +1369,16 @@ declare const _default: {
             }>;
         }, "strip", z.ZodTypeAny, {
             id: string;
+            reason: string;
             metadata: {
                 category: string;
                 severity: string;
                 riskScore: number;
                 originalPermissions?: string | undefined;
             };
+            findings: any[];
             originalPath: string;
             quarantinePath: string;
-            reason: string;
-            findings: any[];
             quarantineDate: string;
             fileSize: number;
             fileHash: string;
@@ -1386,16 +1386,16 @@ declare const _default: {
             restoredDate?: string | undefined;
         }, {
             id: string;
+            reason: string;
             metadata: {
                 category: string;
                 severity: string;
                 riskScore: number;
                 originalPermissions?: string | undefined;
             };
+            findings: any[];
             originalPath: string;
             quarantinePath: string;
-            reason: string;
-            findings: any[];
             quarantineDate: string;
             fileSize: number;
             fileHash: string;
@@ -1421,16 +1421,16 @@ declare const _default: {
     }, "strip", z.ZodTypeAny, {
         entries: {
             id: string;
+            reason: string;
             metadata: {
                 category: string;
                 severity: string;
                 riskScore: number;
                 originalPermissions?: string | undefined;
             };
+            findings: any[];
             originalPath: string;
             quarantinePath: string;
-            reason: string;
-            findings: any[];
             quarantineDate: string;
             fileSize: number;
             fileHash: string;
@@ -1449,16 +1449,16 @@ declare const _default: {
     }, {
         entries: {
             id: string;
+            reason: string;
             metadata: {
                 category: string;
                 severity: string;
                 riskScore: number;
                 originalPermissions?: string | undefined;
             };
+            findings: any[];
             originalPath: string;
             quarantinePath: string;
-            reason: string;
-            findings: any[];
             quarantineDate: string;
             fileSize: number;
             fileHash: string;
@@ -2025,18 +2025,18 @@ declare const _default: {
     }, "strip", z.ZodTypeAny, {
         match: string;
         line: number;
-        hash: string;
         ruleId: string;
         file: string;
+        hash: string;
         acceptedDate: string;
         reason?: string | undefined;
         expiresDate?: string | undefined;
     }, {
         match: string;
         line: number;
-        hash: string;
         ruleId: string;
         file: string;
+        hash: string;
         acceptedDate: string;
         reason?: string | undefined;
         expiresDate?: string | undefined;
@@ -2058,18 +2058,18 @@ declare const _default: {
         }, "strip", z.ZodTypeAny, {
             match: string;
             line: number;
-            hash: string;
             ruleId: string;
             file: string;
+            hash: string;
             acceptedDate: string;
             reason?: string | undefined;
             expiresDate?: string | undefined;
         }, {
             match: string;
             line: number;
-            hash: string;
             ruleId: string;
             file: string;
+            hash: string;
             acceptedDate: string;
             reason?: string | undefined;
             expiresDate?: string | undefined;
@@ -2077,33 +2077,33 @@ declare const _default: {
         checksum: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         version: string;
-        lastUpdated: string;
         findings: {
             match: string;
             line: number;
-            hash: string;
             ruleId: string;
             file: string;
+            hash: string;
             acceptedDate: string;
             reason?: string | undefined;
             expiresDate?: string | undefined;
         }[];
+        lastUpdated: string;
         createdDate: string;
         description?: string | undefined;
         checksum?: string | undefined;
     }, {
         version: string;
-        lastUpdated: string;
         findings: {
             match: string;
             line: number;
-            hash: string;
             ruleId: string;
             file: string;
+            hash: string;
             acceptedDate: string;
             reason?: string | undefined;
             expiresDate?: string | undefined;
         }[];
+        lastUpdated: string;
         createdDate: string;
         description?: string | undefined;
         checksum?: string | undefined;