openclaw-plugin-vt-sentinel 0.12.2 → 0.12.3

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to `openclaw-plugin-vt-sentinel`.
 
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## 0.12.3 — Dependency hygiene + OSS polish
+
+No runtime behavior changes. Pure housekeeping release.
+
+### Security
+
+- Bumped `axios` past GHSA-3p68-rc4w-qgx5 and GHSA-fvcv-3m26-pcqx (critical).
+- Bumped `follow-redirects` past GHSA-r4q5-vmmm-2653 (moderate, header leak
+  on cross-domain redirects).
+- Bumped `picomatch` past GHSA-3v7f-55p6-f55p and GHSA-c2c7-rcm5-vvqj
+  (high, method injection + ReDoS).
+- `npm audit --package-lock-only` now reports `found 0 vulnerabilities`.
+
+### Added
+
+- `LICENSE` (MIT).
+- `SECURITY.md` with private vulnerability reporting process.
+- `CONTRIBUTING.md` with build/test/release workflow.
+- `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1).
+- `engines.node` declaration (`">=18"`) in `package.json`.
+
+### Changed
+
+- `package.json`: corrected `homepage` to point at the repository (was
+  pointing at the VTAI backend service), added `author` and refreshed
+  `openclaw.build.openclawVersion`.
+- `README.md`: fixed a stale reference to the ClawHub host.
+- Changelog now follows Keep a Changelog headings.
+
 ## 0.12.2 — Audit collector accuracy + legacy log sanitization
 
 Small follow-up to 0.12.1. The static collector could only see
@@ -36,8 +68,8 @@ 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
+field instead. Verified on an integration environment (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
@@ -105,16 +137,16 @@ Both views are rendered from the same snapshot function, so they can't drift.
   runtime path is sufficient. One authoritative source, half the
   maintenance surface.
 
-### Internal
+### Implementation notes
 
 - `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.
+  of the pure-helper pattern applied across the codebase.
 
 ### Deferred
 
-- **Migration to `definePluginEntry`.** Verified empirically on the Linux
-  production VM (OpenClaw 2026.4.12): `require('openclaw/plugin-sdk/core')`
+- **Migration to `definePluginEntry`.** Verified empirically on OpenClaw
+  2026.4.12 integration: `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
@@ -307,7 +339,7 @@ scan, which requires no key. Both paths are fully supported.
 
 ## Earlier history
 
-See git log and `memory/v27-bugfixes.md` for details on 0.5.0 through 0.10.0.
+See git log for details on 0.5.0 through 0.10.0.
 Highlights:
 
 - **0.10.0** — SEMANTIC_RISK files (SKILL.md, HOOK.md, AGENTS.md) route

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,53 @@
+# Contributor Code of Conduct
+
+This project follows the
+[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+this project a harassment-free experience for everyone, regardless of age,
+body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation. We pledge to act and interact in ways that contribute to an
+open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility, apologizing to those affected by our mistakes,
+  and learning from the experience.
+- Focusing on what is best for the overall community.
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+  of any kind.
+- Trolling, insulting or derogatory comments, and personal or political
+  attacks.
+- Public or private harassment.
+- Publishing others' private information without their explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting.
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer via the contact method on
+`https://github.com/king-tero`. All complaints will be reviewed and
+investigated promptly and fairly.
+
+Community Impact Guidelines:
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines>

