openclaw-plugin-vt-sentinel 0.4.0

package/dist/scanner.d.ts

@@ -0,0 +1,96 @@
+import { FileCategory } from './classifier';
+export type ScanVerdict = 'clean' | 'malicious' | 'suspicious' | 'unknown' | 'pending' | 'skipped' | 'needs_consent';
+/**
+ * Policy for handling sensitive/ambiguous files (PDF, Office, unknown ZIP).
+ *
+ *   "ask"           → return needs_consent; agent asks user each time (default)
+ *   "ask_once"      → ask the first time, remember choice for the session
+ *   "always_upload"  → always upload sensitive files to VT
+ *   "hash_only"      → never upload, only check hash
+ */
+export type SensitiveFilePolicy = 'ask' | 'ask_once' | 'always_upload' | 'hash_only';
+export interface ScanResult {
+    filePath: string;
+    fileName: string;
+    sha256: string;
+    category: FileCategory;
+    verdict: ScanVerdict;
+    detections?: {
+        malicious: number;
+        suspicious: number;
+        total: number;
+    };
+    codeInsight?: {
+        source: string;
+        analysis: string;
+        verdict: string;
+    };
+    vtLink?: string;
+    message: string;
+}
+export declare class Scanner {
+    private api;
+    private cache;
+    private limiter;
+    private maxFileSizeMb;
+    private sensitivePolicy;
+    /** In-memory consent cache for "ask_once" policy. null = not yet asked. */
+    private consentDecision;
+    private logger;
+    constructor(apiKey: string, logger: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+        error: (m: string) => void;
+    }, maxFileSizeMb?: number, sensitivePolicy?: SensitiveFilePolicy, useVtai?: boolean);
+    /**
+     * Record the user's consent decision (used by the tool when the user responds).
+     * When policy is "ask_once", this persists for the session.
+     */
+    recordConsent(upload: boolean): void;
+    /**
+     * Full scan of a file: classify → hash → VT lookup → code insight if applicable.
+     * When force=true (manual scan), always do at least a hash check even for SAFE/MEDIA files.
+     */
+    scanFile(filePath: string, force?: boolean, precomputedHash?: string): Promise<ScanResult>;
+    /**
+     * Scan a HIGH_RISK or SEMANTIC_RISK file: hash lookup → upload if unknown.
+     * Code Insight is extracted automatically by fromReport() (same as all categories).
+     */
+    private scanAutoUpload;
+    /**
+     * Scan a SENSITIVE file according to the configured policy.
+     *
+     * Step 1 (always): Check hash — this reveals nothing about file content.
+     *   - If VT knows the hash → report findings (malicious PDF templates, etc.)
+     *
+     * Step 2 (if hash unknown): Apply policy:
+     *   - "hash_only"       → done, don't upload
+     *   - "always_upload"   → upload to VT
+     *   - "ask"             → return needs_consent every time
+     *   - "ask_once"        → return needs_consent the first time, then use remembered decision
+     */
+    private scanSensitive;
+    /**
+     * Forced scan for SAFE/MEDIA files when user explicitly requests it.
+     * Always checks hash; does NOT upload (no privacy concern but no reason to upload safe files).
+     */
+    private scanForced;
+    private uploadSensitive;
+    private needsConsent;
+    /**
+     * Upload a file that the user previously consented to (after needs_consent).
+     */
+    uploadWithConsent(filePath: string): Promise<ScanResult>;
+    /**
+     * Quick hash check — no classification, no upload.
+     */
+    checkHash(hash: string): Promise<ScanResult | null>;
+    /**
+     * Build ScanResult from a VT report.
+     * Always extracts both AV detections AND Code Insight (if available).
+     * The final verdict is the worst of: AV engines + AI analysis.
+     */
+    private fromReport;
+    private result;
+    clearCache(): void;
+}

package/dist/scanner.js

