Agentguard

If no subcommand is given, or the first argument is a path, default to scan.

Security Operations

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.

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:

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.

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

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: patrol

OpenClaw-specific daily security patrol. Runs 8 automated checks that leverage AgentGuard's scan engine, trust registry, and audit log to assess the security posture of an OpenClaw deployment.

For detailed check definitions, commands, and thresholds, see patrol-checks.md.

Sub-subcommands

• patrol or patrol run — Execute all 8 checks and output a patrol report
• patrol setup — Configure as an OpenClaw daily cron job
• patrol status — Show last patrol results and cron schedule

Pre-flight: OpenClaw Detection

Before running any checks, verify the OpenClaw environment:

1. Check for $OPENCLAW_STATE_DIR env var, fall back to ~/.openclaw/
2. Verify the directory exists and contains openclaw.json
3. Check if openclaw CLI is available in PATH

If OpenClaw is not detected, output:

This command requires an OpenClaw environment. Detected: <what was found/missing>
For non-OpenClaw environments, use /agentguard scan and /agentguard report instead.

Set $OC to the resolved OpenClaw state directory for all subsequent checks.

The 8 Patrol Checks

[1] Skill/Plugin Integrity

Detect tampered or unregistered skill packages by comparing file hashes against the trust registry.

Steps:

1. Discover skill directories under $OC/skills/ (look for dirs containing SKILL.md)
2. For each skill, compute hash: node scripts/trust-cli.ts hash --path <skill_dir>
3. Look up the attested hash: node scripts/trust-cli.ts lookup --source <skill_dir>
4. If hash differs from attested → INTEGRITY_DRIFT (HIGH)
5. If skill has no trust record → UNREGISTERED_SKILL (MEDIUM)
6. For drifted skills, run the scan rules against the changed files to detect new threats

[2] Secrets Exposure

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:
   • 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
   • action-policies.md secret patterns: AWS keys (AKIA...), GitHub tokens (gh[pousr]_...), DB connection strings
2. Scan any .env* files under $OC/ for plaintext credentials
3. Check ~/.ssh/ and ~/.gnupg/ directory permissions (should be 700)

[3] Network Exposure

Detect dangerous port exposure and firewall misconfigurations.

Steps:

1. List listening ports: ss -tlnp or lsof -i -P -n | grep LISTEN
2. Flag high-risk services on 0.0.0.0: Redis(6379), Docker API(2375), MySQL(3306), PostgreSQL(5432), MongoDB(27017)
3. Check firewall status: ufw status or iptables -L INPUT -n
4. Check outbound connections (ss -tnp state established) and cross-reference against action-policies.md webhook/exfil domain list and high-risk TLDs

[4] Cron & Scheduled Tasks

Audit all cron jobs for download-and-execute patterns.

Steps:

1. List OpenClaw cron jobs: openclaw cron list
2. List system crontab: crontab -l and contents of /etc/cron.d/
3. List systemd timers: systemctl list-timers --all
4. Scan all cron command bodies using scan-rules.md Rule 2 (AUTO_UPDATE) patterns: curl|bash, wget|sh, eval "$(curl, base64 -d | bash
5. Flag unknown cron jobs that touch $OC/ directories

[5] File System Changes (24h)

Detect suspicious file modifications in the last 24 hours.

Steps:

1. Find recently modified files: find $OC/ ~/.ssh/ ~/.gnupg/ /etc/cron.d/ -type f -mtime -1
2. For modified files with scannable extensions (.js/.ts/.py/.sh/.md/.json), run the full scan rule set
3. Check permissions on critical files:
   • $OC/openclaw.json → should be 600
   • $OC/devices/paired.json → should be 600
   • ~/.ssh/authorized_keys → should be 600
4. Detect new executable files in workspace: find $OC/workspace/ -type f -perm +111 -mtime -1

[6] Audit Log Analysis (24h)

Analyze AgentGuard's audit trail for attack patterns.

Steps:

1. Read ~/.agentguard/audit.jsonl, filter to last 24h by timestamp
2. Compute statistics: total events, deny/confirm/allow counts, group denials by risk_tags and initiating_skill
3. Flag patterns:
   • Same skill denied 3+ times → potential attack (HIGH)
   • Any event with risk_level: critical → (CRITICAL)
   • WEBHOOK_EXFIL or NET_EXFIL_UNRESTRICTED tags → (HIGH)
   • PROMPT_INJECTION tag → (CRITICAL)
