@goplus/agentguard 1.1.1 → 1.1.4

package/docs/openclaw.md

@@ -0,0 +1,41 @@
+# OpenClaw
+
+OpenClaw can use AgentGuard as a local runtime guard and optional Cloud-connected audit source.
+
+## Plugin usage
+
+To write a starter plugin file in the current project:
+
+```bash
+agentguard init --agent openclaw
+```
+
+This creates `openclaw.agentguard.plugin.ts`.
+
+```ts
+import { registerOpenClawPlugin } from '@goplus/agentguard';
+
+export default function setup(api) {
+  registerOpenClawPlugin(api, {
+    level: 'balanced',
+    skipAutoScan: false,
+  });
+}
+```
+
+## Runtime hook shape
+
+For direct hook integration, send events to:
+
+```bash
+AGENTGUARD_AGENT_HOST=openclaw \
+AGENTGUARD_ACTION_TYPE=shell \
+AGENTGUARD_TOOL_NAME=exec \
+agentguard protect
+```
+
+AgentGuard accepts OpenClaw-style JSON with `toolName` and `params`, plus Claude-style `tool_name` and `tool_input`.
+
+## Docker demo
+
+See `examples/openclaw-docker/` for a minimal Docker demo that installs `@goplus/agentguard`, runs `agentguard init --agent openclaw`, and provides a starter plugin.

package/docs/privacy-boundary.md

@@ -0,0 +1,37 @@
+# OSS / Cloud Privacy Boundary
+
+AgentGuard OSS protects your machine without requiring a Cloud account.
+
+## Stays local by default
+
+- Full prompts
+- Full file contents
+- Full command output
+- Full secrets and private keys
+- Local audit file at `~/.agentguard/audit.jsonl`
+- Cached policy at `~/.agentguard/policy-cache.json`
+
+## Sent to Cloud when connected
+
+Only redacted runtime audit previews are uploaded by default:
+
+- `sessionId`, `agentHost`, `actionType`, `toolName`
+- Redacted `input` preview, capped at 2,000 characters
+- Decision, risk score, risk level, reasons, and policy version
+- Optional approval request metadata for `require_approval`
+
+## Built-in redaction
+
+AgentGuard redacts common sensitive values before Cloud sync:
+
+- AgentGuard/OpenAI-style API keys
+- `Bearer` tokens
+- `token=`, `api_key=`, `secret=`, `password=`, and similar query/env values
+- Private key PEM blocks
+- URL credentials and sensitive query parameters
+
+Cloud endpoints also apply server-side redaction, but clients should not rely on server redaction as the first line of defense.
+
+## Offline behavior
+
+If Cloud is unreachable, AgentGuard continues local enforcement and spools redacted audit events for later retry. It must never fail open for local `block` decisions.

package/docs/sdk.md

@@ -0,0 +1,83 @@
+# SDK Usage
+
+Use GoPlus AgentGuard as a library in your own project.
+
+## Installation
+
+```bash
+npm install @goplus/agentguard
+```
+
+## Quick Start
+
+```typescript
+import { createAgentGuard } from '@goplus/agentguard';
+
+const { scanner, registry, actionScanner } = createAgentGuard();
+```
+
+## Scan Code
+
+```typescript
+const result = await scanner.scan({
+  skill: {
+    id: 'my-skill',
+    source: 'github.com/org/skill',
+    version_ref: 'v1.0.0',
+    artifact_hash: '',
+  },
+  payload: { type: 'dir', ref: '/path/to/skill' },
+});
+
+console.log(result.risk_level); // 'low' | 'medium' | 'high' | 'critical'
+console.log(result.hits);       // Array of detection rule matches
+```
+
+## Evaluate Actions
+
+```typescript
+const decision = await actionScanner.decide({
+  actor: {
+    skill: { id: 'my-skill', source: 'cli', version_ref: '1.0.0', artifact_hash: '' },
+  },
+  action: {
+    type: 'exec_command',
+    data: { command: 'rm -rf /' },
+  },
+  context: {
+    session_id: 's1',
+    user_present: true,
+    env: 'prod',
+    time: new Date().toISOString(),
+  },
+});
+
+console.log(decision.decision); // 'allow' | 'deny' | 'confirm'
+```
+
+## Trust Registry
+
+```typescript
+// Register a skill
+await registry.attest({
+  skill: { id: 'bot', source: 'github.com/org/bot', version_ref: 'v1.0.0', artifact_hash: 'sha256:abc' },
+  trust_level: 'trusted',
+  capabilities: { network_allowlist: ['api.example.com'], filesystem_allowlist: [], exec: 'deny', secrets_allowlist: [] },
+  review: { reviewed_by: 'admin', evidence_refs: [], notes: 'Verified safe' },
+});
+
+// Look up
+const result = await registry.lookup({
+  id: 'bot', source: 'github.com/org/bot', version_ref: 'v1.0.0', artifact_hash: 'sha256:abc',
+});
+console.log(result.effective_trust_level); // 'trusted'
+```
+
+## API Reference
+
+See the TypeScript types exported from `@goplus/agentguard` for full API details:
+
+- `SkillScanner` — Static analysis engine
+- `SkillRegistry` — Trust level management
+- `ActionScanner` — Runtime action evaluator
+- `CAPABILITY_PRESETS` — Predefined capability sets (none, read_only, trading_bot, defi)