@@ -0,0 +1,312 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scanner = void 0;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const vt_api_1 = require("./vt-api");
+const classifier_1 = require("./classifier");
+const cache_1 = require("./cache");
+// --- Scanner ---
+class Scanner {
+    constructor(apiKey, logger, maxFileSizeMb = 32, sensitivePolicy = 'ask', useVtai = false) {
+        /** In-memory consent cache for "ask_once" policy. null = not yet asked. */
+        this.consentDecision = null;
+        this.api = new vt_api_1.VTApiClient(apiKey, useVtai);
+        this.cache = new cache_1.Cache(15);
+        this.limiter = new cache_1.RateLimiter(4);
+        this.maxFileSizeMb = maxFileSizeMb;
+        this.sensitivePolicy = sensitivePolicy;
+        this.logger = logger;
+    }
+    /**
+     * Record the user's consent decision (used by the tool when the user responds).
+     * When policy is "ask_once", this persists for the session.
+     */
+    recordConsent(upload) {
+        this.consentDecision = upload;
+    }
+    /**
+     * Full scan of a file: classify → hash → VT lookup → code insight if applicable.
+     * When force=true (manual scan), always do at least a hash check even for SAFE/MEDIA files.
+     */
+    async scanFile(filePath, force = false, precomputedHash) {
+        const fileName = path.basename(filePath);
+        if (!fs.existsSync(filePath)) {
+            return this.result(filePath, '', classifier_1.FileCategory.SAFE, 'skipped', `File not found: ${fileName}`);
+        }
+        const stat = fs.statSync(filePath);
+        if (stat.size > this.maxFileSizeMb * 1024 * 1024) {
+            return this.result(filePath, '', classifier_1.FileCategory.SAFE, 'skipped', `File too large (${(stat.size / 1024 / 1024).toFixed(1)}MB > ${this.maxFileSizeMb}MB limit)`);
+        }
+        const category = classifier_1.FileClassifier.classify(filePath);
+        // Auto-scan: skip SAFE/MEDIA early (avoid hashing large benign files and avoid cache poisoning).
+        if (!force && (category === classifier_1.FileCategory.MEDIA || category === classifier_1.FileCategory.SAFE)) {
+            return this.result(filePath, '', category, 'skipped', `Safe/media file (${fileName}) — skipped`);
+        }
+        const sha256 = precomputedHash || await (0, vt_api_1.calculateSHA256)(filePath);
+        const cached = this.cache.get(sha256);
+        if (cached) {
+            this.logger.info(`[VT-Sentinel] Cache hit for ${fileName}`);
+            // Cache entries are keyed by SHA-256 (VT identity). Rebase per-file context.
+            return { ...cached, filePath, fileName, category, sha256 };
+        }
+        let result;
+        // When force=true (code dirs), treat all files as HIGH_RISK: hash + auto-upload.
+        // Media/safe files in skills/hooks/extensions dirs are anomalous and should be fully analyzed.
+        const effectiveCategory = force && (category === classifier_1.FileCategory.MEDIA || category === classifier_1.FileCategory.SAFE)
+            ? classifier_1.FileCategory.HIGH_RISK
+            : category;
+        switch (effectiveCategory) {
+            case classifier_1.FileCategory.HIGH_RISK:
+            case classifier_1.FileCategory.SEMANTIC_RISK:
+                result = await this.scanAutoUpload(filePath, sha256, effectiveCategory);
+                break;
+            case classifier_1.FileCategory.SENSITIVE:
+                result = await this.scanSensitive(filePath, sha256, effectiveCategory);
+                break;
+            case classifier_1.FileCategory.MEDIA:
+            case classifier_1.FileCategory.SAFE:
+            default:
+                // Manual scan: always check hash even for safe/media files
+                result = await this.scanForced(filePath, sha256, category);
+                break;
+        }
+        // Cache only results derived from VT knowledge or an upload attempt.
+        // Do NOT cache "skipped/unknown/needs_consent" because those depend on local policy
+        // and should not prevent future uploads or policy changes.
+        if (result.verdict === 'clean' ||
+            result.verdict === 'malicious' ||
+            result.verdict === 'suspicious' ||
+            result.verdict === 'pending') {
+            this.cache.set(sha256, result);
+        }
+        return result;
+    }
+    /**
+     * Scan a HIGH_RISK or SEMANTIC_RISK file: hash lookup → upload if unknown.
+     * Code Insight is extracted automatically by fromReport() (same as all categories).
+     */
+    async scanAutoUpload(filePath, sha256, category) {
+        const fileName = path.basename(filePath);
+        await this.limiter.acquire();
+        const report = await this.api.checkHash(sha256);
+        if (report) {
+            return this.fromReport(filePath, sha256, category, report);
+        }
+        this.logger.info(`[VT-Sentinel] Unknown ${category} file ${fileName}, uploading...`);
+        await this.limiter.acquire();
+        try {
+            const upload = await this.api.uploadFile(filePath);
+            return this.result(filePath, sha256, category, 'pending', `Uploaded for analysis (${upload.analysisId}). Results pending.`);
+        }
+        catch (err) {
+            return this.result(filePath, sha256, category, 'unknown', `Upload failed: ${err.message}`);
+        }
+    }
+    /**
+     * Scan a SENSITIVE file according to the configured policy.
+     *
+     * Step 1 (always): Check hash — this reveals nothing about file content.
+     *   - If VT knows the hash → report findings (malicious PDF templates, etc.)
+     *
+     * Step 2 (if hash unknown): Apply policy:
+     *   - "hash_only"       → done, don't upload
+     *   - "always_upload"   → upload to VT
+     *   - "ask"             → return needs_consent every time
+     *   - "ask_once"        → return needs_consent the first time, then use remembered decision
+     */
+    async scanSensitive(filePath, sha256, category) {
+        const fileName = path.basename(filePath);
+        // Step 1: Hash check (always safe, reveals nothing)
+        await this.limiter.acquire();
+        const report = await this.api.checkHash(sha256);
+        if (report) {
+            const result = this.fromReport(filePath, sha256, category, report);
+            result.message += ' (hash-only check — file NOT uploaded to VT)';
+            return result;
+        }
+        // Step 2: Hash unknown — apply policy
+        switch (this.sensitivePolicy) {
+            case 'hash_only':
+                return this.result(filePath, sha256, category, 'unknown', `Unknown to VT (${fileName}). Hash checked only — file NOT uploaded (privacy policy).`);
+            case 'always_upload':
+                return this.uploadSensitive(filePath, sha256, category, fileName);
+            case 'ask_once':
+                if (this.consentDecision === true) {
+                    return this.uploadSensitive(filePath, sha256, category, fileName);
+                }
+                if (this.consentDecision === false) {
+                    return this.result(filePath, sha256, category, 'unknown', `Unknown to VT (${fileName}). User previously declined upload — hash-only.`);
+                }
+                // First time — fall through to ask
+                return this.needsConsent(filePath, sha256, category, fileName);
+            case 'ask':
+            default:
+                return this.needsConsent(filePath, sha256, category, fileName);
+        }
+    }
+    /**
+     * Forced scan for SAFE/MEDIA files when user explicitly requests it.
+     * Always checks hash; does NOT upload (no privacy concern but no reason to upload safe files).
+     */
+    async scanForced(filePath, sha256, category) {
+        const fileName = path.basename(filePath);
+        await this.limiter.acquire();
+        const report = await this.api.checkHash(sha256);
+        if (report) {
+            return this.fromReport(filePath, sha256, category, report);
+        }
+        return this.result(filePath, sha256, category, 'unknown', `File "${fileName}" (${category}) not found in VT database. Hash checked — no threats known.`);
+    }
+    async uploadSensitive(filePath, sha256, category, fileName) {
+        this.logger.info(`[VT-Sentinel] Uploading SENSITIVE file ${fileName} (user consented)...`);
+        await this.limiter.acquire();
+        try {
+            const upload = await this.api.uploadFile(filePath);
+            return this.result(filePath, sha256, category, 'pending', `Uploaded with consent (${upload.analysisId}). May contain macros or embedded threats — analysis pending.`);
+        }
+        catch (err) {
+            return this.result(filePath, sha256, category, 'unknown', `Upload failed: ${err.message}`);
+        }
+    }
+    needsConsent(filePath, sha256, category, fileName) {
+        return this.result(filePath, sha256, category, 'needs_consent', `File "${fileName}" may contain private data (detected as ${category}). ` +
+            `Hash is unknown to VT. ` +
+            `Should I upload it to VirusTotal for deep analysis? ` +
+            `This would check for macros, embedded threats, and other risks, ` +
+            `but the file content will be shared with VirusTotal. ` +
+            `Reply YES to upload, NO for hash-only check.`);
+    }
+    /**
+     * Upload a file that the user previously consented to (after needs_consent).
+     */
+    async uploadWithConsent(filePath) {
+        if (!fs.existsSync(filePath)) {
+            return this.result(filePath, '', classifier_1.FileCategory.SENSITIVE, 'skipped', 'File not found');
+        }
+        const sha256 = await (0, vt_api_1.calculateSHA256)(filePath);
+        const category = classifier_1.FileClassifier.classify(filePath);
+        const fileName = path.basename(filePath);
+        // Remember consent for ask_once policy
+        if (this.sensitivePolicy === 'ask_once') {
+            this.consentDecision = true;
+        }
+        return this.uploadSensitive(filePath, sha256, category, fileName);
+    }
+    /**
+     * Quick hash check — no classification, no upload.
+     */
+    async checkHash(hash) {
+        await this.limiter.acquire();
+        const report = await this.api.checkHash(hash);
+        if (!report)
+            return null;
+        return this.fromReport('', hash, classifier_1.FileCategory.SAFE, report);
+    }
+    /**
+     * Build ScanResult from a VT report.
+     * Always extracts both AV detections AND Code Insight (if available).
+     * The final verdict is the worst of: AV engines + AI analysis.
+     */
+    fromReport(filePath, sha256, category, report) {
+        const stats = report.stats;
+        const total = stats.malicious + stats.suspicious + stats.harmless + stats.undetected;
+        // --- AV verdict ---
+        let verdict = 'clean';
+        const msgParts = [];
+        if (stats.malicious > 0) {
+            verdict = 'malicious';
+            msgParts.push(`AV: ${stats.malicious}/${total} engines detected malware`);
+        }
+        else if (stats.suspicious > 0) {
+            verdict = 'suspicious';
+            msgParts.push(`AV: ${stats.suspicious}/${total} engines flagged suspicious`);
+        }
+        else {
+            msgParts.push(`AV: clean (0/${total} detections)`);
+        }
+        const result = {
+            filePath,
+            fileName: filePath ? path.basename(filePath) : sha256.substring(0, 12),
+            sha256,
+            category,
+            verdict,
+            detections: { malicious: stats.malicious, suspicious: stats.suspicious, total },
+            vtLink: report.vtLink,
+            message: '', // set below
+        };
+        // --- Code Insight (always extract if present) ---
+        if (report.crowdsourcedAiResults && report.crowdsourcedAiResults.length > 0) {
+            const ci = report.crowdsourcedAiResults.find((r) => r.source?.toLowerCase().includes('code insight')) || report.crowdsourcedAiResults[0];
+            const ciVerdict = (ci.verdict || 'UNKNOWN').toUpperCase();
+            result.codeInsight = {
+                source: ci.source || 'AI',
+                analysis: ci.analysis || '',
+                verdict: ciVerdict,
+            };
+            // AI can escalate the verdict (never downgrade)
+            if (ciVerdict.includes('MALICIOUS') && verdict !== 'malicious') {
+                verdict = 'malicious';
+                result.verdict = verdict;
+                msgParts.push(`AI: MALICIOUS — ${ci.analysis?.substring(0, 200)}`);
+            }
+            else if (ciVerdict.includes('SUSPICIOUS') && verdict === 'clean') {
+                verdict = 'suspicious';
+                result.verdict = verdict;
+                msgParts.push(`AI: SUSPICIOUS — ${ci.analysis?.substring(0, 200)}`);
+            }
+            else {
+                msgParts.push(`AI: ${ciVerdict}`);
+            }
+        }
+        result.message = msgParts.join(' | ');
+        return result;
+    }
+    result(filePath, sha256, category, verdict, message) {
+        return {
+            filePath,
+            fileName: filePath ? path.basename(filePath) : '',
+            sha256,
+            category,
+            verdict,
+            message,
+        };
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+}
+exports.Scanner = Scanner;

package/dist/vt-api.d.ts

@@ -0,0 +1,69 @@
+export interface VTAnalysisStats {
+    malicious: number;
+    suspicious: number;
+    harmless: number;
+    undetected: number;
+}
+export interface VTCrowdsourcedAiResult {
+    source: string;
+    analysis: string;
+    verdict?: string;
+    id?: string;
+}
+export interface VTReport {
+    hash: string;
+    stats: VTAnalysisStats;
+    name?: string;
+    crowdsourcedAiResults?: VTCrowdsourcedAiResult[];
+    vtLink: string;
+}
+export interface VTUploadResult {
+    analysisId: string;
+    message: string;
+}
+export interface AgentCredentials {
+    agentId: string;
+    agentToken: string;
+    publicHandle: string;
+    registeredAt: string;
+}
+/**
+ * Path to the cached agent credentials file.
+ * Stored in the OpenClaw state directory for persistence across sessions.
+ */
+export declare function getAgentCredentialsPath(): string;
+export declare function loadAgentCredentials(): AgentCredentials | null;
+export declare function saveAgentCredentials(creds: AgentCredentials): void;
+/**
+ * Register a new agent with VirusTotal AI API.
+ * No authentication required — zero-friction onboarding.
+ */
+export declare function registerAgent(version?: string): Promise<AgentCredentials>;
+export declare function calculateSHA256(filePath: string): Promise<string>;
+export declare class VTApiClient {
+    private apiKey;
+    private baseUrl;
+    private vtai;
+    constructor(apiKey: string, useVtai?: boolean);
+    private headers;
+    /**
+     * Lookup a file hash in VirusTotal.
+     * Returns full report including AI results if available, or null if not found.
+     * Handles both standard VT and VTAI response formats.
+     */
+    checkHash(hash: string): Promise<VTReport | null>;
+    /**
+     * Parse standard VT API response (data.attributes.*)
+     */
+    private parseStandardReport;
+    /**
+     * Parse VTAI simplified response (data.* without attributes wrapper)
+     */
+    private parseVtaiReport;
+    /**
+     * Upload a file to VirusTotal for analysis.
+     * Standard VT: supports large files (>32MB) via upload_url endpoint.
+     * VTAI: max 32MB, no large file support.
+     */
+    uploadFile(filePath: string): Promise<VTUploadResult>;
+}