ferret-scan 1.0.0

package/dist/scanner/PatternMatcher.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PatternMatcher - Regex-based pattern matching engine
+ * Applies security rules to file content
+ */
+import type { Rule, Finding, DiscoveredFile } from '../types.js';
+interface MatchOptions {
+    contextLines: number;
+}
+/**
+ * Match a single rule against file content
+ */
+export declare function matchRule(rule: Rule, file: DiscoveredFile, content: string, options: MatchOptions): Finding[];
+/**
+ * Match all rules against file content
+ */
+export declare function matchRules(rules: Rule[], file: DiscoveredFile, content: string, options: MatchOptions): Finding[];
+/**
+ * Create a PatternMatcher instance
+ */
+export declare function createPatternMatcher(options: MatchOptions): {
+    matchRule: (rule: Rule, file: DiscoveredFile, content: string) => Finding[];
+    matchRules: (rules: Rule[], file: DiscoveredFile, content: string) => Finding[];
+};
+export default createPatternMatcher;
+//# sourceMappingURL=PatternMatcher.d.ts.map

package/dist/scanner/PatternMatcher.js

@@ -0,0 +1,206 @@
+/**
+ * PatternMatcher - Regex-based pattern matching engine
+ * Applies security rules to file content
+ */
+import { SEVERITY_WEIGHTS } from '../types.js';
+import logger from '../utils/logger.js';
+/**
+ * Split content into lines
+ */
+function splitLines(content) {
+    return content.split(/\r?\n/);
+}
+/**
+ * Find line number and column for a given offset
+ */
+function getLineAndColumn(content, offset) {
+    const lines = content.slice(0, offset).split(/\r?\n/);
+    const line = lines.length;
+    const column = (lines[lines.length - 1]?.length ?? 0) + 1;
+    return { line, column };
+}
+/**
+ * Get context lines around a match
+ */
+function getContext(lines, matchLine, contextCount) {
+    const context = [];
+    const startLine = Math.max(0, matchLine - contextCount - 1);
+    const endLine = Math.min(lines.length, matchLine + contextCount);
+    for (let i = startLine; i < endLine; i++) {
+        context.push({
+            lineNumber: i + 1,
+            content: lines[i] ?? '',
+            isMatch: i === matchLine - 1,
+        });
+    }
+    return context;
+}
+/**
+ * Calculate risk score based on severity and context
+ */
+function calculateRiskScore(severity, matchCount, fileComponent) {
+    let score = SEVERITY_WEIGHTS[severity];
+    // Multiply by match count (diminishing returns)
+    if (matchCount > 1) {
+        score = Math.min(100, score + Math.log2(matchCount) * 10);
+    }
+    // Increase score for high-risk components
+    const highRiskComponents = ['hook', 'plugin', 'mcp'];
+    if (highRiskComponents.includes(fileComponent)) {
+        score = Math.min(100, score * 1.2);
+    }
+    return Math.round(score);
+}
+/**
+ * Find all pattern matches in content using global regex search
+ */
+function findMatches(content, patterns) {
+    const matches = [];
+    for (const pattern of patterns) {
+        // Create a new regex with global flag
+        const globalPattern = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : pattern.flags + 'g');
+        let match;
+        while ((match = globalPattern.exec(content)) !== null) {
+            const { line, column } = getLineAndColumn(content, match.index);
+            matches.push({
+                pattern,
+                match,
+                lineNumber: line,
+                column,
+            });
+        }
+    }
+    return matches;
+}
+/**
+ * Check if a match should be excluded based on rule filters
+ */
+function shouldExcludeMatch(rule, matchText, lineContent, contextLines) {
+    // Check minimum match length
+    if (rule.minMatchLength && matchText.length < rule.minMatchLength) {
+        return true;
+    }
+    // Check exclude patterns (false positive filters)
+    if (rule.excludePatterns) {
+        for (const excludePattern of rule.excludePatterns) {
+            if (excludePattern.test(lineContent)) {
+                logger.debug(`[${rule.id}] Excluded by excludePattern: ${lineContent.slice(0, 50)}`);
+                return true;
+            }
+        }
+    }
+    // Check exclude context (documentation indicators)
+    if (rule.excludeContext) {
+        const fullContext = contextLines.join('\n');
+        for (const excludeCtx of rule.excludeContext) {
+            if (excludeCtx.test(fullContext)) {
+                logger.debug(`[${rule.id}] Excluded by excludeContext`);
+                return true;
+            }
+        }
+    }
+    // Check require context (must be present)
+    if (rule.requireContext && rule.requireContext.length > 0) {
+        const fullContext = contextLines.join('\n');
+        let hasRequiredContext = false;
+        for (const reqCtx of rule.requireContext) {
+            if (reqCtx.test(fullContext)) {
+                hasRequiredContext = true;
+                break;
+            }
+        }
+        if (!hasRequiredContext) {
+            logger.debug(`[${rule.id}] Missing required context`);
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if a rule applies to a file
+ */
+function ruleApplies(rule, file) {
+    // Check file type
+    if (!rule.fileTypes.includes(file.type)) {
+        return false;
+    }
+    // Check component type
+    if (!rule.components.includes(file.component)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Match a single rule against file content
+ */
+export function matchRule(rule, file, content, options) {
+    if (!ruleApplies(rule, file)) {
+        return [];
+    }
+    const findings = [];
+    const lines = splitLines(content);
+    const matches = findMatches(content, rule.patterns);
+    // Group matches by line to avoid duplicates
+    const matchesByLine = new Map();
+    for (const match of matches) {
+        const existing = matchesByLine.get(match.lineNumber) ?? [];
+        existing.push(match);
+        matchesByLine.set(match.lineNumber, existing);
+    }
+    for (const [lineNumber, lineMatches] of matchesByLine) {
+        const firstMatch = lineMatches[0];
+        if (!firstMatch)
+            continue;
+        const matchText = firstMatch.match[0];
+        const lineContent = lines[lineNumber - 1] ?? '';
+        const contextForCheck = getContext(lines, lineNumber, options.contextLines);
+        const contextStrings = contextForCheck.map(c => c.content);
+        // Check if this match should be excluded (false positive filter)
+        if (shouldExcludeMatch(rule, matchText, lineContent, contextStrings)) {
+            continue;
+        }
+        const finding = {
+            ruleId: rule.id,
+            ruleName: rule.name,
+            severity: rule.severity,
+            category: rule.category,
+            file: file.path,
+            relativePath: file.relativePath,
+            line: lineNumber,
+            column: firstMatch.column,
+            match: matchText,
+            context: contextForCheck,
+            remediation: rule.remediation,
+            timestamp: new Date(),
+            riskScore: calculateRiskScore(rule.severity, lineMatches.length, file.component),
+        };
+        findings.push(finding);
+        logger.debug(`[${rule.id}] Found in ${file.relativePath}:${lineNumber}: ${matchText.slice(0, 50)}`);
+    }
+    return findings;
+}
+/**
+ * Match all rules against file content
+ */
+export function matchRules(rules, file, content, options) {
+    const findings = [];
+    for (const rule of rules) {
+        if (!rule.enabled) {
+            continue;
+        }
+        const ruleFindings = matchRule(rule, file, content, options);
+        findings.push(...ruleFindings);
+    }
+    return findings;
+}
+/**
+ * Create a PatternMatcher instance
+ */
+export function createPatternMatcher(options) {
+    return {
+        matchRule: (rule, file, content) => matchRule(rule, file, content, options),
+        matchRules: (rules, file, content) => matchRules(rules, file, content, options),
+    };
+}
+export default createPatternMatcher;
+//# sourceMappingURL=PatternMatcher.js.map

package/dist/scanner/Scanner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Scanner - Core orchestrator for Ferret security scanning
+ */
+import type { ScannerConfig, ScanResult } from '../types.js';
+/**
+ * Main scan function
+ */
+export declare function scan(config: ScannerConfig): Promise<ScanResult>;
+/**
+ * Determine exit code based on findings and config
+ */
+export declare function getExitCode(result: ScanResult, config: ScannerConfig): number;
+export default scan;
+//# sourceMappingURL=Scanner.d.ts.map

package/dist/scanner/Scanner.js

@@ -0,0 +1,266 @@
+/**
+ * Scanner - Core orchestrator for Ferret security scanning
+ */
+import { readFileSync } from 'node:fs';
+import { SEVERITY_ORDER, SEVERITY_WEIGHTS } from '../types.js';
+import { discoverFiles } from './FileDiscovery.js';
+import { matchRules } from './PatternMatcher.js';
+import { getRulesForScan } from '../rules/index.js';
+import { analyzeFile as analyzeFileSemantics, shouldAnalyze as shouldAnalyzeSemantics, getMemoryUsage } from '../analyzers/AstAnalyzer.js';
+import { analyzeCorrelations, shouldAnalyzeCorrelations } from '../analyzers/CorrelationAnalyzer.js';
+import { loadThreatDatabase } from '../intelligence/ThreatFeed.js';
+import { matchIndicators, shouldMatchIndicators } from '../intelligence/IndicatorMatcher.js';
+import logger from '../utils/logger.js';
+/**
+ * Create an empty scan summary
+ */
+function createEmptySummary() {
+    return {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        info: 0,
+        total: 0,
+    };
+}
+/**
+ * Calculate overall risk score from findings
+ */
+function calculateOverallRiskScore(findings) {
+    if (findings.length === 0)
+        return 0;
+    const totalWeight = findings.reduce((sum, finding) => {
+        return sum + SEVERITY_WEIGHTS[finding.severity];
+    }, 0);
+    // Normalize to 0-100 scale with diminishing returns
+    const normalizedScore = Math.min(100, Math.log1p(totalWeight) * 15);
+    return Math.round(normalizedScore);
+}
+/**
+ * Group findings by severity
+ */
+function groupBySeverity(findings) {
+    const grouped = {
+        CRITICAL: [],
+        HIGH: [],
+        MEDIUM: [],
+        LOW: [],
+        INFO: [],
+    };
+    for (const finding of findings) {
+        grouped[finding.severity].push(finding);
+    }
+    return grouped;
+}
+/**
+ * Group findings by category
+ */
+function groupByCategory(findings) {
+    const grouped = {};
+    for (const finding of findings) {
+        grouped[finding.category] ??= [];
+        grouped[finding.category].push(finding);
+    }
+    return grouped;
+}
+/**
+ * Calculate summary from findings
+ */
+function calculateSummary(findings) {
+    const summary = createEmptySummary();
+    for (const finding of findings) {
+        switch (finding.severity) {
+            case 'CRITICAL':
+                summary.critical++;
+                break;
+            case 'HIGH':
+                summary.high++;
+                break;
+            case 'MEDIUM':
+                summary.medium++;
+                break;
+            case 'LOW':
+                summary.low++;
+                break;
+            case 'INFO':
+                summary.info++;
+                break;
+        }
+        summary.total++;
+    }
+    return summary;
+}
+/**
+ * Sort findings by severity (most severe first)
+ */
+function sortFindings(findings) {
+    return findings.sort((a, b) => {
+        const severityDiff = SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity);
+        if (severityDiff !== 0)
+            return severityDiff;
+        // Then by risk score
+        if (a.riskScore !== b.riskScore)
+            return b.riskScore - a.riskScore;
+        // Then by file
+        return a.relativePath.localeCompare(b.relativePath);
+    });
+}
+/**
+ * Scan a single file
+ */
+function scanFile(file, config) {
+    try {
+        const content = readFileSync(file.path, 'utf-8');
+        const rules = getRulesForScan(config.categories, config.severities);
+        const allFindings = [];
+        // Regular pattern matching
+        const patternFindings = matchRules(rules, file, content, {
+            contextLines: config.contextLines,
+        });
+        allFindings.push(...patternFindings);
+        // Semantic analysis if enabled and applicable
+        if (config.semanticAnalysis && shouldAnalyzeSemantics(file, config)) {
+            // Monitor memory usage
+            const memBefore = getMemoryUsage();
+            if (memBefore.used > 1000) { // More than 1GB used
+                logger.warn(`High memory usage (${memBefore.used}MB) - skipping semantic analysis for ${file.relativePath}`);
+            }
+            else {
+                try {
+                    logger.debug(`Running semantic analysis on ${file.relativePath}`);
+                    const semanticFindings = analyzeFileSemantics(file, content, rules);
+                    // Convert SemanticFinding to Finding for compatibility
+                    allFindings.push(...semanticFindings);
+                    const memAfter = getMemoryUsage();
+                    logger.debug(`Semantic analysis memory: ${memAfter.used - memBefore.used}MB delta`);
+                }
+                catch (semanticError) {
+                    const semanticMessage = semanticError instanceof Error ? semanticError.message : String(semanticError);
+                    logger.warn(`Semantic analysis error for ${file.relativePath}: ${semanticMessage}`);
+                }
+            }
+        }
+        // Threat intelligence matching if enabled
+        if (config.threatIntel && shouldMatchIndicators(file, config)) {
+            try {
+                const threatDB = loadThreatDatabase();
+                logger.debug(`Running threat intelligence matching on ${file.relativePath}`);
+                const threatFindings = matchIndicators(threatDB, file, content, {
+                    minConfidence: 50,
+                    enablePatternMatching: true,
+                    maxMatchesPerFile: 50
+                });
+                allFindings.push(...threatFindings);
+                logger.debug(`Found ${threatFindings.length} threat intelligence matches`);
+            }
+            catch (threatError) {
+                const threatMessage = threatError instanceof Error ? threatError.message : String(threatError);
+                logger.warn(`Threat intelligence error for ${file.relativePath}: ${threatMessage}`);
+            }
+        }
+        return { findings: allFindings };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(`Error scanning ${file.relativePath}: ${message}`);
+        return { findings: [], error: message };
+    }
+}
+/**
+ * Main scan function
+ */
+export async function scan(config) {
+    const startTime = new Date();
+    const allFindings = [];
+    const errors = [];
+    logger.info(`Starting scan of ${config.paths.length} path(s)`);
+    // Discover files
+    const discovery = discoverFiles(config.paths, {
+        maxFileSize: config.maxFileSize,
+        ignore: config.ignore,
+    });
+    // Add discovery errors
+    for (const error of discovery.errors) {
+        errors.push({
+            file: error.path,
+            message: error.error,
+            fatal: false,
+        });
+    }
+    if (discovery.files.length === 0) {
+        logger.warn('No files found to scan');
+    }
+    // Scan each file
+    for (const file of discovery.files) {
+        logger.debug(`Scanning: ${file.relativePath}`);
+        const result = scanFile(file, config);
+        if (result.error) {
+            errors.push({
+                file: file.path,
+                message: result.error,
+                fatal: false,
+            });
+        }
+        allFindings.push(...result.findings);
+    }
+    // Cross-file correlation analysis if enabled
+    if (shouldAnalyzeCorrelations(discovery.files, config)) {
+        try {
+            logger.debug('Running cross-file correlation analysis');
+            const correlationFindings = analyzeCorrelations(discovery.files, getRulesForScan(config.categories, config.severities));
+            allFindings.push(...correlationFindings);
+            logger.debug(`Found ${correlationFindings.length} correlation findings`);
+        }
+        catch (correlationError) {
+            const correlationMessage = correlationError instanceof Error ? correlationError.message : String(correlationError);
+            logger.warn(`Correlation analysis error: ${correlationMessage}`);
+            errors.push({
+                message: `Correlation analysis failed: ${correlationMessage}`,
+                fatal: false,
+            });
+        }
+    }
+    // Sort findings
+    const sortedFindings = sortFindings(allFindings);
+    const endTime = new Date();
+    const duration = endTime.getTime() - startTime.getTime();
+    const result = {
+        success: true,
+        startTime,
+        endTime,
+        duration,
+        scannedPaths: config.paths,
+        totalFiles: discovery.files.length + discovery.skipped,
+        analyzedFiles: discovery.files.length,
+        skippedFiles: discovery.skipped,
+        findings: sortedFindings,
+        findingsBySeverity: groupBySeverity(sortedFindings),
+        findingsByCategory: groupByCategory(sortedFindings),
+        overallRiskScore: calculateOverallRiskScore(sortedFindings),
+        summary: calculateSummary(sortedFindings),
+        errors,
+    };
+    logger.info(`Scan complete: ${result.summary.total} findings in ${result.analyzedFiles} files (${duration}ms)`);
+    return result;
+}
+/**
+ * Determine exit code based on findings and config
+ */
+export function getExitCode(result, config) {
+    if (!result.success)
+        return 3; // Scanner error
+    const failOnIndex = SEVERITY_ORDER.indexOf(config.failOn);
+    // Check if any finding meets or exceeds the fail threshold
+    for (const severity of SEVERITY_ORDER.slice(0, failOnIndex + 1)) {
+        if (result.findingsBySeverity[severity].length > 0) {
+            // Critical findings always return 2
+            if (severity === 'CRITICAL')
+                return 2;
+            return 1;
+        }
+    }
+    return 0; // No findings at or above threshold
+}
+export default scan;
+//# sourceMappingURL=Scanner.js.map

package/dist/scanner/WatchMode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WatchMode - Real-time file watching and scanning
+ * Monitors files for changes and automatically rescans
+ */
+import type { ScannerConfig } from '../types.js';
+interface WatchOptions {
+    debounceMs: number;
+    batchChanges: boolean;
+    ignored: string[];
+}
+/**
+ * Start watching files and scanning on changes
+ */
+export declare function startWatchMode(config: ScannerConfig, options?: Partial<WatchOptions>): Promise<() => void>;
+/**
+ * Watch mode with enhanced console output
+ */
+export declare function startEnhancedWatchMode(config: ScannerConfig, options?: Partial<WatchOptions>): Promise<() => void>;
+/**
+ * Create a simple file change notifier
+ */
+export declare function createChangeNotifier(paths: string[], callback: (changedFiles: string[]) => void, options?: Partial<WatchOptions>): () => void;
+declare const _default: {
+    startWatchMode: typeof startWatchMode;
+    startEnhancedWatchMode: typeof startEnhancedWatchMode;
+    createChangeNotifier: typeof createChangeNotifier;
+};
+export default _default;
+//# sourceMappingURL=WatchMode.d.ts.map