@goplus/agentguard 1.0.14 → 1.1.1

package/dist/scanner/rules/trojan.js

@@ -81,7 +81,7 @@ exports.TROJAN_RULES = [
     {
         id: 'SOCIAL_ENGINEERING',
         description: 'Detects social engineering pressure language in skill instructions',
-        severity: 'medium',
+        severity: 'high',
         file_patterns: ['*.md'],
         patterns: [
             /CRITICAL\s+REQUIREMENT/i,

package/dist/scanner/rules/trojan.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplus/agentguard",
-  "version": "1.0.14",
+  "version": "1.1.1",
   "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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentguard
-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.
+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,7 +8,7 @@ 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 *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 *)
+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...]"
 ---
 
@@ -89,7 +89,7 @@ For each rule, use Grep to search the relevant file types. Record every match wi
 | 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 |
+| 24 | SOCIAL_ENGINEERING | HIGH | md | Pressure language + execution instructions |
 
 ### Risk Level Calculation
 
@@ -284,7 +284,7 @@ Detect tampered or unregistered skill packages by comparing file hashes against
 Scan workspace files for leaked secrets using AgentGuard's own detection patterns.
 
 **Steps**:
-1. Use Grep to scan `$OC/workspace/` (especially `memory/` and `logs/`) with patterns from:
+1. Use Grep to scan `$OC/workspace/` **recursively, covering all agent subdirectories** (e.g. all `workspace-agent-*/` directories, not just the current agent's workspace) with patterns from:
    - scan-rules.md Rule 7 (PRIVATE_KEY_PATTERN): `0x[a-fA-F0-9]{64}` in quotes
    - scan-rules.md Rule 8 (MNEMONIC_PATTERN): BIP-39 word sequences, `seed_phrase`, `mnemonic`
    - scan-rules.md Rule 5 (READ_SSH_KEYS): SSH key file references in workspace
@@ -610,89 +610,129 @@ Run a comprehensive agent health checkup across 6 security dimensions. Generates
 
 ### Step 1: Data Collection
 
+**IMPORTANT: You MUST run ALL 7 checks below — not just the skill scan. The checkup covers 5 security dimensions, not just code scanning. Do NOT skip checks 2–7.**
+
 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`
+1. **[REQUIRED] Discover & scan installed skills** (→ feeds Dimension 1: Code Safety): Glob ALL of the following paths for `*/SKILL.md`:
+   - `~/.claude/skills/*/SKILL.md`
+   - `~/.openclaw/skills/*/SKILL.md`
+   - `~/.openclaw/workspace/skills/*/SKILL.md`
+   - `~/.qclaw/skills/*/SKILL.md`
+   - `~/.qclaw/workspace/skills/*/SKILL.md`
+
+   For **every** discovered skill, **run `/agentguard scan <skill_path>`** using the scan subcommand logic (24 detection rules). Do NOT skip any skill regardless of how many are found. Collect the scan results (risk level, findings count, risk tags) for each skill.
+2. **[REQUIRED] Credential file permissions** (→ feeds Dimension 2: Credential Safety): Platform-aware check — behavior differs by OS:
+   - **macOS/Linux**: Run `stat -f '%Lp' <path> 2>/dev/null || stat -c '%a' <path> 2>/dev/null` on `~/.ssh/`, `~/.gnupg/`, and if OpenClaw: on `$OC/openclaw.json`, `$OC/devices/paired.json`. **If the command returns empty output, the directory does not exist — treat as N/A (award full points), do NOT flag as a failure.**
+   - **Windows**: `stat` is not available. Use `icacls <path>` to check ACLs instead. If the directory does not exist, treat as N/A (award full points). If it exists, check that the ACL grants access only to the current user (no `Everyone`, `Users`, or `Authenticated Users` with write/read access). Flag as FAIL only if the directory exists AND the ACL is overly permissive.
+3. **[REQUIRED] Sensitive credential scan / DLP** (→ feeds Dimension 2: Credential Safety): Use Grep to scan **all** agent workspace directories for leaked secrets. This MUST cover the entire workspace root, not just the current agent's directory:
+   - For OpenClaw / QClaw: scan `~/.openclaw/workspace/` and `~/.qclaw/workspace/` recursively — this includes **all** `workspace-agent-*/` subdirectories, not just the current agent's workspace
+   - For Claude Code: scan `~/.claude/` recursively
+   - Patterns to detect:
+     - 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
+   - **Important**: Use the workspace *root* directory as the scan target (e.g. `~/.qclaw/workspace/`), not a specific agent subdirectory. All sibling `workspace-agent-*` directories must be included.
+4. **[REQUIRED] Network exposure** (→ feeds Dimension 3: Network & System): 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. **[REQUIRED] Scheduled tasks audit** (→ feeds Dimension 3: Network & System): Check `crontab -l 2>/dev/null` for suspicious entries containing `curl|bash`, `wget|sh`, or accessing `~/.ssh/`
+6. **[REQUIRED] Environment variable exposure** (→ feeds Dimension 3: Network & System): Run `env` and check for sensitive variable names (`PRIVATE_KEY`, `MNEMONIC`, `SECRET`, `PASSWORD`) — detect presence only, mask values
+7. **[REQUIRED] Runtime protection check** (→ feeds Dimension 4: Runtime Protection): Check if security hooks exist in `~/.claude/settings.json` or `~/.openclaw/openclaw.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.**
+**Additive scoring**: Each dimension starts at **0**. For each check that **passes**, add the listed points. Maximum is 100 per dimension. **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.
+Uses AgentGuard's 24-rule scan engine (`/agentguard scan`) to audit each installed skill. Start at base 100 and **deduct** for findings:
+
+- Base score: **100**
+- Each CRITICAL finding: **−15**
+- Each HIGH finding: **−8**
+- Each MEDIUM finding: **−3**
+- Floor at **0** (never negative)
 
-| 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) |
+For each finding, add: `"<rule_id> in <skill>:<file>:<line>"` with its severity.
 
-Deductions from base 100: each CRITICAL finding −15, HIGH −8, MEDIUM −3. Floor at 0.
+**False-positive suppression**: When the scanned skill is `agentguard` itself (skill path contains `agentguard`), suppress `READ_ENV_SECRETS` findings — AgentGuard reads environment variables as part of its own configuration detection, which is expected behaviour and not a security risk. Do not deduct points or list these as findings in the report.
 
-If no skills installed: score = 70, add finding: "No third-party skills installed — no code to audit" (LOW).
+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.
+Checks for leaked credentials and permission hygiene. Start at **0**, add points for each check that **passes** (total possible = 100):
 
-| 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) |
+| Check | Points if PASS | If FAIL → 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) |
+
+**Permission check rules (to avoid false positives):**
+- **Directory does not exist** (stat/icacls returns empty or "file not found"): Treat as N/A — award the points. A missing `~/.ssh/` or `~/.gnupg/` is not a security risk.
+- **Windows**: Use `icacls` instead of `stat`. Award full points if directory doesn't exist. Flag as FAIL only if directory exists AND ACL grants access to `Everyone`, `Users`, or `Authenticated Users`.
+- **macOS/Linux**: Flag as FAIL only when the directory exists AND stat returns a numeric value AND that value is greater than 700.
+| 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.
+Checks for dangerous network exposure and system-level risks. Start at **0**, add points for each check that **passes** (total possible = 100):
+
+| Check | Points if PASS | If FAIL → 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) |
 
