openclaw-plugin-vt-sentinel 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to `openclaw-plugin-vt-sentinel`.
 
+## 0.12.2 — Audit collector accuracy + legacy log sanitization
+
+Small follow-up to 0.12.1. The static collector could only see
+user-configured watch dirs (never the runtime auto-derived ones like
+`/tmp`, `~/Downloads`, OpenClaw state subdirs), so its auto-scan finding
+read "Watching 0 directories" on fresh installs — technically correct but
+misleading to operators.
+
+### Fixed
+
+- **Auto-scan finding text reflects the snapshot source.** The
+  `buildComplianceSnapshot` helper now accepts `source: 'runtime' | 'static'`.
+  Runtime (gateway) callers still report the live watcher list.
+  Static (CLI audit) callers now spell out that additional dirs are
+  auto-derived by the gateway and point to `vt_sentinel_status` for the
+  live list.
+- **Legacy audit-log paths mentioned in `vt_sentinel_help` updated.** The
+  help text used to say `~/.openclaw/vt-sentinel-uploads.log` and
+  `vt-sentinel-detections.log`; since 0.12.0 they live in
+  `<stateDir>/vt-sentinel-audit/{uploads,detections}.log`.
+- **Legacy log files tightened to `0o600` on plugin load.** Pre-0.12.0
+  installs left the old stateDir-root log files (`vt-sentinel-uploads.log`,
+  `vt-sentinel-detections.log`) at the process default (typically `0o664`).
+  On each gateway start the plugin now best-effort `chmod 0o600`s them and
+  logs the change. POSIX-only; no-op on Windows.
+- **`package-lock.json` regenerated to the new version** — the shipped
+  tarball never included it, but a stale lock on disk caused confusion.
+
+## 0.12.1 — Security audit collector: dual-path wiring
+
+Fix for the collector introduced in 0.12.0. The in-gateway registration via
+`api.registerSecurityAuditCollector` was insufficient: `openclaw security audit
+--deep` runs in a fresh Node process that doesn't share state with the gateway
+and reads collectors from the plugin's **module-level** `securityAuditCollectors`
+field instead. Verified empirically on the production Linux VM (OpenClaw
+2026.4.12): 0.12.0 shipped with a runtime-only collector that emitted zero
+`vt-sentinel.*` findings under `openclaw security audit --deep --json`.
+
+### Fixed
+
+- **`securityAuditCollectors` declared at module level.** The default export
+  is now a plugin-definition object: `{ id, name, register, securityAuditCollectors }`.
+  The CLI audit picks up the collector from the object's field; the gateway
+  still registers it at runtime via `api.registerSecurityAuditCollector` for
+  any in-process audit surface that uses `getActivePluginRegistry()`. Both
+  paths now light up.
+- **`vtSentinelAuditCollector` is self-contained.** It rebuilds the
+  compliance snapshot exclusively from `ctx.config`, `ctx.stateDir`, and
+  `ctx.configPath` — no closure state, no shared-module variables. Usable
+  from a cold-loaded plugin metadata snapshot.
+- Runtime behavior (scanning, hooks, policies) unchanged.
+
 ## 0.12.0 — Transparency surface + log hygiene
 
 **Headline:** what VT Sentinel does at runtime is now auditable from two

package/dist/compliance-snapshot.d.ts

