@goplus/agentguard 1.1.28-beta.1 → 1.1.28

package/dist/utils/system-paths.d.ts

@@ -0,0 +1,14 @@
+export type SystemPathOperation = 'read' | 'write' | 'delete' | 'move' | 'chmod' | 'chown';
+export type SystemPathDecision = 'block' | 'require_approval';
+export type SystemPathSeverity = 'high' | 'critical';
+export interface SystemPathClassification {
+    path: string;
+    operation: SystemPathOperation;
+    decision: SystemPathDecision;
+    severity: SystemPathSeverity;
+    category: 'system_boot' | 'system_config' | 'security_credentials' | 'kernel_device' | 'root';
+    description: string;
+}
+export declare function classifySystemPathOperation(rawPath: string, operation: SystemPathOperation): SystemPathClassification | null;
+export declare function normalizeSystemPath(rawPath: string): string;
+//# sourceMappingURL=system-paths.d.ts.map

package/dist/utils/system-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-paths.d.ts","sourceRoot":"","sources":["../../src/utils/system-paths.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAC3F,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,kBAAkB,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,aAAa,GAAG,eAAe,GAAG,sBAAsB,GAAG,eAAe,GAAG,MAAM,CAAC;IAC9F,WAAW,EAAE,MAAM,CAAC;CACrB;AA6CD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,mBAAmB,GAC7B,wBAAwB,GAAG,IAAI,CA0GjC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAa3D"}