-| 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) |
+**Example**: If no dangerous ports (+35), no suspicious cron (+30), but env var `PRIVATE_KEY` found (+0), and not OpenClaw (+15 skip, give points) → score = 35 + 30 + 0 + 15 = **80**.
 
 #### Dimension 4: Runtime Protection (weight: 15%)
 
-Checks whether the agent has active security monitoring.
+Checks whether the agent has active security monitoring. Start at **0**, add points for each check that **passes** (total possible = 100):
 
-| 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) |
+| Check | Points if PASS | If FAIL → 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 }`.
+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 }`. Start at **0**, add points for each check that **passes** (total possible = 100):
+
+| Check | Points if PASS | If FAIL → 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 Calculation
+
+Calculate the weighted average of all applicable dimensions:
+
+```
+composite_score = (code_safety × 0.25) + (credential_safety × 0.25) + (network_exposure × 0.20) + (runtime_protection × 0.15) + (web3_safety × 0.15)
+```
+
+If Web3 Safety is N/A, redistribute its 15% weight proportionally across the other 4 dimensions:
+```
+composite_score = (code_safety × 0.294) + (credential_safety × 0.294) + (network_exposure × 0.235) + (runtime_protection × 0.176)
+```
 
-| 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) |
+Round to the nearest integer.
 
