ferret-scan 1.0.0

package/dist/rules/semanticRules.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Semantic Security Rules - AST-based detection patterns
+ * These rules use TypeScript AST analysis to detect complex security patterns
+ * that regular expressions cannot reliably identify.
+ * NOTE: These patterns are for DETECTION purposes only - not execution
+ */
+import type { Rule } from '../types.js';
+export declare const semanticRules: Rule[];
+export default semanticRules;
+//# sourceMappingURL=semanticRules.d.ts.map

package/dist/rules/semanticRules.js

@@ -0,0 +1,212 @@
+/**
+ * Semantic Security Rules - AST-based detection patterns
+ * These rules use TypeScript AST analysis to detect complex security patterns
+ * that regular expressions cannot reliably identify.
+ * NOTE: These patterns are for DETECTION purposes only - not execution
+ */
+export const semanticRules = [
+    {
+        id: 'SEM-001',
+        name: 'Dynamic Code Execution Detection',
+        category: 'injection',
+        severity: 'CRITICAL',
+        description: 'Detects dynamic code execution patterns that could allow code injection',
+        patterns: [],
+        fileTypes: ['md', 'ts', 'js', 'tsx', 'jsx'],
+        components: ['skill', 'agent', 'hook', 'plugin', 'ai-config-md'],
+        remediation: 'Avoid dynamic code execution. Use static imports, predefined functions, or safe templating instead.',
+        references: [
+            'https://owasp.org/www-community/attacks/Code_Injection'
+        ],
+        enabled: true,
+        semanticPatterns: [
+            {
+                type: 'eval-chain',
+                pattern: 'Function',
+                confidence: 0.90
+            },
+            {
+                type: 'dynamic-import',
+                pattern: 'dynamic-import',
+                confidence: 0.85
+            }
+        ]
+    },
+    {
+        id: 'SEM-002',
+        name: 'Process Execution Chain',
+        category: 'backdoors',
+        severity: 'HIGH',
+        description: 'Detects complex process execution chains that could be used for system compromise',
+        patterns: [],
+        fileTypes: ['md', 'ts', 'js', 'tsx', 'jsx'],
+        components: ['skill', 'agent', 'hook', 'plugin'],
+        remediation: 'Review process execution chains for legitimacy. Use subprocess restrictions and input validation.',
+        references: [
+            'https://owasp.org/www-project-top-ten/2021/A03_2021-Injection/'
+        ],
+        enabled: true,
+        semanticPatterns: [
+            {
+                type: 'function-call',
+                pattern: 'exec',
+                confidence: 0.85
+            },
+            {
+                type: 'function-call',
+                pattern: 'spawn',
+                confidence: 0.80
+            },
+            {
+                type: 'function-call',
+                pattern: 'execSync',
+                confidence: 0.90
+            },
+            {
+                type: 'property-access',
+                pattern: 'child_process',
+                confidence: 0.75
+            }
+        ]
+    },
+    {
+        id: 'SEM-003',
+        name: 'File System Access Chain',
+        category: 'exfiltration',
+        severity: 'MEDIUM',
+        description: 'Detects complex file system access patterns that could indicate data exfiltration',
+        patterns: [],
+        fileTypes: ['md', 'ts', 'js', 'tsx', 'jsx'],
+        components: ['skill', 'agent', 'hook', 'plugin'],
+        remediation: 'Review file system access patterns. Implement access controls and audit trails.',
+        references: [
+            'https://attack.mitre.org/techniques/T1005/'
+        ],
+        enabled: true,
+        semanticPatterns: [
+            {
+                type: 'function-call',
+                pattern: 'readFile',
+                confidence: 0.60
+            },
+            {
+                type: 'function-call',
+                pattern: 'writeFile',
+                confidence: 0.70
+            },
+            {
+                type: 'property-access',
+                pattern: 'fs.',
+                confidence: 0.65
+            },
+            {
+                type: 'function-call',
+                pattern: 'createReadStream',
+                confidence: 0.75
+            }
+        ]
+    },
+    {
+        id: 'SEM-004',
+        name: 'Network Request Chain',
+        category: 'exfiltration',
+        severity: 'MEDIUM',
+        description: 'Detects complex network request patterns that could be used for data exfiltration',
+        patterns: [],
+        fileTypes: ['md', 'ts', 'js', 'tsx', 'jsx'],
+        components: ['skill', 'agent', 'hook', 'plugin'],
+        remediation: 'Review network requests for legitimacy. Implement request filtering and monitoring.',
+        references: [
+            'https://attack.mitre.org/techniques/T1041/'
+        ],
+        enabled: true,
+        semanticPatterns: [
+            {
+                type: 'function-call',
+                pattern: 'fetch',
+                confidence: 0.50
+            },
+            {
+                type: 'function-call',
+                pattern: 'axios',
+                confidence: 0.60
+            },
+            {
+                type: 'property-access',
+                pattern: 'XMLHttpRequest',
+                confidence: 0.70
+            },
+            {
+                type: 'function-call',
+                pattern: 'request',
+                confidence: 0.55
+            }
+        ]
+    },
+    {
+        id: 'SEM-005',
+        name: 'Environment Variable Access',
+        category: 'credentials',
+        severity: 'HIGH',
+        description: 'Detects environment variable access patterns that could expose sensitive credentials',
+        patterns: [],
+        fileTypes: ['md', 'ts', 'js', 'tsx', 'jsx'],
+        components: ['skill', 'agent', 'hook', 'plugin', 'settings'],
+        remediation: 'Minimize environment variable access. Use secure credential storage and access patterns.',
+        references: [
+            'https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html'
+        ],
+        enabled: true,
+        semanticPatterns: [
+            {
+                type: 'property-access',
+                pattern: 'process.env',
+                confidence: 0.80
+            },
+            {
+                type: 'property-access',
+                pattern: 'process.environment',
+                confidence: 0.85
+            },
+            {
+                type: 'function-call',
+                pattern: 'getenv',
+                confidence: 0.75
+            }
+        ]
+    },
+    {
+        id: 'SEM-006',
+        name: 'Obfuscated Function Names',
+        category: 'obfuscation',
+        severity: 'MEDIUM',
+        description: 'Detects function names that appear to be obfuscated or suspicious',
+        patterns: [],
+        fileTypes: ['md', 'ts', 'js', 'tsx', 'jsx'],
+        components: ['skill', 'agent', 'hook', 'plugin'],
+        remediation: 'Use clear, descriptive function names. Avoid obfuscation in legitimate code.',
+        references: [
+            'https://attack.mitre.org/techniques/T1027/'
+        ],
+        enabled: true,
+        semanticPatterns: [
+            {
+                type: 'function-call',
+                pattern: '_0x',
+                confidence: 0.95
+            },
+            {
+                type: 'function-call',
+                pattern: '__',
+                confidence: 0.60
+            },
+            {
+                type: 'property-access',
+                pattern: '$_',
+                confidence: 0.70
+            }
+        ]
+    }
+];
+export default semanticRules;
+//# sourceMappingURL=semanticRules.js.map

