@guava-parity/guard-scanner 15.0.0 → 16.0.0

package/src/skill-crawler.js

@@ -1,254 +0,0 @@
-#!/usr/bin/env node
-/**
- * guard-scanner — Skill Crawler
- *
- * @security-manifest
- *   env-read: [GITHUB_TOKEN (optional, for higher rate limits)]
- *   env-write: []
- *   network: [GitHub REST API, raw.githubusercontent.com, ClawHub registry]
- *   fs-read: []
- *   fs-write: []
- *   exec: none
- *   purpose: Crawl ClawHub/GitHub for SKILL.md files and scan for threats
- */
-
-const { httpGet } = require('./asset-auditor.js');
-const { GuardScanner } = require('./scanner.js');
-
-const CRAWLER_VERSION = '1.0.0';
-
-// ClawHub skills repo (openclaw/skills on GitHub)
-const CLAWHUB_OWNER = 'openclaw';
-const CLAWHUB_REPO = 'skills';
-const CLAWHUB_BRANCH = 'main';
-
-class SkillCrawler {
-    constructor(options = {}) {
-        this.verbose = options.verbose || false;
-        this.quiet = options.quiet || false;
-        this.concurrency = options.concurrency || 5;
-        this.scanner = new GuardScanner({
-            verbose: false,
-            soulLock: true,
-            quiet: true,
-        });
-        this._httpGet = options._httpGet || httpGet;
-        this.results = [];
-        this.errors = [];
-    }
-
-    /**
-     * Crawl ClawHub (openclaw/skills) for SKILL.md files
-     * Uses GitHub tree API to list all SKILL.md paths, then fetches each
-     */
-    async crawlClawHub(opts = {}) {
-        const maxSkills = opts.maxSkills || 50;
-        if (!this.quiet) console.log(`\n🔍 Crawling ClawHub (${CLAWHUB_OWNER}/${CLAWHUB_REPO})...`);
-
-        try {
-            // Get recursive tree to find all SKILL.md files
-            const treeUrl = `https://api.github.com/repos/${CLAWHUB_OWNER}/${CLAWHUB_REPO}/git/trees/${CLAWHUB_BRANCH}?recursive=1`;
-            const response = await this._httpGet(treeUrl, {
-                headers: this._getHeaders(),
-            });
-
-            if (response.status !== 200) {
-                this.errors.push({ source: 'clawhub', error: `API returned ${response.status}` });
-                return this.results;
-            }
-
-            const tree = response.data.tree || [];
-            const skillMds = tree
-                .filter(item => item.type === 'blob' && /SKILL\.md$/i.test(item.path))
-                .slice(0, maxSkills);
-
-            if (!this.quiet) console.log(`📦 Found ${skillMds.length} SKILL.md files`);
-
-            // Batch fetch and scan
-            await this._batchProcess(skillMds.map(item => ({
-                source: 'clawhub',
-                path: item.path,
-                rawUrl: `https://raw.githubusercontent.com/${CLAWHUB_OWNER}/${CLAWHUB_REPO}/${CLAWHUB_BRANCH}/${item.path}`,
-                name: this._extractSkillName(item.path),
-            })));
-
-        } catch (e) {
-            this.errors.push({ source: 'clawhub', error: e.message });
-        }
-
-        return this.results;
-    }
-
-    /**
-     * Crawl GitHub code search for SKILL.md files matching a query
-     * e.g. query "polymarket" finds gambling/trading skills
-     */
-    async crawlGitHub(query, opts = {}) {
-        const maxResults = opts.maxResults || 20;
-        if (!this.quiet) console.log(`\n🔍 GitHub code search: "${query}" + SKILL.md...`);
-
-        try {
-            const searchUrl = `https://api.github.com/search/code?q=${encodeURIComponent(query)}+filename:SKILL.md&per_page=${maxResults}`;
-            const response = await this._httpGet(searchUrl, {
-                headers: this._getHeaders(),
-            });
-
-            if (response.status !== 200) {
-                this.errors.push({ source: 'github', error: `Search API returned ${response.status}` });
-                return this.results;
-            }
-
-            const items = (response.data.items || []).slice(0, maxResults);
-            if (!this.quiet) console.log(`📦 Found ${items.length} SKILL.md matches`);
-
-            await this._batchProcess(items.map(item => ({
-                source: 'github',
-                path: item.path,
-                rawUrl: item.html_url
-                    .replace('github.com', 'raw.githubusercontent.com')
-                    .replace('/blob/', '/'),
-                name: item.repository?.full_name || item.path,
-                repo: item.repository?.full_name,
-            })));
-
-        } catch (e) {
-            this.errors.push({ source: 'github', error: e.message });
-        }
-
-        return this.results;
-    }
-
-    /**
-     * Scan a single SKILL.md URL
-     */
-    async scanUrl(url, name = 'unknown') {
-        try {
-            const response = await this._httpGet(url);
-            if (response.status !== 200) {
-                this.errors.push({ source: 'url', url, error: `HTTP ${response.status}` });
-                return null;
-            }
-
-            const content = typeof response.data === 'string'
-                ? response.data
-                : JSON.stringify(response.data);
-
-            const scanResult = this.scanner.scanText(content);
-
-            const result = {
-                name,
-                url,
-                content_length: content.length,
-                safe: scanResult.safe,
-                risk: scanResult.risk,
-                detection_count: scanResult.detections.length,
-                detections: scanResult.detections,
-                scanned_at: new Date().toISOString(),
-            };
-
-            this.results.push(result);
-            return result;
-
-        } catch (e) {
-            this.errors.push({ source: 'url', url, error: e.message });
-            return null;
-        }
-    }
-
-    /**
-     * Process items in batches with concurrency control
-     */
-    async _batchProcess(items) {
-        for (let i = 0; i < items.length; i += this.concurrency) {
-            const batch = items.slice(i, i + this.concurrency);
-            const promises = batch.map(item => this.scanUrl(item.rawUrl, item.name));
-            const results = await Promise.allSettled(promises);
-
-            // Log progress
-            if (!this.quiet) {
-                for (let j = 0; j < batch.length; j++) {
-                    const r = results[j];
-                    if (r.status === 'fulfilled' && r.value) {
-                        const icon = r.value.safe ? '🟢' : '🔴';
-                        console.log(`${icon} ${batch[j].name} — risk: ${r.value.risk} (${r.value.detection_count} findings)`);
-                    } else {
-                        console.log(`⚠️  ${batch[j].name} — fetch failed`);
-                    }
-                }
-            }
-        }
-    }
-
-    /**
-     * Extract skill name from path like "skills/author/skill-name/SKILL.md"
-     */
-    _extractSkillName(filePath) {
-        const parts = filePath.split('/');
-        // typically: skills/<author>/<skill-name>/SKILL.md
-        if (parts.length >= 3) {
-            return `${parts[parts.length - 3]}/${parts[parts.length - 2]}`;
-        }
-        return parts.slice(0, -1).join('/');
-    }
-
-    _getHeaders() {
-        const headers = { 'User-Agent': `guard-scanner-crawler/${CRAWLER_VERSION}` };
-        if (process.env.GITHUB_TOKEN) {
-            headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
-        }
-        return headers;
-    }
-
-    // ── Output ────────────────────────────────────────────────────
-
-    getSummary() {
-        const total = this.results.length;
-        const safe = this.results.filter(r => r.safe).length;
-        const unsafe = total - safe;
-        const highRisk = this.results.filter(r => r.risk >= 80).length;
-
-        return {
-            total,
-            safe,
-            unsafe,
-            highRisk,
-            errors: this.errors.length,
-            results: this.results.sort((a, b) => b.risk - a.risk),
-        };
-    }
-
-    toJSON() {
-        return {
-            scanner: `guard-scanner-crawler/${CRAWLER_VERSION}`,
-            timestamp: new Date().toISOString(),
-            ...this.getSummary(),
-        };
-    }
-
-    printSummary() {
-        const s = this.getSummary();
-        console.log(`\n${'═'.repeat(54)}`);
-        console.log(`📊 Crawler Scan Summary`);
-        console.log(`${'─'.repeat(54)}`);
-        console.log(`   Scanned:      ${s.total}`);
-        console.log(`   🟢 Safe:        ${s.safe}`);
-        console.log(`   🔴 Unsafe:      ${s.unsafe}`);
-        console.log(`   💀 High Risk:   ${s.highRisk}`);
-        if (s.errors > 0) console.log(`   ⚠️  Errors:      ${s.errors}`);
-        console.log(`${'═'.repeat(54)}\n`);
-
-        if (s.unsafe > 0) {
-            console.log(`⚠️  Unsafe skills detected:`);
-            for (const r of s.results.filter(r => !r.safe)) {
-                console.log(`   🔴 ${r.name} (risk: ${r.risk}, ${r.detection_count} findings)`);
-                if (this.verbose) {
-                    for (const d of r.detections.slice(0, 5)) {
-                        console.log(`      └─ [${d.severity}] ${d.desc}`);
-                    }
-                }
-            }
-        }
-    }
-}
-
-module.exports = { SkillCrawler, CRAWLER_VERSION };

