openclaw-plugin-vt-sentinel 0.9.2 → 0.10.0

package/README.md

@@ -21,7 +21,7 @@ openclaw gateway restart
 openclaw plugins list | grep vt-sentinel
 ```
 
-Should show 8 tools registered.
+Should show 9 tools registered.
 
 ## Tools
 
@@ -35,10 +35,12 @@ Should show 8 tools registered.
 | `vt_sentinel_reset_policy` | Reset all settings to defaults |
 | `vt_sentinel_help` | Quick-start guide and privacy info |
 | `vt_sentinel_update` | Check for updates and get upgrade instructions |
+| `vt_sentinel_re_register` | Re-register agent identity with VTAI |
 
 ## What it does
 
 - Scans downloaded and created files automatically (AV + AI Code Insight)
+- Protects instruction files (SKILL.md, TOOLS.md) from being uploaded without consent
 - Blocks execution of malicious files and dangerous command patterns
 - Monitors directories in real-time (Downloads, /tmp, workspace)
 - Quarantines threats with rotating audit logs
@@ -83,6 +85,7 @@ openclaw plugins config openclaw-plugin-vt-sentinel apiKey YOUR_KEY
 | `notifyLevel` | all, threats_only, silent | all |
 | `blockMode` | quarantine, block_only, log_only | quarantine |
 | `sensitiveFilePolicy` | ask, ask_once, always_upload, hash_only | ask |
+| `semanticFilePolicy` | ask, ask_once, always_upload, hash_only | hash_only |
 | `maxFileSizeMb` | 1-32 | 32 |
 | `autoScan` | true, false | true |
 

package/dist/config-manager.d.ts

@@ -9,6 +9,7 @@ export interface FullConfig {
     autoScan: boolean;
     maxFileSizeMb: number;
     sensitiveFilePolicy: SensitiveFilePolicy;
+    semanticFilePolicy: SensitiveFilePolicy;
     notifyLevel: NotifyLevel;
     excludeDirs: string[];
     excludeGlobs: string[];
@@ -33,6 +34,7 @@ export interface StaticConfig {
     autoScan?: boolean;
     maxFileSizeMb?: number;
     sensitiveFilePolicy?: SensitiveFilePolicy;
+    semanticFilePolicy?: SensitiveFilePolicy;
     notifyLevel?: NotifyLevel;
     excludeDirs?: string[];
     excludeGlobs?: string[];

package/dist/config-manager.js

@@ -43,6 +43,7 @@ const PRESETS = {
     balanced: {
         autoScan: true,
         sensitiveFilePolicy: 'ask',
+        semanticFilePolicy: 'hash_only',
         maxFileSizeMb: 32,
         notifyLevel: 'all',
         excludeDirs: [],
@@ -54,6 +55,7 @@ const PRESETS = {
     privacy_first: {
         autoScan: true,
         sensitiveFilePolicy: 'hash_only',
+        semanticFilePolicy: 'hash_only',
         maxFileSizeMb: 32,
         notifyLevel: 'threats_only',
         excludeDirs: [],
@@ -65,6 +67,7 @@ const PRESETS = {
     strict_security: {
         autoScan: true,
         sensitiveFilePolicy: 'always_upload',
+        semanticFilePolicy: 'ask',
         maxFileSizeMb: 64,
         notifyLevel: 'all',
         excludeDirs: [],
@@ -79,6 +82,7 @@ const BALANCED_DEFAULTS = {
     autoScan: true,
     maxFileSizeMb: 32,
     sensitiveFilePolicy: 'ask',
+    semanticFilePolicy: 'hash_only',
     notifyLevel: 'all',
     excludeDirs: [],
     excludeGlobs: [],
@@ -141,6 +145,14 @@ function validateOverrides(input) {
             errors.push(`Invalid sensitiveFilePolicy: "${input.sensitiveFilePolicy}". Must be: ask, ask_once, always_upload, hash_only`);
         }
     }
+    if ('semanticFilePolicy' in input) {
+        if (VALID_SENSITIVE_POLICIES.has(input.semanticFilePolicy)) {
+            valid.semanticFilePolicy = input.semanticFilePolicy;
+        }
+        else {
+            errors.push(`Invalid semanticFilePolicy: "${input.semanticFilePolicy}". Must be: ask, ask_once, always_upload, hash_only`);
+        }
+    }
     if ('autoScan' in input) {
         if (typeof input.autoScan === 'boolean') {
             valid.autoScan = input.autoScan;
@@ -305,6 +317,8 @@ class ConfigManager {
                 result.maxFileSizeMb = s.maxFileSizeMb;
             if (s.sensitiveFilePolicy !== undefined)
                 result.sensitiveFilePolicy = s.sensitiveFilePolicy;
+            if (s.semanticFilePolicy !== undefined)
+                result.semanticFilePolicy = s.semanticFilePolicy;
             if (s.notifyLevel !== undefined)
                 result.notifyLevel = s.notifyLevel;
             if (s.excludeDirs !== undefined)
@@ -337,6 +351,8 @@ class ConfigManager {
             result.maxFileSizeMb = o.maxFileSizeMb;
         if (o.sensitiveFilePolicy !== undefined)
             result.sensitiveFilePolicy = o.sensitiveFilePolicy;
+        if (o.semanticFilePolicy !== undefined)
+            result.semanticFilePolicy = o.semanticFilePolicy;
         if (o.notifyLevel !== undefined)
             result.notifyLevel = o.notifyLevel;
         if (o.excludeDirs !== undefined)
@@ -391,7 +407,7 @@ class ConfigManager {
             const b = JSON.stringify(after[key]);
             if (a !== b) {
                 changedFields.push(key);
-                if (key === 'sensitiveFilePolicy' || key === 'maxFileSizeMb') {
+                if (key === 'sensitiveFilePolicy' || key === 'semanticFilePolicy' || key === 'maxFileSizeMb') {
                     scannerNeedsRebuild = true;
                 }
                 if (key === 'watchDirs' || key === 'excludeDirs' || key === 'autoScan') {

package/dist/index.js

@@ -46,6 +46,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const scanner_1 = require("./scanner");
+const classifier_1 = require("./classifier");
 const path_extractor_1 = require("./path-extractor");
 const vt_api_1 = require("./vt-api");
 const audit_log_1 = require("./audit-log");
@@ -366,7 +367,7 @@ function vtSentinelPlugin(api) {
             // User-provided key → standard VT API
             if (!process.env.VIRUSTOTAL_API_KEY)
                 process.env.VIRUSTOTAL_API_KEY = userApiKey;
-            scanner = new scanner_1.Scanner(userApiKey, api.logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy);
+            scanner = new scanner_1.Scanner(userApiKey, api.logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, false, eff.semanticFilePolicy);
             api.logger.info('[VT-Sentinel] Using user-provided API key (standard VT API)');
         }
         else {
@@ -386,7 +387,7 @@ function vtSentinelPlugin(api) {
             else {
                 api.logger.info(`[VT-Sentinel] Using cached VTAI agent: ${creds.publicHandle}`);
             }
-            scanner = new scanner_1.Scanner(creds.agentToken, api.logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, true);
+            scanner = new scanner_1.Scanner(creds.agentToken, api.logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, true, eff.semanticFilePolicy);
             if (!process.env.VIRUSTOTAL_API_KEY)
                 process.env.VIRUSTOTAL_API_KEY = 'vtai-active';
         }
@@ -862,7 +863,7 @@ function vtSentinelPlugin(api) {
     // --- Tool: vt_upload_consent ---
     api.registerTool({
         name: 'vt_upload_consent',
-        description: 'Confirm or deny uploading a sensitive file to VirusTotal after a needs_consent verdict. Call this after asking the user whether they want to upload a file that was flagged as sensitive (PDF, Office, unknown archive).',
+        description: 'Confirm or deny uploading a file to VirusTotal after a needs_consent verdict. Call this after asking the user whether they want to upload a file that was flagged as sensitive (PDF, Office, unknown archive) or as an instruction file (SKILL.md, TOOLS.md, AGENTS.md, etc.).',
         parameters: {
             type: 'object',
             properties: {
@@ -881,13 +882,16 @@ function vtSentinelPlugin(api) {
             const s = await ensureScanner();
             if (!s)
                 return textResponse('Error: VT-Sentinel not configured (API key missing and VTAI registration failed)');
+            // Determine consent group from file category
+            const fileCategory = classifier_1.FileClassifier.classify(params.path);
+            const consentGroup = fileCategory === classifier_1.FileCategory.SEMANTIC_RISK ? 'semantic' : 'sensitive';
             if (!params.upload) {
-                s.recordConsent(false);
+                s.recordConsent(false, consentGroup);
                 return textResponse(`Upload declined. File hash was already checked (not found in VT). ` +
                     `The file was NOT uploaded — your privacy is preserved.`);
             }
             try {
-                s.recordConsent(true);
+                s.recordConsent(true, consentGroup);
                 const result = await s.uploadWithConsent(params.path);
                 auditResult(result);
                 return textResponse(formatResult(result));
@@ -902,6 +906,7 @@ function vtSentinelPlugin(api) {
         if (diff.scannerNeedsRebuild && scanner) {
             scanner.updateMaxFileSizeMb(newConfig.maxFileSizeMb);
             scanner.updateSensitivePolicy(newConfig.sensitiveFilePolicy);
+            scanner.updateSemanticPolicy(newConfig.semanticFilePolicy);
             api.logger.info('[VT-Sentinel] Scanner config updated');
         }
         if (diff.changedFields.includes('autoScan')) {
@@ -991,6 +996,7 @@ function vtSentinelPlugin(api) {
                 preset: { type: 'string', enum: ['balanced', 'privacy_first', 'strict_security'], description: 'Configuration preset' },
                 notifyLevel: { type: 'string', enum: ['all', 'threats_only', 'silent'], description: 'Notification verbosity' },
                 sensitiveFilePolicy: { type: 'string', enum: ['ask', 'ask_once', 'always_upload', 'hash_only'], description: 'Policy for sensitive files' },
+                semanticFilePolicy: { type: 'string', enum: ['ask', 'ask_once', 'always_upload', 'hash_only'], description: 'Policy for instruction files (SKILL.md, HOOK.md, TOOLS.md, AGENTS.md). Default: hash_only' },
                 autoScan: { type: 'boolean', description: 'Enable/disable auto-scan' },
                 maxFileSizeMb: { type: 'number', description: 'Max file size to scan (MB)' },
                 watchDirsAdd: { type: 'array', items: { type: 'string' }, description: 'Directories to add to watch list' },
@@ -1103,6 +1109,7 @@ function vtSentinelPlugin(api) {
                 if (scanner) {
                     scanner.updateMaxFileSizeMb(newConfig.maxFileSizeMb);
                     scanner.updateSensitivePolicy(newConfig.sensitiveFilePolicy);
+                    scanner.updateSemanticPolicy(newConfig.semanticFilePolicy);
                 }
                 // Reconcile watcher state with restored config
                 if (newConfig.autoScan && !watcher) {
@@ -1255,7 +1262,7 @@ function vtSentinelPlugin(api) {
                 // Update scanner with new token
                 if (scanner) {
                     const scanEff = configManager.getEffective();
-                    scanner = new scanner_1.Scanner(newCreds.agentToken, api.logger, scanEff.maxFileSizeMb, scanEff.sensitiveFilePolicy, true);
+                    scanner = new scanner_1.Scanner(newCreds.agentToken, api.logger, scanEff.maxFileSizeMb, scanEff.sensitiveFilePolicy, true, scanEff.semanticFilePolicy);
                 }
                 const lines = ['Agent re-registered successfully:'];
                 lines.push(`  New handle: ${newCreds.publicHandle}`);
@@ -1276,13 +1283,10 @@ function vtSentinelPlugin(api) {
     });
     // --- Hook: auto-scan tool results ---
     const handleToolResult = async (event) => {
-        const s = await ensureScanner();
-        if (!s)
-            return;
-        // Enrich interesting dirs from context on first event
+        // Enrich interesting dirs from context on first event (no scanner needed)
         if (!contextEnriched)
             enrichFromContext(event);
-        // First-run onboarding: deliver once per workspace scope
+        // First-run onboarding: deliver once per workspace scope (no scanner needed)
         if (!firstRunDelivered) {
             const scope = {
                 workspaceDir: resolvedWorkspaceDir,
@@ -1314,6 +1318,14 @@ function vtSentinelPlugin(api) {
                 firstRunDelivered = true;
             }
         }
+        // autoScan=false disables hook scanning (active blocking in handleBeforeToolCall remains always-on)
+        const hookEff = configManager.getEffective();
+        if (!hookEff.autoScan)
+            return;
+        // Initialize scanner only when we're actually going to scan
+        const s = await ensureScanner();
+        if (!s)
+            return;
         const toolName = event.toolName || event.tool || '';
         const toolParams = event.toolParams || event.params || event.input || {};
         const toolResultText = extractResultText(event);
@@ -1323,13 +1335,25 @@ function vtSentinelPlugin(api) {
         if (shouldLog('pending')) {
             api.logger.info(`[VT-Sentinel] Auto-scan: ${targets.length} file(s) from ${toolName} tool`);
         }
-        const hookEff = configManager.getEffective();
         for (const target of targets) {
             if (isSelfPath(target.path))
                 continue;
+            // excludeGlobs: skip files matching any exclude pattern
+            if (hookEff.excludeGlobs.length > 0) {
+                let excluded = false;
+                for (const glob of hookEff.excludeGlobs) {
+                    if ((0, config_manager_1.matchGlob)(target.path, glob)) {
+                        excluded = true;
+                        break;
+                    }
+                }
+                if (excluded)
+                    continue;
+            }
             try {
                 let precomputedHash;
-                if (target.source === 'read_target') {
+                const isReadTarget = target.source === 'read_target';
+                if (isReadTarget) {
                     try {
                         const currentHash = await (0, vt_api_1.calculateSHA256)(target.path);
                         const previousHash = readScanRegistry.get(target.path);
@@ -1344,7 +1368,7 @@ function vtSentinelPlugin(api) {
                         // If hash computation fails, proceed with scan anyway
                     }
                 }
-                const result = await s.scanFile(target.path, false, precomputedHash);
+                const result = await s.scanFile(target.path, false, precomputedHash, isReadTarget);
                 auditResult(result);
                 if (result.verdict === 'malicious') {
                     if (shouldLog('malicious')) {
@@ -1388,8 +1412,10 @@ function vtSentinelPlugin(api) {
                         api.logger.warn(`[VT-Sentinel] Unknown: ${result.fileName} — ${result.message}`);
                 }
                 // Update read-scan registry AFTER successful scan.
-                // Skip 'unknown' (may be transient VT error → allow retry on next read).
-                if (precomputedHash && result.verdict !== 'unknown') {
+                // For hashOnly (read_target): 'unknown' means "hash not in VT" — stable, cache it.
+                // For non-hashOnly: 'unknown' may be transient API error → allow retry on next read.
+                const cacheableVerdict = result.verdict !== 'unknown' || isReadTarget;
+                if (precomputedHash && cacheableVerdict) {
                     readScanRegistry.set(target.path, precomputedHash);
                     if (readScanRegistry.size > READ_SCAN_REGISTRY_MAX) {
                         const toEvict = Math.floor(READ_SCAN_REGISTRY_MAX / 2);

package/dist/scanner.d.ts

@@ -34,35 +34,42 @@ export declare class Scanner {
     private limiter;
     private maxFileSizeMb;
     private sensitivePolicy;
-    /** In-memory consent cache for "ask_once" policy. null = not yet asked. */
+    private semanticPolicy;
+    /** In-memory consent cache for "ask_once" policy on sensitive files. null = not yet asked. */
     private consentDecision;
+    /** In-memory consent cache for "ask_once" policy on semantic files. null = not yet asked. */
+    private consentDecisionSemantic;
     private logger;
     constructor(apiKey: string, logger: {
         info: (m: string) => void;
         warn: (m: string) => void;
         error: (m: string) => void;
-    }, maxFileSizeMb?: number, sensitivePolicy?: SensitiveFilePolicy, useVtai?: boolean);
+    }, maxFileSizeMb?: number, sensitivePolicy?: SensitiveFilePolicy, useVtai?: boolean, semanticPolicy?: SensitiveFilePolicy);
     /**
      * Record the user's consent decision (used by the tool when the user responds).
      * When policy is "ask_once", this persists for the session.
+     * @param consentGroup — 'sensitive' or 'semantic', determines which consent cache to update.
      */
-    recordConsent(upload: boolean): void;
+    recordConsent(upload: boolean, consentGroup?: 'sensitive' | 'semantic'): void;
     /** Update maxFileSizeMb at runtime without rebuilding scanner. */
     updateMaxFileSizeMb(mb: number): void;
     /** Update sensitiveFilePolicy at runtime. Resets consent decision. */
     updateSensitivePolicy(policy: SensitiveFilePolicy): void;
+    /** Update semanticFilePolicy at runtime. Resets semantic consent decision. */
+    updateSemanticPolicy(policy: SensitiveFilePolicy): 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.
+     * When hashOnly=true: only check hash against VT, never upload regardless of category.
      */
-    scanFile(filePath: string, force?: boolean, precomputedHash?: string): Promise<ScanResult>;
+    scanFile(filePath: string, force?: boolean, precomputedHash?: string, hashOnly?: boolean): 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.
+     * Scan a SENSITIVE or SEMANTIC_RISK file according to the given policy.
      *
      * Step 1 (always): Check hash — this reveals nothing about file content.
      *   - If VT knows the hash → report findings (malicious PDF templates, etc.)
@@ -72,6 +79,8 @@ export declare class Scanner {
      *   - "always_upload"   → upload to VT
      *   - "ask"             → return needs_consent every time
      *   - "ask_once"        → return needs_consent the first time, then use remembered decision
+     *
+     * @param consentGroup — 'sensitive' or 'semantic', determines which consent cache to use
      */
     private scanSensitive;
     /**
@@ -79,6 +88,11 @@ export declare class Scanner {
      * Always checks hash; does NOT upload (no privacy concern but no reason to upload safe files).
      */
     private scanForced;
+    /**
+     * Hash-only check: rate-limited hash lookup, never uploads.
+     * Used when hashOnly=true (e.g., files read by the agent).
+     */
+    private hashCheckOnly;
     private uploadSensitive;
     private needsConsent;
     /**

package/dist/scanner.js

@@ -41,22 +41,31 @@ 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. */
+    constructor(apiKey, logger, maxFileSizeMb = 32, sensitivePolicy = 'ask', useVtai = false, semanticPolicy = 'hash_only') {
+        /** In-memory consent cache for "ask_once" policy on sensitive files. null = not yet asked. */
         this.consentDecision = null;
+        /** In-memory consent cache for "ask_once" policy on semantic files. null = not yet asked. */
+        this.consentDecisionSemantic = 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.semanticPolicy = semanticPolicy;
         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.
+     * @param consentGroup — 'sensitive' or 'semantic', determines which consent cache to update.
      */
-    recordConsent(upload) {
-        this.consentDecision = upload;
+    recordConsent(upload, consentGroup = 'sensitive') {
+        if (consentGroup === 'semantic') {
+            this.consentDecisionSemantic = upload;
+        }
+        else {
+            this.consentDecision = upload;
+        }
     }
     /** Update maxFileSizeMb at runtime without rebuilding scanner. */
     updateMaxFileSizeMb(mb) {
@@ -67,11 +76,17 @@ class Scanner {
         this.sensitivePolicy = policy;
         this.consentDecision = null;
     }
+    /** Update semanticFilePolicy at runtime. Resets semantic consent decision. */
+    updateSemanticPolicy(policy) {
+        this.semanticPolicy = policy;
+        this.consentDecisionSemantic = null;
+    }
     /**
      * 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.
+     * When hashOnly=true: only check hash against VT, never upload regardless of category.
      */
-    async scanFile(filePath, force = false, precomputedHash) {
+    async scanFile(filePath, force = false, precomputedHash, hashOnly = false) {
         const fileName = path.basename(filePath);
         if (!fs.existsSync(filePath)) {
             return this.result(filePath, '', classifier_1.FileCategory.SAFE, 'skipped', `File not found: ${fileName}`);
@@ -92,6 +107,15 @@ class Scanner {
             // Cache entries are keyed by SHA-256 (VT identity). Rebase per-file context.
             return { ...cached, filePath, fileName, category, sha256 };
         }
+        // hashOnly mode: only check hash, never upload (used for read_target scans)
+        if (hashOnly) {
+            const report = await this.hashCheckOnly(filePath, sha256, category);
+            if (report && (report.verdict === 'clean' || report.verdict === 'malicious' ||
+                report.verdict === 'suspicious' || report.verdict === 'pending')) {
+                this.cache.set(sha256, report);
+            }
+            return report;
+        }
         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.
@@ -100,11 +124,13 @@ class Scanner {
             : 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.SEMANTIC_RISK:
+                result = await this.scanSensitive(filePath, sha256, effectiveCategory, this.semanticPolicy, 'semantic');
+                break;
             case classifier_1.FileCategory.SENSITIVE:
-                result = await this.scanSensitive(filePath, sha256, effectiveCategory);
+                result = await this.scanSensitive(filePath, sha256, effectiveCategory, this.sensitivePolicy, 'sensitive');
                 break;
             case classifier_1.FileCategory.MEDIA:
             case classifier_1.FileCategory.SAFE:
@@ -146,7 +172,7 @@ class Scanner {
         }
     }
     /**
-     * Scan a SENSITIVE file according to the configured policy.
+     * Scan a SENSITIVE or SEMANTIC_RISK file according to the given policy.
      *
      * Step 1 (always): Check hash — this reveals nothing about file content.
      *   - If VT knows the hash → report findings (malicious PDF templates, etc.)
@@ -156,8 +182,10 @@ class Scanner {
      *   - "always_upload"   → upload to VT
      *   - "ask"             → return needs_consent every time
      *   - "ask_once"        → return needs_consent the first time, then use remembered decision
+     *
+     * @param consentGroup — 'sensitive' or 'semantic', determines which consent cache to use
      */
-    async scanSensitive(filePath, sha256, category) {
+    async scanSensitive(filePath, sha256, category, policy, consentGroup) {
         const fileName = path.basename(filePath);
         // Step 1: Hash check (always safe, reveals nothing)
         await this.limiter.acquire();
@@ -167,17 +195,19 @@ class Scanner {
             result.message += ' (hash-only check — file NOT uploaded to VT)';
             return result;
         }
+        // Resolve consent for ask_once from the appropriate group
+        const consent = consentGroup === 'semantic' ? this.consentDecisionSemantic : this.consentDecision;
         // Step 2: Hash unknown — apply policy
-        switch (this.sensitivePolicy) {
+        switch (policy) {
             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) {
+                if (consent === true) {
                     return this.uploadSensitive(filePath, sha256, category, fileName);
                 }
-                if (this.consentDecision === false) {
+                if (consent === false) {
                     return this.result(filePath, sha256, category, 'unknown', `Unknown to VT (${fileName}). User previously declined upload — hash-only.`);
                 }
                 // First time — fall through to ask
@@ -200,6 +230,21 @@ class Scanner {
         }
         return this.result(filePath, sha256, category, 'unknown', `File "${fileName}" (${category}) not found in VT database. Hash checked — no threats known.`);
     }
+    /**
+     * Hash-only check: rate-limited hash lookup, never uploads.
+     * Used when hashOnly=true (e.g., files read by the agent).
+     */
+    async hashCheckOnly(filePath, sha256, category) {
+        const fileName = path.basename(filePath);
+        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;
+        }
+        return this.result(filePath, sha256, category, 'unknown', `Unknown to VT (${fileName}). Hash checked only — file NOT uploaded (read-only scan).`);
+    }
     async uploadSensitive(filePath, sha256, category, fileName) {
         this.logger.info(`[VT-Sentinel] Uploading SENSITIVE file ${fileName} (user consented)...`);
         await this.limiter.acquire();
@@ -229,8 +274,11 @@ class Scanner {
         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') {
+        // Remember consent for ask_once policy — only for the file's actual category
+        if (category === classifier_1.FileCategory.SEMANTIC_RISK && this.semanticPolicy === 'ask_once') {
+            this.consentDecisionSemantic = true;
+        }
+        else if (category === classifier_1.FileCategory.SENSITIVE && this.sensitivePolicy === 'ask_once') {
             this.consentDecision = true;
         }
         return this.uploadSensitive(filePath, sha256, category, fileName);

package/dist/status-renderer.js

@@ -65,6 +65,7 @@ function renderStatus(opts) {
     lines.push(`  Auto-scan: ${cfg.autoScan ? 'enabled' : 'disabled'}`);
     lines.push(`  Max file size: ${cfg.maxFileSizeMb} MB`);
     lines.push(`  Sensitive file policy: ${cfg.sensitiveFilePolicy}`);
+    lines.push(`  Semantic file policy: ${cfg.semanticFilePolicy}`);
     lines.push(`  Notify level: ${cfg.notifyLevel}`);
     lines.push(`  Block mode: ${cfg.blockMode}`);
     lines.push(`  Show clean scan logs: ${cfg.showCleanScanLogs}`);
@@ -109,12 +110,16 @@ function renderPolicyMatrix(config) {
         : config.sensitiveFilePolicy === 'hash_only' ? 'No (hash only)'
             : config.sensitiveFilePolicy === 'ask_once' ? 'Ask once'
                 : 'Ask each time';
+    const semanticUpload = config.semanticFilePolicy === 'always_upload' ? 'Yes'
+        : config.semanticFilePolicy === 'hash_only' ? 'No (hash only)'
+            : config.semanticFilePolicy === 'ask_once' ? 'Ask once'
+                : 'Ask each time';
     const lines = [];
     lines.push('Policy Matrix:');
     lines.push('  Category        | Auto-scan | Upload if unknown | If malicious');
     lines.push('  ----------------+-----------+-------------------+-------------');
     lines.push(`  HIGH_RISK       | Yes       | Yes               | ${blockAction}`);
-    lines.push(`  SEMANTIC_RISK   | Yes       | Yes               | ${blockAction}`);
+    lines.push(`  SEMANTIC_RISK   | Yes       | ${semanticUpload.padEnd(17)} | ${blockAction}`);
     lines.push(`  SENSITIVE       | Yes       | ${sensitiveUpload.padEnd(17)} | ${blockAction}`);
     lines.push(`  MEDIA           | Skip      | No                | N/A`);
     lines.push(`  SAFE            | Skip      | No                | N/A`);
@@ -145,6 +150,9 @@ function renderHelp() {
     lines.push('  vt_sentinel_configure { sensitiveFilePolicy: "hash_only", persist: "state" }');
     lines.push('    Change individual settings. persist="state" saves to disk.');
     lines.push('');
+    lines.push('  vt_sentinel_configure { semanticFilePolicy: "ask" }');
+    lines.push('    Change policy for instruction files (SKILL.md, HOOK.md, TOOLS.md, AGENTS.md).');
+    lines.push('');
     lines.push('  vt_sentinel_configure { watchDirsAdd: ["/extra/dir"], excludeGlobs: ["*.log"] }');
     lines.push('    Add watch dirs or exclude patterns');
     lines.push('');
@@ -178,10 +186,12 @@ function renderHelp() {
     lines.push('');
     lines.push('PRIVACY:');
     lines.push('  - File hashes (SHA-256) are always sent to VT for lookup.');
-    lines.push('  - File content is uploaded only when: the file is HIGH_RISK/SEMANTIC_RISK,');
-    lines.push('    OR when the sensitive file policy allows it (ask/always_upload).');
+    lines.push('  - HIGH_RISK files (binaries, scripts) are auto-uploaded when unknown.');
+    lines.push('  - SEMANTIC_RISK files (SKILL.md, TOOLS.md, etc.) follow semanticFilePolicy (default: hash_only).');
+    lines.push('  - SENSITIVE files (PDF, Office) follow sensitiveFilePolicy (default: ask).');
+    lines.push('  - Files read by the agent (read tool) are hash-checked only, never auto-uploaded.');
     lines.push('  - Session memory files are NEVER uploaded (privacy protection).');
-    lines.push('  - Use sensitiveFilePolicy: "hash_only" for maximum privacy.');
+    lines.push('  - autoScan=false disables hook scanning (active blocking remains on).');
     lines.push('  - Audit logs: ~/.openclaw/vt-sentinel-uploads.log + vt-sentinel-detections.log');
     return lines.join('\n');
 }

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

@@ -16,6 +16,14 @@ 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.
 
+Files read by the agent (via the `read` tool) are hash-checked only — never
+auto-uploaded to VirusTotal. This protects configuration and instruction files
+from being shared without explicit consent.
+
+When `autoScan` is set to `false`, hook scanning is disabled entirely.
+Active blocking (dangerous command patterns, blocklist enforcement) remains
+always-on regardless of this setting.
+
 ## Detected Patterns
 
 - `curl -o /path/file`, `wget -O /path/file` — download targets

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,44 @@ 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.
  */
-function createScanner(logger) {
+function createScanner(logger, eff) {
     const apiKey = process.env.VIRUSTOTAL_API_KEY;
 
     // User has their own VT API key (and it's not the 'active' placeholder)
     if (apiKey && apiKey !== 'vtai-active') {
-        return new Scanner(apiKey, logger);
+        return new Scanner(apiKey, logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, false, eff.semanticFilePolicy);
     }
 
     // Try VTAI cached credentials
@@ -40,7 +63,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 +79,37 @@ const handler = async (event) => {
 
     if (!Scanner || !extractPaths) return;
 
+    // Load config (static + persisted overrides) and check autoScan
+    let configManager = null;
+    if (ConfigManager) {
+        const staticConfig = readStaticConfig();
+        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);
     if (!scanner) return;
 
     const toolName = event.toolName || event.tool || '';
@@ -83,8 +130,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

@@ -30,6 +30,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 +100,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,6 +1,6 @@
 {
   "name": "openclaw-plugin-vt-sentinel",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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" }
 ```