@llnvd/openclaw-url-guard 0.0.1 → 0.1.1

package/README.md

@@ -6,54 +6,45 @@ OpenClaw plugin that guards web tool access with hostname allowlist/blocklist po
 > warranty of any kind. We make no guarantees about its security, reliability, or fitness for
 > any particular purpose. Use at your own risk.
 
-## Install
+## How It Works
 
-### From Git (recommended for now)
+This plugin uses OpenClaw's `before_tool_call` hook to intercept calls to `web_fetch` and
+`web_search`. When either tool is called:
 
-The npm package is not yet published. Install directly from Codeberg:
+1. The plugin extracts the URL from the request
+2. Checks it against your configured allowlist/blocklist policy
+3. Optionally queries URLhaus threat feed
+4. Optionally applies trust scoring
+5. **Blocks** the call if the URL fails any check, or **allows** it to proceed
 
-```bash
-# Clone and build
-git clone https://codeberg.org/llnvd/openclaw-url-guard.git
-cd openclaw-url-guard
-npm install
-npm run build
-
-# Install as OpenClaw plugin (from the repo directory)
-openclaw plugins install .
-```
+This approach is transparent to the LLM — it uses the standard `web_fetch` and `web_search`
+tools, but they're guarded by your policy.
 
-Or install directly via npm/git URL:
+## Install
 
 ```bash
-npm install git+https://codeberg.org/llnvd/openclaw-url-guard.git
+npm install @llnvd/openclaw-url-guard
 ```
 
-### From npm (once published)
+Or from git:
 
 ```bash
-npm install @llnvd/openclaw-url-guard
+git clone https://codeberg.org/llnvd/openclaw-url-guard.git
+cd openclaw-url-guard
+npm install
+npm run build
+openclaw plugins install .
 ```
 
-## Quick Start (Secure Installation)
+## Quick Start
 
-This plugin provides guarded alternatives to the native `web_fetch` and `web_search` tools.
-**For full protection, you must disable the native tools** — otherwise the LLM can bypass
-the guard by calling the unprotected tools directly.
+Add to your OpenClaw config (`~/.openclaw/openclaw.json`):
 
-Add to OpenClaw config (`~/.openclaw/openclaw.json`):
-
-```json5
+```json
 {
-  // Disable native web tools (required for security)
-  "tools": {
-    "deny": ["web_fetch", "web_search"]
-  },
-
-  // Enable the url-guard plugin
   "plugins": {
     "entries": {
-      "@llnvd/openclaw-url-guard": {
+      "openclaw-url-guard": {
         "enabled": true,
         "config": {
           "mode": "allowlist",
@@ -62,8 +53,10 @@ Add to OpenClaw config (`~/.openclaw/openclaw.json`):
             "developer.mozilla.org",
             "en.wikipedia.org",
             "github.com",
-            "stackoverflow.com"
-          ]
+            "stackoverflow.com",
+            "*.stackexchange.com"
+          ],
+          "blockPrivateIps": true
         }
       }
     }
@@ -71,120 +64,118 @@ Add to OpenClaw config (`~/.openclaw/openclaw.json`):
 }
 ```
 
-This configuration:
-1. **Denies** the native `web_fetch` and `web_search` tools (they won't be sent to the LLM)
-2. **Enables** the plugin's `safe_web_fetch` and `safe_web_search` as the only web access tools
-
-The guarded tools:
-- `safe_web_fetch` — fetches URLs through the policy filter
-- `safe_web_search` — searches the web and filters results by policy
-
-> **⚠️ Security Note:** Without `tools.deny`, the native tools remain available and a
-> prompt injection attack could instruct the LLM to use `web_fetch` instead of
-> `safe_web_fetch`, completely bypassing the guard.
-
-Optional threat intel feed settings:
-
-```yaml
-plugins:
-  - name: "@llnvd/openclaw-url-guard"
-    config:
-      mode: allowlist
-      allowlist:
-        - docs.python.org
-      threatFeeds:
-        urlhaus: true
-        mode: fail-open # default: fail-open, alternative: fail-closed
-```
+Restart the gateway and the plugin will automatically guard all `web_fetch` and `web_search` calls.
 
-URLhaus behavior:
+## Configuration
 
-- applies to `safe_web_fetch` only
-- runs after local allowlist/blocklist checks pass
-- blocks when URLhaus lists the URL
-- on URLhaus API/network failure:
-  - `fail-open`: allow request
-  - `fail-closed`: block request
+### Modes
 
-## Security Defaults
+| Mode | Description |
+|------|-------------|
+| `allowlist` | Only URLs matching the allowlist are allowed (default) |
+| `blocklist` | All URLs allowed except those matching the blocklist |
+| `hybrid` | URL must be in allowlist AND not in blocklist |
 
-- only `http://` and `https://` URLs are accepted
-- private/internal IP targets are blocked by default (`blockPrivateIps: true`)
-- URLhaus lookups time out after 5 seconds to avoid hanging requests
-- blocked tool responses are minimal by default; set `logging.verboseErrors: true` for detailed reasons and score metadata
+### Basic Options
 
