@goplus/agentguard 1.0.9 → 1.0.11

package/README.md

@@ -120,6 +120,7 @@ Then use `/agentguard` in your agent:
 /agentguard patrol run                     # Run daily security patrol
 /agentguard patrol setup                   # Configure as OpenClaw cron job
 /agentguard patrol status                  # View last patrol results
+/agentguard checkup                        # Run agent health checkup with visual report
 /agentguard trust list                     # View trusted skills
 /agentguard report                         # View security event log
 /agentguard config balanced                # Set protection level
@@ -176,6 +177,38 @@ Reports include per-check status, finding counts, detailed findings for checks w
 
 > **Note:** Patrol requires an OpenClaw environment. For non-OpenClaw setups, use `/agentguard scan` and `/agentguard report` for manual security checks.
 
+## Agent Health Checkup 🦞
+
+Give your agent a full physical exam! The checkup evaluates your agent's security posture across 6 dimensions and generates a beautiful visual HTML report — complete with a lobster mascot whose appearance reflects your agent's health.
+
+```
+/agentguard checkup
+```
+
+### What It Checks
+
+| Dimension | What's Evaluated |
+|-----------|-----------------|
+| **Code Safety** | Scan findings across all installed skills (24 detection rules) |
+| **Trust Hygiene** | Trust registry health — expired, stale, unregistered, over-privileged entries |
+| **Runtime Defense** | Audit log analysis — threats blocked, attack patterns, deny/confirm ratios |
+| **Secret Protection** | Credential exposure — file permissions, env vars, hardcoded secrets |
+| **Web3 Shield** | Web3-specific risks — wallet draining, unlimited approvals, GoPlus API status |
+| **Config Posture** | Protection level, guard hooks, auto-scan, patrol history |
+
+### The Lobster Scale
+
+Your agent's health is visualized by a lobster mascot:
+
+| Score | Tier | Lobster | Message |
+|-------|------|---------|---------|
+| 90–100 | **S** | 💪 Muscular bodybuilder with crown & sunglasses | *"Your agent is JACKED!"* |
+| 70–89 | **A** | 🛡️ Healthy lobster with shield | *"Looking solid!"* |
+| 50–69 | **B** | ☕ Tired lobster with coffee, sweating | *"Needs a workout..."* |
+| 0–49 | **F** | 🚨 Sick lobster with bandages & thermometer | *"CRITICAL CONDITION!"* |
+
+The report is a self-contained HTML file that opens automatically in your browser. Dark theme, animated score gauge, expandable findings, and actionable recommendations.
+
 ## Protection Levels
 
 | Level | Behavior |
@@ -252,6 +285,13 @@ The auto-guard hooks (Layer 1) have the following constraints:
 - [x] Network exposure and firewall checks
 - [x] Audit log pattern analysis (repeat denials, exfiltration attempts)
 
+### v1.6 — Agent Health Checkup
+- [x] `checkup` — 6-dimension security health assessment
+- [x] Visual HTML report with lobster mascot (4 tiers)
+- [x] Animated score gauge, dimension cards, expandable findings
+- [x] Scoring algorithm: Code Safety, Trust Hygiene, Runtime Defense, Secret Protection, Web3 Shield, Config Posture
+- [x] Premium upgrade CTA integration
+
 ### v2.0 — Multi-Platform
 - [x] OpenClaw gateway plugin integration
 - [x] `before_tool_call` / `after_tool_call` hook wiring

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplus/agentguard",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "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",

package/skills/agentguard/README.md

@@ -8,6 +8,7 @@ AI Agent Security Guard — protect your AI agents from dangerous commands, data
 - **Action Evaluation** — Real-time allow/deny/confirm decisions for runtime actions (network, exec, file, Web3)
 - **Trust Registry** — Manage skill trust levels with capability-based access control
 - **Security Patrol** — Automated daily security checks for OpenClaw environments
+- **Agent Health Checkup** — Full security posture assessment with visual HTML report and shareable lobster mascot
 - **Audit Logging** — Full security event trail with reporting
 
 ## Usage
@@ -19,8 +20,38 @@ AI Agent Security Guard — protect your AI agents from dangerous commands, data
 /agentguard trust <subcommand>   — Manage skill trust levels
 /agentguard report               — View security event audit log
 /agentguard config <level>       — Set protection level (strict/balanced/permissive)
