@goplus/agentguard 1.0.4 → 1.0.6

package/skills/agentguard/scripts/auto-scan.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+/**
+ * GoPlus AgentGuard — SessionStart Auto-Scan Hook
+ *
+ * Runs on session startup to discover and scan newly installed skills.
+ * For each skill in ~/.claude/skills/:
+ *   1. Calculate artifact hash
+ *   2. Check trust registry — skip if already registered with same hash
+ *   3. Run quickScan for new/updated skills
+ *   4. Report results to stderr (scan-only, does NOT modify trust registry)
+ *
+ * OPT-IN: This script only runs when AGENTGUARD_AUTO_SCAN=1.
+ * Without this env var, the script exits immediately.
+ *
+ * To register scanned skills, use: /agentguard trust attest
+ *
+ * Exits 0 always (informational only, never blocks session startup).
+ */
+
+import { readdirSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// ---------------------------------------------------------------------------
+// Opt-in gate: only run when explicitly enabled
+// ---------------------------------------------------------------------------
+
+if (process.env.AGENTGUARD_AUTO_SCAN !== '1') {
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Load AgentGuard engine
+// ---------------------------------------------------------------------------
+
+const agentguardPath = join(
+  import.meta.url.replace('file://', ''),
+  '..', '..', '..', '..', 'dist', 'index.js'
+);
+
+let createAgentGuard;
+try {
+  const gs = await import(agentguardPath);
+  createAgentGuard = gs.createAgentGuard || gs.default;
+} catch {
+  try {
+    const gs = await import('@goplus/agentguard');
+    createAgentGuard = gs.createAgentGuard || gs.default;
+  } catch {
+    // Can't load engine — exit silently
+    process.exit(0);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const SKILLS_DIRS = [
+  join(homedir(), '.claude', 'skills'),
+  join(homedir(), '.openclaw', 'skills'),
+];
+const AGENTGUARD_DIR = join(homedir(), '.agentguard');
+const AUDIT_PATH = join(AGENTGUARD_DIR, 'audit.jsonl');
+
+function ensureDir() {
+  if (!existsSync(AGENTGUARD_DIR)) {
+    mkdirSync(AGENTGUARD_DIR, { recursive: true });
+  }
+}
+
+function writeAuditLog(entry) {
+  try {
+    ensureDir();
+    appendFileSync(AUDIT_PATH, JSON.stringify(entry) + '\n');
+  } catch {
+    // Non-critical
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discover skills
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all skill directories under ~/.claude/skills/ and ~/.openclaw/skills/
+ * A skill directory is one that contains a SKILL.md file.
+ */
+function discoverSkills() {
+  const skills = [];
+  for (const skillsDir of SKILLS_DIRS) {
+    if (!existsSync(skillsDir)) continue;
+    try {
+      const entries = readdirSync(skillsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const skillDir = join(skillsDir, entry.name);
+        const skillMd = join(skillDir, 'SKILL.md');
+        if (existsSync(skillMd)) {
+          skills.push({ name: entry.name, path: skillDir });
+        }
+      }
+    } catch {
+      // Can't read skills dir
+    }
+  }
+  return skills;
+}
+
+// ---------------------------------------------------------------------------
+// Main — scan-only mode (no trust registry mutations)
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const skills = discoverSkills();
+  if (skills.length === 0) {
+    process.exit(0);
+  }
+
+  const { scanner } = createAgentGuard();
+
+  let scanned = 0;
+  const results = [];
+
+  for (const skill of skills) {
+    // Skip self (agentguard)
+    if (skill.name === 'agentguard') continue;
+
+    try {
+      const result = await scanner.quickScan(skill.path);
+      scanned++;
+
+      results.push({
+        name: skill.name,
+        risk_level: result.risk_level,
+        risk_tags: result.risk_tags,
+      });
+
+      // Audit log — only record skill name, risk level, and tag names (no code/evidence)
+      writeAuditLog({
+        timestamp: new Date().toISOString(),
+        event: 'auto_scan',
+        skill_name: skill.name,
+        risk_level: result.risk_level,
+        risk_tags: result.risk_tags,
+      });
+    } catch {
+      // Skip skills that fail to scan
+    }
+  }
+
+  // Output summary to stderr (shown as status message)
+  if (scanned > 0) {
+    const lines = results.map(r =>
+      `  ${r.name}: ${r.risk_level}${r.risk_tags.length ? ` [${r.risk_tags.join(', ')}]` : ''}`
+    );
+    process.stderr.write(
+      `GoPlus AgentGuard: scanned ${scanned} skill(s)\n${lines.join('\n')}\n` +
+      `Use /agentguard trust attest to register trusted skills.\n`
+    );
+  }
+
+  process.exit(0);
+}
+
+main();

package/skills/agentguard/scripts/guard-hook.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+/**
+ * GoPlus AgentGuard PreToolUse / PostToolUse Hook (Claude Code)
+ *
+ * Uses the common adapter + engine architecture.
+ * Reads Claude Code hook input from stdin, delegates to evaluateHook(),
+ * and outputs allow / deny / ask via Claude Code protocol.
+ *
+ * PreToolUse exit codes:
+ *   0  = allow (or JSON with permissionDecision)
+ *   2  = deny  (stderr = reason shown to Claude)
+ *
+ * PostToolUse: appends audit log entry (async, always exits 0)
+ */
+
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Load AgentGuard engine + adapters
+// ---------------------------------------------------------------------------
+
+const agentguardPath = join(import.meta.url.replace('file://', ''), '..', '..', '..', '..', 'dist', 'index.js');
+
+let createAgentGuard, ClaudeCodeAdapter, evaluateHook, loadConfig;
+try {
+  const gs = await import(agentguardPath);
+  createAgentGuard = gs.createAgentGuard || gs.default;
+  ClaudeCodeAdapter = gs.ClaudeCodeAdapter;
+  evaluateHook = gs.evaluateHook;
+  loadConfig = gs.loadConfig;
+} catch {
+  try {
+    const gs = await import('@goplus/agentguard');
+    createAgentGuard = gs.createAgentGuard || gs.default;
+    ClaudeCodeAdapter = gs.ClaudeCodeAdapter;
+    evaluateHook = gs.evaluateHook;
+    loadConfig = gs.loadConfig;
+  } catch {
+    process.stderr.write('GoPlus AgentGuard: unable to load engine, allowing action\n');
+    process.exit(0);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read stdin
+// ---------------------------------------------------------------------------
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(data));
+      } catch {
+        resolve(null);
+      }
+    });
+    setTimeout(() => resolve(null), 5000);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code output helpers
+// ---------------------------------------------------------------------------
+
+function outputDeny(reason) {
+  process.stderr.write(reason + '\n');
+  process.exit(2);
+}
+
+function outputAsk(reason) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'ask',
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.exit(0);
+}
+
+function outputAllow() {
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const input = await readStdin();
+  if (!input) {
+    process.exit(0);
+  }
+
+  const adapter = new ClaudeCodeAdapter();
+  const config = loadConfig();
+  const agentguard = createAgentGuard();
+
+  const result = await evaluateHook(adapter, input, { config, agentguard });
+
+  if (result.decision === 'deny') outputDeny(result.reason || 'Action blocked');
+  else if (result.decision === 'ask') outputAsk(result.reason || 'Action requires confirmation');
+  else outputAllow();
+}
+
+main();

package/skills/agentguard/scripts/package.json

@@ -0,0 +1,7 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@goplus/agentguard": "file:../../.."
+  }
+}