package/src/threat-model.js

@@ -1,50 +0,0 @@
-/**
- * Threat Model Layer
- * Generates a threat model by identifying capabilities (network, exec, fs, etc.)
- * within a given context/codebase to contextualize heuristic pattern findings.
- */
-
-const CAPABILITY_PATTERNS = {
-  network: /(?:fetch|axios|http\.get|https\.request|XMLHttpRequest|WebSocket)/i,
-  exec: /(?:exec|spawn|child_process|eval|Function|system)/i,
-  fs_read: /(?:readFileSync|readFile|createReadStream)/i,
-  fs_write: /(?:writeFileSync|writeFile|createWriteStream|appendFile)/i,
-  env_access: /(?:process\.env)/i
-};
-
-function generateModel(codeContent) {
-  const capabilities = {
-    network: false,
-    exec: false,
-    fs_read: false,
-    fs_write: false,
-    env_access: false
-  };
-
-  let riskScore = 0;
-
-  for (const [cap, regex] of Object.entries(CAPABILITY_PATTERNS)) {
-    if (regex.test(codeContent)) {
-      capabilities[cap] = true;
-      riskScore += 10; // Base score for having a risky capability
-    }
-  }
-
-  // Capability compounding (e.g. read + network = exfil risk)
-  if (capabilities.fs_read && capabilities.network) {
-    riskScore += 20;
-  }
-  if (capabilities.env_access && capabilities.network) {
-    riskScore += 30; // High risk of credential exfiltration
-  }
-
-  return {
-    capabilities,
-    riskScore,
-    summary: `Capabilities detected: ${Object.keys(capabilities).filter(k => capabilities[k]).join(', ')}`
-  };
-}
-
-module.exports = {
-  generateModel
-};

