openclaw-plugin-vt-sentinel 0.4.0

package/dist/vt-api.js

@@ -0,0 +1,231 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VTApiClient = void 0;
+exports.getAgentCredentialsPath = getAgentCredentialsPath;
+exports.loadAgentCredentials = loadAgentCredentials;
+exports.saveAgentCredentials = saveAgentCredentials;
+exports.registerAgent = registerAgent;
+exports.calculateSHA256 = calculateSHA256;
+const axios_1 = __importDefault(require("axios"));
+const fs = __importStar(require("fs"));
+const crypto = __importStar(require("crypto"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const form_data_1 = __importDefault(require("form-data"));
+const VT_API_URL = 'https://www.virustotal.com/api/v3';
+const VTAI_API_URL = 'https://ai.virustotal.com/api/v3';
+const HTTP_TIMEOUT_MS = 30000; // 30s timeout for all API calls
+/**
+ * Path to the cached agent credentials file.
+ * Stored in the OpenClaw state directory for persistence across sessions.
+ */
+function getAgentCredentialsPath() {
+    const stateDir = process.env.OPENCLAW_STATE_DIR || path.join(os.homedir(), '.openclaw');
+    return path.join(stateDir, 'vt-sentinel-agent.json');
+}
+function loadAgentCredentials() {
+    try {
+        return JSON.parse(fs.readFileSync(getAgentCredentialsPath(), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveAgentCredentials(creds) {
+    const credsPath = getAgentCredentialsPath();
+    const dir = path.dirname(credsPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(credsPath, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    // Windows: POSIX mode bits are ignored on NTFS. Use icacls to restrict access.
+    if (process.platform === 'win32') {
+        try {
+            const { execSync } = require('child_process');
+            execSync(`icacls "${credsPath}" /inheritance:r /grant:r "%USERNAME%:(F)"`, { stdio: 'ignore' });
+        }
+        catch { /* best effort — may fail without admin */ }
+    }
+}
+/**
+ * Register a new agent with VirusTotal AI API.
+ * No authentication required — zero-friction onboarding.
+ */
+async function registerAgent(version = '0.2.0') {
+    const resp = await axios_1.default.post(`${VTAI_API_URL}/agents/register`, {
+        agent_family: 'vt-sentinel',
+        agent_version: version,
+        display_name: 'VT Sentinel',
+    }, { timeout: HTTP_TIMEOUT_MS });
+    return {
+        agentId: resp.data.agent_id,
+        agentToken: resp.data.agent_token,
+        publicHandle: resp.data.public_handle,
+        registeredAt: new Date().toISOString(),
+    };
+}
+// --- Helpers ---
+function calculateSHA256(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto.createHash('sha256');
+        const stream = fs.createReadStream(filePath);
+        stream.on('data', (data) => hash.update(data));
+        stream.on('end', () => resolve(hash.digest('hex')));
+        stream.on('error', reject);
+    });
+}
+// --- VT API Client (dual-mode: standard VT or VTAI) ---
+class VTApiClient {
+    constructor(apiKey, useVtai = false) {
+        this.apiKey = apiKey;
+        this.vtai = useVtai;
+        this.baseUrl = useVtai ? VTAI_API_URL : VT_API_URL;
+    }
+    headers() {
+        return { 'x-apikey': this.apiKey };
+    }
+    /**
+     * 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.
+     */
+    async checkHash(hash) {
+        if (!/^[a-fA-F0-9]{32,128}$/.test(hash)) {
+            throw new Error(`Invalid hash: expected 32-128 hex characters, got "${hash.substring(0, 20)}${hash.length > 20 ? '...' : ''}"`);
+        }
+        try {
+            const resp = await axios_1.default.get(`${this.baseUrl}/files/${hash}`, {
+                headers: this.headers(),
+                timeout: HTTP_TIMEOUT_MS,
+            });
+            return this.vtai
+                ? this.parseVtaiReport(resp.data)
+                : this.parseStandardReport(resp.data);
+        }
+        catch (err) {
+            if (axios_1.default.isAxiosError(err) && err.response?.status === 404) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Parse standard VT API response (data.attributes.*)
+     */
+    parseStandardReport(data) {
+        const attrs = data?.data?.attributes;
+        if (!attrs)
+            return null;
+        const report = {
+            hash: data.data.id,
+            stats: attrs.last_analysis_stats,
+            name: attrs.meaningful_name,
+            vtLink: `https://www.virustotal.com/gui/file/${data.data.id}`,
+        };
+        if (attrs.crowdsourced_ai_results && attrs.crowdsourced_ai_results.length > 0) {
+            report.crowdsourcedAiResults = attrs.crowdsourced_ai_results.map((r) => ({
+                source: r.source,
+                analysis: r.analysis,
+                verdict: r.verdict,
+                id: r.id,
+            }));
+        }
+        return report;
+    }
+    /**
+     * Parse VTAI simplified response (data.* without attributes wrapper)
+     */
+    parseVtaiReport(data) {
+        const fileData = data?.data;
+        if (!fileData)
+            return null;
+        const report = {
+            hash: fileData.id,
+            stats: fileData.last_analysis_stats || { malicious: 0, suspicious: 0, harmless: 0, undetected: 0 },
+            name: fileData.type_description,
+            vtLink: `https://www.virustotal.com/gui/file/${fileData.id}`,
+        };
+        if (fileData.ai_insights && fileData.ai_insights.length > 0) {
+            report.crowdsourcedAiResults = fileData.ai_insights.map((r) => ({
+                source: r.source,
+                analysis: r.analysis,
+                verdict: r.verdict,
+            }));
+        }
+        return report;
+    }
+    /**
+     * Upload a file to VirusTotal for analysis.
+     * Standard VT: supports large files (>32MB) via upload_url endpoint.
+     * VTAI: max 32MB, no large file support.
+     */
+    async uploadFile(filePath) {
+        const stat = fs.statSync(filePath);
+        const sizeMb = stat.size / (1024 * 1024);
+        if (this.vtai && sizeMb > 32) {
+            throw new Error(`File too large for VTAI (${sizeMb.toFixed(1)}MB > 32MB). Configure your own VT API key for large file uploads.`);
+        }
+        let uploadUrl = `${this.baseUrl}/files/`;
+        if (sizeMb > 32) {
+            const urlResp = await axios_1.default.get(`${this.baseUrl}/files/upload_url`, {
+                headers: this.headers(),
+                timeout: HTTP_TIMEOUT_MS,
+            });
+            uploadUrl = urlResp.data.data;
+        }
+        const form = new form_data_1.default();
+        form.append('file', fs.createReadStream(filePath));
+        if (this.vtai) {
+            form.append('agent_comments', 'Auto-scanned by VT Sentinel for OpenClaw');
+        }
+        const resp = await axios_1.default.post(uploadUrl, form, {
+            headers: {
+                ...form.getHeaders(),
+                ...this.headers(),
+            },
+            maxContentLength: Infinity,
+            maxBodyLength: Infinity,
+            timeout: HTTP_TIMEOUT_MS * 4, // 120s for uploads (large files)
+        });
+        return {
+            analysisId: resp.data.data.id,
+            message: `File uploaded. Analysis ID: ${resp.data.data.id}`,
+        };
+    }
+}
+exports.VTApiClient = VTApiClient;

package/hooks/vt-auto-scan/HOOK.md

@@ -0,0 +1,25 @@
+---
+name: vt-auto-scan
+description: >-
+  Automatically scans files created or downloaded by agent tool calls
+  (exec, write, web_fetch) using VirusTotal. Detects malware downloads,
+  malicious scripts, and compromised skill files in real-time.
+emoji: "\U0001F6E1\uFE0F"
+events:
+  - tool_result_persist
+---
+
+# VT Auto-Scan Hook
+
+Intercepts tool execution results and automatically scans any files that were
+created, downloaded, or modified during the tool call. This provides a
+transparent security layer that catches malicious payloads regardless of
+which skill or command originated the download.
+
+## Detected Patterns
+
+- `curl -o /path/file`, `wget -O /path/file` — download targets
+- `> /path/file`, `tee /path/file` — redirect outputs
+- `bash /path/script.sh`, `python /path/script.py` — executed scripts
+- Files written via `write` / `edit` tools
+- File paths appearing in tool output in monitored directories

package/hooks/vt-auto-scan/handler.js

@@ -0,0 +1,106 @@
+/**
+ * Standalone hook handler for vt-auto-scan.
+ * This handler works when loaded independently by OpenClaw's hook discovery.
+ * It creates its own scanner instance from the environment.
+ *
+ * Supports both standard VT API (user key) and VTAI (cached agent credentials).
+ * For the integrated plugin path, the hook is registered directly in index.ts.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+let Scanner, extractPaths, loadAgentCredentials;
+
+try {
+    // Try to load from the compiled plugin
+    const distDir = path.resolve(__dirname, '../../dist');
+    Scanner = require(path.join(distDir, 'scanner')).Scanner;
+    extractPaths = require(path.join(distDir, 'path-extractor')).extractPaths;
+    loadAgentCredentials = require(path.join(distDir, 'vt-api')).loadAgentCredentials;
+} catch (e) {
+    // Modules not available — this hook won't function standalone
+    console.error('[vt-auto-scan] Could not load scanner modules:', e.message);
+}
+
+/**
+ * Create a scanner instance using available credentials.
+ * Priority: user API key > cached VTAI agent token.
+ */
+function createScanner(logger) {
+    const apiKey = process.env.VIRUSTOTAL_API_KEY;
+
+    // User has their own VT API key (and it's not the 'active' placeholder)
+    if (apiKey && apiKey !== 'active') {
+        return new Scanner(apiKey, logger);
+    }
+
+    // Try VTAI cached credentials
+    if (loadAgentCredentials) {
+        try {
+            const creds = loadAgentCredentials();
+            if (creds) {
+                return new Scanner(creds.agentToken, logger, 32, 'ask', true);
+            }
+        } catch (e) {
+            // Credentials not available
+        }
+    }
+
+    return null;
+}
+
+const handler = async (event) => {
+    // Only handle tool result events
+    if (event.type !== 'tool_result_persist' && event.type !== 'tool_result') return;
+
+    if (!Scanner || !extractPaths) return;
+
+    const logger = {
+        info: (m) => console.log(m),
+        warn: (m) => console.warn(m),
+        error: (m) => console.error(m),
+    };
+
+    const scanner = createScanner(logger);
+    if (!scanner) return;
+
+    const toolName = event.toolName || event.tool || '';
+    const toolParams = event.toolParams || event.params || event.input || {};
+
+    // Extract result text
+    let resultText = '';
+    if (typeof event.toolResult === 'string') resultText = event.toolResult;
+    else if (event.toolResult?.stdout) resultText = event.toolResult.stdout;
+    else if (event.toolResult?.content && Array.isArray(event.toolResult.content)) {
+        resultText = event.toolResult.content
+            .filter(p => p.type === 'text')
+            .map(p => p.text)
+            .join('\n');
+    }
+
+    const targets = extractPaths(toolName, toolParams, resultText);
+    if (targets.length === 0) return;
+
+    for (const target of targets) {
+        try {
+            const result = await scanner.scanFile(target.path);
+            if (result.verdict === 'malicious' || result.verdict === 'suspicious') {
+                const warning = `\n\n⚠️ VT-SENTINEL SECURITY ALERT ⚠️\n` +
+                    `File: ${result.fileName} | Verdict: ${result.verdict.toUpperCase()}\n` +
+                    `${result.vtLink || ''}`;
+
+                if (event.toolResult?.content && Array.isArray(event.toolResult.content)) {
+                    event.toolResult.content.push({ type: 'text', text: warning });
+                }
+
+                logger.error(`[VT-Sentinel] ${result.verdict.toUpperCase()}: ${result.fileName} — ${result.message}`);
+            }
+        } catch (err) {
+            logger.error(`[vt-auto-scan] Scan error: ${err.message}`);
+        }
+    }
+};
+
+module.exports = handler;
+module.exports.default = handler;

package/openclaw.plugin.json

@@ -0,0 +1,43 @@
+{
+  "id": "openclaw-plugin-vt-sentinel",
+  "skills": ["./skills"],
+  "hooks": ["./hooks"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "VirusTotal API Key (v3). Optional — without it, VT Sentinel auto-registers with VTAI for zero-config operation."
+      },
+      "watchDirs": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Directories to monitor for new files"
+      },
+      "autoScan": {
+        "type": "boolean",
+        "default": true,
+        "description": "Automatically scan new files in watched directories"
+      },
+      "maxFileSizeMb": {
+        "type": "number",
+        "default": 32,
+        "description": "Maximum file size to scan (MB)"
+      },
+      "sensitiveFilePolicy": {
+        "type": "string",
+        "enum": ["ask", "ask_once", "always_upload", "hash_only"],
+        "default": "ask",
+        "description": "Policy for sensitive files (PDF, Office, unknown archives): ask = prompt each time, ask_once = prompt once and remember, always_upload = auto-upload, hash_only = never upload"
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "apiKey": { "label": "VirusTotal API Key", "sensitive": true },
+    "watchDirs": { "label": "Watch Directories" },
+    "autoScan": { "label": "Auto-scan new files" },
+    "maxFileSizeMb": { "label": "Max File Size (MB)" },
+    "sensitiveFilePolicy": { "label": "Sensitive File Policy" }
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "openclaw-plugin-vt-sentinel",
+  "version": "0.4.0",
+  "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "node dist/test_runner.js"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "security",
+    "virustotal",
+    "malware",
+    "code-insight"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist/index.*",
+    "dist/scanner.*",
+    "dist/vt-api.*",
+    "dist/classifier.*",
+    "dist/cache.*",
+    "dist/path-extractor.*",
+    "skills/",
+    "hooks/",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": ["./dist/index.js"]
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "chokidar": "^3.5.3",
+    "form-data": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/skills/vt-sentinel/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: vt-sentinel
+description: >-
+  Security scanner using VirusTotal. Use when the user asks to scan a file for
+  malware, check if a downloaded file or script is safe, verify a file hash
+  against threat intelligence, or assess the security of any file. Returns both
+  antivirus engine detections AND AI-powered Code Insight analysis (when
+  available) in a single unified report.
+metadata:
+  openclaw:
+    emoji: "\U0001F6E1\uFE0F"
+---
+
+# VT Sentinel — VirusTotal Active Protection
+
+Protects OpenClaw users with **active prevention**, not just detection:
+
+1. **Antivirus engines** — 60+ vendors check file hashes for known malware
+2. **AI Code Insight** — Gemini-based semantic analysis for scripts, skills, binaries
+3. **Active blocking** — Files detected as malicious are blocklisted and quarantined. Any subsequent attempt to execute them is automatically blocked before it runs.
+
+Both AV and AI sources are always checked. The final verdict is the worst of the two. Malicious files are quarantined (renamed to `.QUARANTINED`) and added to a runtime blocklist that prevents their execution via `exec` or `bash` tools.
+
+## Available Tools
+
+### `vt_scan_file` — Full File Scan
+Classifies the file, computes SHA-256, checks VT (AV + Code Insight), uploads if unknown.
+
+```
+vt_scan_file { "path": "/absolute/path/to/file" }
+```
+
+### `vt_check_hash` — Quick Hash Lookup
+Fast check of a SHA-256 hash against VT. Returns AV detections + Code Insight if available.
+
+```
+vt_check_hash { "hash": "e3b0c44298fc1c149afbf4c8996fb924..." }
+```
+
+### `vt_upload_consent` — Confirm Sensitive File Upload
+When `vt_scan_file` returns `needs_consent`, relay the user's decision.
+
+```
+vt_upload_consent { "path": "/path/to/document.pdf", "upload": true }
+vt_upload_consent { "path": "/path/to/document.pdf", "upload": false }
+```
+
+## When to Use Which Tool
+
+| Scenario | Tool |
+|----------|------|
+| User asks "is this file safe?" | `vt_scan_file` |
+| User provides a SHA-256 hash | `vt_check_hash` |
+| Evaluating a new SKILL.md or HOOK.md | `vt_scan_file` |
+| Checking a downloaded script or binary | `vt_scan_file` |
+| User said YES/NO to uploading a sensitive file | `vt_upload_consent` |
+
+## Interpreting Results
+
+Every result includes both AV detections and Code Insight (when available):
+
+```
+File: example.sh
+Category: HIGH_RISK
+Verdict: MALICIOUS
+Detections: 12 malicious, 0 suspicious / 64 engines
+Code Insight (Code Insight): MALICIOUS
+Analysis: This script downloads and executes a remote payload...
+VT Link: https://www.virustotal.com/gui/file/...
+Summary: AV: 12/64 engines detected malware | AI: MALICIOUS — ...
+```
+
+### Verdicts
+- **CLEAN** — No threats from AV engines or AI
+- **MALICIOUS** — AV engines and/or AI flagged the file. Warn the user immediately.
+- **SUSPICIOUS** — Some concerns raised. Recommend caution.
+- **PENDING** — File uploaded, analysis not yet available. Check again later.
+- **SKIPPED** — File classified as safe/media (auto-scan only; manual scans always check).
+- **NEEDS_CONSENT** — Sensitive file. Hash checked (not found). Ask user before uploading.
+
+### Code Insight
+When present in the result, Code Insight provides:
+- **Source**: Analysis engine (e.g., "Code Insight", "palm")
+- **Verdict**: UNDETECTED / SUSPICIOUS / MALICIOUS
+- **Analysis**: Free-text description of what the file does
+
+Code Insight works on any file type VT can analyze — scripts, skills, binaries (decompiled), documents with macros, etc.
+
+## File Categories
+
+Classification uses magic bytes and content analysis (never extensions alone):
+- **HIGH_RISK**: Binaries (PE, ELF, Mach-O), scripts (shebang/content patterns), ZIPs with executables → auto-scanned
+- **SEMANTIC_RISK**: SKILL.md, HOOK.md, AGENTS.md, SOUL.md, skill ZIPs → auto-scanned
+- **SENSITIVE**: PDF, Office docs, unknown ZIPs → hash checked, upload needs consent
+- **MEDIA/SAFE**: Images, video, audio, plain text → skipped in auto-scan, checked in manual scan
+
+## Consent Flow for Sensitive Files
+
+When `vt_scan_file` returns `NEEDS_CONSENT`:
+
+1. Tell the user: the file's hash was checked (no match), but the file was NOT uploaded.
+2. Explain: uploading enables deep analysis (macros, embedded threats, AI), but content is shared with VirusTotal.
+3. Ask: "Would you like me to upload this file for a full scan?"
+4. Call `vt_upload_consent` with their answer.
+
+## Active Protection
+
+VT Sentinel automatically protects the system in real-time:
+
+1. **Auto-scan**: Every file downloaded or created by tools (`exec`, `write`, `web_fetch`) is automatically scanned
+2. **Blocklist**: Malicious and suspicious files are added to an in-memory blocklist
+3. **Quarantine**: Malicious files are renamed to `.QUARANTINED` so they cannot be executed
+4. **Execution blocking**: Any `exec`/`bash` command that references a blocked file is intercepted and prevented BEFORE execution
+5. **Command pattern inspection**: Commands are analyzed for dangerous patterns BEFORE execution, even when no file is involved:
+   - **Pipe-to-shell**: `curl | bash`, `wget | sh`, `base64 -d | bash` — remote code execution without touching disk
+   - **SSH key injection**: Appending to `authorized_keys` — backdoor persistence
+   - **Data exfiltration**: Sending data to webhook.site, requestbin, pipedream, etc.
+   - **Credential theft**: Piping `.env`, SSH keys, or AWS credentials to network tools
+
+If you see a "BLOCKED" message, it means VT Sentinel prevented a potentially dangerous operation. Do NOT attempt to work around the block — inform the user about the threat.
+
+## Constraints
+
+- Always use absolute file paths
+- Never expose the VT API key in output
+- Rate limit: 4 requests/minute (free tier) — handled automatically
+- For SENSITIVE files, follow the consent flow — never upload without permission
+- If verdict is MALICIOUS, always warn the user prominently
+- Do not attempt to bypass quarantine or blocklist protections