ferret-scan 1.0.0

package/dist/analyzers/CorrelationAnalyzer.js

@@ -0,0 +1,288 @@
+/**
+ * Correlation Analyzer - Cross-file attack pattern detection
+ * Detects sophisticated attack patterns that span multiple configuration files
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, relative } from 'node:path';
+import logger from '../utils/logger.js';
+/**
+ * Build file relationship map based on directory proximity and naming patterns
+ */
+function buildFileRelationships(files) {
+    const relationships = [];
+    for (const file of files) {
+        const related = [];
+        const fileDir = dirname(file.path);
+        for (const otherFile of files) {
+            if (file.path === otherFile.path)
+                continue;
+            const otherDir = dirname(otherFile.path);
+            const distance = calculateDirectoryDistance(fileDir, otherDir);
+            // Consider files related if they're in same directory or close proximity
+            if (distance <= 2) {
+                related.push(otherFile);
+            }
+            // Also consider files related by naming patterns
+            if (areFilesRelatedByNaming(file, otherFile)) {
+                related.push(otherFile);
+            }
+        }
+        relationships.push({
+            file,
+            relatedFiles: [...new Set(related)], // Remove duplicates
+            distance: 0
+        });
+    }
+    return relationships;
+}
+/**
+ * Calculate directory distance between two paths
+ */
+function calculateDirectoryDistance(path1, path2) {
+    const rel = relative(path1, path2);
+    if (rel === '')
+        return 0;
+    const parts = rel.split('/').filter(p => p && p !== '.');
+    return parts.length;
+}
+/**
+ * Check if files are related by naming patterns
+ */
+function areFilesRelatedByNaming(file1, file2) {
+    const name1 = file1.relativePath.toLowerCase();
+    const name2 = file2.relativePath.toLowerCase();
+    // Claude-specific relationships
+    const patterns = [
+        // hooks and skills
+        { pattern1: /hooks?\//, pattern2: /skills?\/|agents?\// },
+        // settings and configs
+        { pattern1: /settings\.json/, pattern2: /config\./ },
+        // claude.md and related configs
+        { pattern1: /claude\.md/, pattern2: /\.mcp\.json|settings\.json/ },
+        // agent and skill relationships
+        { pattern1: /agent/, pattern2: /skill/ },
+        // security-related files
+        { pattern1: /security|auth/, pattern2: /permission|access/ },
+    ];
+    for (const { pattern1, pattern2 } of patterns) {
+        if ((pattern1.test(name1) && pattern2.test(name2)) ||
+            (pattern2.test(name1) && pattern1.test(name2))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Find cross-file patterns
+ */
+function findCrossFilePatterns(relationships, correlationRules) {
+    const matches = [];
+    for (const rule of correlationRules) {
+        logger.debug(`Checking correlation rule: ${rule.id}`);
+        for (const relationship of relationships) {
+            const allFiles = [relationship.file, ...relationship.relatedFiles];
+            // Check if rule file patterns match
+            const matchingFiles = allFiles.filter(file => rule.filePatterns.some(pattern => file.relativePath.toLowerCase().includes(pattern.toLowerCase())));
+            if (matchingFiles.length < 2)
+                continue; // Need at least 2 files for correlation
+            // Find content patterns across files
+            const contentMatches = findContentPatternsAcrossFiles(matchingFiles, rule.contentPatterns);
+            if (contentMatches.length >= rule.contentPatterns.length) {
+                const strength = calculateCorrelationStrength(contentMatches, rule);
+                matches.push({
+                    rule,
+                    files: matchingFiles,
+                    patterns: contentMatches,
+                    strength
+                });
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Find content patterns across multiple files
+ */
+function findContentPatternsAcrossFiles(files, patterns) {
+    const matches = [];
+    for (const file of files) {
+        try {
+            const content = readFileSync(file.path, 'utf-8');
+            const lines = content.split('\n');
+            for (const pattern of patterns) {
+                const regex = new RegExp(pattern, 'gi');
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i] ?? '';
+                    const match = regex.exec(line);
+                    if (match) {
+                        matches.push({
+                            file,
+                            pattern,
+                            line: i + 1,
+                            match: match[0]
+                        });
+                        regex.lastIndex = 0; // Reset regex for next iteration
+                        break; // One match per pattern per file is enough
+                    }
+                }
+            }
+        }
+        catch (error) {
+            logger.warn(`Error reading file ${file.relativePath} for correlation analysis: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return matches;
+}
+/**
+ * Calculate correlation strength based on pattern matches
+ */
+function calculateCorrelationStrength(matches, rule) {
+    // Base strength from pattern coverage
+    const patternCoverage = matches.length / rule.contentPatterns.length;
+    // Bonus for multiple files involvement
+    const uniqueFiles = new Set(matches.map(m => m.file.path)).size;
+    const fileBonus = Math.min(uniqueFiles / rule.filePatterns.length, 1) * 0.2;
+    // Bonus for proximity (if files are close together)
+    const proximityBonus = 0.1;
+    return Math.min(patternCoverage + fileBonus + proximityBonus, 1);
+}
+/**
+ * Create context lines for correlation finding
+ */
+function createCorrelationContext(file, lineNumber) {
+    try {
+        const content = readFileSync(file.path, 'utf-8');
+        const lines = content.split('\n');
+        const contextLines = 3;
+        const start = Math.max(0, lineNumber - contextLines - 1);
+        const end = Math.min(lines.length, lineNumber + contextLines);
+        const context = [];
+        for (let i = start; i < end; i++) {
+            context.push({
+                lineNumber: i + 1,
+                content: lines[i] ?? '',
+                isMatch: i === lineNumber - 1
+            });
+        }
+        return context;
+    }
+    catch {
+        logger.warn(`Error creating context for ${file.relativePath}:${lineNumber}`);
+        return [];
+    }
+}
+/**
+ * Convert cross-file matches to correlation findings
+ */
+function createCorrelationFindings(matches, parentRule) {
+    const findings = [];
+    for (const match of matches) {
+        // Create a finding for the primary pattern
+        const primaryPattern = match.patterns[0];
+        if (!primaryPattern)
+            continue;
+        const context = createCorrelationContext(primaryPattern.file, primaryPattern.line);
+        const riskVectors = generateRiskVectors(match);
+        const finding = {
+            ruleId: parentRule.id,
+            ruleName: parentRule.name,
+            severity: parentRule.severity,
+            category: parentRule.category,
+            file: primaryPattern.file.path,
+            relativePath: primaryPattern.file.relativePath,
+            line: primaryPattern.line,
+            match: primaryPattern.match,
+            context,
+            remediation: parentRule.remediation,
+            metadata: {
+                correlationRule: match.rule,
+                relatedPatterns: match.patterns,
+                totalFiles: match.files.length
+            },
+            timestamp: new Date(),
+            riskScore: Math.round(match.strength * 100),
+            // Correlation-specific fields
+            relatedFiles: match.files.map(f => f.relativePath),
+            attackPattern: match.rule.description,
+            riskVectors,
+            correlationStrength: match.strength
+        };
+        findings.push(finding);
+    }
+    return findings;
+}
+/**
+ * Generate risk vectors for a cross-file match
+ */
+function generateRiskVectors(match) {
+    const vectors = [];
+    // Analyze the attack pattern
+    const description = match.rule.description.toLowerCase();
+    if (description.includes('credential') || description.includes('secret')) {
+        vectors.push('Credential Exposure');
+    }
+    if (description.includes('network') || description.includes('transmission')) {
+        vectors.push('Data Exfiltration');
+    }
+    if (description.includes('permission') || description.includes('escalation')) {
+        vectors.push('Privilege Escalation');
+    }
+    if (description.includes('backdoor') || description.includes('persistence')) {
+        vectors.push('Persistence Mechanism');
+    }
+    if (description.includes('obfuscation') || description.includes('hiding')) {
+        vectors.push('Steganography/Hiding');
+    }
+    // Add file-type specific vectors
+    const fileTypes = match.files.map(f => f.component);
+    if (fileTypes.includes('hook') && fileTypes.includes('skill')) {
+        vectors.push('Hook-Skill Chain');
+    }
+    if (fileTypes.includes('settings') && fileTypes.includes('ai-config-md')) {
+        vectors.push('Configuration Tampering');
+    }
+    return vectors.length > 0 ? vectors : ['Cross-File Coordination'];
+}
+/**
+ * Analyze files for cross-file correlation patterns
+ */
+export function analyzeCorrelations(files, rules) {
+    const findings = [];
+    try {
+        // Get rules with correlation patterns
+        const correlationRules = rules
+            .filter(rule => rule.correlationRules && rule.correlationRules.length > 0)
+            .flatMap(rule => rule.correlationRules.map(corrRule => ({ ...corrRule, parentRule: rule })));
+        if (correlationRules.length === 0 || files.length < 2) {
+            return findings;
+        }
+        logger.debug(`Cross-file correlation analysis with ${correlationRules.length} rules across ${files.length} files`);
+        // Build file relationships
+        const relationships = buildFileRelationships(files);
+        // Find cross-file patterns
+        const matches = findCrossFilePatterns(relationships, correlationRules.map(r => ({ ...r, parentRule: undefined })));
+        // Convert to findings
+        for (const match of matches) {
+            const parentRule = correlationRules.find(r => r.id === match.rule.id)?.parentRule;
+            if (parentRule) {
+                const correlationFindings = createCorrelationFindings([match], parentRule);
+                findings.push(...correlationFindings);
+            }
+        }
+    }
+    catch (error) {
+        logger.error(`Error in cross-file correlation analysis: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return findings;
+}
+/**
+ * Check if correlation analysis should be performed
+ */
+export function shouldAnalyzeCorrelations(files, config) {
+    return config.correlationAnalysis && files.length >= 2;
+}
+export default {
+    analyzeCorrelations,
+    shouldAnalyzeCorrelations
+};
+//# sourceMappingURL=CorrelationAnalyzer.js.map

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ferret-Scan - Security scanner for AI CLI configurations
+ *
+ * @packageDocumentation
+ */
+export type { Severity, ThreatCategory, ComponentType, FileType, Rule, Finding, ContextLine, DiscoveredFile, ScanResult, ScanSummary, ScanError, ScannerConfig, OutputFormat, CliOptions, ConfigFile, } from './types.js';
+export { DEFAULT_CONFIG, SEVERITY_WEIGHTS, SEVERITY_ORDER } from './types.js';
+export { scan, getExitCode } from './scanner/Scanner.js';
+export { discoverFiles } from './scanner/FileDiscovery.js';
+export { matchRules, matchRule, createPatternMatcher } from './scanner/PatternMatcher.js';
+export { getAllRules, getRulesByCategories, getRulesBySeverity, getRuleById, getEnabledRules, getRulesForScan, getRuleStats, } from './rules/index.js';
+export { generateConsoleReport } from './reporters/ConsoleReporter.js';
+export { loadConfig, getAIConfigPaths } from './utils/config.js';
+export { getClaudeConfigPaths } from './utils/config.js';
+export { createIgnoreFilter, shouldIgnore } from './utils/ignore.js';
+export { logger } from './utils/logger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * Ferret-Scan - Security scanner for AI CLI configurations
+ *
+ * @packageDocumentation
+ */
+export { DEFAULT_CONFIG, SEVERITY_WEIGHTS, SEVERITY_ORDER } from './types.js';
+// Scanner
+export { scan, getExitCode } from './scanner/Scanner.js';
+export { discoverFiles } from './scanner/FileDiscovery.js';
+export { matchRules, matchRule, createPatternMatcher } from './scanner/PatternMatcher.js';
+// Rules
+export { getAllRules, getRulesByCategories, getRulesBySeverity, getRuleById, getEnabledRules, getRulesForScan, getRuleStats, } from './rules/index.js';
+// Reporters
+export { generateConsoleReport } from './reporters/ConsoleReporter.js';
+// Utils
+export { loadConfig, getAIConfigPaths } from './utils/config.js';
+// Re-export deprecated for backwards compatibility
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+export { getClaudeConfigPaths } from './utils/config.js';
+export { createIgnoreFilter, shouldIgnore } from './utils/ignore.js';
+export { logger } from './utils/logger.js';
+//# sourceMappingURL=index.js.map

package/dist/intelligence/IndicatorMatcher.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Indicator Matcher - Matches content against threat intelligence indicators
+ * Provides fast lookup and matching of IoCs against scanned content
+ */
+import type { ThreatDatabase, ThreatIndicator, IndicatorType } from './ThreatFeed.js';
+import type { Finding, DiscoveredFile } from '../types.js';
+/**
+ * Threat intelligence finding
+ */
+export interface ThreatIntelFinding extends Finding {
+    /** Matched threat indicator */
+    threatIndicator: ThreatIndicator;
+    /** Match confidence (0-100) */
+    matchConfidence: number;
+    /** Additional threat context */
+    threatContext: {
+        indicatorType: IndicatorType;
+        threatSource: string;
+        firstSeen: string;
+        lastSeen: string;
+        threatTags: string[];
+    };
+}
+/**
+ * Matcher configuration
+ */
+interface MatcherConfig {
+    /** Minimum confidence threshold for matches */
+    minConfidence: number;
+    /** Whether to match patterns (can be expensive) */
+    enablePatternMatching: boolean;
+    /** Maximum number of matches per file */
+    maxMatchesPerFile: number;
+}
+/**
+ * Match all indicators against content
+ */
+export declare function matchIndicators(db: ThreatDatabase, file: DiscoveredFile, content: string, config?: Partial<MatcherConfig>): ThreatIntelFinding[];
+/**
+ * Check if threat intelligence matching should be performed
+ */
+export declare function shouldMatchIndicators(_file: DiscoveredFile, config: {
+    threatIntel: boolean;
+}): boolean;
+declare const _default: {
+    matchIndicators: typeof matchIndicators;
+    shouldMatchIndicators: typeof shouldMatchIndicators;
+};
+export default _default;
+//# sourceMappingURL=IndicatorMatcher.d.ts.map

package/dist/intelligence/IndicatorMatcher.js

@@ -0,0 +1,285 @@
+/**
+ * Indicator Matcher - Matches content against threat intelligence indicators
+ * Provides fast lookup and matching of IoCs against scanned content
+ */
+import logger from '../utils/logger.js';
+/**
+ * Default matcher configuration
+ */
+const DEFAULT_CONFIG = {
+    minConfidence: 50,
+    enablePatternMatching: true,
+    maxMatchesPerFile: 100
+};
+/**
+ * Pre-compiled pattern cache for performance
+ */
+const patternCache = new Map();
+/**
+ * Get or create compiled regex pattern
+ */
+function getCompiledPattern(pattern) {
+    if (!patternCache.has(pattern)) {
+        try {
+            const regex = new RegExp(pattern, 'gi');
+            patternCache.set(pattern, regex);
+        }
+        catch {
+            logger.warn(`Invalid regex pattern: ${pattern}`);
+            // Return a regex that never matches
+            patternCache.set(pattern, /(?!.*)/);
+        }
+    }
+    return patternCache.get(pattern);
+}
+/**
+ * Create context lines for threat intel finding
+ */
+function createThreatContext(_file, content, line, contextLines = 3) {
+    const lines = content.split('\n');
+    const start = Math.max(0, line - contextLines);
+    const end = Math.min(lines.length, line + contextLines + 1);
+    const context = [];
+    for (let i = start; i < end; i++) {
+        context.push({
+            lineNumber: i + 1,
+            content: lines[i] ?? '',
+            isMatch: i === line
+        });
+    }
+    return context;
+}
+/**
+ * Calculate match confidence based on context and indicator confidence
+ */
+function calculateMatchConfidence(indicator, matchContext) {
+    let confidence = indicator.confidence;
+    // Boost confidence for exact matches
+    if (matchContext.exactMatch) {
+        confidence = Math.min(100, confidence + 10);
+    }
+    // Adjust based on file context
+    if (matchContext.component === 'hook' || matchContext.component === 'skill') {
+        confidence = Math.min(100, confidence + 5);
+    }
+    // Adjust based on file type relevance
+    if (indicator.type === 'package' && matchContext.fileType === 'json') {
+        confidence = Math.min(100, confidence + 5);
+    }
+    return confidence;
+}
+/**
+ * Match domain indicators in content
+ */
+function matchDomains(content, indicators, file, config) {
+    const findings = [];
+    const lines = content.split('\n');
+    for (const indicator of indicators) {
+        if (indicator.type !== 'domain')
+            continue;
+        const domain = indicator.value;
+        const regex = new RegExp(`\\b${domain.replace('.', '\\.')}\\b`, 'gi');
+        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+            const line = lines[lineIndex] ?? '';
+            const match = regex.test(line);
+            if (match && findings.length < config.maxMatchesPerFile) {
+                const confidence = calculateMatchConfidence(indicator, {
+                    exactMatch: true,
+                    fileType: file.type,
+                    component: file.component
+                });
+                if (confidence >= config.minConfidence) {
+                    findings.push(createThreatIntelFinding(indicator, file, content, lineIndex + 1, domain, confidence));
+                }
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Match package indicators in content
+ */
+function matchPackages(content, indicators, file, config) {
+    const findings = [];
+    const lines = content.split('\n');
+    for (const indicator of indicators) {
+        if (indicator.type !== 'package')
+            continue;
+        const packageName = indicator.value;
+        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+            const line = lines[lineIndex] ?? '';
+            // Simple string matching for package names
+            if (line.toLowerCase().includes(packageName.toLowerCase()) &&
+                findings.length < config.maxMatchesPerFile) {
+                const confidence = calculateMatchConfidence(indicator, {
+                    exactMatch: true,
+                    fileType: file.type,
+                    component: file.component
+                });
+                if (confidence >= config.minConfidence) {
+                    findings.push(createThreatIntelFinding(indicator, file, content, lineIndex + 1, packageName, confidence));
+                }
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Match pattern indicators in content
+ */
+function matchPatterns(content, indicators, file, config) {
+    if (!config.enablePatternMatching) {
+        return [];
+    }
+    const findings = [];
+    const lines = content.split('\n');
+    for (const indicator of indicators) {
+        if (indicator.type !== 'pattern')
+            continue;
+        const regex = getCompiledPattern(indicator.value);
+        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+            const line = lines[lineIndex] ?? '';
+            const match = regex.test(line);
+            if (match && findings.length < config.maxMatchesPerFile) {
+                const confidence = calculateMatchConfidence(indicator, {
+                    exactMatch: false,
+                    fileType: file.type,
+                    component: file.component
+                });
+                if (confidence >= config.minConfidence) {
+                    findings.push(createThreatIntelFinding(indicator, file, content, lineIndex + 1, indicator.value, confidence));
+                }
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Match hash indicators in content
+ */
+function matchHashes(content, indicators, file, config) {
+    const findings = [];
+    for (const indicator of indicators) {
+        if (indicator.type !== 'hash')
+            continue;
+        const hash = indicator.value.toLowerCase();
+        // Simple hash matching
+        if (content.toLowerCase().includes(hash)) {
+            const lines = content.split('\n');
+            for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+                const line = lines[lineIndex] ?? '';
+                if (line.toLowerCase().includes(hash) && findings.length < config.maxMatchesPerFile) {
+                    const confidence = calculateMatchConfidence(indicator, {
+                        exactMatch: true,
+                        fileType: file.type,
+                        component: file.component
+                    });
+                    if (confidence >= config.minConfidence) {
+                        findings.push(createThreatIntelFinding(indicator, file, content, lineIndex + 1, hash, confidence));
+                    }
+                    break; // Only match once per file
+                }
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Create threat intelligence finding
+ */
+function createThreatIntelFinding(indicator, file, content, line, match, confidence) {
+    return {
+        ruleId: `THREAT-${indicator.type.toUpperCase()}-${indicator.source.toUpperCase().replace(/-/g, '_')}`,
+        ruleName: `Threat Intelligence: ${indicator.description}`,
+        severity: indicator.severity === 'critical' ? 'CRITICAL' :
+            indicator.severity === 'high' ? 'HIGH' :
+                indicator.severity === 'medium' ? 'MEDIUM' : 'LOW',
+        category: 'behavioral',
+        file: file.path,
+        relativePath: file.relativePath,
+        line,
+        match,
+        context: createThreatContext(file, content, line - 1),
+        remediation: `Review and remove this ${indicator.type} indicator. ${indicator.description}`,
+        metadata: {
+            threatIntelligence: true,
+            indicator,
+            threatSource: indicator.source,
+            threatTags: indicator.tags
+        },
+        timestamp: new Date(),
+        riskScore: confidence,
+        // Threat-specific fields
+        threatIndicator: indicator,
+        matchConfidence: confidence,
+        threatContext: {
+            indicatorType: indicator.type,
+            threatSource: indicator.source,
+            firstSeen: indicator.firstSeen,
+            lastSeen: indicator.lastSeen,
+            threatTags: indicator.tags
+        }
+    };
+}
+/**
+ * Match all indicators against content
+ */
+export function matchIndicators(db, file, content, config = {}) {
+    const matcherConfig = { ...DEFAULT_CONFIG, ...config };
+    const findings = [];
+    try {
+        logger.debug(`Matching threat indicators against ${file.relativePath}`);
+        // Get enabled indicators with minimum confidence
+        const eligibleIndicators = db.indicators.filter(indicator => indicator.confidence >= matcherConfig.minConfidence);
+        if (eligibleIndicators.length === 0) {
+            return findings;
+        }
+        // Group indicators by type for efficient matching
+        const indicatorsByType = new Map();
+        for (const indicator of eligibleIndicators) {
+            if (!indicatorsByType.has(indicator.type)) {
+                indicatorsByType.set(indicator.type, []);
+            }
+            indicatorsByType.get(indicator.type).push(indicator);
+        }
+        // Match each indicator type
+        for (const [type, indicators] of indicatorsByType) {
+            switch (type) {
+                case 'domain':
+                case 'url':
+                    findings.push(...matchDomains(content, indicators, file, matcherConfig));
+                    break;
+                case 'package':
+                    findings.push(...matchPackages(content, indicators, file, matcherConfig));
+                    break;
+                case 'pattern':
+                    findings.push(...matchPatterns(content, indicators, file, matcherConfig));
+                    break;
+                case 'hash':
+                    findings.push(...matchHashes(content, indicators, file, matcherConfig));
+                    break;
+                // Additional types can be added here
+            }
+            // Respect max matches limit
+            if (findings.length >= matcherConfig.maxMatchesPerFile) {
+                break;
+            }
+        }
+        logger.debug(`Found ${findings.length} threat intelligence matches in ${file.relativePath}`);
+    }
+    catch (error) {
+        logger.error(`Error matching threat indicators in ${file.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return findings;
+}
+/**
+ * Check if threat intelligence matching should be performed
+ */
+export function shouldMatchIndicators(_file, config) {
+    return config.threatIntel;
+}
+export default {
+    matchIndicators,
+    shouldMatchIndicators
+};
+//# sourceMappingURL=IndicatorMatcher.js.map