package/docs/trust-cli.md

@@ -0,0 +1,58 @@
+# Trust Management
+
+GoPlus AgentGuard includes a trust registry for managing skill permissions.
+
+## Commands
+
+### Attest (Register a Skill)
+
+```
+/agentguard trust attest --id my-bot --source github.com/org/bot --version v1.0.0 --hash abc --trust-level restricted --preset trading_bot --reviewed-by admin
+```
+
+### Lookup
+
+```
+/agentguard trust lookup --source github.com/org/bot
+```
+
+### Revoke
+
+```
+/agentguard trust revoke --source github.com/org/bot --reason "security concern"
+```
+
+### List
+
+```
+/agentguard trust list --trust-level trusted
+```
+
+## Trust Levels
+
+| Level | Description |
+|-------|-------------|
+| `trusted` | Full access per its capability model |
+| `restricted` | Limited access, some actions require confirmation |
+| `untrusted` | Minimal access, most actions blocked or require confirmation |
+
+## Capability Presets
+
+| Preset | Network | Filesystem | Exec | Secrets | Web3 |
+|--------|---------|------------|------|---------|------|
+| `none` | No | No | No | No | No |
+| `read_only` | No | Read `./**` | No | No | No |
+| `trading_bot` | Binance, Bybit, OKX, Coinbase, Dextools, CoinGecko | `./config/**`, `./logs/**` | No | `*_API_KEY`, `*_API_SECRET` | Chains 1, 56, 137, 42161 |
+| `defi` | All | No | No | No | Chains 1, 56, 137, 42161, 10, 8453, 43114 |
+
+## Auto-Scan on Session Start
+
+When installed as a Claude Code plugin, AgentGuard automatically scans new skills on session start:
+
+- Discovers skills in `~/.claude/skills/`
+- Calculates artifact hash and checks the registry
+- Runs `quickScan` on new or updated skills
+- Auto-registers with trust level based on scan results:
+  - Low risk → `trusted`
+  - Medium risk → `restricted`
+  - High/Critical risk → `untrusted`

package/examples/openclaw-docker/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:22-slim
+
+WORKDIR /workspace
+
+RUN npm install -g @goplus/agentguard
+RUN agentguard init --agent openclaw
+
+COPY plugin.ts ./plugin.ts
+
+CMD ["node", "-e", "console.log('AgentGuard OpenClaw demo ready. Mount your OpenClaw workspace and register plugin.ts.')"]

package/examples/openclaw-docker/README.md

@@ -0,0 +1,16 @@
+# OpenClaw Docker Demo
+
+This demo shows the minimal AgentGuard runtime wiring for OpenClaw.
+
+```bash
+docker compose build
+docker compose run --rm agentguard-openclaw-demo
+```
+
+In a real OpenClaw workspace, register `plugin.ts` as a plugin. It uses `registerOpenClawPlugin` to scan loaded skills/plugins and evaluate runtime tool calls before execution.
+
+For Cloud policy and audit sync:
+
+```bash
+AGENTGUARD_API_KEY=ag_live_xxxxx agentguard connect --url https://agentguard.gopluslabs.io
+```

package/examples/openclaw-docker/docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  agentguard-openclaw-demo:
+    build: .
+    working_dir: /workspace
+    volumes:
+      - .:/workspace/demo
+    environment:
+      AGENTGUARD_AGENT_HOST: openclaw