-## Trust Scoring (Issue #3)
+```json
+{
+  "mode": "allowlist",
+  "allowlist": ["github.com", "*.githubusercontent.com"],
+  "blocklist": ["evil.com"],
+  "blockPrivateIps": true
+}
+```
 
-Optional trust scoring replaces binary allow/block with a score range from `+10` to `-10`.
+- **allowlist/blocklist**: Hostname patterns. Use `*.domain.com` for wildcard subdomains.
+- **blockPrivateIps**: Block requests to private/internal IPs (default: `true`)
 
-- `+10` to `+7`: Trusted (always allow, skips threat feed checks)
-- `+6` to `+3`: Preferred (allow, still check threat feeds)
-- `+2` to `-2`: Neutral
-- `-3` to `-6`: Suspicious (allow with warning when logging is enabled)
-- `-7` to `-9`: Risky (blocked by default)
-- `-10`: Forbidden (always blocked)
-
-Scoring is disabled by default for backward compatibility. Enable it with:
-
-```yaml
-plugins:
-  - name: "@llnvd/openclaw-url-guard"
-    config:
-      mode: allowlist
-      scoring:
-        enabled: true
-        defaultScore: 0
-        minScore: -6
-        rules:
-          - domain: github.com
-            score: 8
-            reason: trusted source
+### Threat Feeds
+
+Enable URLhaus threat feed lookups:
+
+```json
+{
+  "mode": "allowlist",
+  "allowlist": ["*"],
+  "threatFeeds": {
+    "urlhaus": true,
+    "mode": "fail-open"
+  }
+}
 ```
 
-## Documentation
+- `urlhaus`: Enable URLhaus API lookups
+- `mode`: `fail-open` (allow on API failure) or `fail-closed` (block on API failure)
 
-- [Documentation Index](./docs/README.md)
-- [OpenClaw Integration](./docs/openclaw-integration.md) — **start here**
-- [Agent Installation Guide](./docs/AGENT-INSTALL.md) — for AI agents installing this plugin
-- [API Reference](./docs/api-reference.md)
-- [Configuration](./docs/configuration.md)
-- [Trust Scoring](./docs/scoring.md)
-- [Testing](./docs/testing.md)
-- [Usage Modes](./docs/usage-modes.md)
+### Trust Scoring
 
-## Development
+Optional scoring system for fine-grained control:
 
-```bash
-npm test
+```json
+{
+  "mode": "allowlist",
+  "allowlist": ["*"],
+  "scoring": {
+    "enabled": true,
+    "defaultScore": 0,
+    "minScore": -6,
+    "rules": [
+      { "domain": "github.com", "score": 10, "reason": "highly trusted" },
+      { "domain": "*.sketch.com", "score": -5, "reason": "known suspicious" }
+    ]
+  }
+}
 ```
 
