openclaw-plugin-vt-sentinel 0.11.3 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to `openclaw-plugin-vt-sentinel`.
 
+## 0.12.0 — Transparency surface + log hygiene
+
+**Headline:** what VT Sentinel does at runtime is now auditable from two
+places: `vt_sentinel_status` and `openclaw security audit --deep --json`.
+Both views are rendered from the same snapshot function, so they can't drift.
+
+### Added
+
+- **`registerSecurityAuditCollector`** (new). Registers a plugin-scoped
+  collector that OpenClaw surfaces under `openclaw security audit --deep`.
+  Emits `info`-level findings for credential mode, endpoints, effective
+  policies, state/log paths, and identity metadata; emits `warn`-level
+  findings for risky config: `always_upload` on sensitive or semantic
+  files, broad watch dirs (root-level or whole-profile), audit files not
+  owner-private, `agentContactEmail` set (PII flagged as user's choice),
+  and the inconsistent `autoScan=false` + `blockMode=quarantine` posture.
+- **`buildComplianceSnapshot`** — pure function in
+  `src/compliance-snapshot.ts`. Single source of truth consumed by the
+  security audit collector, the `vt_sentinel_status` tool output, and
+  tests. Uses `ctx.stateDir` / `ctx.configPath` — no global reads.
+- **`vt_sentinel_status` Compliance / Data Flow block.** Renders live
+  endpoints, credential mode, state and log file paths, VTAI identity
+  metadata shape (never the values), and any active risk flags.
+- **README Privacy & compliance section** with a data-flow table (what's
+  read / uploaded / where credentials live / how to opt out) and the
+  explicit note that `VIRUSTOTAL_API_KEY` was retired in 0.11.x.
+
+### Changed
+
+- **Audit-log hygiene.** Log files (`uploads.log`, `detections.log`) are
+  pre-created at mode `0o600` so the first append cannot race the process
+  umask. The audit directory is created at `0o700`. Rotations rewrite
+  with an explicit owner-only mode and tighten again via `chmodSync`
+  on platforms where `writeFileSync` resets the mode.
+- **Audit logs moved to `<stateDir>/vt-sentinel-audit/`.** Previously
+  `<stateDir>/vt-sentinel-uploads.log` and `...-detections.log`. Clean
+  move because production users had not yet produced entries (no
+  migration needed for most installs).
+- **Empty file path is now recorded as `<in-memory>`.** Detections that
+  surface a SHA-256 without an on-disk path (extracted archive members,
+  EICAR-from-buffer scans) no longer emit an ambiguous trailing tab.
+- **`getLogDir(stateDir)` takes an explicit argument.** The former
+  `process.env.OPENCLAW_STATE_DIR` fallback was removed for module
+  uniformity with the v0.11.x env-free stance.
+- **Standalone `hooks/vt-auto-scan/` retired.** OpenClaw scans
+  `hooks/*/HOOK.md` for hook-pack discovery, which created a duplicate
+  registration alongside the runtime `api.registerHook(...)` calls in
+  `index.ts`. With `install.minHostVersion >=2026.3.22` guaranteed, the
+  runtime path is sufficient. One authoritative source, half the
+  maintenance surface.
+
+### Internal
+
+- `src/update-commands.ts` — split from `index.ts` in 0.11.3 for scanner
+  hygiene; now also used by the compliance snapshot tests as an example
+  of the "pure helper" pattern we apply to new modules.
+
+### Deferred
+
+- **Migration to `definePluginEntry`.** Verified empirically on the Linux
+  production VM (OpenClaw 2026.4.12): `require('openclaw/plugin-sdk/core')`
+  does not resolve from `~/.openclaw/extensions/<plugin>/dist/`. Would
+  require a peerDependency + NODE_PATH surgery with only cosmetic benefit.
+  The plain default-export plugin shape stays. Re-evaluate when OpenClaw
+  ships a formal plugin-sdk resolution helper.
+- **SecretRef for `apiKey`.** Still blocked upstream —
+  `validatePluginConfig` in OpenClaw 2026.4.12 does not auto-resolve
+  SecretRefs for non-channel plugins.
+- **`potential-exfiltration` in `dist/vt-api.js`.** The same finding
+  remains from 0.11.3: credential persistence used to live next to axios
+  calls. Since v0.11.3 split them into `vt-credentials.ts`, static scan
+  now reports clean. No action needed in 0.12.0.
+
+### Compatibility
+
+Runtime-compatible with 0.11.x users. Existing credentials, runtime
+overrides, and cached agent identities carry across the upgrade. The
+two log-file paths are new; legacy files at the old stateDir root remain
+as unused orphans and can be deleted manually if desired.
+
 ## 0.11.3 — ClawHub static-scan: eliminate last warn
 
 Runtime behavior identical to 0.11.2. One last structural change so ClawHub's

package/README.md

@@ -122,7 +122,37 @@ File analysis includes:
 ## Privacy & compliance
 
 VT Sentinel is a security plugin, so transparency about what it reads, writes,
-and sends is part of the threat model. Highlights as of v0.11.0:
+and sends is part of the threat model. The same structured view is emitted by
+`vt_sentinel_status` (Compliance / Data Flow block) and by `openclaw security
+audit --deep` (via the plugin's `securityAuditCollector` — since v0.12.0), so
+you can verify the behavior from either surface without reading source.
+
+### Data flow
+
+| Category | Detail |
+|---|---|
+| **Files read** | Candidate files under configured watch dirs — for hashing and classification. Full contents are uploaded to VirusTotal/VTAI only when upload policy and (for `ask`/`ask_once`) user consent allow it. Instruction files (`SKILL.md`, `HOOK.md`, `AGENTS.md`, etc.) default to `hash_only` and are never auto-uploaded. |
+| **Files uploaded** | Hash lookups are free (no content sent). Content uploads happen only per the configured `sensitiveFilePolicy` / `semanticFilePolicy`. |
+| **Network endpoints** | User-key mode: `www.virustotal.com`. VTAI mode: `ai.virustotal.com`. `registry.npmjs.org` and `clawhub.ai` are contacted **only** when the user explicitly invokes `vt_sentinel_update` — never on plugin load. |
+| **Credentials stored** | `<stateDir>/vt-sentinel-agent.json` (mode `0o600`, owner-only). v0.12.0+ also enforces `0o600` on audit logs and `0o700` on the audit directory. |
+| **Audit logs** | `<stateDir>/vt-sentinel-audit/uploads.log` and `detections.log`. Rotating; track when the plugin uploaded a file and when a detection fired. |
+| **Runtime state** | `<stateDir>/vt-sentinel-state.json` — first-run flags, persisted policy overrides, auto-generated agent name. No sample file contents. |
+| **Opt-outs** | `vt_sentinel_configure` → switch to `configPreset: privacy_first`, set `autoScan: false`, or switch per-category policy to `hash_only`. |
+
+### `VIRUSTOTAL_API_KEY` shell variable is retired
+
+Earlier versions fell back to reading `VIRUSTOTAL_API_KEY` from the shell
+environment. **That fallback was removed in 0.11.0.** If you previously
+exported the variable, move the value into the plugin config once with:
+
+```
+openclaw config set plugins.entries.openclaw-plugin-vt-sentinel.config.apiKey "vt_xxxxxxxx"
+```
+
+or do nothing and let VTAI auto-register on first scan. Both are fully
+supported; the env variable is not.
+
+### Legacy highlights retained from v0.11.0
 
 - **Network endpoints:** only `www.virustotal.com` (VT API) and
   `ai.virustotal.com` (VTAI). `registry.npmjs.org` / `clawhub.com` are

package/dist/audit-log.d.ts

@@ -1,7 +1,18 @@
 /**
  * Simple rotating audit log.
- * Format: ISO-8601 timestamp \t SHA-256 \t full file path
- * Rotates by keeping the newest half when maxLines or maxBytes is exceeded.
+ *
+ * Entry format (v0.12.0+): `{ISO-8601}\t{SHA-256}\t{filePath or <sentinel>}\n`.
+ * Empty filePath (e.g. EICAR detection from a memory buffer or an extracted
+ * archive member whose original path was not surfaced) is recorded as
+ * `<in-memory>` so the log stays self-describing.
+ *
+ * Permissions hardening (v0.12.0+):
+ *  - Parent directory is created with mode 0o700 if missing.
+ *  - Log file is pre-created with mode 0o600 before the first append so the
+ *    owner-only posture doesn't depend on umask.
+ *  - Rotations rewrite the file with an explicit mode 0o600.
+ *
+ * Rotation: when maxLines or maxBytes is exceeded the newest half is kept.
  */
 export declare class AuditLog {
     private logPath;
@@ -9,11 +20,27 @@ export declare class AuditLog {
     private maxBytes;
     private lineCount;
     private approxSize;
+    private ensuredPermissions;
     constructor(logPath: string, maxLines?: number, maxBytes?: number);
+    /** Ensure parent dir exists at 0o700 and the log file exists at 0o600. */
+    private ensureContainerAndFile;
+    private seedCountersFromDisk;
+    /**
+     * Append a record. `filePath` may be empty — in that case we record the
+     * `<in-memory>` sentinel so the log doesn't emit an ambiguous trailing tab.
+     */
     append(sha256: string, filePath: string): void;
     private rotate;
 }
 /**
- * Returns the directory for VT Sentinel logs (same as state dir).
+ * Returns the directory for VT Sentinel audit logs.
+ *
+ * v0.12.0 change: logs now live in a dedicated `<stateDir>/vt-sentinel-audit/`
+ * subdirectory (pre-0.12 they were at the stateDir root). The subdir is
+ * created at 0o700 on first write.
+ *
+ * The stateDir must be supplied by the caller (previously fell back to reading
+ * the environment; that read has been removed to keep this module free of
+ * `process.env` lookups that could co-occur with HTTP clients elsewhere).
  */
-export declare function getLogDir(): string;
+export declare function getLogDir(stateDir: string): string;

package/dist/audit-log.js

@@ -37,31 +37,70 @@ exports.AuditLog = void 0;
 exports.getLogDir = getLogDir;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const os = __importStar(require("os"));
 /**
  * Simple rotating audit log.
- * Format: ISO-8601 timestamp \t SHA-256 \t full file path
- * Rotates by keeping the newest half when maxLines or maxBytes is exceeded.
+ *
+ * Entry format (v0.12.0+): `{ISO-8601}\t{SHA-256}\t{filePath or <sentinel>}\n`.
+ * Empty filePath (e.g. EICAR detection from a memory buffer or an extracted
+ * archive member whose original path was not surfaced) is recorded as
+ * `<in-memory>` so the log stays self-describing.
+ *
+ * Permissions hardening (v0.12.0+):
+ *  - Parent directory is created with mode 0o700 if missing.
+ *  - Log file is pre-created with mode 0o600 before the first append so the
+ *    owner-only posture doesn't depend on umask.
+ *  - Rotations rewrite the file with an explicit mode 0o600.
+ *
+ * Rotation: when maxLines or maxBytes is exceeded the newest half is kept.
  */
 class AuditLog {
     constructor(logPath, maxLines = 1000, maxBytes = 1024 * 1024) {
         this.lineCount = 0;
         this.approxSize = 0;
+        this.ensuredPermissions = false;
         this.logPath = logPath;
         this.maxLines = maxLines;
         this.maxBytes = maxBytes;
-        // Ensure parent directory exists
+        this.ensureContainerAndFile();
+        this.seedCountersFromDisk();
+    }
+    /** Ensure parent dir exists at 0o700 and the log file exists at 0o600. */
+    ensureContainerAndFile() {
         try {
-            const dir = path.dirname(logPath);
-            if (!fs.existsSync(dir))
-                fs.mkdirSync(dir, { recursive: true });
+            const dir = path.dirname(this.logPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            }
+            else {
+                // Tighten permissions on the dir if it pre-existed wide-open (best-effort).
+                try {
+                    fs.chmodSync(dir, 0o700);
+                }
+                catch { /* not a blocker */ }
+            }
+            if (!fs.existsSync(this.logPath)) {
+                // Pre-create empty so the first append doesn't race default umask.
+                fs.writeFileSync(this.logPath, '', { mode: 0o600 });
+            }
+            else {
+                // Tighten permissions on the file if it pre-existed wide-open.
+                try {
+                    fs.chmodSync(this.logPath, 0o600);
+                }
+                catch { /* not a blocker */ }
+            }
+            this.ensuredPermissions = true;
         }
-        catch { /* best-effort */ }
-        // Seed counters from existing file
+        catch {
+            // Best-effort — never crash the plugin for a log setup failure.
+            this.ensuredPermissions = false;
+        }
+    }
+    seedCountersFromDisk() {
         try {
-            const stat = fs.statSync(logPath);
+            const stat = fs.statSync(this.logPath);
             this.approxSize = stat.size;
-            const content = fs.readFileSync(logPath, 'utf-8');
+            const content = fs.readFileSync(this.logPath, 'utf-8');
             this.lineCount = content.split('\n').filter(l => l.length > 0).length;
         }
         catch {
@@ -69,9 +108,18 @@ class AuditLog {
             this.approxSize = 0;
         }
     }
+    /**
+     * Append a record. `filePath` may be empty — in that case we record the
+     * `<in-memory>` sentinel so the log doesn't emit an ambiguous trailing tab.
+     */
     append(sha256, filePath) {
-        const line = `${new Date().toISOString()}\t${sha256}\t${filePath}\n`;
+        const displayPath = filePath && filePath.length > 0 ? filePath : '<in-memory>';
+        const line = `${new Date().toISOString()}\t${sha256}\t${displayPath}\n`;
         try {
+            if (!this.ensuredPermissions) {
+                // Container or file didn't exist at construction — retry now.
+                this.ensureContainerAndFile();
+            }
             fs.appendFileSync(this.logPath, line);
             this.lineCount++;
             this.approxSize += Buffer.byteLength(line);
@@ -85,9 +133,7 @@ class AuditLog {
         try {
             const content = fs.readFileSync(this.logPath, 'utf-8');
             const lines = content.split('\n').filter(l => l.length > 0);
-            // Keep at most half of maxLines
             let keep = lines.slice(-Math.floor(this.maxLines / 2));
-            // Also trim by size: drop oldest lines until under half of maxBytes
             const halfBytes = Math.floor(this.maxBytes / 2);
             while (keep.length > 1) {
                 const size = Buffer.byteLength(keep.join('\n') + '\n');
@@ -96,7 +142,14 @@ class AuditLog {
                 keep.shift();
             }
             const newContent = keep.join('\n') + '\n';
-            fs.writeFileSync(this.logPath, newContent);
+            // Write with explicit owner-only mode — some Node versions reset
+            // the file's mode on writeFileSync with content, so set it again
+            // on the original descriptor path.
+            fs.writeFileSync(this.logPath, newContent, { mode: 0o600 });
+            try {
+                fs.chmodSync(this.logPath, 0o600);
+            }
+            catch { /* ignore */ }
             this.lineCount = keep.length;
             this.approxSize = Buffer.byteLength(newContent);
         }
@@ -105,8 +158,16 @@ class AuditLog {
 }
 exports.AuditLog = AuditLog;
 /**
- * Returns the directory for VT Sentinel logs (same as state dir).
+ * Returns the directory for VT Sentinel audit logs.
+ *
+ * v0.12.0 change: logs now live in a dedicated `<stateDir>/vt-sentinel-audit/`
+ * subdirectory (pre-0.12 they were at the stateDir root). The subdir is
+ * created at 0o700 on first write.
+ *
+ * The stateDir must be supplied by the caller (previously fell back to reading
+ * the environment; that read has been removed to keep this module free of
+ * `process.env` lookups that could co-occur with HTTP clients elsewhere).
  */
-function getLogDir() {
-    return process.env.OPENCLAW_STATE_DIR || path.join(os.homedir(), '.openclaw');
+function getLogDir(stateDir) {
+    return path.join(stateDir, 'vt-sentinel-audit');
 }

package/dist/compliance-snapshot.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Compliance snapshot — the single source of truth that describes, in
+ * structured form, what VT Sentinel reads, writes, sends, and where it keeps
+ * its state.
+ *
+ * Consumed by three call sites:
+ *   1. `registerSecurityAuditCollector` — maps the snapshot to
+ *      `SecurityAuditFinding[]` so `openclaw security audit --deep` can
+ *      display it.
+ *   2. `vt_sentinel_status` — renders a "Compliance / Data Flow" block from
+ *      the same data, so end users see the same picture the audit does.
+ *   3. Tests — assert the snapshot shape against mock configurations.
+ *
+ * This module is a pure function with no module-level side effects. Optional
+ * file-mode info can be collected by the caller via `collectLogModes()` and
+ * passed in; when absent, the snapshot simply omits permission checks.
+ */
+import type { FullConfig, BlockMode, NotifyLevel, PresetName, AgentMetadataMode } from './config-manager';
+import type { SensitiveFilePolicy } from './scanner';
+export type CredentialMode = 'user_key' | 'vtai' | 'none';
+export interface LogFileMode {
+    path: string;
+    exists: boolean;
+    mode?: string;
+    ownerPrivate: boolean;
+}
+export interface LogModesInfo {
+    auditDir: LogFileMode;
+    uploadsLog: LogFileMode;
+    detectionsLog: LogFileMode;
+    credentialsFile: LogFileMode;
+    stateFile: LogFileMode;
+}
+export interface ComplianceSnapshotInput {
+    config: FullConfig;
+    stateDir: string;
+    credentialMode: CredentialMode;
+    watchDirs: string[];
+    agentPublicHandle?: string;
+    /** Optional: pre-collected log permission info (see `collectLogModes`). */
+    logModes?: LogModesInfo;
+}
+export interface ComplianceSnapshot {
+    credentialMode: CredentialMode;
+    endpoints: {
+        virustotal: boolean;
+        virustotalAi: boolean;
+        /** npm registry only consulted from the explicit vt_sentinel_update tool */
+        npm: 'on-demand-only';
+        /** ClawHub only consulted from the explicit vt_sentinel_update tool */
+        clawhub: 'on-demand-only';
+    };
+    policies: {
+        autoScan: boolean;
+        sensitiveFilePolicy: SensitiveFilePolicy;
+        semanticFilePolicy: SensitiveFilePolicy;
+        blockMode: BlockMode;
+        notifyLevel: NotifyLevel;
+        preset: PresetName;
+        maxFileSizeMb: number;
+        showCleanScanLogs: boolean;
+    };
+    watchDirs: string[];
+    excludeDirs: string[];
+    excludeGlobs: string[];
+    paths: {
+        stateDir: string;
+        credentialsFile: string;
+        stateFile: string;
+        auditDir: string;
+        uploadsLog: string;
+        detectionsLog: string;
+    };
+    identity: {
+        /** display name declared to VTAI (either user-set or auto-generated) */
+        displayNameSet: boolean;
+        humanAliasSet: boolean;
+        bioSet: boolean;
+        contactEmailSet: boolean;
+        metadataMode: AgentMetadataMode;
+        publicHandle?: string;
+    };
+    logModes?: LogModesInfo;
+    baseline: AuditFinding[];
+    risks: AuditFinding[];
+}
+export interface AuditFinding {
+    checkId: string;
+    severity: 'info' | 'warn' | 'critical';
+    title: string;
+    detail: string;
+    remediation?: string;
+}
+export declare function computePaths(stateDir: string): ComplianceSnapshot['paths'];
+/**
+ * Stat the log files + state files + audit dir to record their permissions.
+ * Safe to call even if none of them exist yet (returns `exists: false`).
+ */
+export declare function collectLogModes(stateDir: string): LogModesInfo;
+/**
+ * Build the compliance snapshot. Pure function — no I/O.
+ * Callers that want log-permission info should call `collectLogModes(stateDir)`
+ * first and pass the result as `input.logModes`.
+ */
+export declare function buildComplianceSnapshot(input: ComplianceSnapshotInput): ComplianceSnapshot;

package/dist/compliance-snapshot.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * Compliance snapshot — the single source of truth that describes, in
+ * structured form, what VT Sentinel reads, writes, sends, and where it keeps
+ * its state.
+ *
+ * Consumed by three call sites:
+ *   1. `registerSecurityAuditCollector` — maps the snapshot to
+ *      `SecurityAuditFinding[]` so `openclaw security audit --deep` can
+ *      display it.
+ *   2. `vt_sentinel_status` — renders a "Compliance / Data Flow" block from
+ *      the same data, so end users see the same picture the audit does.
+ *   3. Tests — assert the snapshot shape against mock configurations.
+ *
+ * This module is a pure function with no module-level side effects. Optional
+ * file-mode info can be collected by the caller via `collectLogModes()` and
+ * passed in; when absent, the snapshot simply omits permission checks.
+ */
+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.computePaths = computePaths;
+exports.collectLogModes = collectLogModes;
+exports.buildComplianceSnapshot = buildComplianceSnapshot;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// --- Core paths helper (pure) ---
+function computePaths(stateDir) {
+    const auditDir = path.join(stateDir, 'vt-sentinel-audit');
+    return {
+        stateDir,
+        credentialsFile: path.join(stateDir, 'vt-sentinel-agent.json'),
+        stateFile: path.join(stateDir, 'vt-sentinel-state.json'),
+        auditDir,
+        uploadsLog: path.join(auditDir, 'uploads.log'),
+        detectionsLog: path.join(auditDir, 'detections.log'),
+    };
+}
+// --- Log-mode collector (optional, I/O) ---
+/**
+ * Stat the log files + state files + audit dir to record their permissions.
+ * Safe to call even if none of them exist yet (returns `exists: false`).
+ */
+function collectLogModes(stateDir) {
+    const p = computePaths(stateDir);
+    return {
+        auditDir: statMode(p.auditDir, true),
+        uploadsLog: statMode(p.uploadsLog, false),
+        detectionsLog: statMode(p.detectionsLog, false),
+        credentialsFile: statMode(p.credentialsFile, false),
+        stateFile: statMode(p.stateFile, false),
+    };
+}
+function statMode(fsPath, isDir) {
+    try {
+        const st = fs.statSync(fsPath);
+        const modeBits = st.mode & 0o777;
+        const mode = modeBits.toString(8).padStart(isDir ? 3 : 3, '0');
+        // Owner-private means: no group-read AND no other-read
+        // For dirs we also want no group-exec/other-exec.
+        const ownerPrivate = (modeBits & 0o077) === 0;
+        return { path: fsPath, exists: true, mode, ownerPrivate };
+    }
+    catch {
+        // Missing file / dir is fine — the plugin creates it lazily on first
+        // write with {mode: 0o600}/{mode: 0o700} from v0.12.0 onwards, so a
+        // non-existent log is implicitly "private once it exists".
+        return { path: fsPath, exists: false, ownerPrivate: true };
+    }
+}
+// --- Risk detection (pure helpers) ---
+/** A watch dir is "risky" if it's close to the filesystem root or a whole user profile. */
+function isBroadWatchDir(dir) {
+    if (!dir)
+        return false;
+    // Root '/' must be handled before trimming the trailing separator.
+    if (dir === '/' || /^[A-Za-z]:[\\/]?$/.test(dir))
+        return true;
+    const norm = dir.replace(/[\\/]+$/, ''); // trim trailing separator
+    // Unix near-root
+    if (['/home', '/Users'].includes(norm))
+        return true;
+    // Exact $HOME (common mistake — scans user profile including dotfiles)
+    // We can't resolve $HOME here without I/O; instead treat paths that end
+    // with just the user directory segment as broad.
+    // Heuristic: directory depth 2 or less (e.g. /Users/foo, /home/foo, /root).
+    const parts = norm.split(/[\\/]/).filter(Boolean);
+    if (parts.length <= 2 && /^(Users|home|root)$/.test(parts[0] ?? ''))
+        return true;
+    // Windows user dir at depth 2 (e.g. C:\Users\foo)
+    if (parts.length === 3 && /^[A-Za-z]:$/.test(parts[0] ?? '') && parts[1]?.toLowerCase() === 'users')
+        return true;
+    return false;
+}
+// --- Main builder ---
+/**
+ * Build the compliance snapshot. Pure function — no I/O.
+ * Callers that want log-permission info should call `collectLogModes(stateDir)`
+ * first and pass the result as `input.logModes`.
+ */
+function buildComplianceSnapshot(input) {
+    const { config, stateDir, credentialMode, watchDirs, agentPublicHandle, logModes } = input;
+    const paths = computePaths(stateDir);
+    const identity = {
+        displayNameSet: !!config.agentDisplayName,
+        humanAliasSet: !!config.agentHumanAlias,
+        bioSet: !!config.agentBio,
+        contactEmailSet: !!config.agentContactEmail,
+        metadataMode: config.agentMetadataMode ?? 'minimal',
+        publicHandle: agentPublicHandle,
+    };
+    const baseline = [];
+    const risks = [];
+    // --- Baseline info findings (what the plugin does) ---
+    baseline.push({
+        checkId: 'vt-sentinel.credential-mode',
+        severity: 'info',
+        title: `Credential mode: ${credentialMode}`,
+        detail: credentialMode === 'user_key'
+            ? 'Using a user-provided VirusTotal API key from plugin config. All scans go to www.virustotal.com.'
+            : credentialMode === 'vtai'
+                ? 'Using an auto-registered VTAI agent token (zero-config). All scans go to ai.virustotal.com.'
+                : 'No credentials active. Scanner disabled until a config apiKey is set or VTAI auto-registration completes.',
+    });
+    baseline.push({
+        checkId: 'vt-sentinel.endpoints',
+        severity: 'info',
+        title: 'Network endpoints contacted',
+        detail: (credentialMode === 'user_key' ? 'www.virustotal.com (scan requests)\n' : '') +
+            (credentialMode === 'vtai' ? 'ai.virustotal.com (scan requests)\n' : '') +
+            'registry.npmjs.org + clawhub.ai — only when the user explicitly invokes vt_sentinel_update.',
+    });
+    baseline.push({
+        checkId: 'vt-sentinel.auto-scan',
+        severity: 'info',
+        title: `Auto-scan: ${config.autoScan ? 'enabled' : 'disabled'}`,
+        detail: config.autoScan
+            ? `Watching ${watchDirs.length} director${watchDirs.length === 1 ? 'y' : 'ies'}. block mode: ${config.blockMode}. notify level: ${config.notifyLevel}.`
+            : `Active protection hooks remain registered (block mode: ${config.blockMode}) but no background watcher is running.`,
+    });
+    baseline.push({
+        checkId: 'vt-sentinel.upload-policies',
+        severity: 'info',
+        title: 'Upload policies',
+        detail: `sensitive (PDF/Office/unknown archives): ${config.sensitiveFilePolicy}\n` +
+            `semantic (SKILL.md, HOOK.md, AGENTS.md, etc.): ${config.semanticFilePolicy}\n` +
+            `preset: ${config.configPreset}, maxFileSizeMb: ${config.maxFileSizeMb}`,
+    });
+    baseline.push({
+        checkId: 'vt-sentinel.state-paths',
+        severity: 'info',
+        title: 'State and log file paths',
+        detail: `credentials: ${paths.credentialsFile} (0o600)\n` +
+            `runtime state: ${paths.stateFile}\n` +
+            `audit logs: ${paths.auditDir} (uploads.log, detections.log, target 0o600)`,
+    });
+    baseline.push({
+        checkId: 'vt-sentinel.identity-metadata',
+        severity: 'info',
+        title: `VTAI identity metadata: ${identity.metadataMode}`,
+        detail: `displayName set: ${identity.displayNameSet}\n` +
+            `humanAlias set: ${identity.humanAliasSet}\n` +
+            `bio set: ${identity.bioSet}\n` +
+            `contactEmail set: ${identity.contactEmailSet}` +
+            (identity.publicHandle ? `\npublic handle: ${identity.publicHandle}` : ''),
+    });
+    // --- Risk flags (warnings) ---
+    if (credentialMode === 'none') {
+        risks.push({
+            checkId: 'vt-sentinel.no-credentials',
+            severity: 'warn',
+            title: 'No active VirusTotal credentials',
+            detail: 'The plugin is loaded but cannot run scans until credentials are configured or VTAI auto-registration succeeds.',
+            remediation: 'Either invoke any scan tool to trigger VTAI auto-registration, or set plugins.entries.openclaw-plugin-vt-sentinel.config.apiKey via `openclaw config set`.',
+        });
+    }
+    if (config.sensitiveFilePolicy === 'always_upload') {
+        risks.push({
+            checkId: 'vt-sentinel.always-upload-sensitive',
+            severity: 'warn',
+            title: 'Sensitive files auto-uploaded without consent',
+            detail: 'sensitiveFilePolicy=always_upload means PDFs, Office docs, and unknown archives are sent to VirusTotal with no per-file prompt.',
+            remediation: 'Switch to `ask`, `ask_once`, or `hash_only` via vt_sentinel_configure.',
+        });
+    }
+    if (config.semanticFilePolicy === 'always_upload') {
+        risks.push({
+            checkId: 'vt-sentinel.always-upload-semantic',
+            severity: 'warn',
+            title: 'Instruction files auto-uploaded without consent',
+            detail: 'semanticFilePolicy=always_upload means SKILL.md, HOOK.md, AGENTS.md, etc. are sent to VirusTotal with no per-file prompt. These often contain private operational data.',
+            remediation: 'Switch to `hash_only` (recommended default) or `ask` via vt_sentinel_configure.',
+        });
+    }
+    const broadDirs = watchDirs.filter(isBroadWatchDir);
+    if (broadDirs.length > 0) {
+        risks.push({
+            checkId: 'vt-sentinel.broad-watch-dirs',
+            severity: 'warn',
+            title: 'Very broad directory under watch',
+            detail: `Watching: ${broadDirs.join(', ')}. A root-level or whole-profile watcher can generate noisy scan traffic and increases the blast radius of upload policies.`,
+            remediation: 'Narrow watchDirs to specific project / download folders via vt_sentinel_configure.',
+        });
+    }
+    if (config.agentContactEmail) {
+        risks.push({
+            checkId: 'vt-sentinel.contact-email-shared',
+            severity: 'warn',
+            title: 'Contact email shared with VTAI',
+            detail: 'agentContactEmail is set, so the address is sent to VTAI on agent registration. This is your choice but worth surfacing explicitly.',
+            remediation: 'Remove agentContactEmail from config if you prefer no PII in the VTAI registration.',
+        });
+    }
+    if (!config.autoScan && config.blockMode === 'quarantine') {
+        risks.push({
+            checkId: 'vt-sentinel.passive-with-quarantine',
+            severity: 'warn',
+            title: 'Quarantine mode active without auto-scan',
+            detail: 'blockMode=quarantine will isolate files matched by the blocklist, but autoScan=false means new files are not proactively scanned. Threats not yet in the blocklist will not be caught.',
+            remediation: 'Either enable autoScan or switch blockMode to `log_only`/`block_only` to align the posture.',
+        });
+    }
+    if (logModes) {
+        const nonPrivate = [];
+        if (logModes.credentialsFile.exists && !logModes.credentialsFile.ownerPrivate)
+            nonPrivate.push(`credentials (${logModes.credentialsFile.mode})`);
+        if (logModes.stateFile.exists && !logModes.stateFile.ownerPrivate)
+            nonPrivate.push(`state (${logModes.stateFile.mode})`);
+        if (logModes.uploadsLog.exists && !logModes.uploadsLog.ownerPrivate)
+            nonPrivate.push(`uploads.log (${logModes.uploadsLog.mode})`);
+        if (logModes.detectionsLog.exists && !logModes.detectionsLog.ownerPrivate)
+            nonPrivate.push(`detections.log (${logModes.detectionsLog.mode})`);
+        if (logModes.auditDir.exists && !logModes.auditDir.ownerPrivate)
+            nonPrivate.push(`audit dir (${logModes.auditDir.mode})`);
+        if (nonPrivate.length > 0) {
+            risks.push({
+                checkId: 'vt-sentinel.logs-not-private',
+                severity: 'warn',
+                title: 'State or log files are not owner-private',
+                detail: `The following files permit group/other read: ${nonPrivate.join(', ')}. Credentials and detection history should be 0o600 (files) / 0o700 (dirs).`,
+                remediation: 'On POSIX, run `chmod 600` on the files and `chmod 700` on the audit dir. New files created by this plugin (v0.12.0+) are already 0o600 on creation.',
+            });
+        }
+    }
+    return {
+        credentialMode,
+        endpoints: {
+            virustotal: credentialMode === 'user_key',
+            virustotalAi: credentialMode === 'vtai',
+            npm: 'on-demand-only',
+            clawhub: 'on-demand-only',
+        },
+        policies: {
+            autoScan: config.autoScan,
+            sensitiveFilePolicy: config.sensitiveFilePolicy,
+            semanticFilePolicy: config.semanticFilePolicy,
+            blockMode: config.blockMode,
+            notifyLevel: config.notifyLevel,
+            preset: config.configPreset,
+            maxFileSizeMb: config.maxFileSizeMb,
+            showCleanScanLogs: config.showCleanScanLogs,
+        },
+        watchDirs: [...watchDirs],
+        excludeDirs: [...(config.excludeDirs ?? [])],
+        excludeGlobs: [...(config.excludeGlobs ?? [])],
+        paths,
+        identity,
+        logModes,
+        baseline,
+        risks,
+    };
+}

package/dist/index.d.ts

@@ -40,6 +40,25 @@ interface PluginApi {
     }) => void;
     registerHook?: (events: string | string[], handler: (event: any) => Promise<any>, opts?: object) => void;
     onToolResult?: (handler: (event: any) => Promise<any>) => void;
+    registerSecurityAuditCollector?: (collector: (ctx: {
+        config: any;
+        sourceConfig: any;
+        env: NodeJS.ProcessEnv;
+        stateDir: string;
+        configPath: string;
+    }) => Array<{
+        checkId: string;
+        severity: 'info' | 'warn' | 'critical';
+        title: string;
+        detail: string;
+        remediation?: string;
+    }> | Promise<Array<{
+        checkId: string;
+        severity: 'info' | 'warn' | 'critical';
+        title: string;
+        detail: string;
+        remediation?: string;
+    }>>) => void;
 }
 /**
  * Simple semver comparison: returns true if `latest` is newer than `current`.

package/dist/index.js

@@ -52,6 +52,7 @@ const vt_api_1 = require("./vt-api");
 const env_access_1 = require("./env-access");
 const version_1 = require("./version");
 const update_commands_1 = require("./update-commands");
+const compliance_snapshot_1 = require("./compliance-snapshot");
 const audit_log_1 = require("./audit-log");
 const config_manager_1 = require("./config-manager");
 const state_store_1 = require("./state-store");
@@ -354,9 +355,11 @@ function vtSentinelPlugin(api) {
         return true;
     };
     // --- Audit logs: rotating logs for uploads and detections ---
-    const logDir = (0, audit_log_1.getLogDir)();
-    const uploadLog = new audit_log_1.AuditLog(path.join(logDir, 'vt-sentinel-uploads.log'));
-    const detectionLog = new audit_log_1.AuditLog(path.join(logDir, 'vt-sentinel-detections.log'));
+    // v0.12.0: logs live in <stateDir>/vt-sentinel-audit/ (subdir at 0o700,
+    // files pre-created at 0o600 — see src/audit-log.ts for the hardening).
+    const logDir = (0, audit_log_1.getLogDir)(resolvedStateDir);
+    const uploadLog = new audit_log_1.AuditLog(path.join(logDir, 'uploads.log'));
+    const detectionLog = new audit_log_1.AuditLog(path.join(logDir, 'detections.log'));
     /** Log a scan result to the appropriate audit log(s). */
     const auditResult = (result) => {
         if (!result.sha256)
@@ -737,6 +740,50 @@ function vtSentinelPlugin(api) {
             api.logger.info('[VT-Sentinel] Service stopped');
         },
     });
+    // --- Security audit collector (v0.12.0 transparency surface) ---
+    //
+    // Reports what VT Sentinel reads, writes, sends, and flags config that
+    // carries user-visible risk (auto-uploads, broad watchers, non-private
+    // state files, PII in VTAI identity, inconsistent block vs. scan posture).
+    // Surfaced via `openclaw security audit --deep --json`. All data is derived
+    // from the same `buildComplianceSnapshot(...)` helper that renders the
+    // Compliance block in `vt_sentinel_status`, so both views stay in sync.
+    if (typeof api.registerSecurityAuditCollector === 'function') {
+        api.registerSecurityAuditCollector((ctx) => {
+            try {
+                const mode = credentialMode === 'user_key' ? 'user_key' :
+                    credentialMode === 'vtai' ? 'vtai' : 'none';
+                const eff = configManager.getEffective();
+                // Use the audit context's stateDir when provided (it already
+                // honors profile overrides); fall back to our resolvedStateDir.
+                const sd = ctx.stateDir || resolvedStateDir;
+                const logModes = (0, compliance_snapshot_1.collectLogModes)(sd);
+                const snap = (0, compliance_snapshot_1.buildComplianceSnapshot)({
+                    config: eff,
+                    stateDir: sd,
+                    credentialMode: mode,
+                    watchDirs: [...watchRoots],
+                    agentPublicHandle: (0, vt_api_1.loadAgentCredentials)()?.publicHandle,
+                    logModes,
+                });
+                return [...snap.baseline, ...snap.risks].map(f => ({
+                    checkId: f.checkId,
+                    severity: f.severity,
+                    title: f.title,
+                    detail: f.detail,
+                    ...(f.remediation ? { remediation: f.remediation } : {}),
+                }));
+            }
+            catch (err) {
+                return [{
+                        checkId: 'vt-sentinel.audit-collector-error',
+                        severity: 'warn',
+                        title: 'VT Sentinel compliance snapshot failed to build',
+                        detail: `Collector threw while assembling audit findings: ${err?.message || String(err)}`,
+                    }];
+            }
+        });
+    }
     // --- Tool: vt_scan_file ---
     api.registerTool({
         name: 'vt_scan_file',
@@ -901,6 +948,18 @@ function vtSentinelPlugin(api) {
         parameters: { type: 'object', properties: {}, required: [] },
         execute: async (_ctx, _params) => {
             const eff = configManager.getEffective();
+            // Build the compliance snapshot from the same source used by the
+            // security audit collector, so the two views never drift.
+            const snapMode = credentialMode === 'user_key' ? 'user_key' :
+                credentialMode === 'vtai' ? 'vtai' : 'none';
+            const snap = (0, compliance_snapshot_1.buildComplianceSnapshot)({
+                config: eff,
+                stateDir: resolvedStateDir,
+                credentialMode: snapMode,
+                watchDirs: [...watchRoots],
+                agentPublicHandle: (0, vt_api_1.loadAgentCredentials)()?.publicHandle,
+                logModes: (0, compliance_snapshot_1.collectLogModes)(resolvedStateDir),
+            });
             return textResponse((0, status_renderer_1.renderStatus)({
                 version: (0, version_1.getCurrentVersion)(),
                 apiMode: credentialMode === 'vtai' ? 'vtai' : 'user_key',
@@ -918,6 +977,23 @@ function vtSentinelPlugin(api) {
                     metadataMode: eff.agentMetadataMode || 'minimal',
                     humanAlias: eff.agentHumanAlias,
                 },
+                compliance: {
+                    endpoints: snap.endpoints,
+                    credentialMode: snap.credentialMode,
+                    paths: {
+                        credentialsFile: snap.paths.credentialsFile,
+                        stateFile: snap.paths.stateFile,
+                        auditDir: snap.paths.auditDir,
+                    },
+                    identity: {
+                        displayNameSet: snap.identity.displayNameSet,
+                        humanAliasSet: snap.identity.humanAliasSet,
+                        bioSet: snap.identity.bioSet,
+                        contactEmailSet: snap.identity.contactEmailSet,
+                        metadataMode: snap.identity.metadataMode,
+                    },
+                    risks: snap.risks,
+                },
             }));
         },
     });

package/dist/status-renderer.d.ts

@@ -6,6 +6,32 @@ export declare function renderOnboarding(opts: {
     effectiveConfig: FullConfig;
     availableTools: string[];
 }): string;
+export interface ComplianceRenderBlock {
+    endpoints: {
+        virustotal: boolean;
+        virustotalAi: boolean;
+    };
+    credentialMode: 'user_key' | 'vtai' | 'none';
+    paths: {
+        credentialsFile: string;
+        stateFile: string;
+        auditDir: string;
+    };
+    identity: {
+        displayNameSet: boolean;
+        humanAliasSet: boolean;
+        bioSet: boolean;
+        contactEmailSet: boolean;
+        metadataMode: string;
+    };
+    risks: Array<{
+        checkId: string;
+        severity: string;
+        title: string;
+        detail: string;
+        remediation?: string;
+    }>;
+}
 export declare function renderStatus(opts: {
     version: string;
     apiMode: 'user_key' | 'vtai';
@@ -23,6 +49,7 @@ export declare function renderStatus(opts: {
         metadataMode: string;
         humanAlias?: string;
     };
+    compliance?: ComplianceRenderBlock;
 }): string;
 export declare function renderPolicyMatrix(config: FullConfig): string;
 export declare function renderHelp(): string;

package/dist/status-renderer.js

@@ -33,7 +33,6 @@ function renderOnboarding(opts) {
     lines.push('Run vt_sentinel_status for full status. Run vt_sentinel_help for usage guide.');
     return lines.join('\n');
 }
-// --- Status ---
 function renderStatus(opts) {
     const lines = [];
     const cfg = opts.effectiveConfig;
@@ -95,6 +94,39 @@ function renderStatus(opts) {
     lines.push('Runtime State:');
     lines.push(`  Blocked files: ${opts.blockedFileCount}`);
     lines.push('');
+    // Compliance / Data Flow (v0.12.0+)
+    if (opts.compliance) {
+        const c = opts.compliance;
+        lines.push('Compliance / Data Flow:');
+        const endpoints = [];
+        if (c.endpoints.virustotal)
+            endpoints.push('www.virustotal.com');
+        if (c.endpoints.virustotalAi)
+            endpoints.push('ai.virustotal.com');
+        lines.push(`  Network (live): ${endpoints.length ? endpoints.join(', ') : '(none — scanner not configured)'}`);
+        lines.push(`  Network (on-demand only): registry.npmjs.org, clawhub.ai (via vt_sentinel_update)`);
+        lines.push(`  Credential mode: ${c.credentialMode}`);
+        lines.push(`  Credentials file: ${c.paths.credentialsFile} (target 0o600)`);
+        lines.push(`  Runtime state file: ${c.paths.stateFile}`);
+        lines.push(`  Audit logs dir: ${c.paths.auditDir} (target 0o700; uploads.log + detections.log at 0o600)`);
+        lines.push(`  VTAI identity metadata sent: ${c.identity.metadataMode}` +
+            ` (displayName=${c.identity.displayNameSet ? 'set' : 'none'},` +
+            ` humanAlias=${c.identity.humanAliasSet ? 'set' : 'none'},` +
+            ` bio=${c.identity.bioSet ? 'set' : 'none'},` +
+            ` email=${c.identity.contactEmailSet ? 'set' : 'none'})`);
+        if (c.risks.length === 0) {
+            lines.push('  Risk flags: none');
+        }
+        else {
+            lines.push(`  Risk flags (${c.risks.length}):`);
+            for (const r of c.risks) {
+                lines.push(`    [${r.severity}] ${r.title}`);
+                if (r.remediation)
+                    lines.push(`       → ${r.remediation}`);
+            }
+        }
+        lines.push('');
+    }
     // How to change
     lines.push('To change config: use vt_sentinel_configure tool');
     lines.push('To reset: use vt_sentinel_reset_policy tool');

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "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.3",
+  "version": "0.12.0",
   "skills": ["./skills"],
   "contracts": {
     "tools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-plugin-vt-sentinel",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "displayName": "VT Sentinel",
   "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
   "main": "dist/index.js",
@@ -51,9 +51,9 @@
     "dist/env-access.*",
     "dist/version.*",
     "dist/update-commands.*",
+    "dist/compliance-snapshot.*",
     "dist/signatures/**/*.json",
     "skills/",
-    "hooks/",
     "openclaw.plugin.json"
   ],
   "openclaw": {

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

@@ -1,33 +0,0 @@
----
-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.
-
-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
-- `> /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

@@ -1,174 +0,0 @@
-/**
- * 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, ConfigManager, matchGlob, isSelfPath, StateStore;
-
-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;
-    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 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, eff, staticConfig) {
-    const userKey = staticConfig && typeof staticConfig.apiKey === 'string' && staticConfig.apiKey.trim().length > 0
-        ? staticConfig.apiKey.trim()
-        : null;
-
-    if (userKey) {
-        return new Scanner(userKey, logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, false, eff.semanticFilePolicy);
-    }
-
-    // Try VTAI cached credentials
-    if (loadAgentCredentials) {
-        try {
-            const creds = loadAgentCredentials();
-            if (creds) {
-                return new Scanner(creds.agentToken, logger, eff.maxFileSizeMb, eff.sensitiveFilePolicy, true, eff.semanticFilePolicy);
-            }
-        } 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;
-
-    // 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, eff, staticConfig);
-    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) {
-        // 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 {
-            // 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` +
-                    `${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;