package/examples/openclaw-docker/plugin.ts

@@ -0,0 +1,8 @@
+import { registerOpenClawPlugin } from '@goplus/agentguard';
+
+export default function setup(api) {
+  registerOpenClawPlugin(api, {
+    level: 'balanced',
+    skipAutoScan: false,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplus/agentguard",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "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",
@@ -10,13 +10,16 @@
     ]
   },
   "bin": {
-    "agentguard": "./dist/mcp-server.js"
+    "agentguard": "./dist/cli.js",
+    "agentguard-mcp": "./dist/mcp-server.js"
   },
   "scripts": {
     "build": "tsc",
     "start": "node dist/mcp-server.js",
     "dev": "tsc -w",
     "test": "node --test dist/tests/*.test.js",
+    "test:cloud-live": "node --test dist/tests/cloud-live.test.js",
+    "postinstall": "node dist/postinstall.js || true",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -59,6 +62,8 @@
   },
   "files": [
     "dist",
+    "docs",
+    "examples/openclaw-docker",
     "README.md",
     "LICENSE",
     "openclaw.plugin.json",

package/skills/agentguard/SKILL.md

@@ -7,6 +7,25 @@ metadata:
   author: GoPlusSecurity
   version: "1.1"
   optional_env: "GOPLUS_API_KEY, GOPLUS_API_SECRET (for Web3 transaction simulation only)"
+filesystem-access:
+  - path: "~/.ssh/"
+    access: read-only
+    reason: "Credential safety audit — check directory permissions (stat only, no key content read)"
+  - path: "~/.gnupg/"
+    access: read-only
+    reason: "Credential safety audit — check directory permissions (stat only)"
+  - path: "~/.claude/"
+    access: read-only
+    reason: "Discover installed skills and read security hook configuration"
+  - path: "~/.openclaw/"
+    access: read-only
+    reason: "Discover installed skills and read OpenClaw config for patrol checks"
+  - path: "~/.qclaw/"
+    access: read-only
+    reason: "Discover installed skills in QClaw environments"
+  - path: "~/.agentguard/"
+    access: read-write
+    reason: "Read/write audit log (audit.jsonl) and protection level config (config.json)"
 user-invocable: true
 allowed-tools: Read, Write, Grep, Glob, Bash(node *trust-cli.ts *) Bash(node *action-cli.ts *) Bash(*checkup-report.js) Bash(echo *checkup-report.js) Bash(cat *checkup-report.js) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *) Bash(node *) Bash(cd *)
 argument-hint: "[scan|action|patrol|trust|report|config|checkup] [args...]"

package/skills/agentguard/package.json

@@ -2,6 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@goplus/agentguard": "^1.0.6"
+    "@goplus/agentguard": "^1.0.6",
+    "open": "11.0.0"
   }
 }

package/skills/agentguard/scripts/checkup-report.js

@@ -15,7 +15,7 @@
 import { writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { tmpdir, homedir } from 'node:os';
-import { exec, spawn } from 'node:child_process';
+import open from 'open';
 import { fileURLToPath } from 'node:url';
 
 const DIM_META = {
@@ -1376,20 +1376,7 @@ body{background:#0a0e14;color:#dfe2eb;font-family:'Inter',sans-serif}
   // the buffer is flushed, causing the caller (Claude) to receive an empty path.
   process.stdout.write(outPath + '\n', () => {
     if (!isHeadless) {
-      if (process.platform === 'win32') {
-        // Use PowerShell Start-Process to open the file via Shell Execute API,
-        // bypassing cmd.exe entirely — cmd /c start creates a visible intermediate
-        // window whose title is the file path, which is the UX bug in #23.
-        spawn('powershell', [
-          '-NoProfile', '-WindowStyle', 'Hidden', '-Command',
-          `Start-Process '${outPath.replace(/'/g, "''")}'`,
-        ], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
-      } else {
-        const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
-        exec(`${cmd} "${outPath}"`, (err) => {
-          if (err) process.stderr.write(`Could not open browser: ${err.message}\n`);
-        });
-      }
+      open(outPath).catch(err => process.stderr.write(`Could not open browser: ${err.message}\n`));
     }
     // Hard exit after 3s — guards against exec child process hanging and
     // blocking Node from exiting naturally (e.g. xdg-open on misconfigured Linux).