openclaw-plugin-vt-sentinel 0.9.2 → 0.11.0

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

@@ -10,7 +10,7 @@
 const path = require('path');
 const fs = require('fs');
 
-let Scanner, extractPaths, loadAgentCredentials;
+let Scanner, extractPaths, loadAgentCredentials, ConfigManager, matchGlob, isSelfPath, StateStore;
 
 try {
     // Try to load from the compiled plugin
@@ -18,21 +18,51 @@ try {
     Scanner = require(path.join(distDir, 'scanner')).Scanner;
     extractPaths = require(path.join(distDir, 'path-extractor')).extractPaths;
     loadAgentCredentials = require(path.join(distDir, 'vt-api')).loadAgentCredentials;
+    ConfigManager = require(path.join(distDir, 'config-manager')).ConfigManager;
+    matchGlob = require(path.join(distDir, 'config-manager')).matchGlob;
+    isSelfPath = require(path.join(distDir, 'index')).isSelfPath;
+    StateStore = require(path.join(distDir, 'state-store')).StateStore;
 } catch (e) {
     // Modules not available — this hook won't function standalone
     console.error('[vt-auto-scan] Could not load scanner modules:', e.message);
 }
 
+/**
+ * Read static plugin config from OpenClaw config file.
+ * Returns null if not found or on error.
+ */
+function readStaticConfig() {
+    try {
+        const stateDir = process.env.OPENCLAW_STATE_DIR || path.join(require('os').homedir(), '.openclaw');
+        const configPath = path.join(stateDir, 'openclaw.json');
+        if (!fs.existsSync(configPath)) return null;
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsed = (() => {
+            try { return require('json5').parse(raw); } catch { return JSON.parse(raw); }
+        })();
+        return parsed?.plugins?.entries?.['openclaw-plugin-vt-sentinel']?.config || null;
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Create a scanner instance using available credentials.
- * Priority: user API key > cached VTAI agent token.
+ * Priority: user apiKey from static config > cached VTAI agent token.
+ *
+ * v0.11.0 change: removed the `process.env.VIRUSTOTAL_API_KEY` lookup + the
+ * `'vtai-active'` env sentinel. The main plugin no longer mutates the
+ * environment, so this standalone hook mirrors that stance: credential source
+ * is 100% derived from openclaw.json (user apiKey) or the persisted agent
+ * credentials file (VTAI mode).
  */
-function createScanner(logger) {
-    const apiKey = process.env.VIRUSTOTAL_API_KEY;
+function createScanner(logger, eff, staticConfig) {
+    const userKey = staticConfig && typeof staticConfig.apiKey === 'string' && staticConfig.apiKey.trim().length > 0
+        ? staticConfig.apiKey.trim()
+        : null;
 
-    // User has their own VT API key (and it's not the 'active' placeholder)
-    if (apiKey && apiKey !== 'vtai-active') {
-        return new Scanner(apiKey, logger);
+    if (userKey) {
+        return new Scanner(userKey, logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, false, eff.semanticFilePolicy);
     }
 
     // Try VTAI cached credentials
@@ -40,7 +70,7 @@ function createScanner(logger) {
         try {
             const creds = loadAgentCredentials();
             if (creds) {
-                return new Scanner(creds.agentToken, logger, 32, 'ask', true);
+                return new Scanner(creds.agentToken, logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, true, eff.semanticFilePolicy);
             }
         } catch (e) {
             // Credentials not available
@@ -56,13 +86,37 @@ const handler = async (event) => {
 
     if (!Scanner || !extractPaths) return;
 
+    // Load config (static + persisted overrides) and check autoScan
+    let configManager = null;
+    const staticConfig = readStaticConfig();
+    if (ConfigManager) {
+        configManager = new ConfigManager(staticConfig);
+        // Apply persisted runtime overrides from vt-sentinel-state.json
+        if (StateStore) {
+            try {
+                const stateStore = new StateStore();
+                configManager.loadPersistedOverrides(stateStore.getPersistedOverrides());
+            } catch {
+                // State file missing or corrupt — proceed with static config only
+            }
+        }
+    }
+    const eff = configManager ? configManager.getEffective() : {
+        autoScan: true, maxFileSizeMb: 32,
+        sensitiveFilePolicy: 'ask', semanticFilePolicy: 'hash_only',
+        excludeGlobs: [],
+    };
+
+    // autoScan=false disables hook scanning
+    if (!eff.autoScan) return;
+
     const logger = {
         info: (m) => console.log(m),
         warn: (m) => console.warn(m),
         error: (m) => console.error(m),
     };
 
-    const scanner = createScanner(logger);
+    const scanner = createScanner(logger, eff, staticConfig);
     if (!scanner) return;
 
     const toolName = event.toolName || event.tool || '';
@@ -83,8 +137,22 @@ const handler = async (event) => {
     if (targets.length === 0) return;
 
     for (const target of targets) {
+        // Self-exclusion
+        if (isSelfPath && isSelfPath(target.path)) continue;
+
+        // excludeGlobs: skip files matching any exclude pattern
+        if (matchGlob && eff.excludeGlobs && eff.excludeGlobs.length > 0) {
+            let excluded = false;
+            for (const glob of eff.excludeGlobs) {
+                if (matchGlob(target.path, glob)) { excluded = true; break; }
+            }
+            if (excluded) continue;
+        }
+
         try {
-            const result = await scanner.scanFile(target.path);
+            // read_target → hash-only (never upload files the agent merely reads)
+            const isReadTarget = target.source === 'read_target';
+            const result = await scanner.scanFile(target.path, false, undefined, isReadTarget);
             if (result.verdict === 'malicious' || result.verdict === 'suspicious') {
                 const warning = `\n\n⚠️ VT-SENTINEL SECURITY ALERT ⚠️\n` +
                     `File: ${result.fileName} | Verdict: ${result.verdict.toUpperCase()}\n` +

package/openclaw.plugin.json

@@ -1,9 +1,25 @@
 {
   "id": "openclaw-plugin-vt-sentinel",
+  "name": "VT Sentinel",
+  "description": "VirusTotal Sentinel for OpenClaw — malware detection, active protection, and AI-powered code analysis.",
+  "version": "0.11.0",
   "skills": ["./skills"],
-  "hooks": ["./hooks"],
+  "contracts": {
+    "tools": [
+      "vt_scan_file",
+      "vt_check_hash",
+      "vt_upload_consent",
+      "vt_sentinel_status",
+      "vt_sentinel_configure",
+      "vt_sentinel_reset_policy",
+      "vt_sentinel_help",
+      "vt_sentinel_update",
+      "vt_sentinel_re_register"
+    ]
+  },
   "configSchema": {
     "type": "object",
+    "additionalProperties": false,
     "properties": {
       "apiKey": {
         "type": "string",
@@ -30,6 +46,12 @@
         "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"
       },
+      "semanticFilePolicy": {
+        "type": "string",
+        "enum": ["ask", "ask_once", "always_upload", "hash_only"],
+        "default": "hash_only",
+        "description": "Policy for instruction files (SKILL.md, HOOK.md, TOOLS.md, AGENTS.md, etc.): ask = prompt each time, ask_once = prompt once, always_upload = auto-upload, hash_only = never upload (default, privacy-safe)"
+      },
       "notifyLevel": {
         "type": "string",
         "enum": ["all", "threats_only", "silent"],
@@ -94,6 +116,7 @@
     "autoScan": { "label": "Auto-scan new files" },
     "maxFileSizeMb": { "label": "Max File Size (MB)" },
     "sensitiveFilePolicy": { "label": "Sensitive File Policy" },
+    "semanticFilePolicy": { "label": "Instruction File Policy" },
     "notifyLevel": { "label": "Notification Level" },
     "excludeDirs": { "label": "Exclude Directories" },
     "excludeGlobs": { "label": "Exclude File Patterns" },

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "openclaw-plugin-vt-sentinel",
-  "version": "0.9.2",
+  "version": "0.11.0",
+  "displayName": "VT Sentinel",
   "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "homepage": "https://ai.virustotal.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/VirusTotal/openclaw-plugin-vt-sentinel"
+    "url": "https://github.com/king-tero/VT-sentinel"
   },
   "bugs": {
-    "url": "https://github.com/VirusTotal/openclaw-plugin-vt-sentinel/issues"
+    "url": "https://github.com/king-tero/VT-sentinel/issues"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node -e \"require('fs').cpSync('src/signatures','dist/signatures',{recursive:true})\"",
     "watch": "tsc -w",
-    "test": "node dist/test_runner.js"
+    "test": "node dist/test_runner.js",
+    "scan": "node dist/self-scan.js",
+    "scan:json": "node dist/self-scan.js --json",
+    "prescan": "npm run build"
   },
   "keywords": [
     "openclaw",
@@ -32,9 +36,11 @@
   "license": "MIT",
   "files": [
     "README.md",
+    "CHANGELOG.md",
     "dist/index.*",
     "dist/scanner.*",
     "dist/vt-api.*",
+    "dist/vt-credentials.*",
     "dist/classifier.*",
     "dist/cache.*",
     "dist/path-extractor.*",
@@ -42,12 +48,24 @@
     "dist/config-manager.*",
     "dist/state-store.*",
     "dist/status-renderer.*",
+    "dist/env-access.*",
+    "dist/signatures/**/*.json",
     "skills/",
     "hooks/",
     "openclaw.plugin.json"
   ],
   "openclaw": {
-    "extensions": ["./dist/index.js"]
+    "extensions": ["./dist/index.js"],
+    "install": {
+      "minHostVersion": ">=2026.3.22"
+    },
+    "compat": {
+      "pluginApi": ">=2026.3.22",
+      "minGatewayVersion": ">=2026.3.22"
+    },
+    "build": {
+      "openclawVersion": "2026.4.5"
+    }
   },
   "dependencies": {
     "axios": "^1.6.0",

package/skills/vt-sentinel/SKILL.md

@@ -90,11 +90,11 @@ Code Insight works on any file type VT can analyze — scripts, skills, binaries
 
 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
+- **SEMANTIC_RISK**: SKILL.md, HOOK.md, TOOLS.md, AGENTS.md, SOUL.md, skill ZIPs → hash checked, upload needs consent (default: hash_only)
+- **SENSITIVE**: PDF, Office docs, unknown ZIPs → hash checked, upload needs consent (default: ask)
 - **MEDIA/SAFE**: Images, video, audio, plain text → skipped in auto-scan, checked in manual scan
 
-## Consent Flow for Sensitive Files
+## Consent Flow for Sensitive / Semantic Files
 
 When `vt_scan_file` returns `NEEDS_CONSENT`:
 
@@ -103,6 +103,8 @@ When `vt_scan_file` returns `NEEDS_CONSENT`:
 3. Ask: "Would you like me to upload this file for a full scan?"
 4. Call `vt_upload_consent` with their answer.
 
+**Note**: Files read by the agent (via the `read` tool) are only hash-checked, never auto-uploaded. This protects instruction files like TOOLS.md and AGENTS.md from being uploaded to VT during normal agent operations.
+
 ## Admin Tools
 
 ### `vt_sentinel_status` — Current Status
@@ -118,6 +120,7 @@ Update any setting immediately. Changes persist to disk by default.
 ```
 vt_sentinel_configure { "preset": "privacy_first" }
 vt_sentinel_configure { "sensitiveFilePolicy": "hash_only", "notifyLevel": "threats_only" }
+vt_sentinel_configure { "semanticFilePolicy": "ask" }
 vt_sentinel_configure { "watchDirsAdd": ["/extra/dir"], "excludeGlobs": ["*.log"] }
 vt_sentinel_configure { "blockMode": "log_only", "persist": "session" }
 ```