@@ -39,6 +39,16 @@ export interface ComplianceSnapshotInput {
     agentPublicHandle?: string;
     /** Optional: pre-collected log permission info (see `collectLogModes`). */
     logModes?: LogModesInfo;
+    /**
+     * Where the snapshot is being built from. `runtime` means the gateway is
+     * running and `watchDirs` reflects the live watcher state (including
+     * auto-derived dirs like `/tmp`, `~/Downloads`, OpenClaw state subdirs).
+     * `static` means the snapshot is being built by a fresh CLI process
+     * (e.g. `openclaw security audit --deep`) that cannot see auto-derived
+     * dirs — only the user-configured `config.watchDirs` entries.
+     * Defaults to `static`.
+     */
+    source?: 'runtime' | 'static';
 }
 export interface ComplianceSnapshot {
     credentialMode: CredentialMode;
@@ -103,3 +113,16 @@ export declare function collectLogModes(stateDir: string): LogModesInfo;
  * first and pass the result as `input.logModes`.
  */
 export declare function buildComplianceSnapshot(input: ComplianceSnapshotInput): ComplianceSnapshot;
+interface AuditCollectorCtx {
+    config: any;
+    sourceConfig: any;
+    env: NodeJS.ProcessEnv;
+    stateDir: string;
+    configPath: string;
+}
+/**
+ * Static security-audit collector. Pass this to OpenClaw via the plugin's
+ * module-level default export (`securityAuditCollectors: [vtSentinelAuditCollector]`).
+ */
+export declare function vtSentinelAuditCollector(ctx: AuditCollectorCtx): AuditFinding[];
+export {};

package/dist/compliance-snapshot.js

@@ -53,8 +53,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.computePaths = computePaths;
 exports.collectLogModes = collectLogModes;
 exports.buildComplianceSnapshot = buildComplianceSnapshot;
+exports.vtSentinelAuditCollector = vtSentinelAuditCollector;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const config_manager_1 = require("./config-manager");
 // --- Core paths helper (pure) ---
 function computePaths(stateDir) {
     const auditDir = path.join(stateDir, 'vt-sentinel-audit');
@@ -131,6 +133,7 @@ function isBroadWatchDir(dir) {
  */
 function buildComplianceSnapshot(input) {
     const { config, stateDir, credentialMode, watchDirs, agentPublicHandle, logModes } = input;
+    const source = input.source ?? 'static';
     const paths = computePaths(stateDir);
     const identity = {
         displayNameSet: !!config.agentDisplayName,
@@ -161,13 +164,34 @@ function buildComplianceSnapshot(input) {
             (credentialMode === 'vtai' ? 'ai.virustotal.com (scan requests)\n' : '') +
             'registry.npmjs.org + clawhub.ai — only when the user explicitly invokes vt_sentinel_update.',
     });
+    // Auto-scan finding. Detail text branches on (a) whether autoScan is on
+    // and (b) whether we're building the snapshot at runtime (live watcher
+    // list available) or statically (CLI audit process — only config.watchDirs
+    // is visible; auto-derived dirs like /tmp/Downloads/Desktop/OpenClaw state
+    // subdirs are computed by the gateway at runtime and cannot be recovered
+    // here).
+    const autoScanDetail = (() => {
+        if (!config.autoScan) {
+            return `Active protection hooks remain registered (block mode: ${config.blockMode}) but no background watcher is running.`;
+        }
+        const suffix = ` block mode: ${config.blockMode}. notify level: ${config.notifyLevel}.`;
+        if (source === 'runtime') {
+            return `Watching ${watchDirs.length} director${watchDirs.length === 1 ? 'y' : 'ies'}.${suffix}`;
+        }
+        // Static/CLI snapshot.
+        if (watchDirs.length > 0) {
+            return `User-configured watch dirs (${watchDirs.length}): ${watchDirs.join(', ')}. ` +
+                `Additional dirs auto-derived at gateway runtime (OS temp, ~/Downloads, ~/Desktop, OpenClaw state subdirs, workspace). ` +
+                `Run vt_sentinel_status inside the gateway for the live list.${suffix}`;
+        }
+        return `No user-configured watch dirs. At runtime the gateway auto-derives monitors from OS temp, ~/Downloads, ~/Desktop, and the OpenClaw state subdirs (skills, extensions, hooks, workspace). ` +
+            `Run vt_sentinel_status inside the gateway for the live list.${suffix}`;
+    })();
     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.`,
+        detail: autoScanDetail,
     });
     baseline.push({
         checkId: 'vt-sentinel.upload-policies',
@@ -301,3 +325,80 @@ function buildComplianceSnapshot(input) {
         risks,
     };
 }
+// --- Static (module-level) security audit collector ---
+//
+// The OpenClaw `security audit --deep` CLI runs in a fresh process that
+// does NOT share state with the gateway. It therefore reads
+// `securityAuditCollectors` from the plugin's module-level definition, NOT
+// from runtime `api.registerSecurityAuditCollector(...)` calls.
+//
+// This function is the canonical collector used by the CLI. It derives the
+// same snapshot as the gateway-side collector, but exclusively from the
+// audit context (ctx.config, ctx.stateDir, ctx.configPath) — no closure
+// state, no cross-module shared variables. Everything is reconstructable
+// from what the CLI hands us.
+//
+// Differences from the gateway-side invocation:
+//   - `watchDirs` only includes user-configured dirs (`cfg.watchDirs`); the
+//     auto-derived dirs (tmp, ~/Downloads, etc.) are a runtime concept.
+//   - `credentialMode` is inferred from (a) presence of `cfg.apiKey` and
+//     (b) presence of the persisted agent credentials file on disk.
+const PLUGIN_ID = 'openclaw-plugin-vt-sentinel';
+function extractPluginConfig(cfg) {
+    try {
+        return cfg?.plugins?.entries?.[PLUGIN_ID]?.config ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function readAgentPublicHandle(stateDir) {
+    try {
+        const raw = fs.readFileSync(path.join(stateDir, 'vt-sentinel-agent.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed?.publicHandle === 'string' ? parsed.publicHandle : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function credentialsFileExists(stateDir) {
+    try {
+        return fs.statSync(path.join(stateDir, 'vt-sentinel-agent.json')).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Static security-audit collector. Pass this to OpenClaw via the plugin's
+ * module-level default export (`securityAuditCollectors: [vtSentinelAuditCollector]`).
+ */
+function vtSentinelAuditCollector(ctx) {
+    try {
+        const staticCfg = extractPluginConfig(ctx.config) ?? extractPluginConfig(ctx.sourceConfig);
+        const cm = new config_manager_1.ConfigManager(staticCfg);
+        const eff = cm.getEffective();
+        const hasUserKey = typeof staticCfg?.['apiKey'] === 'string' && staticCfg['apiKey'].trim().length > 0;
+        const hasCachedVtai = credentialsFileExists(ctx.stateDir);
+        const credentialMode = hasUserKey ? 'user_key' : (hasCachedVtai ? 'vtai' : 'none');
+        const watchDirs = Array.isArray(eff.watchDirs) ? [...eff.watchDirs] : [];
+        const snap = buildComplianceSnapshot({
+            config: eff,
+            stateDir: ctx.stateDir,
+            credentialMode,
+            watchDirs,
+            agentPublicHandle: readAgentPublicHandle(ctx.stateDir),
+            logModes: collectLogModes(ctx.stateDir),
+        });
+        return [...snap.baseline, ...snap.risks];
+    }
+    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)}`,
+            }];
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { SensitiveFilePolicy } from './scanner';
 import { getCurrentVersion } from './version';
 import { generateUpdateCommands } from './update-commands';
+import { vtSentinelAuditCollector } from './compliance-snapshot';
 interface VTSentinelConfig {
     apiKey?: string;
     watchDirs?: string[];
@@ -77,10 +78,34 @@ declare function buildEnhancedBio(eff: {
     configPreset?: string;
     autoScan?: boolean;
 }): string;
-export default function vtSentinelPlugin(api: PluginApi): void;
+declare function vtSentinelPlugin(api: PluginApi): void;
 export declare const _generateUpdateCommands: typeof generateUpdateCommands;
 export declare const _fetchLatestVersion: typeof fetchLatestVersion;
 export declare const _getCurrentVersion: typeof getCurrentVersion;
 export declare const _generateAgentName: typeof generateAgentName;
 export declare const _buildEnhancedBio: typeof buildEnhancedBio;
-export {};
+/**
+ * Module-level plugin definition.
+ *
+ * `register(api)` runs inside the gateway — it's where the plugin wires up
+ * tools, hooks, the service, the runtime security-audit collector, and
+ * everything else that needs access to the live gateway API.
+ *
+ * `securityAuditCollectors` is read by `openclaw security audit --deep` in
+ * a FRESH Node process that does NOT share state with the gateway. That
+ * collector (`vtSentinelAuditCollector`) is self-contained: it rebuilds the
+ * compliance snapshot from ctx alone. Keeping it at module level is how
+ * plugin-declared findings land in `security audit` output.
+ *
+ * The dual-path wiring (runtime via `api.registerSecurityAuditCollector`
+ * inside `register`, static via `securityAuditCollectors` here) lets both
+ * the in-gateway audit flow and the out-of-process CLI flow surface the
+ * same data.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    register: typeof vtSentinelPlugin;
+    securityAuditCollectors: (typeof vtSentinelAuditCollector)[];
+};
+export default _default;

package/dist/index.js

@@ -39,7 +39,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports._buildEnhancedBio = exports._generateAgentName = exports._getCurrentVersion = exports._fetchLatestVersion = exports._generateUpdateCommands = void 0;
 exports.isNewerVersion = isNewerVersion;
 exports.isSelfPath = isSelfPath;
-exports.default = vtSentinelPlugin;
 const axios_1 = __importDefault(require("axios"));
 const chokidar = __importStar(require("chokidar"));
 const fs = __importStar(require("fs"));
@@ -360,6 +359,26 @@ function vtSentinelPlugin(api) {
     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'));
+    // v0.12.2: pre-0.12.0 installs left `vt-sentinel-uploads.log` and
+    // `vt-sentinel-detections.log` at the stateDir root with the process
+    // umask (typically 0o664). Upgrading doesn't rewrite them. Best-effort
+    // tighten-to-0o600 on load so operators who upgraded in place don't
+    // keep world-readable audit history. POSIX-only — no-op on Windows.
+    if (process.platform !== 'win32') {
+        for (const legacyName of ['vt-sentinel-uploads.log', 'vt-sentinel-detections.log']) {
+            const legacyPath = path.join(resolvedStateDir, legacyName);
+            try {
+                if (fs.existsSync(legacyPath)) {
+                    const mode = fs.statSync(legacyPath).mode & 0o777;
+                    if (mode !== 0o600) {
+                        fs.chmodSync(legacyPath, 0o600);
+                        api.logger.info(`[VT-Sentinel] Tightened permissions on legacy audit log ${legacyPath} (0o${mode.toString(8)} → 0o600)`);
+                    }
+                }
+            }
+            catch { /* best-effort */ }
+        }
+    }
     /** Log a scan result to the appropriate audit log(s). */
     const auditResult = (result) => {
         if (!result.sha256)
@@ -765,6 +784,7 @@ function vtSentinelPlugin(api) {
                     watchDirs: [...watchRoots],
                     agentPublicHandle: (0, vt_api_1.loadAgentCredentials)()?.publicHandle,
                     logModes,
+                    source: 'runtime',
                 });
                 return [...snap.baseline, ...snap.risks].map(f => ({
                     checkId: f.checkId,
@@ -959,6 +979,7 @@ function vtSentinelPlugin(api) {
                 watchDirs: [...watchRoots],
                 agentPublicHandle: (0, vt_api_1.loadAgentCredentials)()?.publicHandle,
                 logModes: (0, compliance_snapshot_1.collectLogModes)(resolvedStateDir),
+                source: 'runtime',
             });
             return textResponse((0, status_renderer_1.renderStatus)({
                 version: (0, version_1.getCurrentVersion)(),
@@ -1612,3 +1633,27 @@ exports._fetchLatestVersion = fetchLatestVersion;
 exports._getCurrentVersion = version_1.getCurrentVersion;
 exports._generateAgentName = generateAgentName;
 exports._buildEnhancedBio = buildEnhancedBio;
+/**
+ * Module-level plugin definition.
+ *
+ * `register(api)` runs inside the gateway — it's where the plugin wires up
+ * tools, hooks, the service, the runtime security-audit collector, and
+ * everything else that needs access to the live gateway API.
+ *
+ * `securityAuditCollectors` is read by `openclaw security audit --deep` in
+ * a FRESH Node process that does NOT share state with the gateway. That
+ * collector (`vtSentinelAuditCollector`) is self-contained: it rebuilds the
+ * compliance snapshot from ctx alone. Keeping it at module level is how
+ * plugin-declared findings land in `security audit` output.
+ *
+ * The dual-path wiring (runtime via `api.registerSecurityAuditCollector`
+ * inside `register`, static via `securityAuditCollectors` here) lets both
+ * the in-gateway audit flow and the out-of-process CLI flow surface the
+ * same data.
+ */
+exports.default = {
+    id: 'openclaw-plugin-vt-sentinel',
+    name: 'VT Sentinel',
+    register: vtSentinelPlugin,
+    securityAuditCollectors: [compliance_snapshot_1.vtSentinelAuditCollector],
+};

package/dist/status-renderer.js

@@ -224,7 +224,7 @@ function renderHelp() {
     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('  - autoScan=false disables hook scanning (active blocking remains on).');
-    lines.push('  - Audit logs: ~/.openclaw/vt-sentinel-uploads.log + vt-sentinel-detections.log');
+    lines.push('  - Audit logs: <stateDir>/vt-sentinel-audit/uploads.log + detections.log (rotating; dir 0o700, files 0o600).');
     return lines.join('\n');
 }
 // --- Config Change Result ---

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.12.0",
+  "version": "0.12.2",
   "skills": ["./skills"],
   "contracts": {
     "tools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-plugin-vt-sentinel",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "displayName": "VT Sentinel",
   "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
   "main": "dist/index.js",