package/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thanks for your interest in VT Sentinel. This guide covers the basics for
+reporting issues, submitting patches, and building the plugin locally.
+
+## Reporting issues
+
+- Non-security bugs and feature requests: open a GitHub issue.
+- Security vulnerabilities: see [`SECURITY.md`](./SECURITY.md).
+
+When filing a bug, please include:
+
+- VT Sentinel version (`openclaw plugins inspect openclaw-plugin-vt-sentinel`).
+- OpenClaw version (`openclaw --version`).
+- OS and Node.js version.
+- The output of `openclaw security audit --deep --json` filtered to
+  `vt-sentinel.*` findings, if relevant.
+
+## Building locally
+
+Requirements: Node.js >= 18, npm, TypeScript.
+
+```bash
+git clone https://github.com/king-tero/VT-sentinel.git
+cd VT-sentinel
+npm install
+npm run build
+npm test
+npm run scan
+```
+
+`npm run scan` runs a local re-implementation of OpenClaw's install-security
+scanner against the compiled `dist/`. A clean baseline is `0 critical, 0 warn`.
+CI blocks on any finding.
+
+## Code style
+
+- TypeScript `strict`.
+- No inline first-person narrative in comments (use neutral phrasing).
+- No references to coding assistants or editors.
+- Defensive threat-detection regex literals belong in
+  `src/signatures/*.json`, not in `.ts` source — so static scanners do not
+  mistake detection patterns for malicious code.
+- Prefer host-runtime helpers (`api.runtime.*`) over direct environment
+  reads. Any residual `process.env` usage must live in a module with no
+  HTTP-client imports, to avoid tripping the install-security scanner's
+  env-harvesting rule.
+
+## Pull requests
+
+- One logical change per PR.
+- Update `CHANGELOG.md` under an `Unreleased` section if the change is user
+  visible.
+- `npm test` and `npm run scan` must pass.
+
+## Release process (maintainers)
+
+1. Bump `version` in `package.json` and `openclaw.plugin.json`.
+2. Add a `CHANGELOG.md` entry.
+3. `npm run build && npm test && npm run scan`.
+4. `npm publish`.
+5. Publish to ClawHub with `--source-commit <new commit SHA> --source-ref vX.Y.Z`.
+6. Tag the release in git: `git tag vX.Y.Z && git push --tags`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 king-tero and VT Sentinel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -116,7 +116,7 @@ VT Sentinel connects to [VTAI](https://ai.virustotal.com) — VirusTotal's LLM-o
 
 File analysis includes:
 - **AV detections** from 60+ antivirus engines
-- **AI Code Insight** (Gemini-powered semantic analysis)
+- **AI Code Insight** (VirusTotal AI-powered semantic analysis)
 - **Crowdsourced AI results** from the VirusTotal community
 
 ## Privacy & compliance
@@ -124,7 +124,8 @@ File analysis includes:
 VT Sentinel is a security plugin, so transparency about what it reads, writes,
 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
+audit --deep` (via the plugin's `securityAuditCollector` — CLI audit support
+since v0.12.1), so
 you can verify the behavior from either surface without reading source.
 
 ### Data flow
@@ -155,7 +156,7 @@ 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
+  `ai.virustotal.com` (VTAI). `registry.npmjs.org` / `clawhub.ai` are
   contacted only when you explicitly invoke `vt_sentinel_update` — not on
   plugin load.
 - **No environment mutations:** the plugin never writes to `process.env`.

package/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest `0.12.x` release line receives security fixes. Earlier
+versions are unsupported; upgrade via ClawHub or npm.
+
+## Reporting a Vulnerability
+
+**Do not open a public issue for security reports.**
+
+Please report suspected vulnerabilities by email to the repository owner via
+the GitHub profile contact method (`https://github.com/king-tero`). Include:
+
+- A description of the vulnerability and its impact.
+- Reproduction steps or a minimal proof of concept.
+- Affected version(s).
+- Your preferred disclosure timeline, if any.
+
+You should receive an acknowledgement within 7 days. We aim to ship a fix
+and a coordinated advisory within 30 days for high-severity issues, faster
+when impact warrants it.
+
+## Scope
+
+In scope:
+
+- The plugin itself (`src/**`, `dist/**`).
+- The installer skill (`vt-sentinel-installer`).
+- Interactions with `virustotal.com` and `ai.virustotal.com` endpoints.
+
+Out of scope:
+
+- Vulnerabilities in upstream VirusTotal services (report to VirusTotal).
+- Vulnerabilities in OpenClaw itself (report to the OpenClaw project).
+- Social engineering or physical attacks.
+
+## Non-Vulnerabilities
+
+The following behaviors are intentional and not security issues:
+
+- Outbound HTTPS requests to `www.virustotal.com` / `ai.virustotal.com`.
+- Reading files under configured watch directories to classify and hash them.
+- Uploading files when consent has been granted (per the configured
+  `sensitiveFilePolicy` / `semanticFilePolicy`).
+- Storing a VTAI agent token on disk under `$OPENCLAW_STATE_DIR` with
+  mode `0o600`.
+
+## Hardening notes
+
+- Audit logs are created under `$OPENCLAW_STATE_DIR/vt-sentinel-audit/`
+  with the directory set to mode `0o700` and individual log files to `0o600`.
+- The plugin does not mutate `process.env`.
+- Threat-detection signatures live in JSON so that static scanners do not
+  confuse defensive patterns with malicious code.
+- Run `openclaw security audit --deep --json` to inspect what the plugin
+  reads, writes, and sends. A structured "compliance snapshot" is emitted.

package/dist/classifier.d.ts

@@ -39,7 +39,7 @@ export declare class FileClassifier {
     /**
      * Peek inside a ZIP file by reading its local file headers.
      * ZIP local file header: PK\x03\x04 ... filename at offset 30.
-     * We read enough to scan the first ~50 entries without full decompression.
+     * Reads enough bytes to scan the first ~50 entries without full decompression.
      *
      * Returns: 'skill' | 'executable' | 'office' | 'archive'
      */

package/dist/classifier.js

@@ -106,7 +106,7 @@ class FileClassifier {
     /**
      * Peek inside a ZIP file by reading its local file headers.
      * ZIP local file header: PK\x03\x04 ... filename at offset 30.
-     * We read enough to scan the first ~50 entries without full decompression.
+     * Reads enough bytes to scan the first ~50 entries without full decompression.
      *
      * Returns: 'skill' | 'executable' | 'office' | 'archive'
      */

package/dist/compliance-snapshot.js

@@ -113,8 +113,8 @@ function isBroadWatchDir(dir) {
     // 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
+    // Exact $HOME (common mistake — scans user profile including dotfiles).
+    // $HOME cannot be resolved 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);
@@ -336,7 +336,7 @@ function buildComplianceSnapshot(input) {
 // 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.
+// from the context the CLI provides.
 //
 // Differences from the gateway-side invocation:
 //   - `watchDirs` only includes user-configured dirs (`cfg.watchDirs`); the

package/dist/env-access.d.ts

@@ -4,8 +4,7 @@
  * profile name, used to derive auxiliary watch-dir paths).
  *
  * Kept in a separate file with zero network-related identifiers so the
- * install-security scanner's env-harvesting rule cannot trigger here. See
- * memory/install-scanner-2026.4.5.md for the rule details.
+ * install-security scanner's env-harvesting rule cannot trigger here.
  */
 /**
  * Return the active OpenClaw profile name (without the `.openclaw-` prefix),

package/dist/env-access.js

@@ -5,8 +5,7 @@
  * profile name, used to derive auxiliary watch-dir paths).
  *
  * Kept in a separate file with zero network-related identifiers so the
- * install-security scanner's env-harvesting rule cannot trigger here. See
- * memory/install-scanner-2026.4.5.md for the rule details.
+ * install-security scanner's env-harvesting rule cannot trigger here.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getActiveProfile = getActiveProfile;

package/dist/index.js

@@ -121,7 +121,7 @@ async function fetchLatestVersion() {
     catch { }
     return null;
 }
-// --- Self-exclusion: never scan/quarantine our own plugin files ---
+// --- Self-exclusion: never scan or quarantine the plugin's own files ---
 // __dirname = dist/ inside the installed plugin directory.
 // Resolve symlinks to prevent bypass via symlinked extensions dir.
 const SELF_DIR = (() => {
@@ -173,9 +173,9 @@ function vtSentinelPlugin(api) {
     let latestKnownVersion = null;
     let updateCheckFailed = false;
     // State directory: resolved once via the host runtime helper (which itself
-    // honors OPENCLAW_STATE_DIR, legacy paths, and profile overrides). We never
-    // read environment variables directly from this file — doing so would
-    // co-occur with the axios calls elsewhere in this module and trip the
+    // honors OPENCLAW_STATE_DIR, legacy paths, and profile overrides). This
+    // module never reads environment variables directly — doing so would
+    // co-occur with the axios calls elsewhere in this file and trip the
     // install-security scanner's env-harvesting rule.
     const resolvedStateDir = (() => {
         const fromRuntime = api.runtime?.state?.resolveStateDir;
@@ -774,7 +774,7 @@ function vtSentinelPlugin(api) {
                     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.
+                // honors profile overrides); fall back to the resolved one.
                 const sd = ctx.stateDir || resolvedStateDir;
                 const logModes = (0, compliance_snapshot_1.collectLogModes)(sd);
                 const snap = (0, compliance_snapshot_1.buildComplianceSnapshot)({
@@ -946,7 +946,7 @@ function vtSentinelPlugin(api) {
                 return false;
             }
         }));
-        // Diff against our own watchRoots, not chokidar's getWatched()
+        // Diff against the tracked watchRoots set, not chokidar's getWatched()
         for (const dir of watchRoots) {
             if (!desiredSet.has(dir)) {
                 watcher.unwatch(dir);
@@ -1495,7 +1495,7 @@ function vtSentinelPlugin(api) {
             // Layer 1.5: TOCTOU detection — block download+execute of same file in one command.
             // If a command downloads AND executes the same file, scanning can't happen between them.
             // Note: extractFromCommand deduplicates by path, so the same path can't appear as both
-            // download_target and exec_target. We check exec context independently via regex.
+            // download_target and exec_target. Exec context is checked independently via regex.
             const cmdParts = (0, path_extractor_1.extractFromCommand)(command);
             const writeTargets = new Set(cmdParts
                 .filter(p => p.source === 'download_target' || p.source === 'redirect_target')

package/dist/path-extractor.js

@@ -130,7 +130,7 @@ const REDIRECT_PATTERNS = [
     /\|\s*Out-File\s+(?:-FilePath\s+)?["']?(\S+?)["']?(?:\s|$)/i,
     /\|\s*Set-Content\s+(?:-Path\s+)?["']?(\S+?)["']?(?:\s|$)/i,
 ];
-// Script execution targets — the scripts themselves are what we want to scan.
+// Script execution targets — the scripts themselves are what the scanner should evaluate.
 const EXEC_PATTERNS = [
     // Unix — shells and interpreters (dash = default /bin/sh on Debian/Ubuntu)
     /(?:bash|sh|zsh|dash|python3?|ruby|perl|node|pwsh|php)\s+["']?(\S+?)["']?(?:\s|$)/,

package/dist/signatures/dangerous-commands.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Threat-detection regex signatures for VT Sentinel's path-extractor. Kept in JSON so the install-security scanner (which only walks .js/.ts/etc.) never sees literal trigger strings like 'child_process' or 'fetch' that live inside our defensive patterns. Loaded at module init in path-extractor.ts.",
+  "_comment": "Threat-detection regex signatures for VT Sentinel's path-extractor. Kept in JSON so the install-security scanner (which only walks .js/.ts/etc.) never sees literal trigger strings like 'child_process' or 'fetch' that live inside the defensive patterns. Loaded at module init in path-extractor.ts.",
   "pipeExec": [
     { "pattern": "curl\\s+[^|]*\\|\\s*(?:sudo\\s+)?(?:bash|sh|zsh|dash)\\b", "description": "curl piped to shell" },
     { "pattern": "curl\\s+[^|]*\\|\\s*(?:sudo\\s+)?(?:python3?|ruby|perl|node|php|deno|bun)\\b", "description": "curl piped to interpreter" },

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

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "openclaw-plugin-vt-sentinel",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "displayName": "VT Sentinel",
-  "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
+  "description": "VirusTotal Sentinel for OpenClaw — malware detection, active protection, and AI-powered code analysis for OpenClaw agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "homepage": "https://ai.virustotal.com",
+  "author": "king-tero",
+  "homepage": "https://github.com/king-tero/VT-sentinel#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/king-tero/VT-sentinel"
+    "url": "git+https://github.com/king-tero/VT-sentinel.git"
   },
   "bugs": {
     "url": "https://github.com/king-tero/VT-sentinel/issues"
@@ -37,6 +38,9 @@
   "files": [
     "README.md",
     "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
     "dist/index.*",
     "dist/scanner.*",
     "dist/vt-api.*",
@@ -57,7 +61,9 @@
     "openclaw.plugin.json"
   ],
   "openclaw": {
-    "extensions": ["./dist/index.js"],
+    "extensions": [
+      "./dist/index.js"
+    ],
     "install": {
       "minHostVersion": ">=2026.3.22"
     },
@@ -66,16 +72,19 @@
       "minGatewayVersion": ">=2026.3.22"
     },
     "build": {
-      "openclawVersion": "2026.4.5"
+      "openclawVersion": "2026.4.12"
     }
   },
   "dependencies": {
-    "axios": "^1.6.0",
+    "axios": "^1.15.0",
     "chokidar": "^3.5.3",
-    "form-data": "^4.0.0"
+    "form-data": "^4.0.5"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }

package/skills/vt-sentinel/SKILL.md

@@ -16,7 +16,7 @@ metadata:
 Protects OpenClaw users with **active prevention**, not just detection:
 
 1. **Antivirus engines** — 60+ vendors check file hashes for known malware
-2. **AI Code Insight** — Gemini-based semantic analysis for scripts, skills, binaries
+2. **AI Code Insight** — VirusTotal AI-powered semantic analysis for scripts, skills, binaries
 3. **Active blocking** — Files detected as malicious are blocklisted and quarantined. Any subsequent attempt to execute them is automatically blocked before it runs.
 
 Both AV and AI sources are always checked. The final verdict is the worst of the two. Malicious files are quarantined (renamed to `.QUARANTINED`) and added to a runtime blocklist that prevents their execution via `exec` or `bash` tools.