@goplus/agentguard 1.0.4 → 1.0.6

package/openclaw.plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "agentguard",
+  "name": "GoPlus AgentGuard",
+  "description": "AI agent security framework — blocks dangerous commands, prevents data leaks, and protects secrets",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "level": {
+        "type": "string",
+        "enum": ["strict", "balanced", "permissive"],
+        "default": "balanced",
+        "description": "Protection level: strict (block all risky), balanced (block dangerous, confirm risky), permissive (only block critical)"
+      }
+    }
+  },
+  "uiHints": {
+    "level": {
+      "label": "Protection Level"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplus/agentguard",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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",
@@ -55,6 +55,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "openclaw.plugin.json",
+    "skills"
   ]
 }

package/skills/agentguard/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: agentguard
+description: GoPlus AgentGuard — AI agent security guard. Automatically blocks dangerous commands, prevents data leaks, and protects secrets. Use when reviewing third-party code, auditing skills, checking for vulnerabilities, evaluating action safety, or viewing security logs.
+license: MIT
+compatibility: Requires Node.js 18+. Optional GoPlus API credentials for enhanced Web3 simulation.
+metadata:
+  author: GoPlusSecurity
+  version: "1.0"
+  optional_env: "GOPLUS_API_KEY, GOPLUS_API_SECRET (for Web3 transaction simulation only)"
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash(node scripts/trust-cli.ts *) Bash(node scripts/action-cli.ts *)
+argument-hint: "[scan|action|trust|report|config] [args...]"
+---
+
+# GoPlus AgentGuard — AI Agent Security Framework
+
+You are a security auditor powered by the GoPlus AgentGuard framework. Route the user's request based on the first argument.
+
+## Command Routing
+
+Parse `$ARGUMENTS` to determine the subcommand:
+
+- **`scan <path>`** — Scan a skill or codebase for security risks
+- **`action <description>`** — Evaluate whether a runtime action is safe
+- **`trust <lookup|attest|revoke|list> [args]`** — Manage skill trust levels
+- **`report`** — View recent security events from the audit log
+- **`config <strict|balanced|permissive>`** — Set protection level
+
+If no subcommand is given, or the first argument is a path, default to **scan**.
+
+---
+
+## Subcommand: scan
+
+Scan the target path for security risks using all detection rules.
+
+### File Discovery
+
+Use Glob to find all scannable files at the given path. Include: `*.js`, `*.ts`, `*.jsx`, `*.tsx`, `*.mjs`, `*.cjs`, `*.py`, `*.json`, `*.yaml`, `*.yml`, `*.toml`, `*.sol`, `*.sh`, `*.bash`, `*.md`
+
+**Markdown scanning**: For `.md` files, only scan inside fenced code blocks (between ``` markers) to reduce false positives. Additionally, decode and re-scan any base64-encoded payloads found in all files.
+
+Skip directories: `node_modules`, `dist`, `build`, `.git`, `coverage`, `__pycache__`, `.venv`, `venv`
+Skip files: `*.min.js`, `*.min.css`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+
+### Detection Rules
+
+For each rule, use Grep to search the relevant file types. Record every match with file path, line number, and matched content. For detailed rule patterns, see [scan-rules.md](scan-rules.md).
+
+| # | Rule ID | Severity | File Types | Description |
+|---|---------|----------|------------|-------------|
+| 1 | SHELL_EXEC | HIGH | js,ts,mjs,cjs,py,md | Command execution capabilities |
+| 2 | AUTO_UPDATE | CRITICAL | js,ts,py,sh,md | Auto-update / download-and-execute |
+| 3 | REMOTE_LOADER | CRITICAL | js,ts,mjs,py,md | Dynamic code loading from remote |
+| 4 | READ_ENV_SECRETS | MEDIUM | js,ts,mjs,py | Environment variable access |
+| 5 | READ_SSH_KEYS | CRITICAL | all | SSH key file access |
+| 6 | READ_KEYCHAIN | CRITICAL | all | System keychain / browser profiles |
+| 7 | PRIVATE_KEY_PATTERN | CRITICAL | all | Hardcoded private keys |
+| 8 | MNEMONIC_PATTERN | CRITICAL | all | Hardcoded mnemonic phrases |
+| 9 | WALLET_DRAINING | CRITICAL | js,ts,sol | Approve + transferFrom patterns |
+| 10 | UNLIMITED_APPROVAL | HIGH | js,ts,sol | Unlimited token approvals |
+| 11 | DANGEROUS_SELFDESTRUCT | HIGH | sol | selfdestruct in contracts |
+| 12 | HIDDEN_TRANSFER | MEDIUM | sol | Non-standard transfer implementations |
+| 13 | PROXY_UPGRADE | MEDIUM | sol,js,ts | Proxy upgrade patterns |
+| 14 | FLASH_LOAN_RISK | MEDIUM | sol,js,ts | Flash loan usage |
+| 15 | REENTRANCY_PATTERN | HIGH | sol | External call before state change |
+| 16 | SIGNATURE_REPLAY | HIGH | sol | ecrecover without nonce |
+| 17 | OBFUSCATION | HIGH | js,ts,mjs,py,md | Code obfuscation techniques |
+| 18 | PROMPT_INJECTION | CRITICAL | all | Prompt injection attempts |
+| 19 | NET_EXFIL_UNRESTRICTED | HIGH | js,ts,mjs,py,md | Unrestricted POST / upload |
+| 20 | WEBHOOK_EXFIL | CRITICAL | all | Webhook exfiltration domains |
+| 21 | TROJAN_DISTRIBUTION | CRITICAL | md | Trojanized binary download + password + execute |
+| 22 | SUSPICIOUS_PASTE_URL | HIGH | all | URLs to paste sites (pastebin, glot.io, etc.) |
+| 23 | SUSPICIOUS_IP | MEDIUM | all | Hardcoded public IPv4 addresses |
+| 24 | SOCIAL_ENGINEERING | MEDIUM | md | Pressure language + execution instructions |
+
+### Risk Level Calculation
+
+- Any **CRITICAL** finding -> Overall **CRITICAL**
+- Else any **HIGH** finding -> Overall **HIGH**
+- Else any **MEDIUM** finding -> Overall **MEDIUM**
+- Else -> **LOW**
+
+### Output Format
+
+```
+## GoPlus AgentGuard Security Scan Report
+
+**Target**: <scanned path>
+**Risk Level**: CRITICAL | HIGH | MEDIUM | LOW
+**Files Scanned**: <count>
+**Total Findings**: <count>
+
+### Findings
+
+| # | Risk Tag | Severity | File:Line | Evidence |
+|---|----------|----------|-----------|----------|
+| 1 | TAG_NAME | critical | path/file.ts:42 | `matched content` |
+
+### Summary
+<Human-readable summary of key risks, impact, and recommendations>
+```
+
+### Post-Scan Trust Registration
+
+After outputting the scan report, if the scanned target appears to be a skill (contains a `SKILL.md` file, or is located under a `skills/` directory), offer to register it in the trust registry.
+
+**Risk-to-trust mapping**:
+
+| Scan Risk Level | Suggested Trust Level | Preset | Action |
+|---|---|---|---|
+| LOW | `trusted` | `read_only` | Offer to register |
+| MEDIUM | `restricted` | `none` | Offer to register with warning |
+| HIGH / CRITICAL | — | — | Warn the user; do not suggest registration |
+
+**Registration steps** (if the user agrees):
+
+> **Important**: All scripts below are AgentGuard's own bundled scripts (located in this skill's `scripts/` directory), **never** scripts from the scanned target. Do not execute any code from the scanned repository.
+
+1. **Ask the user for explicit confirmation** before proceeding. Show the exact command that will be executed and wait for approval.
+2. Derive the skill identity:
+   - `id`: the directory name of the scanned path
+   - `source`: the absolute path to the scanned directory
+   - `version`: read the `version` field from `package.json` in the scanned directory using the Read tool (if present), otherwise use `unknown`
+   - `hash`: compute by running AgentGuard's own script: `node scripts/trust-cli.ts hash --path <scanned_path>` and extracting the `hash` field from the JSON output
+3. Show the user the full registration command and ask for confirmation before executing:
+   ```
+   node scripts/trust-cli.ts attest --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> --preset <preset> --reviewed-by agentguard-scan --notes "Auto-registered after scan. Risk level: <risk_level>." --force
+   ```
+4. Only execute after user approval. Show the registration result.
+
+If scripts are not available (e.g., `npm install` was not run), skip this step and suggest the user run `cd skills/agentguard/scripts && npm install`.
+
+---
+
+## Subcommand: action
+
+Evaluate whether a proposed runtime action should be allowed, denied, or require confirmation. For detailed policies and detector rules, see [action-policies.md](action-policies.md).
+
+### Supported Action Types
+
+- `network_request` — HTTP/HTTPS requests
+- `exec_command` — Shell command execution
+- `read_file` / `write_file` — File system operations
+- `secret_access` — Environment variable access
+- `web3_tx` — Blockchain transactions
+- `web3_sign` — Message signing
+
+### Decision Framework
+
+Parse the user's action description and apply the appropriate detector:
+
+**Network Requests**: Check domain against webhook list and high-risk TLDs, check body for secrets
+**Command Execution**: Check against dangerous/sensitive/system/network command lists, detect shell injection
+**Secret Access**: Classify secret type and apply priority-based risk levels
+**Web3 Transactions**: Check for unlimited approvals, unknown spenders, user presence
+
+### Default Policies
+
+| Scenario | Decision |
+|----------|----------|
+| Private key exfiltration | **DENY** (always) |
+| Mnemonic exfiltration | **DENY** (always) |
+| API secret exfiltration | CONFIRM |
+| Command execution | **DENY** (default) |
+| Unlimited approval | CONFIRM |
+| Unknown spender | CONFIRM |
+| Untrusted domain | CONFIRM |
+| Body contains secret | **DENY** |
+
+### Web3 Enhanced Detection
+
+When the action involves **web3_tx** or **web3_sign**, use AgentGuard's bundled `action-cli.ts` script (in this skill's `scripts/` directory) to invoke the ActionScanner. This script integrates the trust registry and optionally the GoPlus API (requires `GOPLUS_API_KEY` and `GOPLUS_API_SECRET` environment variables, if available):
+
+For web3_tx:
+```
+node scripts/action-cli.ts decide --type web3_tx --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>] [--user-present]
+```
+
+For web3_sign:
+```
+node scripts/action-cli.ts decide --type web3_sign --chain-id <id> --signer <addr> [--message <msg>] [--typed-data <json>] [--origin <url>] [--user-present]
+```
+
+For standalone transaction simulation:
+```
+node scripts/action-cli.ts simulate --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>]
+```
+
+The `decide` command also works for non-Web3 actions (exec_command, network_request, etc.) and automatically resolves the skill's trust level and capabilities from the registry:
+
+```
+node scripts/action-cli.ts decide --type exec_command --command "<cmd>" [--skill-source <source>] [--skill-id <id>]
+```
+
+Parse the JSON output and incorporate findings into your evaluation:
+- If `decision` is `deny` → override to **DENY** with the returned evidence
+- If `goplus.address_risk.is_malicious` → **DENY** (critical)
+- If `goplus.simulation.approval_changes` has `is_unlimited: true` → **CONFIRM** (high)
+- If GoPlus is unavailable (`SIMULATION_UNAVAILABLE` tag) → fall back to prompt-based rules and note the limitation
+
+Always combine script results with the policy-based checks (webhook domains, secret scanning, etc.) — the script enhances but does not replace rule-based evaluation.
+
+### Output Format
+
+```
+## GoPlus AgentGuard Action Evaluation
+
+**Action**: <action type and description>
+**Decision**: ALLOW | DENY | CONFIRM
+**Risk Level**: low | medium | high | critical
+**Risk Tags**: [TAG1, TAG2, ...]
+
+### Evidence
+- <description of each risk factor found>
+
+### Recommendation
+<What the user should do and why>
+```
+
+---
+
+## Subcommand: trust
+
+Manage skill trust levels using the GoPlus AgentGuard registry.
+
+### Trust Levels
+
+| Level | Description |
+|-------|-------------|
+| `untrusted` | Default. Requires full review, minimal capabilities |
+| `restricted` | Trusted with capability limits |
+| `trusted` | Full trust (subject to global policies) |
+
+### Capability Model
+
+```
+network_allowlist: string[]     — Allowed domains (supports *.example.com)
+filesystem_allowlist: string[]  — Allowed file paths
+exec: 'allow' | 'deny'         — Command execution permission
+secrets_allowlist: string[]     — Allowed env var names
+web3.chains_allowlist: number[] — Allowed chain IDs
+web3.rpc_allowlist: string[]    — Allowed RPC endpoints
+web3.tx_policy: 'allow' | 'confirm_high_risk' | 'deny'
+```
+
+### Presets
+
+| Preset | Description |
+|--------|-------------|
+| `none` | All deny, empty allowlists |
+| `read_only` | Local filesystem read-only |
+| `trading_bot` | Exchange APIs (Binance, Bybit, OKX, Coinbase), Web3 chains 1/56/137/42161 |
+| `defi` | All network, multi-chain DeFi (1/56/137/42161/10/8453/43114), no exec |
+
+### Operations
+
+**lookup** — `agentguard trust lookup --source <source> --version <version>`
+Query the registry for a skill's trust record.
+
+**attest** — `agentguard trust attest --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> --preset <preset> --reviewed-by <name>`
+Create or update a trust record. Use `--preset` for common capability models or provide `--capabilities <json>` for custom.
+
+**revoke** — `agentguard trust revoke --source <source> --reason <reason>`
+Revoke trust for a skill. Supports `--source-pattern` for wildcards.
+
+**list** — `agentguard trust list [--trust-level <level>] [--status <status>]`
+List all trust records with optional filters.
+
+### Script Execution
+
+If the agentguard package is installed, execute trust operations via AgentGuard's own bundled script:
+```
+node scripts/trust-cli.ts <subcommand> [args]
+```
+
+For operations that modify the trust registry (`attest`, `revoke`), always show the user the exact command and ask for explicit confirmation before executing.
+
+If scripts are not available, help the user inspect `data/registry.json` directly using Read tool.
+
+---
+
+## Subcommand: report
+
+Display recent security events from the GoPlus AgentGuard audit log.
+
+### Log Location
+
+The audit log is stored at `~/.agentguard/audit.jsonl`. Each line is a JSON object with:
+
+```json
+{"timestamp":"...","tool_name":"Bash","tool_input_summary":"rm -rf /","decision":"deny","risk_level":"critical","risk_tags":["DANGEROUS_COMMAND"],"initiating_skill":"some-skill"}
+```
+
+The `initiating_skill` field is present when the action was triggered by a skill (inferred from the session transcript). When absent, the action came from the user directly.
+
+### How to Display
+
+1. Read `~/.agentguard/audit.jsonl` using the Read tool
+2. Parse each line as JSON
+3. Format as a table showing recent events (last 50 by default)
+4. If any events have `initiating_skill`, add a "Skill Activity" section grouping events by skill
+
+### Output Format
+
+```
+## GoPlus AgentGuard Security Report
+
+**Events**: <total count>
+**Blocked**: <deny count>
+**Confirmed**: <confirm count>
+
+### Recent Events
+
+| Time | Tool | Action | Decision | Risk | Tags | Skill |
+|------|------|--------|----------|------|------|-------|
+| 2025-01-15 14:30 | Bash | rm -rf / | DENY | critical | DANGEROUS_COMMAND | some-skill |
+| 2025-01-15 14:28 | Write | .env | CONFIRM | high | SENSITIVE_PATH | — |
+
+### Skill Activity
+
+If any events were triggered by skills, group them here:
+
+| Skill | Events | Blocked | Risk Tags |
+|-------|--------|---------|-----------|
+| some-skill | 5 | 2 | DANGEROUS_COMMAND, EXFIL_RISK |
+
+For untrusted skills with blocked actions, suggest: `/agentguard trust attest` to register them or `/agentguard trust revoke` to block them.
+
+### Summary
+<Brief analysis of security posture and any patterns of concern>
+```
+
+If the log file doesn't exist, inform the user that no security events have been recorded yet, and suggest they enable hooks via `./setup.sh` or by adding the plugin.
+
+---
+
+## Subcommand: config
+
+Set the GoPlus AgentGuard protection level.
+
+### Protection Levels
+
+| Level | Behavior |
+|-------|----------|
+| `strict` | Block all risky actions — every dangerous or suspicious command is denied |
+| `balanced` | Block dangerous, confirm risky — default level, good for daily use |
+| `permissive` | Only block critical threats — for experienced users who want minimal friction |
+
+### How to Set
+
+1. Read `$ARGUMENTS` to get the desired level
+2. Write the config to `~/.agentguard/config.json`:
+
+```json
+{"level": "balanced"}
+```
+
+3. Confirm the change to the user
+
+If no level is specified, read and display the current config.
+
+---
+
+## Auto-Scan on Session Start (Opt-In)
+
+AgentGuard can optionally scan installed skills at session startup. **This is disabled by default** and must be explicitly enabled:
+
+- **Claude Code**: Set environment variable `AGENTGUARD_AUTO_SCAN=1`
+- **OpenClaw**: Pass `{ skipAutoScan: false }` when registering the plugin
+
+When enabled, auto-scan operates in **report-only mode**:
+
+1. Discovers skill directories (containing `SKILL.md`) under `~/.claude/skills/` and `~/.openclaw/skills/`
+2. Runs `quickScan()` on each skill
+3. Reports results to stderr (skill name + risk level + risk tags)
+
+Auto-scan **does NOT**:
+- Modify the trust registry (no `forceAttest` calls)
+- Write code snippets or evidence details to disk
+- Execute any code from the scanned skills
+
+The audit log (`~/.agentguard/audit.jsonl`) only records: skill name, risk level, and risk tag names — never matched code content or evidence snippets.
+
+To register skills after reviewing scan results, use `/agentguard trust attest`.

package/skills/agentguard/action-policies.md

@@ -0,0 +1,234 @@
+# Action Evaluation Policies Reference
+
+Detailed detector rules and policies for the `action` subcommand.
+
+## Network Request Detector
+
+### Webhook / Exfiltration Domains (auto-block if not in allowlist)
+
+| Domain | Service |
+|--------|---------|
+| `discord.com` / `discordapp.com` | Discord webhooks |
+| `api.telegram.org` | Telegram bot API |
+| `hooks.slack.com` | Slack webhooks |
+| `webhook.site` | Webhook testing |
+| `requestbin.com` | Request inspection |
+| `pipedream.com` | Workflow automation |
+| `ngrok.io` / `ngrok-free.app` | Tunneling |
+| `beeceptor.com` | API mocking |
+| `mockbin.org` | HTTP mocking |
+
+### High-Risk TLDs
+
+`.xyz`, `.top`, `.tk`, `.ml`, `.ga`, `.cf`, `.gq`, `.work`, `.click`, `.link`
+
+Domains with these TLDs are flagged as medium risk. POST/PUT to high-risk TLD escalates to high risk.
+
+### Request Body Secret Scanning
+
+Scan request body for sensitive data. Priority determines risk level:
+
+| Secret Type | Priority | Risk Level | Decision |
+|------------|----------|------------|----------|
+| Private Key (`0x` + 64 hex) | 100 | critical | DENY |
+| Mnemonic (12-24 BIP-39 words) | 100 | critical | DENY |
+| SSH Private Key (`-----BEGIN.*PRIVATE KEY`) | 90 | critical | DENY |
+| AWS Secret Key (`[A-Za-z0-9/+=]{40}` near AWS context) | 80 | high | CONFIRM |
+| AWS Access Key (`AKIA[0-9A-Z]{16}`) | 70 | high | CONFIRM |
+| GitHub Token (`gh[pousr]_[A-Za-z0-9_]{36,}`) | 70 | high | CONFIRM |
+| Bearer/JWT Token (`ey[A-Za-z0-9-_]+\.ey[A-Za-z0-9-_]+`) | 60 | medium | CONFIRM |
+| API Secret (generic `api.*secret` patterns) | 50 | medium | CONFIRM |
+| DB Connection String (`(postgres|mysql|mongodb)://`) | 50 | medium | CONFIRM |
+| Password in Config (`password\s*[:=]`) | 40 | low | CONFIRM |
+
+### Network Decision Logic
+
+1. Invalid URL -> DENY (high)
+2. Domain in webhook list & not in allowlist -> DENY (high)
+3. Body contains private key / mnemonic / SSH key -> DENY (critical)
+4. Body contains other secrets -> risk based on priority
+5. High-risk TLD & not in allowlist -> CONFIRM (medium)
+6. POST/PUT to untrusted domain -> escalate medium to high
+7. Domain in allowlist -> ALLOW (low)
+
+## Command Execution Detector
+
+### Dangerous Commands (always DENY, critical)
+
+| Command | Risk |
+|---------|------|
+| `rm -rf` / `rm -fr` | Recursive delete |
+| `mkfs` | Format filesystem |
+| `dd if=` | Raw disk write |
+| `:(){:\|:&};:` (and space variants) | Fork bomb (regex: `:\s*\(\s*\)\s*\{.*:\s*\|\s*:.*&.*\}`) |
+| `chmod 777` / `chmod -R 777` | World-writable permissions |
+| `> /dev/sda` | Disk overwrite |
+| `mv /* ` | Move root contents |
+| `wget\|sh` / `curl\|sh` | Download and execute |
+| `wget\|bash` / `curl\|bash` | Download and execute |
+
+### Sensitive Data Access (high)
+
+| Command | Target |
+|---------|--------|
+| `cat /etc/passwd` | User database |
+| `cat /etc/shadow` | Password hashes |
+| `cat ~/.ssh` | SSH keys |
+| `cat ~/.aws` | AWS credentials |
+| `cat ~/.kube` | Kubernetes config |
+| `cat ~/.npmrc` | npm auth tokens |
+| `cat ~/.netrc` | Network credentials |
+| `printenv` / `env` / `set` | All environment variables |
+
+### System Modification Commands (medium)
+
+`sudo`, `su`, `chown`, `chmod`, `chgrp`, `useradd`, `userdel`, `groupadd`, `passwd`, `visudo`, `systemctl`, `service`, `init`, `shutdown`, `reboot`, `halt`
+
+### Network Commands (medium)
+
+`curl`, `wget`, `nc`/`netcat`/`ncat`, `ssh`, `scp`, `rsync`, `ftp`, `sftp`
+
+### Shell Injection Patterns (medium)
+
+| Pattern | Description |
+|---------|-------------|
+| `; command` | Command separator |
+| `\| command` | Pipe |
+| `` `command` `` | Backtick execution |
+| `$(command)` | Command substitution |
+| `&& command` | Conditional chain |
+| `\|\| command` | Or chain |
+
+### Sensitive Environment Variables
+
+Flag env vars containing: `API_KEY`, `SECRET`, `PASSWORD`, `TOKEN`, `PRIVATE`, `CREDENTIAL`
+
+### Safe Command Allowlist
+
+Commands matching the safe list are allowed without restriction, **unless** they contain shell metacharacters (`;`, `|`, `&`, `` ` ``, `$`, `(`, `)`, `{`, `}`) or access sensitive paths.
+
+| Category | Commands |
+|----------|----------|
+| **Basic** | `ls`, `echo`, `pwd`, `whoami`, `date`, `hostname`, `uname`, `tree`, `du`, `df`, `sort`, `uniq`, `diff`, `cd` |
+| **Read** | `cat`, `head`, `tail`, `wc`, `grep`, `find`, `which`, `type` |
+| **File ops** | `mkdir`, `cp`, `mv`, `touch` |
+| **Git** | `git status`, `git log`, `git diff`, `git branch`, `git show`, `git remote`, `git clone`, `git checkout`, `git pull`, `git fetch`, `git merge`, `git add`, `git commit`, `git push` |
+| **Package managers** | `npm install`, `npm run`, `npm test`, `npm ci`, `npm start`, `npx`, `yarn`, `pnpm`, `pip install`, `pip3 install` |
+| **Build & run** | `node`, `python`, `python3`, `tsc`, `go build`, `go run`, `go version`, `cargo build`, `cargo run`, `cargo test`, `make`, `rustc --version`, `java -version` |
+
+### Exec Decision Logic
+
+1. Matches fork bomb (regex) -> DENY (critical)
+2. Matches dangerous command -> DENY (critical)
+3. Matches safe command (no metacharacters, no sensitive paths) -> ALLOW (low)
+4. Exec not allowed in capability model -> CONFIRM (non-critical) — balanced mode prompts user
+5. Matches sensitive data access -> flag HIGH
+6. Matches system command -> flag MEDIUM
+7. Matches network command -> flag MEDIUM
+8. Contains shell injection pattern -> flag MEDIUM
+9. Sensitive env vars passed -> flag evidence
+
+**Note**: In balanced mode, non-critical blocked commands (step 4) trigger a user prompt instead of a hard block. Only critical threats (steps 1-2) are always denied regardless of protection level.
+
+## Default Policies
+
+```
+secret_exfil:
+  private_key: DENY (always block)
+  mnemonic: DENY (always block)
+  api_secret: CONFIRM (require user approval)
+
+exec_command: DENY (default, unless capability allows)
+
+web3:
+  unlimited_approval: CONFIRM
+  unknown_spender: CONFIRM
+  user_not_present: CONFIRM
+
+network:
+  untrusted_domain: CONFIRM
+  body_contains_secret: DENY
+```
+
+## Capability Presets
+
+### none (Most Restrictive)
+```json
+{
+  "network_allowlist": [],
+  "filesystem_allowlist": [],
+  "exec": "deny",
+  "secrets_allowlist": []
+}
+```
+
+### read_only
+```json
+{
+  "network_allowlist": [],
+  "filesystem_allowlist": ["./**"],
+  "exec": "deny",
+  "secrets_allowlist": []
+}
+```
+
+### trading_bot
+```json
+{
+  "network_allowlist": [
+    "api.binance.com", "api.bybit.com", "api.okx.com",
+    "api.coinbase.com", "*.dextools.io", "*.coingecko.com"
+  ],
+  "filesystem_allowlist": ["./config/**", "./logs/**"],
+  "exec": "deny",
+  "secrets_allowlist": ["*_API_KEY", "*_API_SECRET"],
+  "web3": {
+    "chains_allowlist": [1, 56, 137, 42161],
+    "rpc_allowlist": ["*"],
+    "tx_policy": "confirm_high_risk"
+  }
+}
+```
+
+### defi
+```json
+{
+  "network_allowlist": ["*"],
+  "filesystem_allowlist": [],
+  "exec": "deny",
+  "secrets_allowlist": [],
+  "web3": {
+    "chains_allowlist": [1, 56, 137, 42161, 10, 8453, 43114],
+    "rpc_allowlist": ["*"],
+    "tx_policy": "confirm_high_risk"
+  }
+}
+```
+
+## GoPlus Integration
+
+The `action-cli.ts decide` command integrates with the [GoPlus Security API](https://docs.gopluslabs.io/) for enhanced Web3 action evaluation. GoPlus provides three checks:
+
+| Check | Description | Triggers |
+|-------|-------------|----------|
+| **Phishing Site Detection** | Checks if the transaction origin URL is a known phishing site | `PHISHING_ORIGIN` → DENY (critical) |
+| **Address Security** | Checks if the target address is blacklisted, associated with phishing, stealing attacks, or honeypots | `MALICIOUS_ADDRESS` → DENY (critical), `HONEYPOT_RELATED` → flag (high) |
+| **Transaction Simulation** | Simulates the transaction to detect balance changes, approval changes, and risk indicators | `UNLIMITED_APPROVAL` → CONFIRM (high), `SIMULATION_FAILED` → flag (medium) |
+
+### Environment Variables
+
+```
+GOPLUS_API_KEY=your_key         # Required for simulation
+GOPLUS_API_SECRET=your_secret   # Required for simulation
+```
+
+Phishing site detection and address security checks work without API keys. Transaction simulation requires configured credentials.
+
+### Degradation Strategy
+
+When GoPlus is unavailable (no API keys, network errors, rate limiting):
+
+1. The `SIMULATION_UNAVAILABLE` or `SIMULATION_FAILED` risk tag is set
+2. Phishing and address checks that fail are silently skipped
+3. The decision falls back to **policy-based rules only** (capability model, webhook detection, secret scanning)
+4. For `web3_tx` and `web3_sign` without GoPlus, the skill should apply prompt-based rules and note the limitation in the output