4. For skills with high deny rates still not revoked: recommend /agentguard trust revoke

[7] Environment & Configuration

Verify security configuration is production-appropriate.

Steps:

1. List environment variables matching sensitive names (values masked): API_KEY, SECRET, PASSWORD, TOKEN, PRIVATE, CREDENTIAL
2. Check if GOPLUS_API_KEY/GOPLUS_API_SECRET are configured (if Web3 features are in use)
3. Read ~/.agentguard/config.json — flag permissive protection level in production
4. If $OC/.config-baseline.sha256 exists, verify: sha256sum -c $OC/.config-baseline.sha256

[8] Trust Registry Health

Check for expired, stale, or over-privileged trust records.

Steps:

1. List all records: node scripts/trust-cli.ts list
2. Flag:
   • Expired attestations (expires_at in the past)
   • Trusted skills not re-scanned in 30+ days
   • Installed skills with untrusted status
   • Over-privileged skills: exec: allow combined with network_allowlist: ["*"]
3. Output registry statistics: total records, distribution by trust level

Patrol Report Format

## GoPlus AgentGuard Patrol Report

**Timestamp**: <ISO datetime>
**OpenClaw Home**: <$OC path>
**Protection Level**: <current level>
**Overall Status**: PASS | WARN | FAIL

### Check Results

| # | Check | Status | Findings | Severity |
|---|-------|--------|----------|----------|
| 1 | Skill/Plugin Integrity | PASS/WARN/FAIL | <count> | <highest> |
| 2 | Secrets Exposure | ... | ... | ... |
| 3 | Network Exposure | ... | ... | ... |
| 4 | Cron & Scheduled Tasks | ... | ... | ... |
| 5 | File System Changes | ... | ... | ... |
| 6 | Audit Log Analysis | ... | ... | ... |
| 7 | Environment & Config | ... | ... | ... |
| 8 | Trust Registry Health | ... | ... | ... |

### Findings Detail
(only checks with findings are shown)

#### [N] Check Name
- <finding with file path, evidence, and severity>

### Recommendations
1. [SEVERITY] <actionable recommendation>

### Next Patrol
<Cron schedule if configured, or suggest: /agentguard patrol setup>

Overall status: Any CRITICAL → FAIL, any HIGH → WARN, else PASS

After outputting the report, append a summary entry to ~/.agentguard/audit.jsonl:

{"timestamp":"...","event":"patrol","overall_status":"PASS|WARN|FAIL","checks":8,"findings":<count>,"critical":<count>,"high":<count>}

patrol setup

Configure the patrol as an OpenClaw daily cron job.

Steps:

1. Verify OpenClaw environment (same pre-flight as patrol run)
2. Ask the user for:
   • Timezone (default: UTC). Examples: Asia/Shanghai, America/New_York, Europe/London
   • Schedule (default: 0 3 * * * — daily at 03:00)
   • Notification channel (optional): telegram, discord, signal
   • Chat ID / webhook (required if channel is set)
3. Generate the cron registration command:

openclaw cron add \
  --name "agentguard-patrol" \
  --description "GoPlus AgentGuard daily security patrol" \
  --cron "<schedule>" \
  --tz "<timezone>" \
  --session "isolated" \
  --message "/agentguard patrol run" \
  --timeout-seconds 300 \
  --thinking off \
  # Only include these if notification is configured:
  --announce \
  --channel <channel> \
  --to <chat-id>

4. Show the exact command to the user and wait for explicit confirmation before executing
5. After execution, verify with openclaw cron list
6. Output confirmation with the cron schedule

Note: --timeout-seconds 300 is required because isolated sessions need cold-start time. The default 120s is not enough.

patrol status

Show the current patrol state.

Steps:

1. Read ~/.agentguard/audit.jsonl, find the most recent event: "patrol" entry
2. If found, display: timestamp, overall status, finding counts
3. Run openclaw cron list and look for agentguard-patrol job
4. If cron is configured, show: schedule, timezone, last run time, next run time
5. If cron is not configured, suggest: /agentguard patrol setup

Trust & Configuration

Subcommand: trust

Manage skill trust levels using the GoPlus AgentGuard registry.

Trust Levels

Capability Model

network_allowlist: string[]     — Allowed domains (supports *.example.com)
filesystem_allowlist: string[]  — Allowed file paths