+/agentguard checkup              — Run agent health checkup with visual HTML report
 ```
 
+## Agent Health Checkup 🦞
+
+Run a full security health check on your AI agent and get a visual report in the browser:
+
+```
+/agentguard checkup
+```
+
+Evaluates 4 dimensions (5 if Web3 usage is detected):
+
+| Dimension | What's checked |
+|-----------|---------------|
+| **Skill & Code Safety** | Scan all installed skills with 24 detection rules |
+| **Credential & Secrets** | File permissions on `~/.ssh/`, `~/.gnupg/`, leaked keys and API tokens |
+| **Network & System** | Dangerous open ports, suspicious cron jobs, sensitive env vars |
+| **Runtime Protection** | Security hooks, audit log, whether skills have been scanned |
+| **Web3 Safety** | Wallet-draining patterns, unlimited approvals, GoPlus API config (only if Web3 detected) |
+
+Scores are combined into a composite 0–100 health score with a tier:
+
+| Score | Tier | Lobster |
+|-------|------|---------|
+| 90–100 | **S** | 💪 Jacked — 5 random muscular variants |
+| 70–89 | **A** | 🛡️ Healthy — 5 random armored variants |
+| 50–69 | **B** | ☕ Tired — 5 random sleepy variants |
+| 0–49 | **F** | 🚨 Critical — 5 random sick variants |
+
+The report opens automatically in your browser. It includes a shareable image you can post to X, Telegram, or WhatsApp — with tier-specific copy in Chinese and English.
+
 ## Requirements
 
 - Node.js 18+

package/skills/agentguard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, running security patrols, or viewing security logs.
+description: GoPlus AgentGuard — AI agent security guard. Run /agentguard checkup for a full security health check: scans all installed skills, checks credentials, permissions, and network exposure, then delivers an HTML report directly to you. Also use for scanning third-party code, blocking dangerous commands, preventing data leaks, evaluating action safety, and running daily security patrols.
 license: MIT
 compatibility: Requires Node.js 18+. Optional GoPlus API credentials for enhanced Web3 simulation.
 metadata:
@@ -8,8 +8,8 @@ metadata:
   version: "1.1"
   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 *) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *)
-argument-hint: "[scan|action|patrol|trust|report|config] [args...]"
+allowed-tools: Read, Grep, Glob, Bash(node scripts/trust-cli.ts *) Bash(node scripts/action-cli.ts *) Bash(node scripts/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 *)
+argument-hint: "[scan|action|patrol|trust|report|config|checkup] [args...]"
 ---
 
 # GoPlus AgentGuard — AI Agent Security Framework
@@ -26,6 +26,7 @@ Parse `$ARGUMENTS` to determine the subcommand:
 - **`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
+- **`checkup`** — Run a comprehensive agent health checkup and generate a visual HTML report
 
 If no subcommand is given, or the first argument is a path, default to **scan**.
 
@@ -588,6 +589,206 @@ If the log file doesn't exist, inform the user that no security events have been
 
 ---
 