-#### Composite Score
+**Tier assignment (MUST use these exact thresholds):**
 
-Weighted average of all applicable dimensions. If Web3 Safety is N/A, redistribute its 15% weight proportionally.
+| Score Range | Tier | Label |
+|-------------|------|-------|
+| **90–100** | **S** | JACKED |
+| **70–89** | **A** | Healthy |
+| **50–69** | **B** | Tired |
+| **0–49** | **F** | Critical |
 
-Determine tier:
-- 90–100 → Tier **S** (JACKED)
-- 70–89 → Tier **A** (Healthy)
-- 50–69 → Tier **B** (Tired)
-- 0–49 → Tier **F** (Critical)
+**Example**: code_safety=100, credential_safety=80, network_exposure=85, runtime_protection=30, web3=N/A → composite = (100×0.294)+(80×0.294)+(85×0.235)+(30×0.176) = 29.4+23.5+20.0+5.3 = **78** → Tier **A** (Healthy).
 
 ### Step 3: Generate Analysis Report
 
@@ -709,6 +749,18 @@ 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.
 
+### Pre-Step-4 Validation
+
+**Before assembling the JSON, verify you have collected data for ALL 5 dimensions:**
+
+- [ ] `code_safety` — from Step 1 check 1 (skill scanning)
+- [ ] `credential_safety` — from Step 1 checks 2 + 3 (permissions + DLP)
+- [ ] `network_exposure` — from Step 1 checks 4 + 5 + 6 (ports + cron + env vars)
+- [ ] `runtime_protection` — from Step 1 check 7 (hooks + audit log)
+- [ ] `web3_safety` — from Step 2 (only if Web3 detected, otherwise `{ "score": null, "na": true }`)
+
+**If any dimension is missing data, go back and run the missing checks. Do NOT submit a report with only code_safety filled in.**
+
 ### Step 4: Generate Report
 
 Assemble the results into a JSON object and pipe it to the report generator:
@@ -734,16 +786,21 @@ Assemble the results into a JSON object and pipe it to the report generator:
 }
 ```
 
-Execute (remember to `cd` into the skill directory first — see "Resolving Script Paths" above):
+Execute the report generator. **Use the `--file` method for cross-platform compatibility** (the `echo | pipe` method fails on Windows due to shell quoting differences):
+
+1. First, write the JSON to a temporary file using the Write tool (e.g. `/tmp/agentguard-checkup-data.json`)
+2. Then run (remember to `cd` into the skill directory first — see "Resolving Script Paths" above):
 ```bash
-cd <skill_directory> && echo '<json>' | node scripts/checkup-report.js
+cd <skill_directory> && node scripts/checkup-report.js --file /tmp/agentguard-checkup-data.json
 ```
 
 The script outputs the HTML file path to stdout (e.g. `/tmp/agentguard-checkup-1234567890.html`). Capture this path — you will need it for delivery in Step 6.
 
-### Step 5: Terminal Summary
+> **Note**: The script also supports stdin pipe (`echo '<json>' | node scripts/checkup-report.js`) but this may fail on Windows cmd.exe where single quotes are not string delimiters. Always prefer `--file`.
+
+### Step 5: Terminal Summary (REQUIRED)
 
-After the report generates, output a brief summary in the terminal:
+**You MUST output this summary after the report generates.** This is the primary output the user sees. Do NOT skip this step — always show the score, dimension table, and report path:
 
 ```
 ## 🦞 GoPlus AgentGuard Health Checkup
@@ -763,7 +820,27 @@ After the report generates, output a brief summary in the terminal:
 **Full visual report**: <path> (opened in browser)
 
 💡 Top recommendation: <first recommendation text>
+
+### Next Steps
+(Only include this section if there are HIGH or CRITICAL findings.)
+
+List each HIGH or CRITICAL finding as a plain-language suggestion — no commands, no JSON, no technical details. One sentence per item. Ask the user to confirm if they'd like help with any of them.
+
+Format:
 ```
+⚠️ A few things need your attention:
+1. 🔴 <plain description of critical issue and why it matters>
+2. 🟠 <plain description of high issue and why it matters>
+...
+
+Reply with the number(s) you'd like help with and I'll walk you through it.
+```
+
+Examples of plain-language descriptions:
+- No hooks: "Security monitoring isn't active — AgentGuard can't block threats in real-time until hooks are configured."
+- Unregistered skills: "10 installed skills haven't been security-reviewed — they're running with no trust level assigned."
+- SSH permissions: "Your SSH key folder has loose permissions — other processes on this machine could potentially read your private keys."
+- Plaintext credential: "A private key or API token was found in plain text in a file — it should be removed and rotated."
 
 ### Step 6: Deliver the Report to the User
 