package/dist/rules/supply-chain.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Supply Chain Attack Detection Rules
+ * Detects compromised or malicious dependencies
+ */
+import type { Rule } from '../types.js';
+export declare const supplyChainRules: Rule[];
+export default supplyChainRules;
+//# sourceMappingURL=supply-chain.d.ts.map

package/dist/rules/supply-chain.js

@@ -0,0 +1,148 @@
+/**
+ * Supply Chain Attack Detection Rules
+ * Detects compromised or malicious dependencies
+ */
+export const supplyChainRules = [
+    {
+        id: 'SUPP-001',
+        name: 'Unsafe npm Install',
+        category: 'supply-chain',
+        severity: 'HIGH',
+        description: 'Detects npm install with disabled script execution checks',
+        patterns: [
+            /npm\s+install.*--ignore-scripts/gi,
+            /npm\s+i.*--ignore-scripts/gi,
+            /npm\s+install.*--unsafe-perm/gi,
+        ],
+        fileTypes: ['sh', 'bash', 'zsh', 'md'],
+        components: ['hook', 'skill', 'agent', 'ai-config-md', 'plugin'],
+        remediation: 'Never use --ignore-scripts or --unsafe-perm with npm install.',
+        references: [],
+        enabled: true,
+    },
+    {
+        id: 'SUPP-002',
+        name: 'Direct Script Execution from URL',
+        category: 'supply-chain',
+        severity: 'CRITICAL',
+        description: 'Detects downloading and executing scripts from URLs',
+        patterns: [
+            /curl\s+.*\|\s*(ba)?sh/gi,
+            /wget\s+.*\|\s*(ba)?sh/gi,
+            /curl\s+-s.*\|\s*bash/gi,
+            /wget\s+-q.*\|\s*bash/gi,
+        ],
+        fileTypes: ['sh', 'bash', 'zsh', 'md'],
+        components: ['hook', 'skill', 'agent', 'ai-config-md', 'plugin'],
+        remediation: 'Never pipe downloaded content directly to a shell.',
+        references: [],
+        enabled: true,
+    },
+    {
+        id: 'SUPP-003',
+        name: 'Untrusted Source Download',
+        category: 'supply-chain',
+        severity: 'HIGH',
+        description: 'Detects downloads from potentially untrusted sources',
+        patterns: [
+            /curl\s+.*--no-check-certificate/gi,
+            /wget\s+.*--no-check-certificate/gi,
+            /curl\s+-k\s+/gi,
+            /curl\s+--insecure/gi,
+        ],
+        fileTypes: ['sh', 'bash', 'zsh', 'md'],
+        components: ['hook', 'skill', 'agent', 'ai-config-md', 'plugin'],
+        remediation: 'Always verify SSL certificates when downloading files.',
+        references: [],
+        enabled: true,
+    },
+    {
+        id: 'SUPP-004',
+        name: 'Suspicious MCP Server',
+        category: 'supply-chain',
+        severity: 'HIGH',
+        description: 'Detects MCP servers from unknown or suspicious sources',
+        patterns: [
+            /command.*npx\s+-y\s+[^@\s]+/gi, // npx without explicit version
+            /command.*npm.*exec/gi,
+        ],
+        fileTypes: ['json'],
+        components: ['mcp', 'settings'],
+        remediation: 'Review MCP server sources. Only use trusted, versioned packages.',
+        references: [],
+        enabled: true,
+    },
+    {
+        id: 'SUPP-005',
+        name: 'Typosquatting Package Names',
+        category: 'supply-chain',
+        severity: 'HIGH',
+        description: 'Detects potential typosquatting variants of popular packages in dependency contexts',
+        patterns: [
+            /["']l[o0]d[a4]sh["']/gi, // lodash typos in quoted strings
+            /["']requ[ei]st["']/gi, // request typos (but not just "request")
+            /["']expresss["']/gi, // express typos
+            /["']reactt["']/gi, // react typos
+            /["']angularr["']/gi, // angular typos
+            /npm\s+i(nstall)?\s+.*l[o0]d[a4]sh/gi, // npm install typos
+            /npm\s+i(nstall)?\s+.*expresss/gi,
+        ],
+        fileTypes: ['json'],
+        components: ['mcp', 'settings', 'plugin'],
+        remediation: 'Verify package names are correct. Typosquatting is a common attack vector.',
+        references: [],
+        enabled: true,
+        // Exclude common false positives
+        excludePatterns: [
+            /http_request/gi, // Prometheus metrics
+            /requests?_total/gi, // Prometheus metrics
+            /request_duration/gi, // Prometheus metrics
+            /request_count/gi, // Prometheus metrics
+            /XMLHttpRequest/gi, // Browser API
+            /fetch.*request/gi, // Fetch API
+            /request\s*=/gi, // Variable assignment
+            /request\s*:/gi, // Object property
+            /request\s*\(/gi, // Function call
+            /\.request\(/gi, // Method call
+            /request\s+body/gi, // HTTP context
+            /request\s+header/gi, // HTTP context
+            /request\s+method/gi, // HTTP context
+            /pull\s+request/gi, // Git context
+        ],
+    },
+    {
+        id: 'SUPP-006',
+        name: 'Unverified Plugin Source',
+        category: 'supply-chain',
+        severity: 'MEDIUM',
+        description: 'Detects plugins or skills from unverified sources',
+        patterns: [
+            /downloaded\s+from(?!.*github\.com|.*anthropic\.com|.*npmjs\.com)/gi,
+            /source.*http(?!s)/gi,
+        ],
+        fileTypes: ['md', 'json'],
+        components: ['skill', 'agent', 'plugin', 'mcp'],
+        remediation: 'Only use plugins from verified sources.',
+        references: [],
+        enabled: true,
+    },
+    {
+        id: 'SUPP-007',
+        name: 'Package Postinstall Hook',
+        category: 'supply-chain',
+        severity: 'MEDIUM',
+        description: 'Detects references to package postinstall hooks',
+        patterns: [
+            /postinstall/gi,
+            /preinstall/gi,
+            /scripts.*install/gi,
+        ],
+        fileTypes: ['json'],
+        components: ['mcp', 'plugin'],
+        remediation: 'Review postinstall scripts carefully. They can execute arbitrary code.',
+        references: [],
+        enabled: true,
+    },
+];
+export default supplyChainRules;
+//# sourceMappingURL=supply-chain.js.map

package/dist/scanner/FileDiscovery.d.ts

@@ -0,0 +1,24 @@
+/**
+ * FileDiscovery - Discovers AI CLI configuration files
+ * Scans directories for skills, agents, hooks, MCP configs, rules files, and other AI CLI files
+ * Supports: Claude Code, Cursor, Windsurf, Continue, Aider, Cline, and generic AI configs
+ */
+import type { DiscoveredFile } from '../types.js';
+interface DiscoveryOptions {
+    maxFileSize: number;
+    ignore: string[];
+}
+interface DiscoveryResult {
+    files: DiscoveredFile[];
+    skipped: number;
+    errors: {
+        path: string;
+        error: string;
+    }[];
+}
+/**
+ * Main file discovery function
+ */
+export declare function discoverFiles(paths: string[], options: DiscoveryOptions): DiscoveryResult;
+export default discoverFiles;
+//# sourceMappingURL=FileDiscovery.d.ts.map

package/dist/scanner/FileDiscovery.js

@@ -0,0 +1,282 @@
+/**
+ * FileDiscovery - Discovers AI CLI configuration files
+ * Scans directories for skills, agents, hooks, MCP configs, rules files, and other AI CLI files
+ * Supports: Claude Code, Cursor, Windsurf, Continue, Aider, Cline, and generic AI configs
+ */
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { resolve, extname, basename, relative } from 'node:path';
+import { createIgnoreFilter, shouldIgnore } from '../utils/ignore.js';
+import logger from '../utils/logger.js';
+/**
+ * Map file extensions to FileType
+ */
+function getFileType(filePath) {
+    const ext = extname(filePath).toLowerCase().slice(1);
+    const fileTypeMap = {
+        'md': 'md',
+        'sh': 'sh',
+        'bash': 'bash',
+        'zsh': 'zsh',
+        'json': 'json',
+        'yaml': 'yaml',
+        'yml': 'yml',
+    };
+    return fileTypeMap[ext] ?? null;
+}
+/**
+ * Detect component type from file path
+ * Supports multiple AI CLI patterns
+ */
+function detectComponentType(filePath) {
+    const normalizedPath = filePath.toLowerCase();
+    const fileName = basename(filePath).toLowerCase();
+    // Skills directory
+    if (normalizedPath.includes('/skills/') || normalizedPath.includes('\\skills\\')) {
+        return 'skill';
+    }
+    // Agents directory
+    if (normalizedPath.includes('/agents/') || normalizedPath.includes('\\agents\\')) {
+        return 'agent';
+    }
+    // Hooks directory or hook files
+    if (normalizedPath.includes('/hooks/') ||
+        normalizedPath.includes('\\hooks\\') ||
+        fileName.includes('hook')) {
+        return 'hook';
+    }
+    // Plugins directory
+    if (normalizedPath.includes('/plugins/') || normalizedPath.includes('\\plugins\\')) {
+        return 'plugin';
+    }
+    // MCP configuration
+    if (fileName === '.mcp.json' || fileName === 'mcp.json') {
+        return 'mcp';
+    }
+    // Rules files (Cursor, Windsurf, Cline)
+    if (fileName === '.cursorrules' ||
+        fileName === '.windsurfrules' ||
+        fileName === '.clinerules') {
+        return 'rules-file';
+    }
+    // Settings files
+    if (fileName === 'settings.json' ||
+        fileName === 'settings.local.json' ||
+        fileName.includes('config')) {
+        return 'settings';
+    }
+    // AI config markdown files (CLAUDE.md, AI.md, AGENT.md, etc.)
+    if (fileName === 'claude.md' ||
+        fileName.startsWith('claude') ||
+        fileName === 'ai.md' ||
+        fileName === 'agent.md' ||
+        fileName === 'agents.md') {
+        return 'ai-config-md';
+    }
+    // Default to settings for JSON, ai-config-md for markdown
+    const type = getFileType(filePath);
+    if (type === 'json') {
+        return 'settings';
+    }
+    if (type === 'md') {
+        return 'ai-config-md';
+    }
+    return 'settings';
+}
+/**
+ * Check if a file should be analyzed
+ */
+function isAnalyzableFile(filePath) {
+    const type = getFileType(filePath);
+    if (!type)
+        return false;
+    const fileName = basename(filePath).toLowerCase();
+    // Specific files we care about (multi-CLI support)
+    const targetFiles = [
+        // Claude Code
+        'claude.md',
+        '.mcp.json',
+        'mcp.json',
+        'settings.json',
+        'settings.local.json',
+        // Cursor
+        '.cursorrules',
+        // Windsurf
+        '.windsurfrules',
+        // Cline
+        '.clinerules',
+        // Aider
+        '.aider.conf.yml',
+        '.aiderignore',
+        // Generic AI
+        'ai.md',
+        'agent.md',
+        'agents.md',
+    ];
+    if (targetFiles.includes(fileName)) {
+        return true;
+    }
+    // All markdown files in AI CLI config directories
+    if (type === 'md') {
+        return true;
+    }
+    // Shell scripts in hooks or anywhere in .claude
+    if (type === 'sh' || type === 'bash' || type === 'zsh') {
+        return true;
+    }
+    // JSON files that might be configs
+    if (type === 'json') {
+        return true;
+    }
+    // YAML files
+    if (type === 'yaml' || type === 'yml') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Recursively discover files in a directory
+ */
+function discoverFilesInDirectory(dir, baseDir, ig, options, result) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        result.errors.push({ path: dir, error: message });
+        logger.debug(`Cannot read directory: ${dir}`);
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = resolve(dir, entry);
+        const relativePath = relative(baseDir, fullPath);
+        // Check if ignored
+        if (shouldIgnore(ig, fullPath, baseDir)) {
+            result.skipped++;
+            logger.debug(`Ignored: ${relativePath}`);
+            continue;
+        }
+        let stats;
+        try {
+            stats = statSync(fullPath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            result.errors.push({ path: fullPath, error: message });
+            continue;
+        }
+        if (stats.isDirectory()) {
+            // Recurse into directory
+            discoverFilesInDirectory(fullPath, baseDir, ig, options, result);
+        }
+        else if (stats.isFile()) {
+            // Check if file should be analyzed
+            if (!isAnalyzableFile(fullPath)) {
+                result.skipped++;
+                continue;
+            }
+            // Check file size
+            if (stats.size > options.maxFileSize) {
+                logger.debug(`Skipping large file: ${relativePath} (${stats.size} bytes)`);
+                result.skipped++;
+                continue;
+            }
+            const fileType = getFileType(fullPath);
+            if (!fileType) {
+                result.skipped++;
+                continue;
+            }
+            const discoveredFile = {
+                path: fullPath,
+                relativePath,
+                type: fileType,
+                component: detectComponentType(fullPath),
+                size: stats.size,
+                modified: stats.mtime,
+            };
+            result.files.push(discoveredFile);
+            logger.debug(`Discovered: ${relativePath} (${discoveredFile.component})`);
+        }
+    }
+}
+/**
+ * Discover a single file
+ */
+function discoverSingleFile(filePath, options, result) {
+    if (!existsSync(filePath)) {
+        result.errors.push({ path: filePath, error: 'File does not exist' });
+        return;
+    }
+    let stats;
+    try {
+        stats = statSync(filePath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        result.errors.push({ path: filePath, error: message });
+        return;
+    }
+    if (!stats.isFile()) {
+        result.errors.push({ path: filePath, error: 'Not a file' });
+        return;
+    }
+    if (stats.size > options.maxFileSize) {
+        result.skipped++;
+        return;
+    }
+    const fileType = getFileType(filePath);
+    if (!fileType) {
+        result.skipped++;
+        return;
+    }
+    const discoveredFile = {
+        path: filePath,
+        relativePath: basename(filePath),
+        type: fileType,
+        component: detectComponentType(filePath),
+        size: stats.size,
+        modified: stats.mtime,
+    };
+    result.files.push(discoveredFile);
+}
+/**
+ * Main file discovery function
+ */
+export function discoverFiles(paths, options) {
+    const result = {
+        files: [],
+        skipped: 0,
+        errors: [],
+    };
+    if (paths.length === 0) {
+        logger.warn('No paths provided for scanning');
+        return result;
+    }
+    for (const inputPath of paths) {
+        const resolvedPath = resolve(inputPath);
+        if (!existsSync(resolvedPath)) {
+            logger.warn(`Path does not exist: ${resolvedPath}`);
+            result.errors.push({ path: resolvedPath, error: 'Path does not exist' });
+            continue;
+        }
+        const stats = statSync(resolvedPath);
+        if (stats.isDirectory()) {
+            const ig = createIgnoreFilter(resolvedPath, options.ignore);
+            discoverFilesInDirectory(resolvedPath, resolvedPath, ig, options, result);
+        }
+        else if (stats.isFile()) {
+            discoverSingleFile(resolvedPath, options, result);
+        }
+    }
+    // Sort files by component type, then by path
+    result.files.sort((a, b) => {
+        if (a.component !== b.component) {
+            return a.component.localeCompare(b.component);
+        }
+        return a.relativePath.localeCompare(b.relativePath);
+    });
+    logger.info(`Discovered ${result.files.length} files, skipped ${result.skipped}`);
+    return result;
+}
+export default discoverFiles;
+//# sourceMappingURL=FileDiscovery.js.map