-Run E2E tests only:
+Score ranges:
+- `+10` to `+7`: Trusted (always allow)
+- `+6` to `+3`: Preferred
+- `+2` to `-2`: Neutral
+- `-3` to `-6`: Suspicious
+- `-7` to `-10`: Blocked
 
-```bash
-npm run test:e2e
+## Security Defaults
+
+- Only `http://` and `https://` protocols accepted
+- Private/internal IP targets blocked by default
+- URLhaus lookups timeout after 5 seconds
+- Invalid URLs are blocked
+
+## Logging
+
+Enable verbose logging to see guard decisions:
+
+```json
+{
+  "logging": {
+    "enabled": true,
+    "logBlocked": true,
+    "verboseErrors": true
+  }
+}
 ```
 
-Enable live URLhaus network E2E test:
+## Development
 
 ```bash
-E2E_NETWORK_TESTS=true npm run test:e2e
+npm install
+npm run build
+npm test
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for contributor workflow.
-
-## CI Pipeline
+Run E2E tests:
 
-This project uses Codeberg Actions (Forgejo Actions) for continuous integration.
+```bash
+npm run test:e2e
+```
 
-| Job | Runner | Trigger | Description |
-|-----|--------|---------|-------------|
-| Lint & Format | `codeberg-tiny` | push, PR | oxlint + prettier |
-| Build | `codeberg-tiny` | push, PR | TypeScript compilation |
-| Unit Tests | `codeberg-small` | push, PR | Core functionality tests |
-| E2E Tests | `codeberg-small` | push, PR | Integration test harness |
-| Live Feed Tests | `codeberg-small` | main push only | URLhaus network tests |
+## Documentation
 
-Workflow: [`.forgejo/workflows/ci.yaml`](./.forgejo/workflows/ci.yaml)
+- [Configuration](./docs/configuration.md)
+- [API Reference](./docs/api-reference.md)
+- [Trust Scoring](./docs/scoring.md)
+- [Testing](./docs/testing.md)
 
 ## License
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@llnvd/openclaw-url-guard",
-    "version": "0.0.1",
+    "version": "0.1.1",
     "description": "OpenClaw plugin for URL allowlisting/blocklisting in web_fetch and web_search tools",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/dist/src/index.d.ts

@@ -1,3 +1,200 @@
-import type { PluginDefinition } from './types';
-declare const plugin: PluginDefinition;
+import type { UrlGuardConfig } from './types';
+interface PluginLogger {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+interface BeforeToolCallEvent {
+    toolName: string;
+    params: Record<string, unknown>;
+    runId?: string;
+    toolCallId?: string;
+}
+interface BeforeToolCallContext {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    toolCallId?: string;
+}
+interface BeforeToolCallResult {
+    block?: boolean;
+    blockReason?: string;
+    params?: Record<string, unknown>;
+}
+type BeforeToolCallHandler = (event: BeforeToolCallEvent, ctx: BeforeToolCallContext) => Promise<BeforeToolCallResult | void> | BeforeToolCallResult | void;
+interface OpenClawPluginApi {
+    id: string;
+    name: string;
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    on: (hookName: 'before_tool_call', handler: BeforeToolCallHandler) => void;
+}
+declare const GUARDED_TOOLS: Set<string>;
+/**
+ * Check a URL against the guard policy.
+ * Returns { allowed: true } or { allowed: false, reason: string }
+ */
+declare function checkUrl(url: string, config: UrlGuardConfig, logger: PluginLogger): Promise<{
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+}>;
+declare const plugin: {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    configSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["mode"];
+        readonly properties: {
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["allowlist", "blocklist", "hybrid"];
+            };
+            readonly allowlist: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly blocklist: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly blockPrivateIps: {
+                readonly type: "boolean";
+            };
+            readonly threatFeeds: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly urlhaus: {
+                        readonly type: "boolean";
+                    };
+                    readonly mode: {
+                        readonly type: "string";
+                        readonly enum: readonly ["fail-open", "fail-closed"];
+                    };
+                };
+            };
+            readonly scoring: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly enabled: {
+                        readonly type: "boolean";
+                    };
+                    readonly defaultScore: {
+                        readonly type: "number";
+                        readonly minimum: -10;
+                        readonly maximum: 10;
+                    };
+                    readonly minScore: {
+                        readonly type: "number";
+                        readonly minimum: -10;
+                        readonly maximum: 10;
+                    };
+                    readonly rules: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["domain", "score"];
+                            readonly properties: {
+                                readonly domain: {
+                                    readonly type: "string";
+                                };
+                                readonly score: {
+                                    readonly type: "number";
+                                    readonly minimum: -10;
+                                    readonly maximum: 10;
+                                };
+                                readonly reason: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                    readonly feedScores: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly urlhaus: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly properties: {
+                                    readonly online: {
+                                        readonly type: "number";
+                                        readonly minimum: -10;
+                                        readonly maximum: 10;
+                                    };
+                                    readonly offline: {
+                                        readonly type: "number";
+                                        readonly minimum: -10;
+                                        readonly maximum: 10;
+                                    };
+                                };
+                            };
+                            readonly spamhaus: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly properties: {
+                                    readonly botnet_cc: {
+                                        readonly type: "number";
+                                        readonly minimum: -10;
+                                        readonly maximum: 10;
+                                    };
+                                    readonly phishing_domain: {
+                                        readonly type: "number";
+                                        readonly minimum: -10;
+                                        readonly maximum: 10;
+                                    };
+                                    readonly spammer_domain: {
+                                        readonly type: "number";
+                                        readonly minimum: -10;
+                                        readonly maximum: 10;
+                                    };
+                                    readonly abused_redirector: {
+                                        readonly type: "number";
+                                        readonly minimum: -10;
+                                        readonly maximum: 10;
+                                    };
+                                    readonly 'abused_legit_*': {
+                                        readonly type: "number";
+                                        readonly minimum: -10;
+                                        readonly maximum: 10;
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            readonly logging: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly enabled: {
+                        readonly type: "boolean";
+                    };
+                    readonly logBlocked: {
+                        readonly type: "boolean";
+                    };
+                    readonly verboseErrors: {
+                        readonly type: "boolean";
+                    };
+                };
+            };
+        };
+    };
+    register(api: OpenClawPluginApi): void;
+};
 export default plugin;
+export { checkUrl, GUARDED_TOOLS };

package/dist/src/index.js

@@ -3,14 +3,127 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUARDED_TOOLS = void 0;
+exports.checkUrl = checkUrl;
 const config_1 = require("./config");
-const safeFetch_1 = require("./tools/safeFetch");
-const safeSearch_1 = require("./tools/safeSearch");
+const matcher_1 = require("./filters/matcher");
+const urlhaus_1 = require("./filters/urlhaus");
+const engine_1 = require("./scoring/engine");
 const package_json_1 = __importDefault(require("../package.json"));
+// Tools we intercept
+const GUARDED_TOOLS = new Set(['web_fetch', 'web_search']);
+exports.GUARDED_TOOLS = GUARDED_TOOLS;
+/**
+ * Check a URL against the guard policy.
+ * Returns { allowed: true } or { allowed: false, reason: string }
+ */
+async function checkUrl(url, config, logger) {
+    const hostname = (0, matcher_1.extractHostname)(url);
+    if (!hostname) {
+        return { allowed: false, reason: 'Invalid URL format' };
+    }
+    // Check private IP blocking
+    if (config.blockPrivateIps && (0, matcher_1.isPrivateIp)(hostname)) {
+        return { allowed: false, reason: 'Private/internal IP addresses are blocked' };
+    }
+    // Check allowlist/blocklist policy
+    if (!(0, matcher_1.isAllowed)(url, config)) {
+        const reason = (0, matcher_1.getBlockReason)(url, config);
+        return { allowed: false, reason: `URL blocked: ${reason}` };
+    }
+    // Check threat feeds if enabled
+    let feedResults;
+    if (config.threatFeeds?.urlhaus) {
+        try {
+            const urlhausResult = await (0, urlhaus_1.lookupUrlhaus)(url);
+            if (urlhausResult.listed) {
+                return {
+                    allowed: false,
+                    reason: `URL blocked by threat feed: ${urlhausResult.reason ?? 'listed in URLhaus'}`,
+                };
+            }
+            if (urlhausResult.feedSignals) {
+                feedResults = { signals: urlhausResult.feedSignals };
+            }
+            if (urlhausResult.unavailable) {
+                feedResults = { unavailable: true, reason: urlhausResult.reason };
+                if (config.threatFeeds.mode === 'fail-closed') {
+                    return {
+                        allowed: false,
+                        reason: 'Threat feed unavailable and fail-closed mode is enabled',
+                    };
+                }
+                logger.warn?.(`[url-guard] Threat feed unavailable: ${urlhausResult.reason}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn?.(`[url-guard] Threat feed lookup failed: ${message}`);
+            if (config.threatFeeds.mode === 'fail-closed') {
+                return {
+                    allowed: false,
+                    reason: 'Threat feed lookup failed and fail-closed mode is enabled',
+                };
+            }
+        }
+    }
+    // Apply scoring if enabled
+    if (config.scoring?.enabled) {
+        const scoreResult = (0, engine_1.calculateScore)(url, config, feedResults);
+        if (!scoreResult.allowed) {
+            const sources = scoreResult.sources.map((s) => s.source).join(', ');
+            return {
+                allowed: false,
+                reason: `URL blocked by scoring (score: ${scoreResult.finalScore}, sources: ${sources})`,
+            };
+        }
+    }
+    return { allowed: true };
+}
 const plugin = {
-    name: '@llnvd/openclaw-url-guard',
+    id: 'openclaw-url-guard',
+    name: 'URL Guard',
     version: package_json_1.default.version,
-    tools: [safeFetch_1.safeWebFetchTool, safeSearch_1.safeWebSearchTool],
+    description: 'Guards web tool access with hostname allowlist/blocklist policy and optional URLhaus threat feed integration.',
     configSchema: config_1.configSchema,
+    register(api) {
+        const config = (0, config_1.normalizeConfig)(api.pluginConfig);
+        api.logger.info(`[url-guard] Registering URL Guard plugin v${package_json_1.default.version}`);
+        api.logger.info(`[url-guard] Mode: ${config.mode}, Allowlist: ${config.allowlist?.length ?? 0} domains, ` +
+            `Blocklist: ${config.blocklist?.length ?? 0} domains`);
+        if (config.threatFeeds?.urlhaus) {
+            api.logger.info(`[url-guard] URLhaus threat feed enabled (mode: ${config.threatFeeds.mode ?? 'fail-open'})`);
+        }
+        if (config.scoring?.enabled) {
+            api.logger.info(`[url-guard] Scoring enabled (minScore: ${config.scoring.minScore ?? -6}, ` +
+                `rules: ${config.scoring.rules?.length ?? 0})`);
+        }
+        // Register the before_tool_call hook to intercept web_fetch and web_search
+        api.on('before_tool_call', async (event, _ctx) => {
+            // Only intercept guarded tools
+            if (!GUARDED_TOOLS.has(event.toolName)) {
+                return;
+            }
+            // Extract URL from params
+            const url = event.params.url;
+            if (!url || typeof url !== 'string') {
+                // No URL parameter - let it through (tool will handle the error)
+                return;
+            }
+            // Check the URL against our policy
+            const result = await checkUrl(url, config, api.logger);
+            if (!result.allowed) {
+                api.logger.info?.(`[url-guard] Blocked ${event.toolName}: ${url} - ${result.reason}`);
+                return {
+                    block: true,
+                    blockReason: result.reason,
+                };
+            }
+            // URL is allowed - let the tool execute
+            api.logger.debug?.(`[url-guard] Allowed ${event.toolName}: ${url}`);
+            return;
+        });
+        api.logger.info('[url-guard] Hook registered for: web_fetch, web_search');
+    },
 };
 exports.default = plugin;