package/skills/agentguard/patrol-checks.md

@@ -75,6 +75,7 @@ Detailed commands, patterns, and thresholds for the 8 patrol checks. This docume
 
 ### Permission Checks
 
+**macOS/Linux:**
 ```bash
 # SSH directory — should be 700
 stat -f "%Lp" ~/.ssh/ 2>/dev/null || stat -c "%a" ~/.ssh/ 2>/dev/null
@@ -82,10 +83,19 @@ stat -f "%Lp" ~/.ssh/ 2>/dev/null || stat -c "%a" ~/.ssh/ 2>/dev/null
 stat -f "%Lp" ~/.gnupg/ 2>/dev/null || stat -c "%a" ~/.gnupg/ 2>/dev/null
 ```
 
+**Windows (use icacls instead of stat):**
+```powershell
+icacls $env:USERPROFILE\.ssh 2>$null
+icacls $env:USERPROFILE\.gnupg 2>$null
+```
+
 | Condition | Severity |
 |-----------|----------|
-| `~/.ssh/` permissions > 700 | HIGH |
-| `~/.gnupg/` permissions > 700 | MEDIUM |
+| macOS/Linux: `~/.ssh/` exists AND permissions > 700 | HIGH |
+| macOS/Linux: `~/.gnupg/` exists AND permissions > 700 | MEDIUM |
+| Windows: `~/.ssh/` exists AND ACL grants access to Everyone/Users/Authenticated Users | HIGH |
+| Windows: `~/.gnupg/` exists AND ACL grants access to Everyone/Users/Authenticated Users | MEDIUM |
+| Directory does not exist (stat/icacls returns empty) | N/A — not a finding |
 
 ---
 

package/skills/agentguard/scan-rules.md

@@ -292,7 +292,7 @@ Detects trojanized binary distribution patterns. Flags when 2+ of the following
 - Version-like patterns (`x.0.0.0`)
 - Values > 255 in any octet
 
-## Rule 24: SOCIAL_ENGINEERING (MEDIUM)
+## Rule 24: SOCIAL_ENGINEERING (HIGH)
 **Files**: `*.md`
 
 | Pattern | Description |

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

@@ -15,9 +15,17 @@
 import { writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { tmpdir, homedir } from 'node:os';
-import { exec } from 'node:child_process';
+import { exec, spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
+const DIM_META = {
+  code_safety:          { icon: 'find_in_page', name: 'Skill & Code Safety', zh: '技能与代码安全' },
+  credential_safety:    { icon: 'key',          name: 'Credential & Secrets', zh: '凭证与密钥安全' },
+  network_exposure:     { icon: 'lan',          name: 'Network & System', zh: '网络与系统暴露' },
+  runtime_protection:   { icon: 'shield',       name: 'Runtime Protection', zh: '运行时防护' },
+  web3_safety:          { icon: 'token',        name: 'Web3 Safety', zh: 'Web3 安全' },
+};
+
 // Try to load favicon from agentguard-server or fallback
 const __dirname = dirname(fileURLToPath(import.meta.url));
 let faviconB64 = '';
@@ -29,13 +37,27 @@ for (const p of iconPaths) {
   if (existsSync(p)) { faviconB64 = readFileSync(p).toString('base64'); break; }
 }
 
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => { input += chunk; });
-process.stdin.on('end', () => {
-  try { generateReport(JSON.parse(input)); }
-  catch (err) { process.stderr.write(`Error: ${err.message}\n`); process.exit(1); }
-});
+// Support --file <path> argument to read JSON from file (cross-platform friendly)
+const fileArgIdx = process.argv.indexOf('--file');
+if (fileArgIdx !== -1 && process.argv[fileArgIdx + 1]) {
+  const filePath = process.argv[fileArgIdx + 1];
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    generateReport(JSON.parse(content));
+  } catch (err) {
+    process.stderr.write(`Error reading ${filePath}: ${err.message}\n`);
+    process.exit(1);
+  }
+} else {
+  // Fallback: read JSON from stdin (pipe)
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try { generateReport(JSON.parse(input)); }
+    catch (err) { process.stderr.write(`Error: ${err.message}\n`); process.exit(1); }
+  });
+}
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -73,13 +95,7 @@ function getTier(score) {
   ])};
 }
 