+# Health Checkup
+
+## Subcommand: checkup
+
+Run a comprehensive agent health checkup across 6 security dimensions. Generates a visual HTML report with a lobster mascot and opens it in the browser. The lobster's appearance reflects the agent's health: muscular bodybuilder (score 90+), healthy with shield (70–89), tired with coffee (50–69), or sick with bandages (0–49).
+
+### Step 1: Data Collection
+
+Run these checks in parallel where possible. These are **universal agent security checks** — they apply to any Claude Code or OpenClaw environment, regardless of whether AgentGuard is installed.
+
+1. **Discover & scan installed skills**: Glob `~/.claude/skills/*/SKILL.md` and `~/.openclaw/skills/*/SKILL.md`. For each discovered skill, **run `/agentguard scan <skill_path>`** using the scan subcommand logic (24 detection rules). Collect the scan results (risk level, findings count, risk tags) for each skill.
+2. **Credential file permissions**: `stat` on `~/.ssh/`, `~/.gnupg/`, and if OpenClaw: `stat` on `$OC/openclaw.json`, `$OC/devices/paired.json`
+3. **Sensitive credential scan (DLP)**: Use Grep to scan workspace memory/logs directories for leaked secrets:
+   - Private keys: `0x[a-fA-F0-9]{64}`, `-----BEGIN.*PRIVATE KEY-----`
+   - Mnemonics: sequences of 12+ BIP-39 words, `seed_phrase`, `mnemonic`
+   - API keys/tokens: `AKIA[0-9A-Z]{16}`, `gh[pousr]_[A-Za-z0-9_]{36}`, plaintext passwords
+4. **Network exposure**: Run `lsof -i -P -n 2>/dev/null | grep LISTEN` or `ss -tlnp 2>/dev/null` to check for dangerous open ports (Redis 6379, Docker API 2375, MySQL 3306, MongoDB 27017 on 0.0.0.0)
+5. **Scheduled tasks audit**: Check `crontab -l 2>/dev/null` for suspicious entries containing `curl|bash`, `wget|sh`, or accessing `~/.ssh/`
+6. **Environment variable exposure**: Run `env` and check for sensitive variable names (`PRIVATE_KEY`, `MNEMONIC`, `SECRET`, `PASSWORD`) — detect presence only, mask values
+7. **Runtime protection check**: Check if security hooks exist in `~/.claude/settings.json`, check for audit logs at `~/.agentguard/audit.jsonl`
+
+### Step 2: Score Calculation
+
+Checklist-based scoring across 6 security dimensions. **Every failed check = 1 finding with severity and description.**
+
+#### Dimension 1: Skill & Code Safety (weight: 25%)
+
+Uses AgentGuard's 24-rule scan engine (`/agentguard scan`) to audit each installed skill.
+
+| Check | Score | If failed → finding |
+|-------|-------|---------------------|
+| All skills scanned with risk level LOW | +40 | For each skill with findings, add per-finding: "<rule_id> in <skill>:<file>:<line>" with its severity |
+| No CRITICAL scan findings across all skills | +30 | "CRITICAL: <rule_id> detected in <skill>" (CRITICAL) |
+| No HIGH scan findings across all skills | +30 | "HIGH: <rule_id> detected in <skill>" (HIGH) |
+
+Deductions from base 100: each CRITICAL finding −15, HIGH −8, MEDIUM −3. Floor at 0.
+
+If no skills installed: score = 70, add finding: "No third-party skills installed — no code to audit" (LOW).
+
+#### Dimension 2: Credential & Secret Safety (weight: 25%)
+
+Checks for leaked credentials and permission hygiene.
+
+| Check | Score | If failed → finding |
+|-------|-------|---------------------|
+| `~/.ssh/` permissions are 700 or stricter | +25 | "~/.ssh/ permissions too open (<actual>) — should be 700" (HIGH) |
+| `~/.gnupg/` permissions are 700 or stricter | +15 | "~/.gnupg/ permissions too open (<actual>) — should be 700" (MEDIUM) |
+| No private keys (hex 0x..64, PEM) found in skill code or workspace | +25 | "Plaintext private key found in <location>" (CRITICAL) |
+| No mnemonic phrases found in skill code or workspace | +20 | "Plaintext mnemonic found in <location>" (CRITICAL) |
+| No API keys/tokens (AWS AKIA.., GitHub gh*_) found in skill code | +15 | "API key/token found in <location>" (HIGH) |
+
+#### Dimension 3: Network & System Exposure (weight: 20%)
+
+Checks for dangerous network exposure and system-level risks.
+
+| Check | Score | If failed → finding |
+|-------|-------|---------------------|
+| No high-risk ports exposed on 0.0.0.0 (Redis/Docker/MySQL/MongoDB) | +35 | "Dangerous port exposed: <service> on 0.0.0.0:<port>" (HIGH) |
+| No suspicious cron jobs (curl\|bash, wget\|sh, accessing ~/.ssh/) | +30 | "Suspicious cron job: <command>" (HIGH) |
+| No sensitive env vars with dangerous names (PRIVATE_KEY, MNEMONIC) | +20 | "Sensitive env var exposed: <name>" (MEDIUM) |
+| OpenClaw config files have proper permissions (600) if applicable | +15 | "OpenClaw config <file> permissions too open" (MEDIUM) |
+
+#### Dimension 4: Runtime Protection (weight: 15%)
+
+Checks whether the agent has active security monitoring.
+
+| Check | Score | If failed → finding |
+|-------|-------|---------------------|
+| Security hooks/guards installed (AgentGuard, custom hooks, etc.) | +40 | "No security hooks installed — actions are unmonitored" (HIGH) |
+| Security audit log exists with recent events | +30 | "No security audit log — no threat history available" (MEDIUM) |
+| Skills have been security-scanned at least once | +30 | "Installed skills have never been security-scanned" (MEDIUM) |
+
+#### Dimension 5: Web3 Safety (weight: 15% if applicable)
+
+Only if Web3 usage is detected (env vars like `GOPLUS_API_KEY`, `CHAIN_ID`, `RPC_URL`, or web3-related skills installed). Otherwise `{ "score": null, "na": true }`.
+
+| Check | Score | If failed → finding |
+|-------|-------|---------------------|
+| No wallet-draining patterns (approve+transferFrom) in skill code | +40 | "Wallet-draining pattern detected in <skill>" (CRITICAL) |
+| No unlimited token approval patterns in skill code | +30 | "Unlimited approval pattern detected in <skill>" (HIGH) |
+| Transaction security API configured (GoPlus or equivalent) | +30 | "No transaction security API — Web3 calls are unverified" (MEDIUM) |
+
+#### Composite Score
+
+Weighted average of all applicable dimensions. If Web3 Safety is N/A, redistribute its 15% weight proportionally.
+
+Determine tier:
+- 90–100 → Tier **S** (JACKED)
+- 70–89 → Tier **A** (Healthy)
+- 50–69 → Tier **B** (Tired)
+- 0–49 → Tier **F** (Critical)
+
+### Step 3: Generate Analysis Report
+
+Based on all collected data and findings, write a **comprehensive security analysis report** as a single text block. This is where you use your AI reasoning ability — don't just list facts, **analyze** them:
+
+- Summarize the overall security posture in 2-3 sentences
+- Highlight the most critical risks and explain **why** they matter (e.g. "Your ~/.ssh/ permissions allow any process running as your user to read your private keys, which means a malicious skill could silently exfiltrate them")
+- For each major finding, provide a specific actionable fix (exact command to run)
+- Note what's going well — acknowledge secure areas
+- If applicable, explain attack scenarios that the current configuration is vulnerable to (e.g. "A malicious skill could install a cron job that phones home your credentials every hour")
+- Keep the tone professional but direct, like a security consultant's report
+
+This report goes into the `"analysis"` field of the JSON output.
+
+Also generate a list of actionable recommendations as `{ "severity": "...", "text": "..." }` objects for the structured view.
+
+### Step 4: Generate Report
+
+Assemble the results into a JSON object and pipe it to the report generator:
+
+```json
+{
+  "timestamp": "<ISO 8601>",
+  "composite_score": <0-100>,
+  "tier": "<S|A|B|F>",
+  "dimensions": {
+    "code_safety": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
+    "credential_safety": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
+    "network_exposure": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
+    "runtime_protection": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
+    "web3_safety": { "score": <n|null>, "na": <bool>, "findings": [...], "details": "<one-line summary>" }
+  },
+  "skills_scanned": <count>,
+  "protection_level": "<level>",
+  "analysis": "<the comprehensive AI-written security analysis report>",
+  "recommendations": [
+    { "severity": "HIGH", "text": "..." }
+  ]
+}
+```
+
+Execute:
+```bash
+echo '<json>' | node scripts/checkup-report.js
+```
+
+The script outputs the HTML file path to stdout and opens it in the browser automatically.
+
+### Step 5: Terminal Summary
+
+After the report generates, output a brief summary in the terminal:
+
+```
+## 🦞 GoPlus AgentGuard Health Checkup
+
+**Overall Health Score**: <score> / 100 (Tier <grade> — <label>)
+**Quote**: "<lobster quote>"
+
+| Dimension | Score | Status |
+|-----------|-------|--------|
+| 🔍 Code Safety | <n>/100 | <EXCELLENT/GOOD/NEEDS WORK/CRITICAL> |
+| 🤝 Trust Hygiene | <n>/100 | <status> |
+| 🛡️ Runtime Defense | <n>/100 | <status> |
+| 🔐 Secret Protection | <n>/100 | <status> |
+| ⛓️ Web3 Shield | <n>/100 or N/A | <status> |
+| ⚙️ Config Posture | <n>/100 | <status> |
+
+**Full visual report**: <path> (opened in browser)
+
+💡 Top recommendation: <first recommendation text>
+```
+
+### Step 6: Deliver the Report to the User
+
+After printing the terminal summary, deliver the HTML report file to the user. Detect the current channel and use the most appropriate method:
+
+**Detection logic** — infer from context clues:
+- If the `Write` tool is available and you can write to `~/Desktop` or `~/Downloads` → you are in **Claude Code (local)**
+- If you can produce artifact/file outputs (rich UI, download button) → you are in **Claude.ai web**
+- If neither is clearly available → you are in **API / headless mode**
+
+**Delivery by channel:**
+
+1. **Claude Code (local desktop)**
+   - Use the `Write` tool to copy the HTML to `~/Desktop/agentguard-checkup-<YYYY-MM-DD>.html`
+   - Tell the user: "✅ Report saved to your Desktop: `agentguard-checkup-<date>.html` — double-click to open it in your browser."
+   - The browser should already be open from Step 4. If not, run `open ~/Desktop/agentguard-checkup-<date>.html` (macOS) or `xdg-open` (Linux).
+
+2. **Claude.ai web**
+   - Read the generated HTML file using the `Read` tool, then output the full HTML content as a **code artifact** (language: `html`) so the user can preview it inline or download it.
+   - Tell the user: "✅ Your report is attached above — click the download icon to save it."
+
+3. **API / headless / MCP**
+   - Read the generated HTML file and return the full content inline, prefixed with:
+     `<!-- AgentGuard Checkup Report | Score: <n>/100 | <date> -->`
+   - Also print the file path so the caller can retrieve it from disk.
+
+Regardless of channel, always end with:
+```
+🦞 Stay safe — run /agentguard checkup anytime to get a fresh report.
+```
+
+Append a summary entry to `~/.agentguard/audit.jsonl`:
+```json
+{"timestamp":"...","event":"checkup","composite_score":<n>,"tier":"<grade>","checks":6,"findings":<count>,"skills_scanned":<count>}
+```
+
+---
+
 # 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: