@exelerus/openclaw-vexscan 1.0.0

package/CLAUDE.md

@@ -0,0 +1,112 @@
+# OpenClaw Plugin Development
+
+## Plugin API (verified against OpenClaw 2026.2.x)
+
+The official docs are outdated. These are the actual patterns from the installed Gateway.
+
+### Export Pattern
+
+Two valid patterns — use the object form when the plugin has metadata:
+
+```typescript
+// Object with register method (preferred for plugins with metadata)
+const myPlugin = {
+  id: "my-plugin",
+  name: "My Plugin",
+  kind: "tool" as const,
+  configSchema: MySchema,
+  register(api: OpenClawPluginApi) { ... },
+};
+export default myPlugin;
+
+// Bare function (simpler plugins)
+export default function register(api: OpenClawPluginApi) { ... }
+```
+
+**Do NOT use:** `export const plugin`, named exports, or `init()` — the Gateway looks for a default export with a `register` method.
+
+### Type Import
+
+```typescript
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+```
+
+The SDK type is `OpenClawPluginApi`, not `PluginContext` or `ToolPlugin` as docs suggest. Our `src/openclaw-sdk.d.ts` provides the ambient declaration so TypeScript compiles without the SDK installed.
+
+### Plugin ID Must Match Package Name
+
+The Gateway derives the plugin config key by stripping the npm scope from the package name:
+- Package: `@exelerus/openclaw-vexscan` → config key: `openclaw-vexscan`
+- The `id` in both `openclaw.plugin.json` and the plugin object **must** match this derived key
+
+### Required Files
+
+| File | Required | Purpose |
+|------|----------|---------|
+| `openclaw.plugin.json` | **Yes** | Discovery manifest (`id`, `kind`, `configSchema`) |
+| `package.json` `openclaw.extensions` | Yes | Points Gateway to entry file |
+| `index.ts` | Yes | Plugin entry with `register()` |
+
+### Manifest (`openclaw.plugin.json`)
+
+Uses `"kind"` not `"slots"`:
+```json
+{
+  "id": "openclaw-vexscan",
+  "kind": "tool",
+  "configSchema": { ... }
+}
+```
+
+### Tool Registration
+
+`api.registerTool()` accepts a plain object or a factory function:
+
+```typescript
+// Plain object (our approach)
+api.registerTool({
+  name: "vexscan",
+  description: "...",
+  parameters: TypeBoxSchema,
+  async execute(toolCallId, params) { return { content: [...] }; },
+});
+
+// Factory function (bundled plugin pattern)
+api.registerTool(
+  (ctx) => createMyTool(api),
+  { optional: true },
+);
+```
+
+### Config Schema
+
+The manifest uses JSON Schema. The plugin object can use TypeBox (which is JSON Schema compatible). Config validation uses a Zod-like `safeParse` interface internally.
+
+## Build & Test
+
+```bash
+npm run build          # Compile TypeScript
+npm run clean          # Remove dist/
+```
+
+### Testing with Live OpenClaw
+
+```bash
+openclaw setup                                          # One-time: creates ~/.openclaw/openclaw.json
+openclaw plugins install -l /path/to/plugins/openclaw   # Symlink plugin
+openclaw plugins list                                   # Verify "loaded" status
+openclaw vexscan --help                                 # Test CLI registration
+```
+
+To uninstall: remove the plugin entry from `~/.openclaw/openclaw.json` under `plugins.entries`, `plugins.load.paths`, and `plugins.installs`.
+
+### Peer Dependency
+
+OpenClaw uses calendar versioning (e.g., `2026.2.3-1`). Peer dep is `>=2026.1.26`.
+
+## Reference Plugins
+
+Look at bundled plugins for real-world patterns:
+- `~/.npm-global/lib/node_modules/openclaw/extensions/memory-core/` — object export, tool + CLI
+- `~/.npm-global/lib/node_modules/openclaw/extensions/llm-task/` — function export, tool only
+- SDK types: `~/.npm-global/lib/node_modules/openclaw/dist/plugin-sdk/index.d.ts`

package/README.md

@@ -0,0 +1,149 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/edimuj/vexscan/main/assets/sir-clawsalot-256.png" alt="Sir Clawsalot" width="180">
+</p>
+
+<h1 align="center">Vexscan Plugin for OpenClaw</h1>
+
+<p align="center">
+  <strong>Security scanner plugin that protects your OpenClaw environment from malicious extensions and skills.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@exelerus/openclaw-vexscan"><img src="https://img.shields.io/npm/v/@exelerus/openclaw-vexscan?style=flat-square&color=blue" alt="npm"></a>
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square" alt="License"></a>
+</p>
+
+## Features
+
+- **Automatic Scanning**: Scans third-party extensions on startup
+- **Pre-Install Vetting**: Vet extensions before installing with `openclaw vexscan vet`
+- **AI-Integrated**: The AI assistant can scan code on your behalf
+- **Smart Filtering**: Skips official extensions, focuses on untrusted code
+
+## Installation
+
+### Install the Plugin
+
+```bash
+# From npm
+openclaw plugins install @exelerus/openclaw-vexscan
+
+# From local path
+openclaw plugins install ./plugins/openclaw
+
+# Development (symlink)
+openclaw plugins install -l ./plugins/openclaw
+```
+
+### CLI Installation (Optional)
+
+The plugin will **auto-install** the Vexscan CLI on first run. For manual installation:
+
+```bash
+# Quick install (macOS/Linux)
+curl -fsSL https://raw.githubusercontent.com/edimuj/vexscan/main/install.sh | bash
+
+# Or from source
+git clone https://github.com/edimuj/vexscan && cd vexscan && cargo install --path .
+```
+
+## Usage
+
+### CLI Commands
+
+```bash
+# Scan installed extensions
+openclaw vexscan scan
+
+# Scan specific path
+openclaw vexscan scan ~/.openclaw/extensions
+
+# Vet before installing
+openclaw vexscan vet https://github.com/user/cool-extension
+
+# Vet and install in one step (blocked if critical/high findings)
+openclaw vexscan install https://github.com/user/cool-extension
+
+# Install with overrides
+openclaw vexscan install ./local-extension --link       # symlink for dev
+openclaw vexscan install @org/extension --force         # allow medium findings
+openclaw vexscan install @org/extension --dry-run       # vet only, don't install
+
+# List detection rules
+openclaw vexscan rules
+```
+
+### AI Tool Usage
+
+The AI assistant can use Vexscan directly:
+
+```
+User: "Is this extension safe? https://github.com/user/extension"
+AI: *uses vexscan tool to vet the extension*
+```
+
+```
+User: "Check my extensions for security issues"
+AI: *uses vexscan tool to scan ~/.openclaw/extensions*
+```
+
+```
+User: "Install this extension: @org/cool-plugin"
+AI: *uses vexscan install action to vet and install*
+```
+
+## Configuration
+
+Configure in your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "vexscan": {
+      "enabled": true,
+      "scanOnInstall": true,
+      "minSeverity": "medium",
+      "thirdPartyOnly": true,
+      "skipDeps": true
+    }
+  }
+}
+```
+
+| Option           | Default  | Description                                 |
+|------------------|----------|---------------------------------------------|
+| `enabled`        | `true`   | Enable security scanning                    |
+| `scanOnInstall`  | `true`   | Scan on startup                             |
+| `minSeverity`    | `medium` | Minimum severity to report                  |
+| `thirdPartyOnly` | `true`   | Only scan non-official extensions           |
+| `skipDeps`       | `true`   | Skip node_modules to reduce false positives |
+| `ast`            | `true`   | AST analysis for obfuscation detection      |
+| `deps`           | `true`   | Dependency scanning for supply chain attacks|
+| `cliPath`        | (auto)   | Path to vexscan binary                      |
+
+## What It Detects
+
+| Category             | Examples                                        |
+|----------------------|-------------------------------------------------|
+| Code Execution       | `eval()`, `new Function()`, `exec()`, SQL injection |
+| Shell Injection      | `child_process`, `subprocess`, reverse shells   |
+| Data Exfiltration    | Discord webhooks, external POST                 |
+| Credential Access    | SSH keys, AWS credentials                       |
+| Hardcoded Secrets    | API keys, tokens, passwords, connection strings |
+| Prompt Injection     | Instruction override, system prompt reveal      |
+| Obfuscation          | Base64, hex encoding                            |
+| Backdoor Detection   | Time bombs, C2 callbacks                        |
+| Dangerous Operations | `rm -rf`, `chmod 777`, `sudo`                   |
+| Resource Abuse       | Fork bombs, infinite loops                      |
+
+## Development
+
+```bash
+cd plugins/openclaw
+npm install
+npm run build
+```
+
+## License
+
+Apache 2.0

package/SKILL.md

@@ -0,0 +1,129 @@
+# Vexscan Security Scanner
+
+Vexscan scans extensions, skills, and code for security threats. Use it when:
+
+- User wants to install a new extension or skill
+- User asks about security of their OpenClaw setup
+- User mentions suspicious behavior from an extension
+- User wants to audit installed extensions
+- Before recommending any third-party extension
+
+## When to use Vexscan
+
+| User intent                          | Action                                |
+|--------------------------------------|---------------------------------------|
+| "Install this extension from GitHub" | Use **install** — vets and installs   |
+| "Is this extension safe?"            | Use **vet** — scan without installing |
+| "Is my setup secure?"                | Use **scan** — scan all extensions    |
+| "This extension is acting weird"     | Use **scan** — scan for malicious patterns |
+| "Show me my installed extensions"    | No — use OpenClaw's built-in list     |
+
+## Install (vet + install in one step)
+
+**Always prefer install over vet** when the user wants to add an extension. It vets first and only installs if the security check passes.
+
+```json
+{
+  "action": "install",
+  "source": "https://github.com/user/cool-extension"
+}
+```
+
+Returns on success:
+
+```json
+{
+  "ok": true,
+  "action": "installed",
+  "findings": 0,
+  "message": "Installed — no security issues found."
+}
+```
+
+Returns when blocked:
+
+```json
+{
+  "ok": false,
+  "action": "install_blocked",
+  "verdict": "high_risk",
+  "findings": 3,
+  "maxSeverity": "high",
+  "reason": "HIGH severity findings — installation blocked. Use allowHigh/--allow-high to override."
+}
+```
+
+### Severity gates
+
+| Max severity | Default    | Override         |
+|-------------|------------|------------------|
+| Critical    | **Blocked** | Cannot override  |
+| High        | **Blocked** | `"allowHigh": true` |
+| Medium      | **Blocked** | `"force": true`  |
+| Low / Info  | Allowed    | —                |
+
+**Never set `allowHigh` or `force` without explaining the risks to the user first.**
+
+## Scan installed extensions
+
+```json
+{
+  "action": "scan",
+  "path": "~/.openclaw/extensions"
+}
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "findings": 3,
+  "maxSeverity": "medium",
+  "summary": {
+    "critical": 0,
+    "high": 0,
+    "medium": 3,
+    "low": 1,
+    "info": 2
+  }
+}
+```
+
+## Vet without installing
+
+Use when the user just wants a security assessment:
+
+```json
+{
+  "action": "vet",
+  "source": "https://github.com/user/cool-extension"
+}
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "verdict": "clean",
+  "findings": 0,
+  "message": "No security issues found"
+}
+```
+
+## Verdicts
+
+| Verdict     | Meaning              | Recommendation              |
+|-------------|----------------------|-----------------------------|
+| `clean`     | No issues found      | Safe to install             |
+| `warnings`  | Low/medium issues    | Review findings, usually OK |
+| `high_risk` | High severity issues | Warn user, review carefully |
+| `dangerous` | Critical issues      | Do NOT recommend installing |
+
+## Important
+
+- **Always use install** (not raw `openclaw plugins install`) so extensions are vetted first
+- If install is blocked, explain the specific threats found
+- Never override severity gates without user consent
+- Third-party extensions are higher risk than official ones

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+declare const vexscanPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    kind: "tool";
+    configSchema: import("@sinclair/typebox").TObject<{
+        enabled: import("@sinclair/typebox").TBoolean;
+        scanOnInstall: import("@sinclair/typebox").TBoolean;
+        minSeverity: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"info">, import("@sinclair/typebox").TLiteral<"low">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"critical">]>;
+        thirdPartyOnly: import("@sinclair/typebox").TBoolean;
+        skipDeps: import("@sinclair/typebox").TBoolean;
+        ast: import("@sinclair/typebox").TBoolean;
+        deps: import("@sinclair/typebox").TBoolean;
+        cliPath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    register(api: OpenClawPluginApi): void;
+};
+export default vexscanPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAkH7D,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;kBAOH,iBAAiB;CAsXhC,CAAC;AAEF,eAAe,aAAa,CAAC"}