package/dist/utils/system-paths.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySystemPathOperation = classifySystemPathOperation;
+exports.normalizeSystemPath = normalizeSystemPath;
+const node_os_1 = require("node:os");
+const BOOT_PREFIXES = [
+    '/bin',
+    '/sbin',
+    '/usr',
+    '/usr/bin',
+    '/usr/sbin',
+    '/lib',
+    '/lib64',
+];
+const CRITICAL_CONFIG_EXACT = [
+    '/etc/shadow',
+    '/etc/sudoers',
+];
+const HIGH_CONFIG_EXACT = [
+    '/etc/passwd',
+    '/etc/group',
+    '/etc/hosts',
+    '/etc/resolv.conf',
+];
+const MEDIUM_CONFIG_EXACT = [
+    '/etc/crontab',
+];
+const CONFIG_PREFIXES = [
+    '/etc',
+    '/etc/ssh',
+    '/etc/systemd',
+];
+const SECURITY_HOME_PATHS = [
+    '~/.ssh',
+    '~/.gnupg',
+    '~/.aws',
+    '~/.kube',
+    '~/.npmrc',
+    '~/.netrc',
+];
+const MUTATING_OPERATIONS = new Set(['write', 'delete', 'move', 'chmod', 'chown']);
+function classifySystemPathOperation(rawPath, operation) {
+    const path = normalizeSystemPath(rawPath);
+    if (!path)
+        return null;
+    if (path === '/') {
+        return {
+            path,
+            operation,
+            decision: operation === 'read' ? 'require_approval' : 'block',
+            severity: operation === 'read' ? 'high' : 'critical',
+            category: 'root',
+            description: 'Root filesystem path',
+        };
+    }
+    if (matchesAnyPrefix(path, BOOT_PREFIXES)) {
+        if (operation === 'read')
+            return null;
+        return {
+            path,
+            operation,
+            decision: 'block',
+            severity: 'critical',
+            category: 'system_boot',
+            description: 'System boot or runtime directory',
+        };
+    }
+    if (CRITICAL_CONFIG_EXACT.includes(path) || path.startsWith('/etc/ssh/ssh_host_')) {
+        return {
+            path,
+            operation,
+            decision: operation === 'read' ? 'require_approval' : 'block',
+            severity: operation === 'read' ? 'high' : 'critical',
+            category: 'system_config',
+            description: 'Critical system credential or privilege file',
+        };
+    }
+    if (HIGH_CONFIG_EXACT.includes(path)) {
+        return {
+            path,
+            operation,
+            decision: operation === 'read' ? 'require_approval' : 'block',
+            severity: operation === 'read' ? 'high' : 'critical',
+            category: 'system_config',
+            description: 'System configuration file',
+        };
+    }
+    if (MEDIUM_CONFIG_EXACT.includes(path)) {
+        return {
+            path,
+            operation,
+            decision: operation === 'read' ? 'require_approval' : 'require_approval',
+            severity: 'high',
+            category: 'system_config',
+            description: 'Sensitive system configuration path',
+        };
+    }
+    if (matchesAnyPrefix(path, CONFIG_PREFIXES)) {
+        return {
+            path,
+            operation,
+            decision: operation === 'read' ? 'require_approval' : 'block',
+            severity: operation === 'read' ? 'high' : 'critical',
+            category: 'system_config',
+            description: 'Sensitive system configuration path',
+        };
+    }
+    if (matchesKernelOrDevicePath(path)) {
+        if (operation === 'read' && !path.startsWith('/proc/1'))
+            return null;
+        return {
+            path,
+            operation,
+            decision: operation === 'read' ? 'require_approval' : 'block',
+            severity: operation === 'read' ? 'high' : 'critical',
+            category: 'kernel_device',
+            description: 'Kernel, process, or device path',
+        };
+    }
+    if (path === '/root' || path.startsWith('/root/')) {
+        return {
+            path,
+            operation,
+            decision: operation === 'read' ? 'require_approval' : 'require_approval',
+            severity: 'high',
+            category: 'security_credentials',
+            description: 'Root user home directory',
+        };
+    }
+    if (matchesSecurityHomePath(path)) {
+        return {
+            path,
+            operation,
+            decision: operation === 'read' || MUTATING_OPERATIONS.has(operation) ? 'require_approval' : 'require_approval',
+            severity: 'high',
+            category: 'security_credentials',
+            description: 'User credential path',
+        };
+    }
+    return null;
+}
+function normalizeSystemPath(rawPath) {
+    let path = rawPath.trim();
+    if (!path)
+        return '';
+    path = path.replace(/^['"]|['"]$/g, '');
+    path = path.replace(/[),.;]+$/g, '');
+    path = path.replace(/\\/g, '/');
+    path = path.replace(/[?*[\]{}]+.*$/g, '');
+    if (path.startsWith('~/')) {
+        path = `${(0, node_os_1.homedir)().replace(/\\/g, '/')}/${path.slice(2)}`;
+    }
+    path = path.replace(/\/+/g, '/');
+    if (path.length > 1)
+        path = path.replace(/\/+$/g, '');
+    return path;
+}
+function matchesAnyPrefix(path, prefixes) {
+    return prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+function matchesKernelOrDevicePath(path) {
+    return path === '/proc/1' ||
+        path.startsWith('/proc/1/') ||
+        path.startsWith('/sys/') ||
+        /^\/dev\/(?:sd[a-z]\d*|vd[a-z]\d*|xvd[a-z]\d*|nvme\d+n\d+(?:p\d+)?|disk\/)/.test(path);
+}
+function matchesSecurityHomePath(path) {
+    const home = (0, node_os_1.homedir)().replace(/\\/g, '/');
+    const expanded = SECURITY_HOME_PATHS.map((item) => item.startsWith('~/') ? `${home}/${item.slice(2)}` : item);
+    return expanded.some((item) => path === item || path.startsWith(`${item}/`));
+}
+//# sourceMappingURL=system-paths.js.map

package/dist/utils/system-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-paths.js","sourceRoot":"","sources":["../../src/utils/system-paths.ts"],"names":[],"mappings":"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"}

package/docs/SECURITY-POLICY.md

@@ -180,6 +180,28 @@ Commands matching the safe list are allowed without restriction, **unless** they
 6. POST/PUT to untrusted domain → escalate medium → high
 7. Domain in allowlist → **ALLOW** (low)
 
+#### Social Account Actions
+
+Mutating requests to X/Twitter or TweetClaw social account endpoints receive the
+`SOCIAL_ACCOUNT_ACTION` risk tag and escalate to **high** risk. These actions can
+post tweets, post tweet replies, send direct messages, upload media, create
+monitors, register webhooks, or run giveaway draws, so balanced mode prompts the
+operator before execution instead of silently allowing the request.
+
+| Example | Risk |
+|---------|------|
+| `POST https://api.twitter.com/2/tweets` | high |
+| `POST https://xquik.com/api/v1/x/tweets` | high |
+| `POST https://xquik.com/api/v1/x/dm/12345` | high |
+| `POST https://xquik.com/api/v1/x/media` | high |
+| `POST https://xquik.com/api/v1/monitors` | high |
+| `POST https://xquik.com/api/v1/webhooks` | high |
+| `POST https://xquik.com/api/v1/draws` | high |
+
+Read-only TweetClaw requests such as tweet search, user lookup, or follower
+export remain low risk unless they hit another rule such as secret scanning,
+high-risk TLD handling, or webhook exfiltration.
+
 ---
 
 ### 4.3 File Operations (`read_file` / `write_file`)

package/docs/hermes.md

@@ -1,20 +1,54 @@
 # Hermes Agent
 
-Hermes Agent can use AgentGuard through Hermes shell hooks. AgentGuard evaluates
-`pre_tool_call` events before risky tools execute and returns Hermes-compatible
-block decisions on stdout.
+AgentGuard integrates with [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+two ways: a **native plugin** (recommended) and **shell hooks** (fallback). Both
+route tool calls through the same AgentGuard decision engine, so detection logic
+is identical; they differ only in how they are installed and managed.
 
-## Shell hook usage
+## Native plugin (recommended)
 
-Build AgentGuard first so the hook script can import `dist/index.js`:
+The plugin is managed the Hermes-native way (`hermes plugins
+enable/disable/list`), runs before shell hooks, and adds a `/agentguard`
+slash command. `agentguard init --agent hermes` installs the plugin and enables
+it in `~/.hermes/config.yaml`.
 
 ```bash
+# Build the engine so the plugin can reach it
 npm run build
+
+# Install the plugin into ~/.hermes/plugins/agentguard/
+agentguard init --agent hermes
+
+# Confirm it is enabled
+hermes plugins list
+```
+
+The plugin shells out to the `agentguard` CLI (or a `hermes-hook.js` you point it
+at). Make sure `agentguard` is on `PATH` (`npm i -g @goplus/agentguard`) or set
+`AGENTGUARD_BIN`. See [`plugins/hermes/README.md`](../plugins/hermes/README.md)
+for the full configuration reference (`AGENTGUARD_HERMES_*` env vars, fail policy,
+autoscan).
+
+| Hermes hook        | Behavior                                                        |
+|--------------------|-----------------------------------------------------------------|
+| `pre_tool_call`    | Blocks dangerous actions (`{"action":"block","message":...}`).  |
+| `post_tool_call`   | Audit-only; never blocks.                                       |
+| `on_session_start` | Best-effort skill scan (opt out: `AGENTGUARD_HERMES_AUTOSCAN=0`).|
+| `/agentguard`      | Slash command: `status`, `report` (default), `checkup`.         |
+
+## Shell hooks (fallback)
+
+Use shell hooks when you prefer wiring AgentGuard directly into the Hermes config,
+or on a Hermes build without the plugin system:
+
+```bash
+npm run build
+agentguard init --agent hermes --shell-hooks
 ```
 
-Run `agentguard init --agent hermes` to install the skill and merge the
-AgentGuard hook entries into `~/.hermes/config.yaml`. The bundled template at
-`skills/agentguard/hermes-hooks.yaml` is still available for manual setups.
+This merges the AgentGuard hook entries into `~/.hermes/config.yaml`. The bundled
+template at `skills/agentguard/hermes-hooks.yaml` is also available for manual
+setups:
 
 ```yaml
 hooks:
@@ -29,10 +63,7 @@ hooks:
     - matcher: "write_file|patch|skill_manage"
       command: "node \"/path/to/agentguard/skills/agentguard/scripts/hermes-hook.js\""
       timeout: 10
-    - matcher: "web_search"
-      command: "node \"/path/to/agentguard/skills/agentguard/scripts/hermes-hook.js\""
-      timeout: 10
-    - matcher: "web_extract|browser_navigate"
+    - matcher: "web_search|web_extract|browser_navigate"
       command: "node \"/path/to/agentguard/skills/agentguard/scripts/hermes-hook.js\""
       timeout: 10
 
@@ -59,7 +90,7 @@ or set `hooks_auto_accept: true` in `~/.hermes/config.yaml`.
 | `write_file`, `patch`, `skill_manage` | `write_file` |
 | `read_file` | `read_file` |
 | `web_search` | `web_search` |
-| `web_extract`, `browser_navigate` | `network_request` |
+| `web_extract`, `browser_navigate`, `browser_open`, … | `network_request` |
 
 ## Decisions
 
@@ -70,5 +101,5 @@ returned as:
 {"action":"block","message":"GoPlus AgentGuard: ..."}
 ```
 
-AgentGuard `ask` decisions are also represented as blocks because Hermes shell
-hooks do not have a native confirmation decision.
+AgentGuard `confirm` decisions are also represented as blocks because Hermes
+`pre_tool_call` has no native confirmation decision.

package/docs/mcpb-build.md

@@ -0,0 +1,49 @@
+# Building the `.mcpb` bundle
+
+AgentGuard ships to the Anthropic **MCP / Desktop Extensions Directory** as an
+`.mcpb` bundle (an MCP Bundle / Desktop Extension — a zip containing a
+`manifest.json`, an `icon.png`, and the Node server with its production
+dependencies).
+
+The bundle is built reproducibly from this repo. Nothing is assembled by hand.
+
+## Source files
+
+| Path | Purpose |
+| --- | --- |
+| `mcpb/manifest.json` | The bundle manifest (`manifest_version` `0.3`, `icon`, `privacy_policies`, tool list). The `version` is stamped from `package.json` at build time. |
+| `mcpb/icon.png` | 256×256 square icon shown in the directory. |
+| `scripts/build-mcpb.sh` | Assembles the staging tree and packs the `.mcpb`. |
+
+## Build locally
+
+```bash
+npm run build:mcpb
+```
+
+This compiles TypeScript, stages `server/` with production-only
+`node_modules`, copies the manifest and icon to the bundle root, and packs the
+result with the official [`@anthropic-ai/mcpb`](https://www.npmjs.com/package/@anthropic-ai/mcpb)
+CLI. Output lands at:
+
+```
+dist-mcpb/agentguard-<version>.mcpb
+```
+
+Verify the manifest of a built bundle:
+
+```bash
+unzip -p dist-mcpb/agentguard-*.mcpb manifest.json \
+  | jq '{manifest_version, icon, privacy_policies, version}'
+```
+
+## Publishing a release
+
+Pushing a `v*` tag runs `.github/workflows/release-mcpb.yml`, which builds the
+bundle and attaches it to the matching GitHub Release. Publishing the `.mcpb` as
+a Release asset lets the MCP Directory pick up new versions automatically.
+
+```bash
+npm version patch        # bumps package.json, creates the tag
+git push --follow-tags
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplus/agentguard",
-  "version": "1.1.28-beta.1",
+  "version": "1.1.28",
   "description": "GoPlus AgentGuard — Security guard for AI agents. Blocks dangerous commands, prevents data leaks, protects secrets. 20 detection rules, runtime action evaluation, trust registry.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:mcpb": "bash scripts/build-mcpb.sh",
     "start": "node dist/mcp-server.js",
     "dev": "tsc -w",
     "test": "node --test dist/tests/*.test.js",
@@ -57,6 +58,7 @@
     "zod": "3.25.76"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2",
     "@types/node": "22.19.15",
     "typescript": "5.7.3"
   },
@@ -73,6 +75,7 @@
     "openclaw.d.ts",
     "openclaw.js",
     "openclaw.plugin.json",
-    "skills"
+    "skills",
+    "plugins"
   ]
 }

package/plugins/hermes/README.md

@@ -0,0 +1,78 @@
+# GoPlus AgentGuard — Hermes plugin
+
+A native [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin that
+runs every tool call through the [GoPlus AgentGuard](https://github.com/GoPlusSecurity/agentguard)
+decision engine and **blocks risky shell, file, and network actions** before they
+execute.
+
+Unlike the shell-hook integration (which you wire into `~/.hermes/config.yaml` by
+hand), this plugin is managed the Hermes-native way — `hermes plugins
+enable/disable/list` — runs before shell hooks, and adds a `/agentguard` slash
+command. It reuses the same AgentGuard engine, so detection logic stays in one
+place.
+
+## Requirements
+
+- Hermes Agent (with the plugin system).
+- The AgentGuard engine reachable as the `agentguard` CLI on `PATH`
+  (`npm i -g @goplus/agentguard`), or pointed at via `AGENTGUARD_BIN` /
+  `AGENTGUARD_HERMES_HOOK`.
+
+## Install
+
+```bash
+# Installs the plugin into ~/.hermes/plugins/agentguard/
+agentguard init --agent hermes
+
+# Confirm it is enabled:
+hermes plugins list
+```
+
+Or copy this directory to `~/.hermes/plugins/agentguard/` manually.
+
+## What it does
+
+| Hermes hook        | Behavior                                                        |
+|--------------------|-----------------------------------------------------------------|
+| `pre_tool_call`    | Evaluates the call; returns `{"action":"block","message":...}` to veto a dangerous action. |
+| `post_tool_call`   | Audit-only; never blocks.                                       |
+| `on_session_start` | Best-effort background scan of installed skills (opt out: `AGENTGUARD_HERMES_AUTOSCAN=0`). |
+| `/agentguard`      | Slash command — `status`, `report` (default), or `checkup`.     |
+
+Tools evaluated (others pass through untouched): `terminal`, `execute_code`,
+`write_file`, `patch`, `skill_manage`, `read_file`, `web_search`, `web_extract`,
+`browser_navigate`, `browser_open`, `web_open`, `open_url`, `visit_url`, `open`.
+
+Hermes `pre_tool_call` has no native "ask"/confirm decision, so AgentGuard's
+*confirm* decisions are surfaced as blocks with a confirmation-oriented message.
+
+## Configuration
+
+| Env var | Default | Effect |
+|---------|---------|--------|
+| `AGENTGUARD_BIN` | — | Explicit path to the `agentguard` CLI. |
+| `AGENTGUARD_HERMES_HOOK` | — | Explicit path to `hermes-hook.js` (used instead of the CLI). |
+| `AGENTGUARD_HERMES_TIMEOUT` | `10` | Per-call engine timeout (seconds). |
+| `AGENTGUARD_HERMES_FAIL_OPEN` | `0` | `1` allows tool calls when the engine can't be reached (default fails closed). |
+| `AGENTGUARD_HERMES_ALLOW_NPX` | `0` | `1` permits the `npx -y @goplus/agentguard` fallback when no local binary is found. Off by default — `npx` fetches an unpinned package over the network, which is unsafe for a security gate. |
+| `AGENTGUARD_HERMES_AUTOSCAN` | `1` | `0` disables the session-start skill scan. |
+
+**Activation:** `agentguard init --agent hermes` installs the plugin and enables
+it in `~/.hermes/config.yaml`. It takes effect on the next Hermes session. If you
+copy this directory manually, run `hermes plugins enable agentguard`.
+
+**Fail policy:** for the security-sensitive tools above, the plugin fails
+**closed** (blocks) on `pre_tool_call` when the engine cannot be reached, and also
+when a mapped event arrives without its required field (e.g. `terminal` with no
+`command`) — matching the shell-hook behavior. Out-of-scope tools pass through
+without an engine call. Post-tool evaluation never blocks.
+
+## Development / tests
+
+```bash
+cd plugins/hermes
+python -m pytest        # no Node engine required — the bridge is stubbed
+```
+
+Tests stub the engine via an injected runner, so they exercise the allow / block /
+confirm→block / post-audit / fail-mode contract without spawning a subprocess.

package/plugins/hermes/__init__.py

@@ -0,0 +1,13 @@
+"""GoPlus AgentGuard native plugin for Hermes Agent.
+
+Hermes imports this package and calls :func:`register` at load time.
+"""
+
+from __future__ import annotations
+
+try:  # package context (installed under ~/.hermes/plugins/agentguard/)
+    from .plugin import register
+except ImportError:  # top-level module context (tests / ad-hoc)
+    from plugin import register
+
+__all__ = ["register"]