ferret-scan 1.0.0

package/dist/scanner/WatchMode.js

@@ -0,0 +1,195 @@
+/**
+ * WatchMode - Real-time file watching and scanning
+ * Monitors files for changes and automatically rescans
+ */
+import chokidar from 'chokidar';
+import { scan } from './Scanner.js';
+import { generateConsoleReport } from '../reporters/ConsoleReporter.js';
+import logger from '../utils/logger.js';
+const DEFAULT_WATCH_OPTIONS = {
+    debounceMs: 1000, // Wait 1 second after last change
+    batchChanges: true, // Batch multiple changes together
+    ignored: [
+        '**/node_modules/**',
+        '**/.git/**',
+        '**/dist/**',
+        '**/build/**',
+        '**/*.log',
+        '**/tmp/**',
+        '**/.DS_Store',
+    ],
+};
+/**
+ * Debounce function calls
+ */
+function debounce(func, wait) {
+    let timeout;
+    return (...args) => {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => { func(...args); }, wait);
+    };
+}
+/**
+ * Start watching files and scanning on changes
+ */
+export async function startWatchMode(config, options = {}) {
+    const watchOptions = { ...DEFAULT_WATCH_OPTIONS, ...options };
+    const events = [];
+    let isScanning = false;
+    logger.info(`🔍 Starting watch mode for: ${config.paths.join(', ')}`);
+    logger.info(`⏱️  Debounce: ${watchOptions.debounceMs}ms`);
+    // Initial scan
+    /* eslint-disable no-console */
+    console.log('🚀 Running initial scan...\n');
+    const initialResult = await scan(config);
+    const initialReport = generateConsoleReport(initialResult, {
+        verbose: config.verbose,
+        ci: config.ci,
+    });
+    console.log(initialReport);
+    console.log('\n👀 Watching for changes...\n');
+    /* eslint-enable no-console */
+    // Debounced scan function
+    const performScan = async () => {
+        if (isScanning) {
+            logger.debug('Scan already in progress, skipping');
+            return;
+        }
+        isScanning = true;
+        const changedFiles = events.splice(0); // Clear events
+        try {
+            logger.info(`📝 File changes detected: ${changedFiles.length} event(s)`);
+            if (config.verbose) {
+                for (const event of changedFiles.slice(0, 5)) { // Show max 5 files
+                    const icon = event.type === 'add' ? '➕' : event.type === 'change' ? '📝' : '➖';
+                    logger.info(`   ${icon} ${event.path}`);
+                }
+                if (changedFiles.length > 5) {
+                    logger.info(`   ... and ${changedFiles.length - 5} more`);
+                }
+            }
+            /* eslint-disable no-console */
+            console.log('🔄 Rescanning...\n');
+            const result = await scan(config);
+            // Clear previous output and show new results
+            if (!config.verbose && !config.ci) {
+                process.stdout.write('\x1Bc'); // Clear screen
+            }
+            const report = generateConsoleReport(result, {
+                verbose: config.verbose,
+                ci: config.ci,
+            });
+            console.log(report);
+            const timestamp = new Date().toLocaleTimeString();
+            console.log(`\n✅ Scan completed at ${timestamp}`);
+            console.log('👀 Watching for changes...\n');
+            /* eslint-enable no-console */
+        }
+        catch (error) {
+            // eslint-disable-next-line no-console
+            console.error('❌ Scan failed:', error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            isScanning = false;
+        }
+    };
+    const debouncedScan = debounce(() => {
+        void performScan();
+    }, watchOptions.debounceMs);
+    // Set up file watcher
+    const watcher = chokidar.watch(config.paths, {
+        ignored: [
+            ...watchOptions.ignored,
+            ...config.ignore.map(pattern => `**/${pattern}`),
+        ],
+        persistent: true,
+        ignoreInitial: true, // Don't trigger on initial scan
+        followSymlinks: false,
+        depth: 10, // Reasonable recursion depth
+        awaitWriteFinish: {
+            stabilityThreshold: 100,
+            pollInterval: 50,
+        },
+    });
+    // Watch event handlers
+    watcher.on('add', (path) => {
+        events.push({ type: 'add', path, timestamp: new Date() });
+        if (config.verbose) {
+            logger.debug(`File added: ${path}`);
+        }
+        debouncedScan();
+    });
+    watcher.on('change', (path) => {
+        events.push({ type: 'change', path, timestamp: new Date() });
+        if (config.verbose) {
+            logger.debug(`File changed: ${path}`);
+        }
+        debouncedScan();
+    });
+    watcher.on('unlink', (path) => {
+        events.push({ type: 'unlink', path, timestamp: new Date() });
+        if (config.verbose) {
+            logger.debug(`File removed: ${path}`);
+        }
+        debouncedScan();
+    });
+    watcher.on('error', (error) => {
+        // eslint-disable-next-line no-console
+        console.error('❌ Watch error:', error);
+    });
+    watcher.on('ready', () => {
+        const watched = watcher.getWatched();
+        const watchedCount = Object.keys(watched).length;
+        logger.info(`👁️  Watching ${watchedCount || 'multiple'} directories`);
+    });
+    // Handle graceful shutdown
+    const cleanup = () => {
+        logger.info('🛑 Stopping watch mode...');
+        void watcher.close();
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    // Return cleanup function
+    return cleanup;
+}
+/**
+ * Watch mode with enhanced console output
+ */
+export async function startEnhancedWatchMode(config, options = {}) {
+    // Enhanced version with better UX
+    const watchOptions = { ...DEFAULT_WATCH_OPTIONS, ...options };
+    /* eslint-disable no-console */
+    console.log('🚀 Ferret Watch Mode Starting...\n');
+    console.log(`📂 Watching: ${config.paths.join(', ')}`);
+    console.log(`⚙️  Debounce: ${watchOptions.debounceMs}ms`);
+    console.log(`🔍 Severities: ${config.severities.join(', ')}`);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+    /* eslint-enable no-console */
+    return startWatchMode(config, options);
+}
+/**
+ * Create a simple file change notifier
+ */
+export function createChangeNotifier(paths, callback, options = {}) {
+    const watchOptions = { ...DEFAULT_WATCH_OPTIONS, ...options };
+    const changedFiles = [];
+    const debouncedCallback = debounce(() => {
+        const files = [...changedFiles];
+        changedFiles.length = 0; // Clear array
+        callback(files);
+    }, watchOptions.debounceMs);
+    const watcher = chokidar.watch(paths, {
+        ignored: watchOptions.ignored,
+        persistent: true,
+        ignoreInitial: true,
+    });
+    watcher.on('all', (event, path) => {
+        if (['add', 'change', 'unlink'].includes(event)) {
+            changedFiles.push(path);
+            debouncedCallback();
+        }
+    });
+    return () => { void watcher.close(); };
+}
+export default { startWatchMode, startEnhancedWatchMode, createChangeNotifier };
+//# sourceMappingURL=WatchMode.js.map

package/dist/types.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Ferret-Scan Type Definitions
+ * Security scanner for AI CLI configurations
+ */
+/** Severity levels for security findings */
+export type Severity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'INFO';
+/** Threat categories detected by the scanner */
+export type ThreatCategory = 'exfiltration' | 'credentials' | 'injection' | 'backdoors' | 'supply-chain' | 'permissions' | 'persistence' | 'obfuscation' | 'ai-specific' | 'advanced-hiding' | 'behavioral';
+/** Component types that can be analyzed */
+export type ComponentType = 'skill' | 'agent' | 'hook' | 'plugin' | 'mcp' | 'settings' | 'ai-config-md' | 'rules-file';
+/** File types supported for analysis */
+export type FileType = 'md' | 'sh' | 'bash' | 'zsh' | 'json' | 'yaml' | 'yml' | 'ts' | 'js' | 'tsx' | 'jsx';
+/** Semantic pattern for AST-based analysis */
+export interface SemanticPattern {
+    /** Pattern type */
+    type: 'function-call' | 'property-access' | 'dynamic-import' | 'eval-chain' | 'object-structure';
+    /** Pattern identifier */
+    pattern: string;
+    /** Required context */
+    context?: string[];
+    /** Minimum confidence level (0-1) */
+    confidence?: number;
+}
+/** Correlation rule for multi-file analysis */
+export interface CorrelationRule {
+    /** Rule identifier */
+    id: string;
+    /** Description of the correlation pattern */
+    description: string;
+    /** File patterns that must be present */
+    filePatterns: string[];
+    /** Content patterns that must exist across files */
+    contentPatterns: string[];
+    /** Maximum distance between related files (directory levels) */
+    maxDistance?: number;
+}
+/** Remediation fix definition */
+export interface RemediationFix {
+    /** Fix type */
+    type: 'replace' | 'remove' | 'quarantine' | 'permission-change';
+    /** Fix description */
+    description: string;
+    /** Pattern to match for fix */
+    pattern: string;
+    /** Replacement content (for replace type) */
+    replacement?: string;
+    /** Safety level (0=dangerous, 1=safe) */
+    safety: number;
+    /** Whether fix can be applied automatically */
+    automatic: boolean;
+}
+/** A single security rule definition */
+export interface Rule {
+    /** Unique rule identifier (e.g., "EXFIL-001") */
+    id: string;
+    /** Human-readable rule name */
+    name: string;
+    /** Category of threat this rule detects */
+    category: ThreatCategory;
+    /** Severity level of findings from this rule */
+    severity: Severity;
+    /** Detailed description of what this rule detects */
+    description: string;
+    /** Regex patterns to match against content */
+    patterns: RegExp[];
+    /** File types this rule applies to */
+    fileTypes: FileType[];
+    /** Component types this rule applies to */
+    components: ComponentType[];
+    /** Recommended remediation steps */
+    remediation: string;
+    /** Reference URLs for more information */
+    references: string[];
+    /** Whether this rule is enabled by default */
+    enabled: boolean;
+    /** Patterns that exclude a match (false positive filters) */
+    excludePatterns?: RegExp[];
+    /** Context patterns that must also be present for a match */
+    requireContext?: RegExp[];
+    /** Context patterns that invalidate a match (documentation indicators) */
+    excludeContext?: RegExp[];
+    /** Minimum match length to trigger (filters short matches) */
+    minMatchLength?: number;
+    /** Semantic patterns for AST-based detection */
+    semanticPatterns?: SemanticPattern[];
+    /** Correlation rules for multi-file analysis */
+    correlationRules?: CorrelationRule[];
+    /** Available fixes for this rule */
+    remediationFixes?: RemediationFix[];
+}
+/** AST node information for semantic findings */
+export interface ASTNodeInfo {
+    /** Node type (function, property, etc.) */
+    nodeType: string;
+    /** Node name/identifier */
+    name?: string;
+    /** Parent context */
+    parent?: string;
+    /** Child nodes */
+    children?: string[];
+}
+/** Semantic context for advanced analysis */
+export interface SemanticContext {
+    /** Function/method name */
+    functionName?: string;
+    /** Variable names in scope */
+    variables?: string[];
+    /** Import statements */
+    imports?: string[];
+    /** Call chain */
+    callChain?: string[];
+}
+/** A security finding from the scanner */
+export interface Finding {
+    /** Rule ID that triggered this finding */
+    ruleId: string;
+    /** Rule name */
+    ruleName: string;
+    /** Severity level */
+    severity: Severity;
+    /** Category of threat */
+    category: ThreatCategory;
+    /** Full path to the file */
+    file: string;
+    /** Relative path for display */
+    relativePath: string;
+    /** Line number where the finding occurred */
+    line: number;
+    /** Column number (if available) */
+    column?: number;
+    /** The matched text */
+    match: string;
+    /** Context lines around the finding */
+    context: ContextLine[];
+    /** Remediation recommendation */
+    remediation: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Timestamp when finding was detected */
+    timestamp: Date;
+    /** Risk score (0-100) */
+    riskScore: number;
+}
+/** Semantic finding with AST information */
+export interface SemanticFinding extends Finding {
+    /** AST node information */
+    astNode?: ASTNodeInfo;
+    /** Semantic context */
+    semanticContext?: SemanticContext;
+    /** Confidence level (0-1) */
+    confidence: number;
+}
+/** Correlation finding across multiple files */
+export interface CorrelationFinding extends Finding {
+    /** Related files in the attack pattern */
+    relatedFiles: string[];
+    /** Attack pattern name */
+    attackPattern: string;
+    /** Risk vectors identified */
+    riskVectors: string[];
+    /** Correlation strength (0-1) */
+    correlationStrength: number;
+}
+/** A line of context around a finding */
+export interface ContextLine {
+    /** Line number */
+    lineNumber: number;
+    /** Line content */
+    content: string;
+    /** Whether this is the matched line */
+    isMatch: boolean;
+}
+/** A discovered file to be analyzed */
+export interface DiscoveredFile {
+    /** Full absolute path */
+    path: string;
+    /** Relative path from scan root */
+    relativePath: string;
+    /** File extension/type */
+    type: FileType;
+    /** Detected component type */
+    component: ComponentType;
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp */
+    modified: Date;
+}
+/** Results from a complete scan */
+export interface ScanResult {
+    /** Whether the scan completed successfully */
+    success: boolean;
+    /** Timestamp when scan started */
+    startTime: Date;
+    /** Timestamp when scan completed */
+    endTime: Date;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Paths that were scanned */
+    scannedPaths: string[];
+    /** Total files discovered */
+    totalFiles: number;
+    /** Files that were actually analyzed */
+    analyzedFiles: number;
+    /** Files that were skipped (ignored) */
+    skippedFiles: number;
+    /** All findings from the scan */
+    findings: Finding[];
+    /** Findings grouped by severity */
+    findingsBySeverity: Record<Severity, Finding[]>;
+    /** Findings grouped by category */
+    findingsByCategory: Record<ThreatCategory, Finding[]>;
+    /** Overall risk score (0-100) */
+    overallRiskScore: number;
+    /** Summary statistics */
+    summary: ScanSummary;
+    /** Any errors encountered during scanning */
+    errors: ScanError[];
+}
+/** Summary statistics for a scan */
+export interface ScanSummary {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+    total: number;
+}
+/** An error encountered during scanning */
+export interface ScanError {
+    /** File path where error occurred */
+    file?: string;
+    /** Error message */
+    message: string;
+    /** Error code */
+    code?: string;
+    /** Whether the error was fatal */
+    fatal: boolean;
+}
+/** Scanner configuration options */
+export interface ScannerConfig {
+    /** Paths to scan */
+    paths: string[];
+    /** Severity levels to report */
+    severities: Severity[];
+    /** Categories to scan for */
+    categories: ThreatCategory[];
+    /** Patterns to ignore (glob) */
+    ignore: string[];
+    /** Path to custom rules directory */
+    customRules?: string;
+    /** Minimum severity to fail on */
+    failOn: Severity;
+    /** Enable watch mode */
+    watch: boolean;
+    /** Enable AI-powered detection */
+    aiDetection: boolean;
+    /** Enable threat intelligence */
+    threatIntel: boolean;
+    /** Enable behavioral analysis */
+    behaviorAnalysis: boolean;
+    /** Enable semantic analysis */
+    semanticAnalysis: boolean;
+    /** Enable cross-file correlation */
+    correlationAnalysis: boolean;
+    /** Enable auto-remediation */
+    autoRemediation: boolean;
+    /** Context lines to show around findings */
+    contextLines: number;
+    /** Maximum file size to scan (bytes) */
+    maxFileSize: number;
+    /** Output format */
+    format: OutputFormat;
+    /** Output file path */
+    outputFile?: string;
+    /** Verbose output */
+    verbose: boolean;
+    /** CI mode (simplified output) */
+    ci: boolean;
+}
+/** Supported output formats */
+export type OutputFormat = 'console' | 'json' | 'sarif' | 'html' | 'csv';
+/** CLI options passed from command line */
+export interface CliOptions {
+    path?: string;
+    format?: OutputFormat;
+    severity?: string;
+    categories?: string;
+    failOn?: string;
+    output?: string;
+    watch?: boolean;
+    ci?: boolean;
+    verbose?: boolean;
+    aiDetection?: boolean;
+    threatIntel?: boolean;
+    semanticAnalysis?: boolean;
+    correlationAnalysis?: boolean;
+    autoRemediation?: boolean;
+    config?: string;
+}
+/** Configuration file structure (.ferretrc.json) */
+export interface ConfigFile {
+    severity?: Severity[];
+    categories?: ThreatCategory[];
+    ignore?: string[];
+    customRules?: string;
+    failOn?: Severity;
+    aiDetection?: {
+        enabled: boolean;
+        confidence?: number;
+    };
+    threatIntelligence?: {
+        enabled: boolean;
+        feeds?: string[];
+        updateInterval?: string;
+    };
+    behaviorAnalysis?: {
+        enabled: boolean;
+        patterns?: string[];
+    };
+    remediation?: {
+        autoFix?: boolean;
+        quarantineDir?: string;
+        backupOriginals?: boolean;
+    };
+}
+/** Default scanner configuration */
+export declare const DEFAULT_CONFIG: ScannerConfig;
+/** Severity weights for risk scoring */
+export declare const SEVERITY_WEIGHTS: Record<Severity, number>;
+/** Severity order for sorting */
+export declare const SEVERITY_ORDER: Severity[];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,53 @@
+/**
+ * Ferret-Scan Type Definitions
+ * Security scanner for AI CLI configurations
+ */
+/** Default scanner configuration */
+export const DEFAULT_CONFIG = {
+    paths: [],
+    severities: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'],
+    categories: [
+        'exfiltration',
+        'credentials',
+        'injection',
+        'backdoors',
+        'supply-chain',
+        'permissions',
+        'persistence',
+        'obfuscation',
+        'ai-specific',
+        'advanced-hiding',
+        'behavioral',
+    ],
+    ignore: ['**/node_modules/**', '**/.git/**'],
+    failOn: 'HIGH',
+    watch: false,
+    aiDetection: false,
+    threatIntel: false,
+    behaviorAnalysis: false,
+    semanticAnalysis: false,
+    correlationAnalysis: false,
+    autoRemediation: false,
+    contextLines: 3,
+    maxFileSize: 10 * 1024 * 1024, // 10MB
+    format: 'console',
+    verbose: false,
+    ci: false,
+};
+/** Severity weights for risk scoring */
+export const SEVERITY_WEIGHTS = {
+    CRITICAL: 100,
+    HIGH: 75,
+    MEDIUM: 50,
+    LOW: 25,
+    INFO: 10,
+};
+/** Severity order for sorting */
+export const SEVERITY_ORDER = [
+    'CRITICAL',
+    'HIGH',
+    'MEDIUM',
+    'LOW',
+    'INFO',
+];
+//# sourceMappingURL=types.js.map

package/dist/utils/baseline.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Baseline Management - Track and ignore accepted findings
+ * Allows users to create baselines of known/accepted security findings
+ */
+import type { Finding, ScanResult } from '../types.js';
+export interface BaselineFinding {
+    ruleId: string;
+    file: string;
+    line: number;
+    match: string;
+    hash: string;
+    acceptedDate: string;
+    reason?: string;
+    expiresDate?: string;
+}
+export interface Baseline {
+    version: string;
+    createdDate: string;
+    lastUpdated: string;
+    description?: string;
+    findings: BaselineFinding[];
+}
+/**
+ * Load baseline from file
+ */
+export declare function loadBaseline(baselinePath: string): Baseline | null;
+/**
+ * Save baseline to file
+ */
+export declare function saveBaseline(baseline: Baseline, baselinePath: string): void;
+/**
+ * Create a new baseline from scan results
+ */
+export declare function createBaseline(result: ScanResult, description?: string): Baseline;
+/**
+ * Add findings to an existing baseline
+ */
+export declare function addToBaseline(baseline: Baseline, findings: Finding[], reason?: string): Baseline;
+/**
+ * Remove findings from baseline
+ */
+export declare function removeFromBaseline(baseline: Baseline, findingHashes: string[]): Baseline;
+/**
+ * Filter scan results against baseline
+ */
+export declare function filterAgainstBaseline(result: ScanResult, baseline: Baseline | null): ScanResult;
+/**
+ * Check if baseline findings are still valid
+ */
+export declare function validateBaseline(baseline: Baseline, currentResult: ScanResult): {
+    valid: BaselineFinding[];
+    invalid: BaselineFinding[];
+};
+/**
+ * Get default baseline path for a project
+ */
+export declare function getDefaultBaselinePath(scanPaths: string[]): string;
+/**
+ * Baseline statistics
+ */
+export declare function getBaselineStats(baseline: Baseline): {
+    totalFindings: number;
+    byRule: Record<string, number>;
+    bySeverity: Record<string, number>;
+    oldestFinding: string;
+    newestFinding: string;
+};
+declare const _default: {
+    loadBaseline: typeof loadBaseline;
+    saveBaseline: typeof saveBaseline;
+    createBaseline: typeof createBaseline;
+    addToBaseline: typeof addToBaseline;
+    removeFromBaseline: typeof removeFromBaseline;
+    filterAgainstBaseline: typeof filterAgainstBaseline;
+    validateBaseline: typeof validateBaseline;
+    getDefaultBaselinePath: typeof getDefaultBaselinePath;
+    getBaselineStats: typeof getBaselineStats;
+};
+export default _default;
+//# sourceMappingURL=baseline.d.ts.map