/** * Waggle Marketplace — Security Gate * * Multi-layered security verification for skills, plugins, and MCP servers * before they are installed into the user's Waggle instance. * * Layers: * 1. Gen Trust Hub API — Cloud URL-based pre-check (fast, free) * 2. Cisco Skill Scanner — Local deep analysis (pattern + behavioral + LLM) * 3. MCP Guardian — Inline pattern matching for MCP tool descriptions * 4. Built-in heuristics — Custom rules for Waggle-specific threat patterns * * Each layer produces findings with severity levels: * CRITICAL → Block installation, flag in DB * HIGH → Block installation by default (override with --force-insecure) * MEDIUM → Warn user, allow installation * LOW → Informational, log only * CLEAN → No issues found */ import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs'; import { join, dirname } from 'path'; import { homedir } from 'os'; import { execFileSync } from 'child_process'; import { createHash } from 'crypto'; import type { MarketplacePackage, InstallManifest, McpServerConfig } from './types.js'; import { isCiscoScannerAvailable, ciscoScan, getCiscoScannerVersion, type CiscoScanResult, } from './cisco-scanner.js'; // ─── Types ────────────────────────────────────────────────────────── export type Severity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'CLEAN'; export interface SecurityFinding { rule_id: string; severity: Severity; category: SecurityCategory; title: string; description: string; location?: string; engine: SecurityEngine; } export type SecurityCategory = | 'prompt_injection' | 'data_exfiltration' | 'malicious_code' | 'privilege_escalation' | 'suspicious_network' | 'obfuscation' | 'sensitive_path_access' | 'tool_poisoning' | 'cross_origin_escalation' | 'rug_pull' | 'untrusted_source'; export type SecurityEngine = | 'gen_trust_hub' | 'cisco_skill_scanner' | 'mcp_guardian' | 'waggle_heuristics' | 'content_hash'; /** Response shape from the Gen Trust Hub cloud scan API (best-effort). */ interface GenTrustHubResponse { severity?: string; risk_level?: string; details?: string; message?: string; threats?: Array<{ type?: string; severity?: string; title?: string; description?: string; details?: string; }>; } /** A single issue as reported by the optional `mcp-guardian` library. */ interface GuardianIssue { ruleId?: string; category?: string; message?: string; description?: string; details?: string; } /** Raw JSON emitted by the Cisco `skill-scanner` CLI (best-effort shape). */ interface CiscoScannerOutput { verdict?: string; summary?: string; findings?: Array<{ rule_id?: string; id?: string; severity?: string; level?: string; category?: string; type?: string; title?: string; message?: string; description?: string; details?: string; location?: string; line?: number; }>; } /** * Error thrown by `child_process.execFileSync`/`execSync` — augmented with the * captured stdio and exit status. Narrowed from `unknown` in catch blocks. */ interface ExecError { status?: number; stdout?: string | Buffer; stderr?: string | Buffer; message?: string; } /** Narrow an unknown caught value into an {@link ExecError} view. */ function asExecError(err: unknown): ExecError { return (typeof err === 'object' && err !== null) ? err as ExecError : {}; } export interface ScanResult { package_name: string; package_type: string; scanned_at: string; overall_severity: Severity; security_score: number; // 0-100 (100 = perfectly safe) findings: SecurityFinding[]; engines_used: SecurityEngine[]; content_hash: string; // SHA-256 of scanned content blocked: boolean; scan_duration_ms: number; /** Detailed result from the Cisco skill-scanner, when available */ ciscoScanResult?: CiscoScanResult; } export interface SecurityGateConfig { /** Enable Gen Trust Hub cloud API pre-check */ enable_gen_trust_hub: boolean; /** Enable Cisco Skill Scanner (requires `cisco-ai-skill-scanner` pip package) */ enable_cisco_scanner: boolean; /** Enable MCP Guardian pattern matching (requires `mcp-guardian` npm package) */ enable_mcp_guardian: boolean; /** Enable built-in Waggle heuristic rules */ enable_heuristics: boolean; /** Minimum severity to block installation */ block_threshold: Severity; /** Allow --force-insecure to bypass blocks */ allow_force_bypass: boolean; /** Gen Trust Hub API endpoint */ gen_trust_hub_url: string; /** Gen Trust Hub API key (if required for high volume) */ gen_trust_hub_api_key?: string; /** Cisco scanner extra arguments */ cisco_scanner_args: string[]; /** Path to custom Cisco scanner policy file */ cisco_scanner_policy?: string; /** Directory to cache scan results */ cache_dir: string; /** Cache TTL in hours (re-scan after this period) */ cache_ttl_hours: number; } const DEFAULT_CONFIG: SecurityGateConfig = { enable_gen_trust_hub: true, enable_cisco_scanner: true, enable_mcp_guardian: true, enable_heuristics: true, block_threshold: 'HIGH', allow_force_bypass: false, gen_trust_hub_url: 'https://ai.gendigital.com/api/scan/lookup', cisco_scanner_args: ['--use-behavioral', '--format', 'json'], cache_dir: join(homedir(), '.waggle', 'security-cache'), cache_ttl_hours: 24, }; // ─── Severity Utilities ───────────────────────────────────────────── const SEVERITY_ORDER: Record = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3, CLEAN: 4, }; function maxSeverity(a: Severity, b: Severity): Severity { return SEVERITY_ORDER[a] <= SEVERITY_ORDER[b] ? a : b; } function severityToScore(severity: Severity): number { switch (severity) { case 'CRITICAL': return 0; case 'HIGH': return 25; case 'MEDIUM': return 60; case 'LOW': return 85; case 'CLEAN': return 100; } } function shouldBlock(severity: Severity, threshold: Severity): boolean { return SEVERITY_ORDER[severity] <= SEVERITY_ORDER[threshold]; } // ─── Security Gate ────────────────────────────────────────────────── export class SecurityGate { private config: SecurityGateConfig; constructor(config: Partial = {}) { this.config = { ...DEFAULT_CONFIG, ...config }; mkdirSync(this.config.cache_dir, { recursive: true }); } /** * Run the full security scan pipeline on a package. * Call this BEFORE writing any files to disk. */ async scan( pkg: MarketplacePackage, content?: string, ): Promise { const startTime = Date.now(); const findings: SecurityFinding[] = []; const enginesUsed: SecurityEngine[] = []; const contentHash = content ? this.hash(content) : ''; // Check cache first const cached = this.getCachedResult(pkg.name, contentHash); if (cached) return cached; // Layer 1: Gen Trust Hub (cloud, URL-based pre-check) if (this.config.enable_gen_trust_hub && (pkg.homepage_url || pkg.repository_url)) { enginesUsed.push('gen_trust_hub'); const genFindings = await this.scanWithGenTrustHub(pkg); findings.push(...genFindings); } // Layer 2: Cisco Skill Scanner (local, deep analysis for skills) let ciscoResult: CiscoScanResult | undefined; if (this.config.enable_cisco_scanner && content && pkg.waggle_install_type === 'skill') { enginesUsed.push('cisco_skill_scanner'); const { findings: ciscoFindings, ciscoScanResult: csResult } = await this.scanWithCiscoScannerAdapter(pkg, content); findings.push(...ciscoFindings); ciscoResult = csResult; } // Layer 3: MCP Guardian (pattern matching for MCP servers) if (this.config.enable_mcp_guardian && pkg.waggle_install_type === 'mcp') { enginesUsed.push('mcp_guardian'); const mcpFindings = await this.scanWithMcpGuardian(pkg); findings.push(...mcpFindings); } // Layer 4: Built-in Waggle heuristics (always runs) if (this.config.enable_heuristics && content) { enginesUsed.push('waggle_heuristics'); const heuristicFindings = this.scanWithHeuristics(pkg, content); findings.push(...heuristicFindings); } // Layer 5: Content hash for integrity tracking if (content) { enginesUsed.push('content_hash'); } // Compute overall severity let overallSeverity: Severity = 'CLEAN'; for (const f of findings) { overallSeverity = maxSeverity(overallSeverity, f.severity); } const result: ScanResult = { package_name: pkg.name, package_type: pkg.waggle_install_type, scanned_at: new Date().toISOString(), overall_severity: overallSeverity, security_score: severityToScore(overallSeverity), findings, engines_used: enginesUsed, content_hash: contentHash, blocked: shouldBlock(overallSeverity, this.config.block_threshold), scan_duration_ms: Date.now() - startTime, ciscoScanResult: ciscoResult, }; // Cache the result this.cacheResult(pkg.name, contentHash, result); return result; } /** * Quick check: is this package safe to install? * Returns true if safe, false if blocked. */ async isSafe(pkg: MarketplacePackage, content?: string): Promise { const result = await this.scan(pkg, content); return !result.blocked; } /** * Verify content integrity against a known hash. * Use after download to ensure content hasn't been tampered with. */ verifyIntegrity(content: string, expectedHash: string): boolean { return this.hash(content) === expectedHash; } // ─── Layer 1: Gen Trust Hub ───────────────────────────────────── private async scanWithGenTrustHub(pkg: MarketplacePackage): Promise { const findings: SecurityFinding[] = []; const url = pkg.homepage_url || pkg.repository_url; if (!url) return findings; try { const headers: Record = { 'Content-Type': 'application/json', }; if (this.config.gen_trust_hub_api_key) { headers['Authorization'] = `Bearer ${this.config.gen_trust_hub_api_key}`; } const response = await fetch(this.config.gen_trust_hub_url, { method: 'POST', headers, body: JSON.stringify({ skillUrl: url }), signal: AbortSignal.timeout(15_000), }); if (!response.ok) { // API failure is not a security finding — just log and continue console.warn(`[security] Gen Trust Hub API returned ${response.status} for ${url}`); return findings; } const data = await response.json() as GenTrustHubResponse; // Parse the response into findings if (data.severity === 'CRITICAL THREAT' || data.severity === 'CRITICAL') { findings.push({ rule_id: 'GEN-001', severity: 'CRITICAL', category: 'malicious_code', title: 'Gen Trust Hub: Critical threat detected', description: data.details || data.message || `Package flagged as critical threat by Gen AI Defense.`, engine: 'gen_trust_hub', }); } else if (data.severity === 'HIGH' || data.risk_level === 'high') { findings.push({ rule_id: 'GEN-002', severity: 'HIGH', category: 'malicious_code', title: 'Gen Trust Hub: High risk detected', description: data.details || data.message || `Package flagged as high risk.`, engine: 'gen_trust_hub', }); } else if (data.severity === 'MEDIUM' || data.risk_level === 'medium') { findings.push({ rule_id: 'GEN-003', severity: 'MEDIUM', category: 'suspicious_network', title: 'Gen Trust Hub: Medium risk detected', description: data.details || data.message || `Package flagged as medium risk.`, engine: 'gen_trust_hub', }); } // Check for specific threat types from the response if (data.threats && Array.isArray(data.threats)) { for (const threat of data.threats) { findings.push({ rule_id: `GEN-T-${threat.type || 'unknown'}`, severity: (threat.severity || 'MEDIUM').toUpperCase() as Severity, category: this.mapGenCategory(threat.type || ''), title: threat.title || threat.type || 'Gen Trust Hub threat', description: threat.description || threat.details || '', engine: 'gen_trust_hub', }); } } } catch (err) { // Network errors are not security findings — fail open for this layer console.warn(`[security] Gen Trust Hub unreachable: ${(err as Error).message}`); } return findings; } private mapGenCategory(type: string): SecurityCategory { const map: Record = { 'data_exfiltration': 'data_exfiltration', 'prompt_injection': 'prompt_injection', 'malicious_code': 'malicious_code', 'file_access': 'sensitive_path_access', 'network': 'suspicious_network', 'dynamic_code': 'malicious_code', }; return map[type] || 'malicious_code'; } // ─── Layer 2: Cisco Skill Scanner ────────────────────────────── private async scanWithCiscoScanner( pkg: MarketplacePackage, content: string, ): Promise { const findings: SecurityFinding[] = []; // Check if cisco scanner is installed if (!this.isCiscoScannerInstalled()) { console.warn('[security] Cisco Skill Scanner not installed. Run: pip install cisco-ai-skill-scanner'); return findings; } try { // Write content to a temp file for scanning const tempDir = join(this.config.cache_dir, 'tmp'); mkdirSync(tempDir, { recursive: true }); const tempFile = join(tempDir, `${pkg.name}.md`); writeFileSync(tempFile, content, 'utf-8'); // Run the scanner const args = [ 'scan', tempFile, '--format', 'json', ...this.config.cisco_scanner_args, ]; if (this.config.cisco_scanner_policy) { args.push('--policy', this.config.cisco_scanner_policy); } const output = execFileSync('skill-scanner', args, { timeout: 60_000, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], }); // Parse JSON output const result = JSON.parse(output); // Map Cisco findings to our format if (result.findings && Array.isArray(result.findings)) { for (const f of result.findings) { findings.push({ rule_id: f.rule_id || f.id || `CISCO-${findings.length}`, severity: this.mapCiscoSeverity(f.severity || f.level), category: this.mapCiscoCategory(f.category || f.type), title: f.title || f.message || f.rule_id, description: f.description || f.details || '', location: f.location || f.line ? `line ${f.line}` : undefined, engine: 'cisco_skill_scanner', }); } } // Also check the summary-level verdict if (result.verdict === 'FAIL' || result.verdict === 'fail') { if (findings.length === 0) { findings.push({ rule_id: 'CISCO-VERDICT', severity: 'HIGH', category: 'malicious_code', title: 'Cisco Skill Scanner: Overall verdict FAIL', description: result.summary || 'Scanner returned FAIL verdict without specific findings.', engine: 'cisco_skill_scanner', }); } } // Clean up temp file try { unlinkSync(tempFile); } catch { /* ignore */ } } catch (err) { const execErr = asExecError(err); const errMsg = (execErr.stderr?.toString()) || (err instanceof Error ? err.message : String(err)); // Exit code 1 from skill-scanner means findings were found — try to parse stdout if (execErr.status === 1 && execErr.stdout) { try { const result = JSON.parse(execErr.stdout.toString()) as CiscoScannerOutput; if (result.findings) { for (const f of result.findings) { findings.push({ rule_id: f.rule_id || `CISCO-${findings.length}`, severity: this.mapCiscoSeverity(f.severity || f.level || ''), category: this.mapCiscoCategory(f.category || f.type || ''), title: f.title || f.message || 'Cisco scanner finding', description: f.description || '', location: f.location, engine: 'cisco_skill_scanner', }); } } } catch { console.warn(`[security] Failed to parse Cisco scanner output: ${errMsg}`); } } else { console.warn(`[security] Cisco scanner error: ${errMsg}`); } } return findings; } private isCiscoScannerInstalled(): boolean { try { execFileSync('skill-scanner', ['--version'], { stdio: 'pipe', timeout: 5_000 }); return true; } catch { return false; } } private mapCiscoSeverity(level: string): Severity { const normalized = (level || '').toLowerCase(); if (normalized === 'critical' || normalized === 'error') return 'CRITICAL'; if (normalized === 'high') return 'HIGH'; if (normalized === 'medium' || normalized === 'warning') return 'MEDIUM'; if (normalized === 'low' || normalized === 'info') return 'LOW'; return 'MEDIUM'; } private mapCiscoCategory(type: string): SecurityCategory { const map: Record = { 'prompt_injection': 'prompt_injection', 'data_exfiltration': 'data_exfiltration', 'malicious_code': 'malicious_code', 'privilege_escalation': 'privilege_escalation', 'suspicious_network': 'suspicious_network', 'obfuscation': 'obfuscation', 'shell_injection': 'malicious_code', 'file_access': 'sensitive_path_access', }; return map[(type || '').toLowerCase()] || 'malicious_code'; } // ─── Layer 2b: Cisco Scanner via Adapter ──────────────────────── /** * Scan using the cisco-scanner.ts adapter module. * This is the preferred path — uses async execFile (safer than execSync), * proper temp file management in os.tmpdir(), and 30s timeout. * * Falls back gracefully if the scanner is not installed. */ private async scanWithCiscoScannerAdapter( pkg: MarketplacePackage, content: string, ): Promise<{ findings: SecurityFinding[]; ciscoScanResult?: CiscoScanResult }> { const findings: SecurityFinding[] = []; // Check availability via the adapter (cached, fast) const available = await isCiscoScannerAvailable(); if (!available) { console.warn('[security] Cisco Skill Scanner not installed. Run: pip install cisco-ai-skill-scanner'); return { findings }; } try { const ciscoResult = await ciscoScan(content, pkg.name); // Scanner returned but was unable to actually scan (score = -1) if (ciscoResult.score === -1) { return { findings, ciscoScanResult: ciscoResult }; } // Map Cisco issues to SecurityFinding format for (const issue of ciscoResult.issues) { findings.push({ rule_id: issue.rule_id || `CISCO-${findings.length}`, severity: this.mapCiscoSeverity(issue.severity), category: this.mapCiscoCategory(issue.type), title: issue.message || issue.type || 'Cisco scanner finding', description: issue.description || '', location: issue.location || (issue.line ? `line ${issue.line}` : undefined), engine: 'cisco_skill_scanner', }); } // If the scan failed overall but no individual issues, add a summary finding if (!ciscoResult.passed && findings.length === 0) { findings.push({ rule_id: 'CISCO-VERDICT', severity: 'HIGH', category: 'malicious_code', title: 'Cisco Skill Scanner: Overall verdict FAIL', description: 'Scanner returned FAIL verdict without specific findings.', engine: 'cisco_skill_scanner', }); } return { findings, ciscoScanResult: ciscoResult }; } catch (err) { console.warn(`[security] Cisco scanner adapter error: ${(err as Error).message}`); return { findings }; } } // ─── Layer 3: MCP Guardian ──────────────────────────────────── private async scanWithMcpGuardian(pkg: MarketplacePackage): Promise { const findings: SecurityFinding[] = []; const manifest = pkg.install_manifest as InstallManifest | null; const mcpConfig = manifest?.mcp_config; if (!mcpConfig) return findings; // Try using the mcp-guardian npm library try { // Attempt to import dynamically (installed as optional peer dep) const guardian = await import('mcp-guardian').catch(() => null); if (guardian && guardian.scanToolDescription) { // Scan the MCP tool description / name const descToScan = [ mcpConfig.name, pkg.description, mcpConfig.command, ...(mcpConfig.args || []), ...Object.entries(mcpConfig.env || {}).flatMap(([key, value]) => [key, value]), ].join(' '); const result = guardian.scanToolDescription(mcpConfig.name, descToScan); if (result.status === 'critical') { for (const issue of (result.issues || []) as GuardianIssue[]) { findings.push({ rule_id: `MCG-${issue.ruleId || 'CRIT'}`, severity: 'CRITICAL', category: this.mapGuardianCategory(issue.category || ''), title: issue.message || 'MCP Guardian: Critical pattern detected', description: issue.description || issue.details || '', engine: 'mcp_guardian', }); } } else if (result.status === 'warning') { for (const issue of (result.issues || []) as GuardianIssue[]) { findings.push({ rule_id: `MCG-${issue.ruleId || 'WARN'}`, severity: 'MEDIUM', category: this.mapGuardianCategory(issue.category || ''), title: issue.message || 'MCP Guardian: Warning pattern detected', description: issue.description || issue.details || '', engine: 'mcp_guardian', }); } } // Tool pinning check if (guardian.verifyToolDefinitions) { const tools = [{ name: mcpConfig.name, description: pkg.description, schema: {} }]; const pinResult = guardian.verifyToolDefinitions(tools); if (pinResult.status === 'changed') { findings.push({ rule_id: 'MCG-RUGPULL', severity: 'HIGH', category: 'rug_pull', title: 'MCP tool definition changed since last approval', description: `Tool "${mcpConfig.name}" has been modified. Changed: ${pinResult.changedTools?.join(', ')}`, engine: 'mcp_guardian', }); } } } else { // Fallback: run our own MCP pattern detection const fallbackFindings = this.mcpPatternScan(mcpConfig, pkg.description); findings.push(...fallbackFindings); } } catch { // mcp-guardian not installed — use built-in fallback const fallbackFindings = this.mcpPatternScan(mcpConfig, pkg.description); findings.push(...fallbackFindings); } return findings; } /** * Built-in fallback MCP pattern detection (subset of MCP Guardian's 51 rules). * Used when mcp-guardian npm package is not installed. */ private mcpPatternScan(config: McpServerConfig, description: string): SecurityFinding[] { const findings: SecurityFinding[] = []; const allText = [ config.name, description, config.command, ...(config.args || []), ...Object.entries(config.env || {}).flatMap(([key, value]) => [key, value]), ].join(' ').toLowerCase(); // ── Critical: Cross-tool instructions ── const crossToolPatterns = [ /before using this tool/i, /first call/i, /then execute/i, /always call .+ before/i, /after this tool.*call/i, /instead of .+ use this/i, ]; for (const pat of crossToolPatterns) { if (pat.test(allText)) { findings.push({ rule_id: 'MCG-F-CROSS', severity: 'CRITICAL', category: 'cross_origin_escalation', title: 'Cross-tool instruction detected in MCP description', description: `Pattern "${pat.source}" found — this may be a tool shadowing attack.`, engine: 'mcp_guardian', }); break; } } // ── Critical: Privilege escalation ── const privEscPatterns = [ /ignore previous instructions/i, /override system/i, /you are now/i, /disregard all prior/i, /forget everything/i, /new instructions:/i, ]; for (const pat of privEscPatterns) { if (pat.test(allText)) { findings.push({ rule_id: 'MCG-F-PRIV', severity: 'CRITICAL', category: 'privilege_escalation', title: 'Privilege escalation pattern in MCP description', description: `Pattern "${pat.source}" found — possible prompt injection.`, engine: 'mcp_guardian', }); break; } } // ── Critical: Data exfiltration URLs ── const exfilPatterns = [ /https?:\/\/[^\s]+/i, // Any URL in tool description /send to/i, /post to/i, /forward to/i, /upload to/i, /exfiltrate/i, ]; if (/https?:\/\/(?!github\.com|npmjs\.com|localhost)[^\s]+/.test(allText)) { findings.push({ rule_id: 'MCG-F-EXFIL', severity: 'HIGH', category: 'data_exfiltration', title: 'External URL found in MCP tool description', description: 'Tool description contains a URL pointing to an external server, which could be used for data exfiltration.', engine: 'mcp_guardian', }); } // ── Warning: Sensitive paths ── const sensitivePaths = [ /~\/\.ssh/i, /~\/\.aws/i, /~\/\.gnupg/i, /\/etc\/passwd/i, /\/etc\/shadow/i, /\.env/i, /api_key/i, /secret_key/i, /private_key/i, ]; for (const pat of sensitivePaths) { if (pat.test(allText)) { findings.push({ rule_id: 'MCG-F-PATH', severity: 'MEDIUM', category: 'sensitive_path_access', title: 'Sensitive path reference in MCP description', description: `Pattern "${pat.source}" found — tool may access sensitive files.`, engine: 'mcp_guardian', }); break; } } // ── Warning: Encoded/obfuscated content ── const obfuscationPatterns = [ /[A-Za-z0-9+/]{40,}={0,2}/, // Base64 strings /\\u[0-9a-fA-F]{4}/, // Unicode escapes /\\x[0-9a-fA-F]{2}/, // Hex encoding /eval\s*\(/i, /Function\s*\(/i, ]; for (const pat of obfuscationPatterns) { if (pat.test(allText)) { findings.push({ rule_id: 'MCG-F-OBFUS', severity: 'MEDIUM', category: 'obfuscation', title: 'Obfuscated content detected in MCP description', description: `Encoded or obfuscated content found — may be hiding malicious instructions.`, engine: 'mcp_guardian', }); break; } } return findings; } private mapGuardianCategory(category: string): SecurityCategory { const map: Record = { 'cross-tool': 'cross_origin_escalation', 'privilege-escalation': 'privilege_escalation', 'exfiltration': 'data_exfiltration', 'sensitive-path': 'sensitive_path_access', 'encoded-content': 'obfuscation', }; return map[category] || 'tool_poisoning'; } // ─── Layer 4: Built-in Waggle Heuristics ────────────────────── /** * Waggle-specific security heuristics that run on all content types. * These catch patterns specific to agent skill abuse. */ private scanWithHeuristics( pkg: MarketplacePackage, content: string, ): SecurityFinding[] { const findings: SecurityFinding[] = []; // ── CRITICAL: System prompt manipulation ── const promptManipulation = [ /ignore all previous instructions/i, /disregard your system prompt/i, /you are now a/i, /override your instructions/i, /forget your rules/i, /new persona:/i, /act as if you have no restrictions/i, /jailbreak/i, /DAN mode/i, /bypass safety/i, ]; for (const pat of promptManipulation) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-001', severity: 'CRITICAL', category: 'prompt_injection', title: 'System prompt manipulation attempt', description: `Found "${match[0]}" — this attempts to override the agent's system prompt.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── CRITICAL: Data exfiltration via curl/wget/fetch ── const exfilCommands = [ /curl\s+.*-X\s*POST\s+https?:\/\/(?!localhost)/i, /curl\s+.*--data.*https?:\/\/(?!localhost)/i, /wget\s+.*-O-.*\|/i, /fetch\s*\(\s*['"]https?:\/\/(?!localhost)/i, /\bexfiltrate\b/i, /base64.*\|\s*curl/i, /cat\s+.*\|\s*nc\s/i, ]; for (const pat of exfilCommands) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-002', severity: 'CRITICAL', category: 'data_exfiltration', title: 'Data exfiltration command detected', description: `Found "${match[0]}" — this may send user data to an external server.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── HIGH: Suspicious file access ── const fileAccess = [ /~\/\.waggle\/.*\.mind/i, // Agent memory files /~\/\.ssh\/id_/i, // SSH private keys /~\/\.aws\/credentials/i, // AWS credentials /~\/\.gnupg/i, // GPG keys /\/etc\/shadow/i, // System passwords /\.env\b/i, // Environment files /WAGGLE_.*TOKEN/i, // Waggle tokens /registry\.json/i, // Plugin registry (write access) ]; for (const pat of fileAccess) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-003', severity: 'HIGH', category: 'sensitive_path_access', title: 'Access to sensitive file path', description: `Found "${match[0]}" — this skill references sensitive files that should not be accessed.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── HIGH: Code execution patterns ── const codeExec = [ /eval\s*\(/i, /exec\s*\(/i, /Function\s*\(\s*['"]return/i, /child_process/i, /require\s*\(\s*['"]child_process/i, /import.*child_process/i, /subprocess\.run/i, /os\.system\s*\(/i, /\bexecSync\b/i, ]; for (const pat of codeExec) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-004', severity: 'HIGH', category: 'malicious_code', title: 'Arbitrary code execution pattern', description: `Found "${match[0]}" — skills should not contain executable code patterns.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── MEDIUM: Excessive permission requests ── const excessivePerms = [ /full access to.*filesystem/i, /unrestricted.*bash/i, /sudo/i, /root access/i, /disable.*confirmation/i, /auto.?approve/i, /skip.*verification/i, /bypass.*security/i, ]; for (const pat of excessivePerms) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-005', severity: 'MEDIUM', category: 'privilege_escalation', title: 'Excessive permission request', description: `Found "${match[0]}" — this skill requests elevated privileges that may not be necessary.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── MEDIUM: Hidden instructions (zero-width chars, HTML comments) ── const hiddenContent = [ // Zero-width chars (incl. ZWJ U+200D). Written as an alternation rather than a // character class so no-misleading-character-class doesn't flag the joiner \u2014 // behavior is identical (matches a run of 2+ zero-width code points). /(?:\u200B|\u200C|\u200D|\u2060|\uFEFF){2,}/, //, // HTML comments (hidden instructions) /\[hidden\]/i, /\[invisible\]/i, /display:\s*none/i, /opacity:\s*0/i, /color:\s*transparent/i, ]; for (const pat of hiddenContent) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-006', severity: 'MEDIUM', category: 'obfuscation', title: 'Hidden content detected', description: `Found obfuscated or hidden content that may contain concealed instructions.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── HIGH: Tool poisoning — MCP/tool descriptions that trick the agent ── const toolPoisoning = [ /when the user asks you to.*instead/i, /always (?:run|execute|call) this (?:tool|command) (?:first|before)/i, /do not (?:tell|inform|show) the user/i, /secretly|covertly|without.*(?:user|them) knowing/i, /pretend (?:this|you|that)/i, /this tool (?:should|must|needs to) (?:be )?(?:run|called|executed) (?:on every|before each|automatically)/i, /override.*(?:user|default).*(?:preference|setting|choice)/i, ]; for (const pat of toolPoisoning) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-008', severity: 'HIGH', category: 'tool_poisoning', title: 'Tool poisoning — deceptive agent instruction', description: `Found "${match[0]}" — this may manipulate agent behavior without user awareness.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── HIGH: Credential harvesting patterns ── const credentialHarvest = [ /(?:api[_-]?key|token|password|secret|credential).*(?:send|post|upload|transmit|forward)/i, /(?:send|post|upload|transmit|forward).*(?:api[_-]?key|token|password|secret|credential)/i, /(?:extract|harvest|collect|gather).*(?:key|token|password|secret|credential)/i, /(?:ANTHROPIC|OPENAI|GITHUB|AWS|STRIPE)[_-](?:API[_-])?(?:KEY|TOKEN|SECRET)/, /process\.env\[.*(?:KEY|TOKEN|SECRET|PASSWORD)/i, /vault\.(?:get|read|reveal|list)/i, ]; for (const pat of credentialHarvest) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-009', severity: 'HIGH', category: 'data_exfiltration', title: 'Credential harvesting pattern', description: `Found "${match[0]}" — this may attempt to extract or transmit credentials.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── HIGH: Network beaconing — DNS/webhook/ping-back patterns ── const beaconing = [ /(?:webhook|callback|ping[_-]?back|beacon|phone[_-]?home).*(?:url|endpoint|server)/i, /(?:url|endpoint|server).*(?:webhook|callback|ping[_-]?back|beacon|phone[_-]?home)/i, /dns[_-]?(?:lookup|resolve|query).*(?:encode|embed|exfil)/i, /(?:ngrok|requestbin|webhook\.site|pipedream|hookbin|burp|interactsh)/i, /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d{2,5}\b/, // Raw IP:port ]; for (const pat of beaconing) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-010', severity: 'HIGH', category: 'suspicious_network', title: 'Network beaconing pattern', description: `Found "${match[0]}" — this may establish unauthorized external communication.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── MEDIUM: Behavioral dataflow — read sensitive then write to network ── const readsSensitive = /(?:read|cat|load|open|access).*(?:\.env|\.ssh|\.aws|credentials|vault|secret|\.mind)/i.test(content); const writesNetwork = /(?:fetch|curl|wget|http|post|send|upload|socket)/i.test(content); if (readsSensitive && writesNetwork) { findings.push({ rule_id: 'WAG-011', severity: 'MEDIUM', category: 'data_exfiltration', title: 'Sensitive data + network access pattern', description: 'Skill reads sensitive local files AND makes network calls — potential data exfiltration pipeline.', engine: 'waggle_heuristics', }); } // ── MEDIUM: Supply chain — suspicious package/dependency patterns ── const supplyChain = [ /npm install\s+[a-z0-9-]+(?![\s\S]*(?:npm\.js|npmjs\.com|github\.com))/i, // Install unknown packages /pip install\s+[a-z0-9-]+\s+--index-url\s+(?!https:\/\/pypi)/i, // Custom PyPI index /go get\s+[a-z0-9./]+/i, /(?:require|import)\s*\(?['"][a-z0-9-]+['"]\)?\s*.*(?:eval|exec|Function)/i, // Dynamic import + execution ]; for (const pat of supplyChain) { const match = content.match(pat); if (match) { findings.push({ rule_id: 'WAG-012', severity: 'MEDIUM', category: 'malicious_code', title: 'Supply chain risk — dynamic dependency installation', description: `Found "${match[0]}" — skills should not install dependencies at runtime.`, location: this.findLineNumber(content, match.index || 0), engine: 'waggle_heuristics', }); } } // ── MEDIUM: Cross-origin escalation — skill tries to modify other skills/plugins ── const crossOrigin = [ /~\/\.claude\/(?:skills|plugins|hooks|commands)/i, /~\/\.waggle\/skills/i, /CLAUDE\.md/i, /\.cursorrules/i, /write.*(?:CLAUDE\.md|\.cursorrules|settings\.json|hooks\/)/i, ]; let crossOriginCount = 0; for (const pat of crossOrigin) { if (pat.test(content)) crossOriginCount++; } if (crossOriginCount >= 2) { findings.push({ rule_id: 'WAG-013', severity: 'MEDIUM', category: 'cross_origin_escalation', title: 'Cross-origin skill modification', description: `Skill references ${crossOriginCount} external agent config paths — may attempt to modify other agents' behavior.`, engine: 'waggle_heuristics', }); } // ── LOW: Waggle internals referenced ── const internals = [ /orchestrator/i, /PluginManager/i, /MindDB/i, /waggle-dance/i, /system-prompt\.md/i, ]; let internalCount = 0; for (const pat of internals) { if (pat.test(content)) internalCount++; } if (internalCount >= 3) { findings.push({ rule_id: 'WAG-007', severity: 'LOW', category: 'suspicious_network', title: 'Excessive Waggle internal references', description: `Skill references ${internalCount} Waggle internal components — may be probing platform internals.`, engine: 'waggle_heuristics', }); } return findings; } // ─── Helpers ────────────────────────────────────────────────── private hash(content: string): string { return createHash('sha256').update(content, 'utf-8').digest('hex'); } private findLineNumber(content: string, charIndex: number): string { const lines = content.substring(0, charIndex).split('\n'); return `line ${lines.length}`; } private getCacheKey(name: string, hash: string): string { return join(this.config.cache_dir, `${name}-${hash.substring(0, 12)}.json`); } private getCachedResult(name: string, hash: string): ScanResult | null { if (!hash) return null; const cachePath = this.getCacheKey(name, hash); if (!existsSync(cachePath)) return null; try { const cached = JSON.parse(readFileSync(cachePath, 'utf-8')) as ScanResult & { _cached_at: number }; const ageHours = (Date.now() - cached._cached_at) / (1000 * 60 * 60); if (ageHours > this.config.cache_ttl_hours) return null; return cached; } catch { return null; } } private cacheResult(name: string, hash: string, result: ScanResult): void { if (!hash) return; const cachePath = this.getCacheKey(name, hash); try { writeFileSync(cachePath, JSON.stringify({ ...result, _cached_at: Date.now() }, null, 2), 'utf-8'); } catch { /* ignore cache write failures */ } } // ─── Reporting ──────────────────────────────────────────────── /** * Format scan results as a human-readable report. */ formatReport(result: ScanResult): string { const lines: string[] = []; const statusIcon = result.blocked ? '🚫' : result.overall_severity === 'CLEAN' ? '✅' : '⚠️'; lines.push(`${statusIcon} Security Scan: ${result.package_name}`); lines.push(`${'─'.repeat(50)}`); lines.push(`Type: ${result.package_type}`); lines.push(`Severity: ${result.overall_severity}`); lines.push(`Score: ${result.security_score}/100`); lines.push(`Blocked: ${result.blocked ? 'YES' : 'no'}`); lines.push(`Engines: ${result.engines_used.join(', ')}`); lines.push(`Duration: ${result.scan_duration_ms}ms`); lines.push(`Hash: ${result.content_hash.substring(0, 16)}...`); lines.push(''); if (result.findings.length === 0) { lines.push(' No security issues found.'); } else { lines.push(` ${result.findings.length} finding(s):`); lines.push(''); for (const f of result.findings) { const icon = f.severity === 'CRITICAL' ? '🔴' : f.severity === 'HIGH' ? '🟠' : f.severity === 'MEDIUM' ? '🟡' : '🔵'; lines.push(` ${icon} [${f.severity}] ${f.title}`); lines.push(` Rule: ${f.rule_id} | Engine: ${f.engine} | Category: ${f.category}`); if (f.description) lines.push(` ${f.description}`); if (f.location) lines.push(` Location: ${f.location}`); lines.push(''); } } return lines.join('\n'); } }