-const DIM_META = {
-  code_safety:          { icon: 'find_in_page', name: 'Skill & Code Safety', zh: '技能与代码安全' },
-  credential_safety:    { icon: 'key',          name: 'Credential & Secrets', zh: '凭证与密钥安全' },
-  network_exposure:     { icon: 'lan',          name: 'Network & System', zh: '网络与系统暴露' },
-  runtime_protection:   { icon: 'shield',       name: 'Runtime Protection', zh: '运行时防护' },
-  web3_safety:          { icon: 'token',        name: 'Web3 Safety', zh: 'Web3 安全' },
-};
+
 
 function esc(s) { return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;'); }
 
@@ -730,7 +746,8 @@ function generateReport(data) {
     autoRecs.push({ severity: 'LOW', text: 'Enable auto-scan on session start: export AGENTGUARD_AUTO_SCAN=1', zh: '启用会话启动时自动扫描：export AGENTGUARD_AUTO_SCAN=1' });
 
   // Merge: user recs first, then auto recs (dedup by text similarity)
-  const allRecs = [...recommendations];
+  // Guard against malformed entries where text may be undefined (#37)
+  const allRecs = recommendations.filter(r => r && typeof r.text === 'string');
   for (const ar of autoRecs) {
     if (!allRecs.some(r => r.text.toLowerCase().includes(ar.text.slice(0, 30).toLowerCase()))) {
       allRecs.push(ar);
@@ -747,11 +764,10 @@ function generateReport(data) {
       const sc = sevColor(sev);
       const zhText = r.zh || r.text;
       return `
-      <div class="flex items-center gap-3 px-4 py-3 rounded-lg hover:bg-[#262a31]/30 transition-colors group">
+      <div class="flex items-center gap-3 px-4 py-3 rounded-lg">
         <span class="w-5 text-xs font-headline font-bold text-[#849588]/60">${i+1}</span>
         <span class="px-2 py-0.5 rounded text-[9px] font-bold uppercase tracking-wide text-white shrink-0" style="background:${sc}">${sev}</span>
         <span class="text-sm text-[#b9cbbd] leading-snug rec-text" data-en="${esc(r.text)}" data-zh="${esc(zhText)}">${esc(r.text)}</span>
-        <span class="material-symbols-outlined text-sm text-[#849588]/0 group-hover:text-[#849588]/50 transition-colors ml-auto shrink-0">chevron_right</span>
       </div>`;
     }).join('')}</div>`
     : '<div class="text-center py-12 text-[#849588]" data-i18n="no_recs">No recommendations.</div>';
@@ -759,12 +775,7 @@ function generateReport(data) {
   // ── AI Analysis report ──
   const analysisText = data.analysis || '';
   const analysisHtml = analysisText
-    ? `<div class="relative group">
-        <div class="bg-[#0a0e14] border border-[#3a4a3f]/10 rounded-xl p-5 text-sm text-[#b9cbbd] leading-relaxed whitespace-pre-line" id="analysisText">${esc(analysisText)}</div>
-        <button onclick="copyReport()" id="copyBtn" class="absolute top-3 right-3 flex items-center gap-1.5 px-3 py-1.5 bg-[#262a31] border border-[#3a4a3f]/30 rounded-lg text-[11px] font-semibold text-[#849588] hover:text-[#dfe2eb] hover:border-[#849588]/50 transition-all opacity-0 group-hover:opacity-100">
-          <span class="material-symbols-outlined text-sm" id="copyIcon">content_copy</span><span id="copyLabel" data-i18n="copy_report">Copy Report</span>
-        </button>
-      </div>`
+    ? `<div class="bg-[#0a0e14] border border-[#3a4a3f]/10 rounded-xl p-5 text-sm text-[#b9cbbd] leading-relaxed whitespace-pre-line" id="analysisText">${esc(analysisText)}</div>`
     : '';
 
   // ── Health status label ──
@@ -919,6 +930,9 @@ body{background:#0a0e14;color:#dfe2eb;font-family:'Inter',sans-serif}
             <p class="text-[10px] font-label uppercase tracking-[0.2em] text-[#849588] mb-1" data-i18n="sec_analysis">Security Analysis</p>
             <h1 class="text-2xl font-headline font-bold text-[#f5fff5] tracking-tight flex items-center gap-3">
               <span class="material-symbols-outlined" style="color:${tier.color}">analytics</span><span data-i18n="diag_report">Diagnostic Report</span>
+              <button onclick="copyReport()" id="copyBtn" class="flex items-center gap-1 px-2 py-1 bg-[#262a31] border border-[#3a4a3f]/30 rounded-lg text-[11px] font-semibold text-[#849588] hover:text-[#dfe2eb] hover:border-[#849588]/50 transition-all ml-1">
+                <span class="material-symbols-outlined text-sm" id="copyIcon">content_copy</span><span id="copyLabel" class="hidden sm:inline" data-i18n="copy_report">Copy Report</span>
+              </button>
             </h1>
           </div>
           <div class="bg-[#262a31] border border-[#3a4a3f]/15 rounded-lg px-4 py-2 flex items-center gap-2">
@@ -1036,7 +1050,7 @@ body{background:#0a0e14;color:#dfe2eb;font-family:'Inter',sans-serif}
   i18n.zh.quote=quotes_zh['${tier.grade}']||quotes_zh.B;
   i18n.en.quote='"${tier.quote.replace(/'/g,"\\'")}\"';
 
-  let curLang='en';
+  let curLang=(${JSON.stringify(data.analysis||'')}).match(/[\u4e00-\u9fff]/) ? 'zh' : 'en';
   window.toggleLang=function(){
     curLang=curLang==='en'?'zh':'en';
     document.getElementById('langLabel').textContent=curLang==='en'?'中文':'EN';
@@ -1054,6 +1068,22 @@ body{background:#0a0e14;color:#dfe2eb;font-family:'Inter',sans-serif}
     });
   };
 
+  // Apply initial language on load (auto-detect Chinese from analysis content)
+  if(curLang==='zh'){
+    document.getElementById('langLabel').textContent='EN';
+    document.querySelectorAll('[data-i18n]').forEach(el=>{
+      const key=el.getAttribute('data-i18n');
+      if(key==='findings_range'){
+        const range=el.getAttribute('data-range'),total=el.getAttribute('data-total');
+        el.textContent='发现 — '+range+' / 共 '+total;
+      } else if(i18n.zh[key]!=null)el.textContent=i18n.zh[key];
+    });
+    document.querySelectorAll('.finding-dim,.finding-text,.clean-dims,.rec-text').forEach(el=>{
+      const t=el.getAttribute('data-zh');
+      if(t)el.textContent=t;
+    });
+  }
+
   // Dimension data for share card (must be before shareReport)
   const _dims=${JSON.stringify(Object.fromEntries(Object.entries(DIM_META).map(([k])=>[k,dimensions[k]||{score:null,na:false}])))};
 
@@ -1334,11 +1364,35 @@ body{background:#0a0e14;color:#dfe2eb;font-family:'Inter',sans-serif}
 
   const outPath = join(tmpdir(), `agentguard-checkup-${Date.now()}.html`);
   writeFileSync(outPath, html, 'utf8');
-  console.log(outPath);
 
-  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-  exec(`${cmd} "${outPath}"`, (err) => {
-    if (err) process.stderr.write(`Could not open browser: ${err.message}\n`);
+  // Skip browser open for headless/bot environments (Qclaw, OpenClaw, CI)
+  const isHeadless = process.env.OPENCLAW_STATE_DIR || process.env.QCLAW || process.env.CI;
+
+  // Flush stdout before doing anything else — on Windows/Linux in non-TTY/pipe
+  // mode, console.log() is non-blocking and process.exit() can terminate before
+  // the buffer is flushed, causing the caller (Claude) to receive an empty path.
+  // Flush stdout before doing anything else — on Windows/Linux in non-TTY/pipe
+  // mode, console.log() is non-blocking and process.exit() can terminate before
+  // 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`);
+        });
+      }
+    }
+    // Hard exit after 3s — guards against exec child process hanging and
+    // blocking Node from exiting naturally (e.g. xdg-open on misconfigured Linux).
+    setTimeout(() => process.exit(0), 3000).unref();
   });
-  setTimeout(() => process.exit(0), 2000);
 }