ferret-scan 1.0.0

package/dist/remediation/Quarantine.js

@@ -0,0 +1,329 @@
+/**
+ * Quarantine System - Safely isolate suspicious files and content
+ * Provides reversible quarantine operations with audit trails
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, unlinkSync, statSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import logger from '../utils/logger.js';
+/**
+ * Default quarantine options
+ */
+const DEFAULT_OPTIONS = {
+    quarantineDir: '.ferret-quarantine',
+    createBackup: true,
+    removeOriginal: false, // By default, keep originals for safety
+    compressFiles: true,
+    maxFileSizeMB: 100
+};
+/**
+ * Generate quarantine ID
+ */
+function generateQuarantineId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 7);
+    return `quar-${timestamp}-${random}`;
+}
+/**
+ * Calculate file hash
+ */
+function calculateFileHash(filePath) {
+    try {
+        const content = readFileSync(filePath);
+        return createHash('sha256').update(content).digest('hex');
+    }
+    catch (error) {
+        logger.warn(`Could not calculate hash for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        return 'unknown';
+    }
+}
+/**
+ * Load quarantine database
+ */
+export function loadQuarantineDatabase(quarantineDir) {
+    const dbPath = resolve(quarantineDir, 'quarantine.json');
+    if (!existsSync(dbPath)) {
+        return createEmptyDatabase();
+    }
+    try {
+        const content = readFileSync(dbPath, 'utf-8');
+        const db = JSON.parse(content);
+        // Validate database structure
+        if (!db.version || !db.entries || !Array.isArray(db.entries)) {
+            logger.warn('Invalid quarantine database, creating new one');
+            return createEmptyDatabase();
+        }
+        return db;
+    }
+    catch (error) {
+        logger.error(`Failed to load quarantine database: ${error instanceof Error ? error.message : String(error)}`);
+        return createEmptyDatabase();
+    }
+}
+/**
+ * Save quarantine database
+ */
+export function saveQuarantineDatabase(db, quarantineDir) {
+    try {
+        // Ensure directory exists
+        mkdirSync(quarantineDir, { recursive: true });
+        // Update stats and metadata
+        db.lastUpdated = new Date().toISOString();
+        db.stats = calculateQuarantineStats(db.entries);
+        const dbPath = resolve(quarantineDir, 'quarantine.json');
+        const content = JSON.stringify(db, null, 2);
+        writeFileSync(dbPath, content, 'utf-8');
+        logger.debug(`Saved quarantine database with ${db.entries.length} entries`);
+    }
+    catch (error) {
+        logger.error(`Failed to save quarantine database: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
+}
+/**
+ * Create empty quarantine database
+ */
+function createEmptyDatabase() {
+    return {
+        version: '1.0',
+        created: new Date().toISOString(),
+        lastUpdated: new Date().toISOString(),
+        entries: [],
+        stats: {
+            totalQuarantined: 0,
+            totalRestored: 0,
+            byCategory: {},
+            bySeverity: {}
+        }
+    };
+}
+/**
+ * Calculate quarantine statistics
+ */
+function calculateQuarantineStats(entries) {
+    const stats = {
+        totalQuarantined: entries.length,
+        totalRestored: entries.filter(e => e.restored).length,
+        byCategory: {},
+        bySeverity: {}
+    };
+    for (const entry of entries) {
+        // Count by category
+        stats.byCategory[entry.metadata.category] = (stats.byCategory[entry.metadata.category] ?? 0) + 1;
+        // Count by severity
+        stats.bySeverity[entry.metadata.severity] = (stats.bySeverity[entry.metadata.severity] ?? 0) + 1;
+    }
+    return stats;
+}
+/**
+ * Quarantine a file based on findings
+ */
+export function quarantineFile(filePath, findings, reason, options = {}) {
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    try {
+        // Check if file exists
+        if (!existsSync(filePath)) {
+            logger.error(`File not found for quarantine: ${filePath}`);
+            return null;
+        }
+        // Check file size
+        const stats = statSync(filePath);
+        const fileSizeMB = stats.size / (1024 * 1024);
+        if (fileSizeMB > config.maxFileSizeMB) {
+            logger.warn(`File too large for quarantine: ${filePath} (${fileSizeMB.toFixed(1)}MB)`);
+            return null;
+        }
+        // Generate quarantine entry
+        const id = generateQuarantineId();
+        const fileName = basename(filePath);
+        const quarantineFileName = `${id}_${fileName}`;
+        const quarantinePath = resolve(config.quarantineDir, 'files', quarantineFileName);
+        // Ensure quarantine directory exists
+        mkdirSync(dirname(quarantinePath), { recursive: true });
+        // Copy file to quarantine
+        copyFileSync(filePath, quarantinePath);
+        // Calculate metadata
+        const fileHash = calculateFileHash(filePath);
+        const maxRiskScore = Math.max(...findings.map(f => f.riskScore));
+        const severities = findings.map(f => f.severity);
+        const severityOrder = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
+        const highestSeverity = severityOrder.find(s => severities.includes(s)) ?? 'INFO';
+        const entry = {
+            id,
+            originalPath: filePath,
+            quarantinePath,
+            reason,
+            findings,
+            quarantineDate: new Date().toISOString(),
+            fileSize: stats.size,
+            fileHash,
+            restored: false,
+            metadata: {
+                riskScore: maxRiskScore,
+                severity: highestSeverity,
+                category: findings[0]?.category ?? 'unknown'
+            }
+        };
+        // Update quarantine database
+        const db = loadQuarantineDatabase(config.quarantineDir);
+        db.entries.push(entry);
+        saveQuarantineDatabase(db, config.quarantineDir);
+        // Optionally remove original file
+        if (config.removeOriginal) {
+            try {
+                unlinkSync(filePath);
+                logger.info(`Quarantined and removed: ${filePath}`);
+            }
+            catch (error) {
+                logger.warn(`Could not remove original file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        else {
+            logger.info(`Quarantined (original preserved): ${filePath}`);
+        }
+        return entry;
+    }
+    catch (error) {
+        logger.error(`Error quarantining file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Restore a quarantined file
+ */
+export function restoreQuarantinedFile(entryId, quarantineDir = DEFAULT_OPTIONS.quarantineDir) {
+    try {
+        const db = loadQuarantineDatabase(quarantineDir);
+        const entry = db.entries.find(e => e.id === entryId);
+        if (!entry) {
+            logger.error(`Quarantine entry not found: ${entryId}`);
+            return false;
+        }
+        if (entry.restored) {
+            logger.warn(`File already restored: ${entryId}`);
+            return false;
+        }
+        if (!existsSync(entry.quarantinePath)) {
+            logger.error(`Quarantined file not found: ${entry.quarantinePath}`);
+            return false;
+        }
+        // Ensure original directory exists
+        mkdirSync(dirname(entry.originalPath), { recursive: true });
+        // Restore file
+        copyFileSync(entry.quarantinePath, entry.originalPath);
+        // Update entry
+        entry.restored = true;
+        entry.restoredDate = new Date().toISOString();
+        // Save updated database
+        saveQuarantineDatabase(db, quarantineDir);
+        logger.info(`Restored quarantined file: ${entry.originalPath}`);
+        return true;
+    }
+    catch (error) {
+        logger.error(`Error restoring quarantined file: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+/**
+ * Delete a quarantined file permanently
+ */
+export function deleteQuarantinedFile(entryId, quarantineDir = DEFAULT_OPTIONS.quarantineDir) {
+    try {
+        const db = loadQuarantineDatabase(quarantineDir);
+        const entryIndex = db.entries.findIndex(e => e.id === entryId);
+        if (entryIndex === -1) {
+            logger.error(`Quarantine entry not found: ${entryId}`);
+            return false;
+        }
+        const entry = db.entries[entryIndex];
+        if (!entry) {
+            logger.error(`Entry not found at index ${entryIndex}`);
+            return false;
+        }
+        // Delete quarantined file
+        if (existsSync(entry.quarantinePath)) {
+            unlinkSync(entry.quarantinePath);
+        }
+        // Remove entry from database
+        db.entries.splice(entryIndex, 1);
+        saveQuarantineDatabase(db, quarantineDir);
+        logger.info(`Permanently deleted quarantined file: ${entryId}`);
+        return true;
+    }
+    catch (error) {
+        logger.error(`Error deleting quarantined file: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+/**
+ * List quarantined files
+ */
+export function listQuarantinedFiles(quarantineDir = DEFAULT_OPTIONS.quarantineDir) {
+    const db = loadQuarantineDatabase(quarantineDir);
+    return db.entries.sort((a, b) => new Date(b.quarantineDate).getTime() - new Date(a.quarantineDate).getTime());
+}
+/**
+ * Get quarantine statistics
+ */
+export function getQuarantineStats(quarantineDir = DEFAULT_OPTIONS.quarantineDir) {
+    const db = loadQuarantineDatabase(quarantineDir);
+    return db.stats;
+}
+/**
+ * Clean up old quarantine entries
+ */
+export function cleanupQuarantine(maxAgeDays = 30, quarantineDir = DEFAULT_OPTIONS.quarantineDir) {
+    try {
+        const db = loadQuarantineDatabase(quarantineDir);
+        const cutoffDate = new Date(Date.now() - maxAgeDays * 24 * 60 * 60 * 1000);
+        const entriesToDelete = db.entries.filter(entry => {
+            const entryDate = new Date(entry.quarantineDate);
+            return entryDate < cutoffDate && entry.restored;
+        });
+        let deletedCount = 0;
+        for (const entry of entriesToDelete) {
+            if (deleteQuarantinedFile(entry.id, quarantineDir)) {
+                deletedCount++;
+            }
+        }
+        logger.info(`Cleaned up ${deletedCount} old quarantine entries`);
+        return deletedCount;
+    }
+    catch (error) {
+        logger.error(`Error cleaning up quarantine: ${error instanceof Error ? error.message : String(error)}`);
+        return 0;
+    }
+}
+/**
+ * Check quarantine health
+ */
+export function checkQuarantineHealth(quarantineDir = DEFAULT_OPTIONS.quarantineDir) {
+    const issues = [];
+    const db = loadQuarantineDatabase(quarantineDir);
+    // Check for missing quarantined files
+    for (const entry of db.entries) {
+        if (!entry.restored && !existsSync(entry.quarantinePath)) {
+            issues.push(`Missing quarantined file: ${entry.id} (${entry.originalPath})`);
+        }
+    }
+    // Check quarantine directory structure
+    const quarantineFilesDir = resolve(quarantineDir, 'files');
+    if (!existsSync(quarantineFilesDir)) {
+        issues.push('Quarantine files directory missing');
+    }
+    return {
+        healthy: issues.length === 0,
+        issues,
+        stats: db.stats
+    };
+}
+export default {
+    quarantineFile,
+    restoreQuarantinedFile,
+    deleteQuarantinedFile,
+    listQuarantinedFiles,
+    getQuarantineStats,
+    cleanupQuarantine,
+    checkQuarantineHealth
+};
+//# sourceMappingURL=Quarantine.js.map

package/dist/reporters/ConsoleReporter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ConsoleReporter - Beautiful terminal output for scan results
+ */
+import type { ScanResult } from '../types.js';
+/**
+ * Generate console report
+ */
+export declare function generateConsoleReport(result: ScanResult, options?: {
+    verbose?: boolean;
+    ci?: boolean;
+}): string;
+export default generateConsoleReport;
+//# sourceMappingURL=ConsoleReporter.d.ts.map

package/dist/reporters/ConsoleReporter.js

@@ -0,0 +1,185 @@
+/**
+ * ConsoleReporter - Beautiful terminal output for scan results
+ */
+// ANSI color codes
+const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+    bgRed: '\x1b[41m',
+    bgYellow: '\x1b[43m',
+    bgBlue: '\x1b[44m',
+};
+const FERRET_BANNER = `
+${colors.cyan} ⡠⢂⠔⠚⠟⠓⠒⠒⢂⠐⢄
+ ⣷⣧⣀⠀⢀⣀⣤⣄⠈⢢⢸⡀   ${colors.bold}███████╗███████╗██████╗ ██████╗ ███████╗████████╗
+${colors.cyan}⢀⣿⣭⣿⣿⣿⣿⣽⣹⣧⠈⣾⢱⡀  ${colors.bold}██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
+${colors.cyan}⢸⢿⠋⢸⠂⠈⠹⢿⣿⡿⠀⢸⡷⡇  ${colors.bold}█████╗  █████╗  ██████╔╝██████╔╝█████╗     ██║
+${colors.cyan}⠈⣆⠉⢇⢁⠶⠈⠀⠉⠀⢀⣾⣇⡇  ${colors.bold}██╔══╝  ██╔══╝  ██╔══██╗██╔══██╗██╔══╝     ██║
+${colors.cyan}  ⢑⣦⣤⣤⣤⣤⣴⣶⣿⡿⢨⠃  ${colors.bold}██║     ███████╗██║  ██║██║  ██║███████╗   ██║
+${colors.cyan} ⢰⣿⣿⣟⣯⡿⣽⣻⣾⣽⣇⠏   ${colors.bold}╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝   ╚═╝${colors.reset}
+${colors.dim} Security Scanner for AI CLI Configs${colors.reset}
+`;
+const SEVERITY_COLORS = {
+    CRITICAL: colors.bgRed + colors.white + colors.bold,
+    HIGH: colors.red + colors.bold,
+    MEDIUM: colors.yellow,
+    LOW: colors.blue,
+    INFO: colors.dim,
+};
+const SEVERITY_ICONS = {
+    CRITICAL: '!!!',
+    HIGH: '!!',
+    MEDIUM: '!',
+    LOW: '*',
+    INFO: '-',
+};
+/**
+ * Format a severity badge
+ */
+function formatSeverity(severity) {
+    const color = SEVERITY_COLORS[severity];
+    const icon = SEVERITY_ICONS[severity];
+    return `${color}[${icon} ${severity}]${colors.reset}`;
+}
+/**
+ * Format a finding for display
+ */
+function formatFinding(finding, verbose) {
+    const lines = [];
+    // Header
+    lines.push(`${formatSeverity(finding.severity)} ${colors.bold}${finding.ruleId}${colors.reset} - ${finding.ruleName}`);
+    // Location
+    lines.push(`  ${colors.cyan}File:${colors.reset} ${finding.relativePath}:${finding.line}`);
+    // Match
+    const matchDisplay = finding.match.length > 80
+        ? finding.match.slice(0, 77) + '...'
+        : finding.match;
+    lines.push(`  ${colors.cyan}Match:${colors.reset} ${colors.yellow}${matchDisplay}${colors.reset}`);
+    // Context (if verbose)
+    if (verbose && finding.context.length > 0) {
+        lines.push('');
+        lines.push(`  ${colors.dim}Context:${colors.reset}`);
+        for (const ctx of finding.context) {
+            const lineNum = String(ctx.lineNumber).padStart(4, ' ');
+            const marker = ctx.isMatch ? `${colors.red}>${colors.reset}` : ' ';
+            const lineColor = ctx.isMatch ? colors.yellow : colors.dim;
+            lines.push(`  ${marker} ${colors.dim}${lineNum}${colors.reset} ${colors.dim}|${colors.reset} ${lineColor}${ctx.content}${colors.reset}`);
+        }
+    }
+    // Remediation
+    lines.push(`  ${colors.green}Remediation:${colors.reset} ${finding.remediation}`);
+    // Risk score
+    lines.push(`  ${colors.magenta}Risk Score:${colors.reset} ${finding.riskScore}/100`);
+    return lines.join('\n');
+}
+/**
+ * Format summary statistics
+ */
+function formatSummary(summary, result) {
+    const lines = [];
+    lines.push('');
+    lines.push(`${colors.bold}${'━'.repeat(60)}${colors.reset}`);
+    lines.push(`${colors.bold}SUMMARY${colors.reset}`);
+    lines.push(`${colors.bold}${'━'.repeat(60)}${colors.reset}`);
+    const stats = [
+        summary.critical > 0 ? `${SEVERITY_COLORS['CRITICAL']}Critical: ${summary.critical}${colors.reset}` : `Critical: ${summary.critical}`,
+        summary.high > 0 ? `${SEVERITY_COLORS['HIGH']}High: ${summary.high}${colors.reset}` : `High: ${summary.high}`,
+        summary.medium > 0 ? `${SEVERITY_COLORS['MEDIUM']}Medium: ${summary.medium}${colors.reset}` : `Medium: ${summary.medium}`,
+        `Low: ${summary.low}`,
+        `Info: ${summary.info}`,
+    ];
+    lines.push(stats.join('  |  '));
+    lines.push(`Files scanned: ${result.analyzedFiles}  |  Time: ${result.duration}ms  |  Risk Score: ${result.overallRiskScore}/100`);
+    return lines.join('\n');
+}
+/**
+ * Format findings grouped by severity
+ */
+function formatGroupedFindings(result, verbose) {
+    const lines = [];
+    const severities = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
+    for (const severity of severities) {
+        const findings = result.findingsBySeverity[severity];
+        if (findings.length === 0)
+            continue;
+        lines.push('');
+        lines.push(`${SEVERITY_COLORS[severity]}${severity} (${findings.length})${colors.reset}`);
+        lines.push(`${colors.dim}${'━'.repeat(60)}${colors.reset}`);
+        lines.push('');
+        for (const finding of findings) {
+            lines.push(formatFinding(finding, verbose));
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format scan errors
+ */
+function formatErrors(result) {
+    if (result.errors.length === 0)
+        return '';
+    const lines = [];
+    lines.push('');
+    lines.push(`${colors.yellow}Errors (${result.errors.length})${colors.reset}`);
+    lines.push(`${colors.dim}${'━'.repeat(60)}${colors.reset}`);
+    for (const error of result.errors) {
+        const file = error.file ? `${error.file}: ` : '';
+        lines.push(`  ${colors.yellow}!${colors.reset} ${file}${error.message}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Generate console report
+ */
+export function generateConsoleReport(result, options = {}) {
+    const { verbose = false, ci = false } = options;
+    if (ci) {
+        return generateCiReport(result);
+    }
+    const lines = [];
+    // Banner
+    lines.push(FERRET_BANNER);
+    // Scan info
+    lines.push(`${colors.dim}Scanning: ${result.scannedPaths.join(', ')}${colors.reset}`);
+    lines.push(`${colors.dim}Found: ${result.analyzedFiles} configuration files${colors.reset}`);
+    // Findings
+    if (result.summary.total === 0) {
+        lines.push('');
+        lines.push(`${colors.green}${colors.bold}No security issues found!${colors.reset}`);
+        lines.push(`${colors.green}Your AI CLI configurations look clean.${colors.reset}`);
+    }
+    else {
+        lines.push(formatGroupedFindings(result, verbose));
+    }
+    // Errors
+    if (result.errors.length > 0) {
+        lines.push(formatErrors(result));
+    }
+    // Summary
+    lines.push(formatSummary(result.summary, result));
+    return lines.join('\n');
+}
+/**
+ * Generate CI-friendly report (minimal formatting)
+ */
+function generateCiReport(result) {
+    const lines = [];
+    lines.push(`[FERRET] Scanned ${result.analyzedFiles} files in ${result.duration}ms`);
+    for (const finding of result.findings) {
+        lines.push(`[${finding.severity}] ${finding.ruleId}: ${finding.relativePath}:${finding.line} - ${finding.ruleName}`);
+    }
+    lines.push(`[SUMMARY] Critical: ${result.summary.critical} | High: ${result.summary.high} | Medium: ${result.summary.medium} | Low: ${result.summary.low} | Info: ${result.summary.info}`);
+    lines.push(`[RISK] Overall risk score: ${result.overallRiskScore}/100`);
+    return lines.join('\n');
+}
+export default generateConsoleReport;
+//# sourceMappingURL=ConsoleReporter.js.map

package/dist/reporters/HtmlReporter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * HTML Reporter - Beautiful HTML reports with interactive filtering
+ * Generates standalone HTML files with embedded CSS and JavaScript
+ */
+import type { ScanResult } from '../types.js';
+interface HtmlReportOptions {
+    title?: string;
+    includeContext?: boolean;
+    darkMode?: boolean;
+    showCode?: boolean;
+}
+/**
+ * Generate complete HTML report
+ */
+export declare function generateHtmlReport(result: ScanResult, options?: HtmlReportOptions): string;
+/**
+ * Format HTML report as string
+ */
+export declare function formatHtmlReport(result: ScanResult, options?: HtmlReportOptions): string;
+declare const _default: {
+    generateHtmlReport: typeof generateHtmlReport;
+    formatHtmlReport: typeof formatHtmlReport;
+};
+export default _default;
+//# sourceMappingURL=HtmlReporter.d.ts.map