openclaw-plugin-vt-sentinel 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 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
+static scanner lands at `status: clean`.
+
+### Fixed
+
+- **`vt_sentinel_update` tool moved to its own module.** The bash snippet
+  that this tool prints to the user (for the rare "pinned install" fallback
+  upgrade path) mentions file-I/O primitives by name as plain text. When
+  that template literal lived in `dist/index.js` — which also carries the
+  outbound HTTP calls — ClawHub's static scanner flagged the pair as
+  `potential_exfiltration`. The template now lives in `src/update-commands.ts`
+  alongside no network code.
+
 ## 0.11.2 — ClawHub static-scan hygiene
 
 Runtime behavior identical to 0.11.1. This release only reshapes file

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;