package/skills/agentguard/scripts/trust-cli.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * GoPlus AgentGuard Trust CLI — lightweight wrapper for SkillRegistry operations.
+ *
+ * Usage:
+ *   node trust-cli.ts lookup --id <id> --source <source> --version <version> --hash <hash>
+ *   node trust-cli.ts attest  --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> [--preset <preset>] [--capabilities <json>] [--reviewed-by <name>] [--notes <text>] [--expires <iso>] [--force]
+ *   node trust-cli.ts revoke  [--source <source>] [--key <record_key>] --reason <reason>
+ *   node trust-cli.ts list    [--trust-level <level>] [--status <status>] [--source-pattern <pattern>]
+ *   node trust-cli.ts hash    --path <dir>
+ */
+
+import { createAgentGuard, CAPABILITY_PRESETS, SkillScanner } from '@goplus/agentguard';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getArg(name: string): string | undefined {
+  const idx = args.indexOf(`--${name}`);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+function hasFlag(name: string): boolean {
+  return args.includes(`--${name}`);
+}
+
+async function main() {
+  const registryPath = getArg('registry-path');
+  const { registry } = createAgentGuard({ registryPath });
+
+  switch (command) {
+    case 'lookup': {
+      const skill = {
+        id: getArg('id') || '',
+        source: getArg('source') || '',
+        version_ref: getArg('version') || '',
+        artifact_hash: getArg('hash') || '',
+      };
+      const record = await registry.lookup(skill);
+      console.log(JSON.stringify(record, null, 2));
+      break;
+    }
+
+    case 'attest': {
+      const skill = {
+        id: getArg('id') || '',
+        source: getArg('source') || '',
+        version_ref: getArg('version') || '',
+        artifact_hash: getArg('hash') || '',
+      };
+      const trustLevel = (getArg('trust-level') || 'restricted') as
+        | 'untrusted'
+        | 'restricted'
+        | 'trusted';
+
+      let capabilities;
+      const preset = getArg('preset');
+      if (preset && preset in CAPABILITY_PRESETS) {
+        capabilities =
+          CAPABILITY_PRESETS[preset as keyof typeof CAPABILITY_PRESETS];
+      } else if (getArg('capabilities')) {
+        capabilities = JSON.parse(getArg('capabilities')!);
+      }
+
+      const force = hasFlag('force');
+      const attestFn = force ? registry.forceAttest : registry.attest;
+      const result = await attestFn.call(registry, {
+        skill,
+        trust_level: trustLevel,
+        capabilities,
+        review: {
+          reviewed_by: getArg('reviewed-by') || 'cli',
+          reviewed_at: new Date().toISOString(),
+          notes: getArg('notes') || '',
+        },
+        expires_at: getArg('expires'),
+      });
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'revoke': {
+      const source = getArg('source');
+      const key = getArg('key');
+      const reason = getArg('reason') || 'Revoked via CLI';
+      const result = await registry.revoke(
+        { source, record_key: key },
+        reason
+      );
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'list': {
+      const filters: Record<string, string> = {};
+      const trustLevel = getArg('trust-level');
+      const status = getArg('status');
+      const sourcePattern = getArg('source-pattern');
+      if (trustLevel) filters.trust_level = trustLevel;
+      if (status) filters.status = status;
+      if (sourcePattern) filters.source_pattern = sourcePattern;
+
+      const records = await registry.list(filters);
+      console.log(JSON.stringify(records, null, 2));
+      break;
+    }
+
+    case 'hash': {
+      const dirPath = getArg('path');
+      if (!dirPath) {
+        console.error('Error: --path is required for hash');
+        process.exit(1);
+      }
+      const scanner = new SkillScanner({ useExternalScanner: false });
+      const hash = await scanner.calculateArtifactHash(dirPath);
+      console.log(JSON.stringify({ hash }));
+      break;
+    }
+
+    default:
+      console.error(
+        'Usage: trust-cli.ts <lookup|attest|revoke|list|hash> [options]'
+      );
+      console.error('Run with --help for details.');
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(JSON.stringify({ error: err.message }));
+  process.exit(1);
+});

package/skills/agentguard/web3-patterns.md

@@ -0,0 +1,161 @@
+# Web3 Vulnerability Patterns Reference
+
+Detailed vulnerability patterns for the `web3` subcommand. Use this when performing Web3/smart contract security audits.
+
+## Solidity Vulnerability Categories
+
+### 1. Reentrancy (HIGH)
+
+**Pattern**: External call before state update in the same function.
+
+```solidity
+// VULNERABLE: state updated after external call
+function withdraw(uint amount) public {
+    require(balances[msg.sender] >= amount);
+    (bool success, ) = msg.sender.call{value: amount}("");  // external call
+    balances[msg.sender] -= amount;  // state change AFTER call
+}
+```
+
+**Detection**: Look for `.call{`, `.transfer(`, `.send(` followed by storage variable assignment (`var =`, `var +=`, `var -=`) within the same function body.
+
+**Fix**: Use Checks-Effects-Interactions pattern or ReentrancyGuard.
+
+### 2. Wallet Draining (CRITICAL)
+
+**Patterns**:
+- `approve()` with max uint256 value followed by `transferFrom()`
+- `permit()` with far-future deadline enabling gasless approvals
+- Approval granted to attacker-controlled address
+
+**Detection**:
+- `approve(address, type(uint256).max)` or `MaxUint256` or `2**256-1`
+- `transferFrom` in same contract/flow as `approve`
+- `permit(` with `deadline` parameter
+
+### 3. Unlimited Approval (HIGH)
+
+**Pattern**: Token approval for maximum amount, giving spender unlimited access.
+
+```solidity
+token.approve(spender, type(uint256).max);
+token.setApprovalForAll(operator, true);
+```
+
+**Risk**: If the spender contract is compromised, all approved tokens can be drained.
+
+### 4. Self-Destruct (HIGH)
+
+**Pattern**: `selfdestruct(address)` or deprecated `suicide(address)`.
+
+**Risk**: Permanently destroys the contract, sending remaining ETH to the specified address. Can be exploited if access control is weak.
+
+### 5. Signature Replay (HIGH)
+
+**Pattern**: Using `ecrecover()` without nonce or chain ID protection.
+
+```solidity
+// VULNERABLE: no nonce, signature can be replayed
+function execute(bytes memory signature, uint amount) public {
+    bytes32 hash = keccak256(abi.encodePacked(msg.sender, amount));
+    address signer = ecrecover(hash, v, r, s);
+    // Missing: nonce check, chain ID, contract address in hash
+}
+```
+
+**Fix**: Include nonce, chainId, and contract address in signed message. Use EIP-712 typed data.
+
+### 6. Flash Loan Attacks (MEDIUM)
+
+**Patterns**:
+- `flashLoan()`, `IFlashLoan`, `executeOperation()`
+- AAVE/dYdX/Uniswap flash loan interfaces
+
+**Risk**: Attacker borrows large amounts without collateral within a single transaction to manipulate prices, governance, or vulnerable protocols.
+
+**Check**: Ensure price oracles use TWAP, governance has timelock, and lending markets have proper collateral checks.
+
+### 7. Proxy Upgrade Risks (MEDIUM)
+
+**Patterns**:
+- `upgradeTo(address)`, `upgradeToAndCall(address, bytes)`
+- `_setImplementation()`, `IMPLEMENTATION_SLOT`
+- Transparent proxy / UUPS patterns
+
+**Check**:
+- Is upgrade function access-controlled?
+- Is there a timelock on upgrades?
+- Can the proxy be upgraded to a malicious implementation?
+
+### 8. Hidden Transfers (MEDIUM)
+
+**Pattern**: ETH or token transfers hidden in functions not named transfer/send.
+
+```solidity
+// Transfer hidden in an innocuous-looking function
+function updateConfig(address _new) public {
+    payable(_new).transfer(address(this).balance);  // hidden drain
+}
+```
+
+**Detection**: `.transfer(`, `.call{value:}` in functions not named `transfer`, `_transfer`, `send`, `withdraw`.
+
+### 9. Price Oracle Manipulation
+
+**Patterns**:
+- Single-block spot price from DEX (e.g., `getReserves()` used directly for pricing)
+- No TWAP (Time-Weighted Average Price) implementation
+- Price feed without staleness check
+
+**Check**: Look for Uniswap `getReserves()`, Chainlink `latestRoundData()` without `updatedAt` staleness check.
+
+### 10. Access Control Issues
+
+**Patterns**:
+- Public/external functions that modify critical state without access modifiers
+- Missing `onlyOwner`, `onlyRole`, or similar guards
+- `tx.origin` used for authentication (vulnerable to phishing)
+
+**Check**:
+- All state-changing functions should have appropriate access control
+- `tx.origin` should never be used for authorization (use `msg.sender`)
+- Owner/admin functions should be behind multisig or timelock
+
+## JavaScript/TypeScript Web3 Patterns
+
+### Private Key Exposure
+
+- Hardcoded private keys: `0x` followed by 64 hex characters in quotes
+- `PRIVATE_KEY` in environment variable assignments
+- Private key in config files, .env files committed to repo
+
+### Mnemonic Exposure
+
+- BIP-39 seed phrases (12-24 words) in source code
+- `seed_phrase`, `mnemonic`, `recovery_phrase` variable assignments
+
+### Unsafe RPC Usage
+
+- Sending signed transactions without user confirmation
+- Using `eth_sendTransaction` with hardcoded parameters
+- Missing gas limit estimation (risk of out-of-gas)
+
+### Front-End Risks
+
+- Phishing patterns: UI mimicking wallet approval screens
+- Hidden iframe/overlay for approval harvesting
+- Approval transactions disguised as other operations
+
+## GoPlus Security Checks (Optional)
+
+If GoPlus API is available, these additional checks can be performed:
+
+| Check | API | Description |
+|-------|-----|-------------|
+| Token Security | `tokenSecurity(chainId, address)` | Honeypot, tax, owner control |
+| Address Security | `addressSecurity(chainId, address)` | Blacklisted, phishing, mixer |
+| Approval Risk | `approvalSecurity(chainId, address)` | Risky approvals |
+| Phishing Site | `phishingSite(url)` | Known phishing URL |
+| Transaction Simulation | `simulateTransaction(...)` | Pre-execution risk analysis |
+
+Requires `GOPLUS_API_KEY` and `GOPLUS_API_SECRET` environment variables.