@hungpg/skill-audit 0.1.0

package/dist/index.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { discoverSkills } from "./discover.js";
+import { auditSecurity } from "./security.js";
+import { validateSkillSpec } from "./spec.js";
+import { createGroupedAuditResult } from "./scoring.js";
+import { scanDependencies } from "./deps.js";
+import { getKEV, getEPSS, isCacheStale } from "./intel.js";
+import { writeFileSync } from "fs";
+// Build CLI - no subcommands, just options + action
+const program = new Command();
+program
+    .name("skills-audit")
+    .description("Security auditing CLI for AI agent skills")
+    .version("0.1.0")
+    .option("-g, --global", "Audit global skills only (default: true)")
+    .option("-p, --project", "Audit project-level skills only")
+    .option("-a, --agent <agents...>", "Filter by specific agents")
+    .option("-j, --json", "Output as JSON")
+    .option("-o, --output <file>", "Save report to file (JSON format)")
+    .option("-v, --verbose", "Show detailed findings")
+    .option("-t, --threshold <score>", "Fail if risk score exceeds threshold", parseFloat)
+    .option("--no-deps", "Skip dependency scanning (faster)")
+    .option("--mode <mode>", "Audit mode: 'lint' (spec only) or 'audit' (full)", "audit")
+    .option("--update-db", "Update advisory intelligence feeds")
+    .option("--source <sources...>", "Sources for update-db: kev, epss, all", ["all"])
+    .option("--strict", "Fail if feeds are stale")
+    .option("--quiet", "Suppress non-error output");
+program.parse(process.argv);
+const options = program.opts();
+// Handle update-db action
+if (options.updateDb) {
+    await updateAdvisoryDB({ source: options.source, strict: options.strict });
+    process.exit(0);
+}
+// Default to global skills
+const scope = options.project ? "project" : "global";
+const mode = options.mode || "audit";
+if (!options.json) {
+    console.log(mode === "lint"
+        ? "📋 Linting skills (spec validation)..."
+        : "🔍 Auditing skills (full security + intelligence)...");
+}
+const skills = await discoverSkills(scope);
+// Filter by agents if specified
+let filteredSkills = skills;
+if (options.agent && options.agent.length > 0) {
+    filteredSkills = skills.filter(s => s.agents.some(a => options.agent.includes(a)));
+}
+if (!options.json) {
+    console.log("Found " + filteredSkills.length + " skills\n");
+}
+const results = [];
+for (const skill of filteredSkills) {
+    // Step 1: Spec validation (always runs first)
+    const specResult = validateSkillSpec(skill.path, skill.name);
+    // Step 2: Security audit (full or lite based on mode)
+    let securityResult = { findings: [], unreadableFiles: [] };
+    let depFindings = [];
+    if (mode === "audit") {
+        securityResult = auditSecurity(skill, specResult.manifest);
+        if (options.deps !== false) {
+            depFindings = scanDependencies(skill.path);
+        }
+    }
+    const allSecurityFindings = [...securityResult.findings, ...depFindings];
+    const result = createGroupedAuditResult(skill, specResult.manifest, specResult.findings, allSecurityFindings, []);
+    results.push(result);
+}
+reportGroupedResults(results, {
+    json: options.json,
+    output: options.output,
+    verbose: options.verbose,
+    threshold: options.threshold,
+    mode
+});
+async function updateAdvisoryDB(opts) {
+    const sources = opts.source.includes("all") ? ["kev", "epss"] : opts.source;
+    const quiet = program.opts().quiet;
+    if (!quiet) {
+        console.log("📥 Updating advisory intelligence feeds...\n");
+    }
+    let hasErrors = false;
+    for (const source of sources) {
+        if (!quiet) {
+            console.log(`Fetching ${source.toUpperCase()}...`);
+        }
+        try {
+            if (source === "kev") {
+                const result = await getKEV();
+                if (!quiet) {
+                    console.log(`   ✓ CISA KEV: ${result.findings.length} vulnerabilities cached (stale: ${result.stale})`);
+                }
+            }
+            else if (source === "epss") {
+                const result = await getEPSS();
+                if (!quiet) {
+                    console.log(`   ✓ EPSS: ${result.findings.length} scores cached (stale: ${result.stale})`);
+                }
+            }
+        }
+        catch (e) {
+            console.error(`   ✗ Failed to fetch ${source}:`, e);
+            hasErrors = true;
+        }
+    }
+    if (!quiet) {
+        console.log("\n✅ Advisory DB updated");
+    }
+    if (opts.strict && hasErrors) {
+        process.exit(1);
+    }
+}
+function reportGroupedResults(results, options) {
+    const { json, output, verbose, threshold, mode } = options;
+    // Export to file if specified
+    if (output) {
+        const report = {
+            generated: new Date().toISOString(),
+            mode,
+            summary: {
+                total: results.length,
+                safe: results.filter(r => r.riskLevel === "safe").length,
+                risky: results.filter(r => r.riskLevel === "risky").length,
+                dangerous: results.filter(r => r.riskLevel === "dangerous").length,
+                malicious: results.filter(r => r.riskLevel === "malicious").length,
+                specIssues: results.filter(r => r.specFindings.length > 0).length,
+                securityIssues: results.filter(r => r.securityFindings.length > 0).length
+            },
+            results
+        };
+        writeFileSync(output, JSON.stringify(report, null, 2));
+        console.log(`\n📄 Report saved to: ${output}`);
+        return;
+    }
+    if (json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    let safeCount = 0, riskyCount = 0, dangerousCount = 0, maliciousCount = 0;
+    let specErrors = 0, securityIssues = 0;
+    for (const r of results) {
+        if (r.riskLevel === "safe")
+            safeCount++;
+        else if (r.riskLevel === "risky")
+            riskyCount++;
+        else if (r.riskLevel === "dangerous")
+            dangerousCount++;
+        else
+            maliciousCount++;
+        if (r.specFindings.length > 0)
+            specErrors++;
+        if (r.securityFindings.length > 0)
+            securityIssues++;
+    }
+    console.log(`\n📊 Summary (${mode} mode):`);
+    console.log(`   Safe: ${safeCount} | Risky: ${riskyCount} | Dangerous: ${dangerousCount} | Malicious: ${maliciousCount}`);
+    console.log(`   Skills with spec issues: ${specErrors} | Security issues: ${securityIssues}`);
+    // Check cache freshness and warn if stale
+    const kevStale = isCacheStale("kev");
+    const epssStale = isCacheStale("epss");
+    if (!options.json && (kevStale.warn || epssStale.warn)) {
+        console.log(`\n⚠️  Vulnerability DB is stale (${kevStale.age?.toFixed(1)} days for KEV, ${epssStale.age?.toFixed(1)} days for EPSS)`);
+        console.log(`   Run: npx skill-audit --update-db`);
+    }
+    if (threshold !== undefined) {
+        const failing = results.filter(r => r.riskScore > threshold);
+        if (failing.length > 0) {
+            console.log(`\n❌ ${failing.length} skills exceed threshold ${threshold}`);
+            for (const f of failing) {
+                console.log(`   - ${f.skill.name}: ${f.riskScore}`);
+            }
+        }
+        else {
+            console.log(`\n✅ All skills pass threshold ${threshold}`);
+        }
+    }
+    if (verbose) {
+        for (const r of results) {
+            console.log(`\n--- ${r.skill.name} ---`);
+            if (r.specFindings.length > 0) {
+                console.log(`\n📋 Spec Issues (${r.specFindings.length}):`);
+                for (const f of r.specFindings) {
+                    console.log(`   [${f.severity.toUpperCase()}] ${f.id}: ${f.message}`);
+                }
+            }
+            if (r.securityFindings.length > 0) {
+                console.log(`\n🔒 Security Issues (${r.securityFindings.length}):`);
+                for (const f of r.securityFindings) {
+                    console.log(`   [${f.severity.toUpperCase()}] ${f.id}: ${f.message}`);
+                }
+            }
+        }
+    }
+}

package/dist/intel.js

@@ -0,0 +1,416 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+// Cache directory - in package root (parent of src)
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const CACHE_DIR = join(PACKAGE_ROOT, ".cache/skill-audit/feeds");
+const METRICS_FILE = join(PACKAGE_ROOT, ".cache/skill-audit/metrics.json");
+// Cache configuration - differentiated by source update frequency
+const MAX_CACHE_AGE_DAYS = {
+    kev: 1, // Daily updates - critical for actively exploited vulns
+    epss: 3, // Matches FIRST.org update cycle
+    osv: 7 // Stable database - weekly acceptable
+};
+const WARN_CACHE_AGE_DAYS = 3;
+const FETCH_TIMEOUT_MS = 30000; // 30 seconds
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1000; // Base delay for exponential backoff
+/**
+ * Ensure cache directory exists
+ */
+function ensureCacheDir() {
+    if (!existsSync(CACHE_DIR)) {
+        mkdirSync(CACHE_DIR, { recursive: true });
+    }
+    // Also ensure parent dir exists for metrics file
+    const metricsDir = dirname(METRICS_FILE);
+    if (!existsSync(metricsDir)) {
+        mkdirSync(metricsDir, { recursive: true });
+    }
+}
+/**
+ * Fetch with retry and exponential backoff
+ */
+async function fetchWithRetry(url, timeoutMs = FETCH_TIMEOUT_MS, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal,
+                headers: {
+                    'User-Agent': 'skill-audit/0.1.0 (Vulnerability Intelligence Scanner)',
+                    ...options.headers
+                }
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                return response;
+            }
+            console.error(`Fetch failed (${url}): HTTP ${response.status}`);
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (attempt === MAX_RETRIES - 1) {
+                throw error; // Last attempt - rethrow
+            }
+            // Exponential backoff: 1s, 2s, 4s
+            const delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+            console.error(`Fetch failed (${url}), retrying in ${delay}ms... (attempt ${attempt + 1}/${MAX_RETRIES})`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw new Error('Max retries exceeded');
+}
+/**
+ * Load update metrics
+ */
+function loadMetrics() {
+    if (!existsSync(METRICS_FILE)) {
+        return { lastUpdate: '', kevCount: 0, epssCount: 0, fetchDurationMs: 0, errors: [] };
+    }
+    try {
+        return JSON.parse(readFileSync(METRICS_FILE, 'utf-8'));
+    }
+    catch {
+        return { lastUpdate: '', kevCount: 0, epssCount: 0, fetchDurationMs: 0, errors: [] };
+    }
+}
+/**
+ * Save update metrics
+ */
+function saveMetrics(metrics) {
+    try {
+        writeFileSync(METRICS_FILE, JSON.stringify(metrics, null, 2));
+    }
+    catch (error) {
+        console.error('Failed to save metrics:', error);
+    }
+}
+/**
+ * Record fetch result in metrics
+ */
+function recordFetchResult(source, count, durationMs, error) {
+    const metrics = loadMetrics();
+    metrics.lastUpdate = new Date().toISOString();
+    metrics.fetchDurationMs += durationMs;
+    if (source === 'kev') {
+        metrics.kevCount = count;
+    }
+    else if (source === 'epss') {
+        metrics.epssCount = count;
+    }
+    if (error) {
+        metrics.errors.push(`${source}: ${error}`);
+        // Keep only last 10 errors
+        if (metrics.errors.length > 10) {
+            metrics.errors = metrics.errors.slice(-10);
+        }
+    }
+    saveMetrics(metrics);
+}
+/**
+ * Get cache file path for a source
+ */
+function getCachePath(source) {
+    ensureCacheDir();
+    return join(CACHE_DIR, `${source.toLowerCase()}.jsonl`);
+}
+/**
+ * Get metadata file path
+ */
+function getMetaPath(source) {
+    ensureCacheDir();
+    return join(CACHE_DIR, `${source.toLowerCase()}.meta.json`);
+}
+/**
+ * Check if cache is stale and return age info
+ */
+export function isCacheStale(source) {
+    const metaPath = getMetaPath(source);
+    if (!existsSync(metaPath)) {
+        return { stale: true, warn: false };
+    }
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+        const fetchedAt = new Date(meta.fetchedAt);
+        const now = new Date();
+        const ageMs = now.getTime() - fetchedAt.getTime();
+        const ageDays = ageMs / (1000 * 60 * 60 * 24);
+        // Use source-specific max age
+        const maxAge = MAX_CACHE_AGE_DAYS[source.toLowerCase()] || MAX_CACHE_AGE_DAYS.osv;
+        return {
+            stale: ageDays > maxAge,
+            age: ageDays,
+            warn: ageDays > WARN_CACHE_AGE_DAYS
+        };
+    }
+    catch {
+        return { stale: true, warn: false };
+    }
+}
+/**
+ * Save advisory records to cache
+ */
+function saveToCache(source, records) {
+    const cachePath = getCachePath(source);
+    const metaPath = getMetaPath(source);
+    // Save records as JSONL
+    const lines = records.map(r => JSON.stringify(r)).join('\n');
+    writeFileSync(cachePath, lines);
+    // Save metadata
+    const meta = {
+        source,
+        fetchedAt: new Date().toISOString(),
+        recordCount: records.length
+    };
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+}
+/**
+ * Load cached records
+ */
+function loadFromCache(source) {
+    const cachePath = getCachePath(source);
+    if (!existsSync(cachePath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(cachePath, "utf-8");
+        return content.split('\n').filter(Boolean).map(line => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Query OSV API for vulnerabilities (using native fetch)
+ * Note: Replaces curl-based approach with native Node.js HTTP
+ */
+export async function queryOSV(ecosystem, packageName) {
+    try {
+        const response = await fetchWithRetry('https://api.osv.dev/v1/query', FETCH_TIMEOUT_MS, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                package: {
+                    name: packageName,
+                    ecosystem: ecosystem
+                }
+            })
+        });
+        if (!response.ok) {
+            console.error(`OSV API error: ${response.status}`);
+            return [];
+        }
+        const data = await response.json();
+        if (!data.vulns) {
+            return [];
+        }
+        return data.vulns.map(v => ({
+            id: v.id,
+            aliases: v.aliases || [],
+            source: "OSV",
+            ecosystem,
+            packageName,
+            severity: v.severity?.[0]?.type,
+            published: v.published,
+            modified: v.modified,
+            summary: v.summary,
+            references: v.references?.map(r => r.url) || []
+        }));
+    }
+    catch (error) {
+        console.error(`OSV query failed for ${ecosystem}/${packageName}:`, error);
+        return [];
+    }
+}
+/**
+ * Query GHSA via GitHub API
+ */
+export async function queryGHSA(ecosystem, packageName) {
+    // GHSA API requires authentication for higher rate limits
+    // This is a placeholder - in production, use a GitHub token
+    try {
+        const ghsaEcosystemMap = {
+            'npm': 'npm',
+            'pypi': 'PyPI',
+            'go': 'Go',
+            'cargo': 'Cargo',
+            'rubygems': 'RubyGems',
+            'maven': 'Maven',
+            'nuget': 'NuGet'
+        };
+        const ghsaQuery = encodeURIComponent(`${packageName} repo:github/advisory-database`);
+        // Note: This is a simplified approach - production would use GraphQL API
+        console.log(`GHSA query: ${ecosystem}/${packageName} (API token recommended for production)`);
+        return [];
+    }
+    catch (error) {
+        console.error(`GHSA query failed:`, error);
+        return [];
+    }
+}
+/**
+ * Fetch CISA KEV (Known Exploited Vulnerabilities)
+ */
+export async function fetchKEV() {
+    const startTime = Date.now();
+    const url = 'https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json';
+    try {
+        const response = await fetchWithRetry(url);
+        const data = await response.json();
+        if (!data.vulnerabilities) {
+            recordFetchResult('kev', 0, Date.now() - startTime, 'No vulnerabilities in response');
+            return [];
+        }
+        const records = data.vulnerabilities.map(v => ({
+            id: v.cveID,
+            aliases: [v.cveID],
+            source: "KEV",
+            kev: true,
+            published: v.dateAdded,
+            summary: v.shortDescription,
+            references: v.reference ? [v.reference] : []
+        }));
+        recordFetchResult('kev', records.length, Date.now() - startTime);
+        return records;
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        recordFetchResult('kev', 0, Date.now() - startTime, errorMsg);
+        console.error(`KEV fetch failed:`, error);
+        return [];
+    }
+}
+/**
+ * Fetch EPSS scores
+ */
+export async function fetchEPSS() {
+    const startTime = Date.now();
+    const url = 'https://api.first.org/data/v1/epss?limit=500&sort=epss';
+    try {
+        const response = await fetchWithRetry(url);
+        const data = await response.json();
+        if (!data.data) {
+            recordFetchResult('epss', 0, Date.now() - startTime, 'No data in response');
+            return [];
+        }
+        const records = data.data.map(entry => ({
+            id: entry.cve,
+            aliases: [entry.cve],
+            source: "EPSS",
+            epss: parseFloat(entry.epss),
+            published: entry.date,
+            references: []
+        }));
+        recordFetchResult('epss', records.length, Date.now() - startTime);
+        return records;
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        recordFetchResult('epss', 0, Date.now() - startTime, errorMsg);
+        console.error(`EPSS fetch failed:`, error);
+        return [];
+    }
+}
+/**
+ * Query vulnerability intelligence for a package
+ */
+export async function queryIntel(ecosystem, packageName) {
+    const findings = [];
+    // Check cache freshness
+    const { stale, age } = isCacheStale("osv");
+    // Try OSV first (most comprehensive for package vulns)
+    const osvResults = await queryOSV(ecosystem, packageName);
+    findings.push(...osvResults);
+    // Try GHSA
+    const ghsaResults = await queryGHSA(ecosystem, packageName);
+    findings.push(...ghsaResults);
+    return {
+        findings,
+        cacheAge: age,
+        stale
+    };
+}
+/**
+ * Get KEV vulnerabilities (enriched)
+ */
+export async function getKEV() {
+    const { stale, age, warn } = isCacheStale("kev");
+    let records = loadFromCache("kev");
+    if (records.length === 0 || stale) {
+        records = await fetchKEV();
+        if (records.length > 0) {
+            saveToCache("kev", records);
+        }
+    }
+    return {
+        findings: records,
+        cacheAge: age,
+        stale,
+        warn
+    };
+}
+/**
+ * Get EPSS scores (enriched)
+ */
+export async function getEPSS() {
+    const { stale, age, warn } = isCacheStale("epss");
+    let records = loadFromCache("epss");
+    if (records.length === 0 || stale) {
+        records = await fetchEPSS();
+        if (records.length > 0) {
+            saveToCache("epss", records);
+        }
+    }
+    return {
+        findings: records,
+        cacheAge: age,
+        stale,
+        warn
+    };
+}
+/**
+ * Merge advisory records by alias
+ */
+export function mergeByAlias(records) {
+    const aliasMap = new Map();
+    for (const record of records) {
+        // Use all IDs and aliases as keys
+        const ids = [record.id, ...record.aliases];
+        for (const id of ids) {
+            const key = id.toUpperCase();
+            if (!aliasMap.has(key)) {
+                aliasMap.set(key, []);
+            }
+            aliasMap.get(key).push(record);
+        }
+    }
+    return aliasMap;
+}
+/**
+ * Prioritize records by source (OSV/GHSA > KEV > EPSS)
+ */
+export function prioritizeRecords(records) {
+    const sourcePriority = {
+        "OSV": 1,
+        "GHSA": 2,
+        "NVD": 3,
+        "KEV": 4,
+        "EPSS": 5
+    };
+    return [...records].sort((a, b) => {
+        const aP = sourcePriority[a.source] || 10;
+        const bP = sourcePriority[b.source] || 10;
+        if (aP !== bP)
+            return aP - bP;
+        // Secondary: EPSS score (higher is worse)
+        if (a.epss !== undefined && b.epss !== undefined) {
+            return b.epss - a.epss;
+        }
+        return 0;
+    });
+}

package/dist/reporter.js

@@ -0,0 +1,77 @@
+const LEVEL_ICONS = {
+    "safe": "✅",
+    "risky": "⚠️",
+    "dangerous": "🔴",
+    "malicious": "☠️",
+};
+const SEVERITY_COLORS = {
+    "critical": "\x1b[31m",
+    "high": "\x1b[33m",
+    "medium": "\x1b[35m",
+    "low": "\x1b[36m",
+    "info": "\x1b[90m",
+};
+const RESET = "\x1b[0m";
+function padEnd(str, len) {
+    while (str.length < len)
+        str += " ";
+    return str;
+}
+export function reportResults(results, options) {
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    const byAgent = new Map();
+    for (const result of results) {
+        for (const agent of result.skill.agents) {
+            if (!byAgent.has(agent))
+                byAgent.set(agent, []);
+            byAgent.get(agent).push(result);
+        }
+    }
+    const uniqueSkills = new Map();
+    for (const result of results) {
+        uniqueSkills.set(result.skill.name, result);
+    }
+    const uniqueResults = Array.from(uniqueSkills.values());
+    console.log("\n🔍 Auditing installed skills...\n");
+    console.log("Total: " + uniqueResults.length + " skills scanned");
+    const safe = uniqueResults.filter(r => r.riskLevel === "safe").length;
+    const risky = uniqueResults.filter(r => r.riskLevel === "risky").length;
+    const dangerous = uniqueResults.filter(r => r.riskLevel === "dangerous").length;
+    const malicious = uniqueResults.filter(r => r.riskLevel === "malicious").length;
+    console.log("✅ Safe: " + safe + " | ⚠️ Risky: " + risky + " | 🔴 Dangerous: " + dangerous + " | ☠️ Malicious: " + malicious + "\n");
+    for (const [agent, agentResults] of byAgent) {
+        const uniqueAgentSkills = new Map();
+        for (const r of agentResults) {
+            uniqueAgentSkills.set(r.skill.name, r);
+        }
+        console.log("📂 " + agent + " (" + uniqueAgentSkills.size + " skills)");
+        for (const result of uniqueAgentSkills.values()) {
+            const icon = LEVEL_ICONS[result.riskLevel];
+            const score = result.riskScore.toFixed(1);
+            console.log("  " + icon + " " + padEnd(result.skill.name, 40) + " " + score);
+            if (options.verbose && result.findings.length > 0) {
+                for (const f of result.findings.slice(0, 5)) {
+                    const color = SEVERITY_COLORS[f.severity] || "";
+                    console.log("      " + color + f.severity.toUpperCase() + RESET + ": [" + f.asixx + "] " + f.message);
+                }
+                if (result.findings.length > 5) {
+                    console.log("      ... and " + (result.findings.length - 5) + " more");
+                }
+            }
+        }
+        console.log("");
+    }
+    if (options.threshold !== undefined) {
+        const failed = uniqueResults.filter(r => r.riskScore > options.threshold);
+        if (failed.length > 0) {
+            console.log("❌ " + failed.length + " skills exceed threshold (" + options.threshold + ")");
+            process.exit(1);
+        }
+        else {
+            console.log("✅ All skills within acceptable risk threshold");
+        }
+    }
+}