package/src/validation-layer.js

@@ -1,39 +0,0 @@
-/**
- * Validation Layer
- * Evaluates heuristic findings against contextual evidence to separate
- * "validated" threats from "heuristic-only" (potential false positives).
- */
-
-function validateFindings(findings, context) {
-  return findings.map(finding => {
-    let status = 'heuristic-only';
-
-    // Contextual Validation Rules
-    
-    // 1. If it's a prompt injection but found inside a code block, it might be a false positive 
-    // (e.g., someone writing an article about prompt injection)
-    if (finding.id.startsWith('PI_')) {
-      if (context.isInCodeBlock(finding.text)) {
-        status = 'heuristic-only'; // False positive likely
-      } else {
-        status = 'validated';
-      }
-    }
-
-    // 2. If it's malicious code, verify if the execution environment allows it
-    if (finding.id.startsWith('MAL_')) {
-      if (context.isExecutable(finding.text)) {
-        status = 'validated';
-      }
-    }
-
-    return {
-      ...finding,
-      status
-    };
-  });
-}
-
-module.exports = {
-  validateFindings
-};

package/src/vt-client.js

@@ -1,202 +0,0 @@
-/**
- * guard-scanner v7 — VirusTotal API v3 Client
- *
- * @security-manifest
- *   env-read: [VT_API_KEY]
- *   env-write: []
- *   network: [virustotal.com API v3]
- *   fs-read: [files for SHA256 hashing]
- *   fs-write: []
- *   exec: none
- *   purpose: VirusTotal threat intelligence integration
- */
-
-const https = require('https');
-const crypto = require('crypto');
-const fs = require('fs');
-
-const VT_API_BASE = 'https://www.virustotal.com/api/v3';
-const VT_RATE_LIMIT = 4; // requests per minute (free tier)
-
-class VTClient {
-    constructor(apiKey, options = {}) {
-        if (!apiKey) throw new Error('VirusTotal API key is required. Set VT_API_KEY environment variable.');
-        this.apiKey = apiKey;
-        this.timeout = options.timeout || 15000;
-        this.verbose = options.verbose || false;
-        this._requestCount = 0;
-        this._windowStart = Date.now();
-        this._httpGet = options._httpGet || null; // DI for testing
-        this._httpPost = options._httpPost || null;
-    }
-
-    // ── Rate limiter (4 req/min free tier) ──────────────────────
-    async _throttle() {
-        const now = Date.now();
-        const elapsed = now - this._windowStart;
-        if (elapsed >= 60000) {
-            this._requestCount = 0;
-            this._windowStart = now;
-        }
-        if (this._requestCount >= VT_RATE_LIMIT) {
-            const waitMs = 60000 - elapsed + 100;
-            if (this.verbose) console.log(`⏳ VT rate limit: waiting ${Math.ceil(waitMs / 1000)}s`);
-            await new Promise(r => setTimeout(r, waitMs));
-            this._requestCount = 0;
-            this._windowStart = Date.now();
-        }
-        this._requestCount++;
-    }
-
-    // ── HTTP helpers ────────────────────────────────────────────
-    async _get(path) {
-        await this._throttle();
-        if (this._httpGet) return this._httpGet(`${VT_API_BASE}${path}`);
-
-        return new Promise((resolve, reject) => {
-            const req = https.request({
-                hostname: 'www.virustotal.com',
-                path: `/api/v3${path}`,
-                method: 'GET',
-                headers: {
-                    'x-apikey': this.apiKey,
-                    'Accept': 'application/json',
-                },
-            }, (res) => {
-                let data = '';
-                res.on('data', chunk => { data += chunk; });
-                res.on('end', () => {
-                    try {
-                        const parsed = JSON.parse(data);
-                        if (res.statusCode === 429) {
-                            reject(new Error('VT rate limit exceeded'));
-                        } else if (res.statusCode === 404) {
-                            resolve({ found: false, data: null });
-                        } else if (res.statusCode >= 200 && res.statusCode < 300) {
-                            resolve({ found: true, data: parsed });
-                        } else {
-                            reject(new Error(`VT API error ${res.statusCode}: ${JSON.stringify(parsed).substring(0, 200)}`));
-                        }
-                    } catch (e) {
-                        reject(new Error(`VT response parse error: ${e.message}`));
-                    }
-                });
-            });
-            req.on('error', reject);
-            req.setTimeout(this.timeout, () => { req.destroy(); reject(new Error('VT API timeout')); });
-            req.end();
-        });
-    }
-
-    // ── File Hash Lookup ───────────────────────────────────────
-    async lookupHash(hash) {
-        if (!hash || hash.length < 32) throw new Error('Invalid hash: provide MD5, SHA1, or SHA256');
-        const result = await this._get(`/files/${hash}`);
-
-        if (!result.found) {
-            return { found: false, hash, malicious: 0, suspicious: 0, harmless: 0, undetected: 0, engines: {} };
-        }
-
-        const attrs = result.data.data?.attributes || {};
-        const stats = attrs.last_analysis_stats || {};
-        const results = attrs.last_analysis_results || {};
-
-        // Extract detected engines
-        const detectedEngines = {};
-        for (const [engine, info] of Object.entries(results)) {
-            if (info.category === 'malicious' || info.category === 'suspicious') {
-                detectedEngines[engine] = { category: info.category, result: info.result };
-            }
-        }
-
-        return {
-            found: true,
-            hash,
-            malicious: stats.malicious || 0,
-            suspicious: stats.suspicious || 0,
-            harmless: stats.harmless || 0,
-            undetected: stats.undetected || 0,
-            engines: detectedEngines,
-            reputation: attrs.reputation || 0,
-            tags: attrs.tags || [],
-        };
-    }
-
-    // ── URL Scan ───────────────────────────────────────────────
-    async scanURL(url) {
-        if (!url) throw new Error('URL is required');
-        // URL ID = base64url of the URL
-        const urlId = Buffer.from(url).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
-        const result = await this._get(`/urls/${urlId}`);
-
-        if (!result.found) {
-            return { found: false, url, malicious: 0, suspicious: 0, harmless: 0 };
-        }
-
-        const attrs = result.data.data?.attributes || {};
-        const stats = attrs.last_analysis_stats || {};
-
-        return {
-            found: true,
-            url,
-            malicious: stats.malicious || 0,
-            suspicious: stats.suspicious || 0,
-            harmless: stats.harmless || 0,
-            categories: attrs.categories || {},
-        };
-    }
-
-    // ── Domain Report ──────────────────────────────────────────
-    async checkDomain(domain) {
-        if (!domain) throw new Error('Domain is required');
-        const result = await this._get(`/domains/${domain}`);
-
-        if (!result.found) {
-            return { found: false, domain, reputation: 0, malicious: 0 };
-        }
-
-        const attrs = result.data.data?.attributes || {};
-        const stats = attrs.last_analysis_stats || {};
-
-        return {
-            found: true,
-            domain,
-            reputation: attrs.reputation || 0,
-            malicious: stats.malicious || 0,
-            suspicious: stats.suspicious || 0,
-            categories: attrs.categories || {},
-            registrar: attrs.registrar || 'unknown',
-        };
-    }
-
-    // ── IP Report ──────────────────────────────────────────────
-    async checkIP(ip) {
-        if (!ip) throw new Error('IP address is required');
-        const result = await this._get(`/ip_addresses/${ip}`);
-
-        if (!result.found) {
-            return { found: false, ip, reputation: 0, malicious: 0 };
-        }
-
-        const attrs = result.data.data?.attributes || {};
-        const stats = attrs.last_analysis_stats || {};
-
-        return {
-            found: true,
-            ip,
-            reputation: attrs.reputation || 0,
-            malicious: stats.malicious || 0,
-            suspicious: stats.suspicious || 0,
-            country: attrs.country || 'unknown',
-            as_owner: attrs.as_owner || 'unknown',
-        };
-    }
-
-    // ── File SHA256 helper ──────────────────────────────────────
-    static hashFile(filePath) {
-        const content = fs.readFileSync(filePath);
-        return crypto.createHash('sha256').update(content).digest('hex');
-    }
-}
-
-module.exports = { VTClient, VT_API_BASE, VT_RATE_LIMIT };