@goplus/agentguard 1.1.9 → 1.1.13

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

@@ -4,10 +4,10 @@
  * GoPlus AgentGuard Hermes shell hook.
  *
  * Hermes shell hooks read JSON from stdin and use stdout JSON to influence
- * behavior. For pre_tool_call, returning { action: "block", message: "..." }
- * vetoes tool execution. There is no native "ask" decision in Hermes'
- * pre_tool_call contract, so AgentGuard's ask decision is represented as a
- * block with a confirmation-oriented message.
+ * behavior. For pre_tool_call, returning a block decision vetoes tool
+ * execution. There is no native "ask" decision in Hermes' pre_tool_call
+ * contract, so AgentGuard's confirmation decision is represented as a block
+ * with a confirmation-oriented message.
  */
 
 import { join } from 'node:path';
@@ -62,6 +62,11 @@ function validatePreToolPayload(input) {
       return null;
     case 'web_extract':
     case 'browser_navigate':
+    case 'browser_open':
+    case 'web_open':
+    case 'open_url':
+    case 'visit_url':
+    case 'open':
       if (!firstString(toolInput.url, toolInput.href, toolInput.target)) return `Hermes ${toolName} hook payload is missing URL`;
       return null;
     case 'web_search':
@@ -82,7 +87,7 @@ function shouldFailClosed(input) {
 
 const agentguardPath = join(import.meta.url.replace('file://', ''), '..', '..', '..', '..', 'dist', 'index.js');
 
-let createAgentGuard, HermesAdapter, evaluateHook, loadConfig;
+let loadRuntimeConfig, loadHookConfig, protectAction, createAgentGuard, HermesAdapter, evaluateHook;
 
 async function loadEngine() {
   if (process.env.AGENTGUARD_TEST_FORCE_ENGINE_LOAD_FAILURE === '1') {
@@ -92,19 +97,23 @@ async function loadEngine() {
   try {
     const gs = await import(agentguardPath);
     return {
+      loadRuntimeConfig: gs.loadAgentGuardConfig || gs.ensureConfig,
+      loadHookConfig: gs.loadConfig,
+      protectAction: gs.protectAction,
       createAgentGuard: gs.createAgentGuard || gs.default,
       HermesAdapter: gs.HermesAdapter,
       evaluateHook: gs.evaluateHook,
-      loadConfig: gs.loadConfig,
     };
   } catch {
     try {
       const gs = await import('@goplus/agentguard');
       return {
+        loadRuntimeConfig: gs.loadAgentGuardConfig || gs.ensureConfig,
+        loadHookConfig: gs.loadConfig,
+        protectAction: gs.protectAction,
         createAgentGuard: gs.createAgentGuard || gs.default,
         HermesAdapter: gs.HermesAdapter,
         evaluateHook: gs.evaluateHook,
-        loadConfig: gs.loadConfig,
       };
     } catch {
       return null;
@@ -148,7 +157,10 @@ function readStdin() {
 function outputBlock(reason) {
   console.log(JSON.stringify({
     action: 'block',
+    decision: 'block',
+    block: true,
     message: reason || 'GoPlus AgentGuard blocked this action',
+    reason: reason || 'GoPlus AgentGuard blocked this action',
   }));
   process.exit(0);
 }
@@ -158,6 +170,41 @@ function outputAllow() {
   process.exit(0);
 }
 
+function runtimeActionTypeFrom(toolName) {
+  switch (toolName) {
+    case 'terminal':
+    case 'execute_code':
+      return 'shell';
+    case 'write_file':
+    case 'patch':
+    case 'skill_manage':
+      return 'file_write';
+    case 'read_file':
+      return 'file_read';
+    case 'web_search':
+    case 'web_extract':
+    case 'browser_navigate':
+    case 'browser_open':
+    case 'web_open':
+    case 'open_url':
+    case 'visit_url':
+    case 'open':
+      return 'network';
+    default:
+      return 'other';
+  }
+}
+
+function runtimeToolNameFrom(toolName) {
+  return toolName || 'HermesTool';
+}
+
+function debugLog(message, details) {
+  if (process.env.AGENTGUARD_HERMES_DEBUG !== '1') return;
+  const suffix = details === undefined ? '' : ` ${JSON.stringify(details)}`;
+  console.error(`[AgentGuard Hermes] ${message}${suffix}`);
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -181,21 +228,61 @@ async function main() {
     outputAllow();
   }
 
-  ({ createAgentGuard, HermesAdapter, evaluateHook, loadConfig } = engine);
+  ({ loadRuntimeConfig, loadHookConfig, protectAction, createAgentGuard, HermesAdapter, evaluateHook } = engine);
+
+  if (isPostHook(input)) {
+    try {
+      if (createAgentGuard && HermesAdapter && evaluateHook) {
+        const adapter = new HermesAdapter();
+        const config = loadHookConfig ? loadHookConfig() : { level: loadRuntimeConfig().level };
+        const agentguard = createAgentGuard();
+        await evaluateHook(adapter, input, { config, agentguard });
+      }
+    } catch {
+      // Post hooks are audit-only; never affect Hermes execution.
+    }
+    outputAllow();
+  }
+
+  const config = loadRuntimeConfig();
+  const result = await protectAction({
+    config,
+    rawInput: input,
+    agentHost: 'hermes',
+    actionType: runtimeActionTypeFrom(toolNameFrom(input)),
+    toolName: runtimeToolNameFrom(toolNameFrom(input)),
+    sessionId: typeof input.session_id === 'string' ? input.session_id : undefined,
+  });
 
-  const adapter = new HermesAdapter();
-  const config = loadConfig();
-  const agentguard = createAgentGuard();
+  if (!result) {
+    debugLog('allow: no runtime action was built');
+    outputAllow();
+  }
 
-  const result = await evaluateHook(adapter, input, { config, agentguard });
+  debugLog('decision', {
+    decision: result.decision.decision,
+    riskLevel: result.decision.riskLevel,
+    riskScore: result.decision.riskScore,
+    policySource: result.policySource,
+  });
 
-  if (result.decision === 'deny') {
-    outputBlock(result.reason || 'GoPlus AgentGuard blocked this Hermes tool call');
-  } else if (result.decision === 'ask') {
-    outputBlock(result.reason || 'GoPlus AgentGuard requires confirmation for this Hermes tool call');
+  if (result.decision.decision === 'block') {
+    outputBlock(formatDecisionReason(result, 'blocked this Hermes tool call'));
+  } else if (result.decision.decision === 'require_approval') {
+    outputBlock(formatDecisionReason(result, 'requires confirmation for this Hermes tool call'));
   } else {
     outputAllow();
   }
 }
 
+function formatDecisionReason(result, fallback) {
+  const titles = result.decision.reasons
+    .map((item) => item.title)
+    .filter(Boolean)
+    .slice(0, 3)
+    .join(', ');
+  const suffix = titles ? ` Reasons: ${titles}.` : '';
+  return `GoPlus AgentGuard ${fallback} (action: ${result.decision.actionId}, risk: ${result.decision.riskScore}/100, level: ${result.decision.riskLevel}).${suffix}`;
+}
+
 main();

package/skills/agentguard/scripts/scan-to-sarif.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * scan-to-sarif.js — convert AgentGuard scan findings to SARIF 2.1.0
+ *
+ * Usage:
+ *   node scripts/scan-to-sarif.js --file <findings.json>
+ *   cat findings.json | node scripts/scan-to-sarif.js
+ *
+ * Input schema (findings.json):
+ * {
+ *   "target": "<scanned path>",
+ *   "scanned_at": "<ISO 8601>",
+ *   "files_scanned": <number>,
+ *   "risk_level": "CRITICAL|HIGH|MEDIUM|LOW",
+ *   "findings": [
+ *     {
+ *       "rule_id": "SHELL_EXEC",
+ *       "severity": "CRITICAL|HIGH|MEDIUM|LOW",
+ *       "file": "relative/path/to/file.js",
+ *       "line": 42,
+ *       "evidence": "matched content snippet"
+ *     }
+ *   ]
+ * }
+ *
+ * Output: SARIF 2.1.0 JSON to stdout
+ */
+
+import { readFileSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Rule definitions (all 24 AgentGuard rules)
+// ---------------------------------------------------------------------------
+
+const RULES = [
+  { id: 'SHELL_EXEC',             name: 'Shell Command Execution',        severity: 'HIGH',     description: 'Detects capabilities to execute shell commands (child_process, subprocess, os.system).' },
+  { id: 'AUTO_UPDATE',            name: 'Auto-Update / Download-Execute', severity: 'CRITICAL', description: 'Detects scheduled self-update or download-and-execute patterns (curl|bash, wget|sh).' },
+  { id: 'REMOTE_LOADER',          name: 'Remote Code Loader',             severity: 'CRITICAL', description: 'Detects dynamic code loading from remote sources (dynamic import, eval(fetch(...))).' },
+  { id: 'READ_ENV_SECRETS',       name: 'Environment Secret Access',      severity: 'MEDIUM',   description: 'Detects access to environment variables that may contain secrets (process.env, os.environ).' },
+  { id: 'READ_SSH_KEYS',          name: 'SSH Key Access',                 severity: 'CRITICAL', description: 'Detects references to SSH key files (~/.ssh/id_rsa, authorized_keys, etc.).' },
+  { id: 'READ_KEYCHAIN',          name: 'System Keychain Access',         severity: 'CRITICAL', description: 'Detects access to system keychains, browser credential stores, or Windows Credential Manager.' },
+  { id: 'PRIVATE_KEY_PATTERN',    name: 'Hardcoded Private Key',          severity: 'CRITICAL', description: 'Detects hardcoded Ethereum private keys or PEM private key headers in source code.' },
+  { id: 'MNEMONIC_PATTERN',       name: 'Hardcoded Mnemonic Phrase',      severity: 'CRITICAL', description: 'Detects hardcoded BIP-39 mnemonic seed phrases in source code.' },
+  { id: 'WALLET_DRAINING',        name: 'Wallet Draining Pattern',        severity: 'CRITICAL', description: 'Detects approve+transferFrom or permit patterns that can drain wallets.' },
+  { id: 'UNLIMITED_APPROVAL',     name: 'Unlimited Token Approval',       severity: 'HIGH',     description: 'Detects ERC-20 approve(MaxUint256) or setApprovalForAll(true) patterns.' },
+  { id: 'DANGEROUS_SELFDESTRUCT', name: 'Dangerous selfdestruct',         severity: 'HIGH',     description: 'Detects selfdestruct() or suicide() calls in Solidity contracts.' },
+  { id: 'HIDDEN_TRANSFER',        name: 'Hidden Transfer',                severity: 'MEDIUM',   description: 'Detects ETH transfers hidden inside non-transfer functions.' },
+  { id: 'PROXY_UPGRADE',          name: 'Proxy Upgrade Pattern',          severity: 'MEDIUM',   description: 'Detects upgradeable proxy patterns that may allow unauthorized logic replacement.' },
+  { id: 'FLASH_LOAN_RISK',        name: 'Flash Loan Risk',                severity: 'MEDIUM',   description: 'Detects flash loan usage that may enable price manipulation or reentrancy attacks.' },
+  { id: 'REENTRANCY_PATTERN',     name: 'Reentrancy Vulnerability',       severity: 'HIGH',     description: 'Detects external calls followed by state changes, violating Checks-Effects-Interactions.' },
+  { id: 'SIGNATURE_REPLAY',       name: 'Signature Replay Risk',          severity: 'HIGH',     description: 'Detects ecrecover usage without nonce protection, enabling signature replay attacks.' },
+  { id: 'OBFUSCATION',            name: 'Code Obfuscation',               severity: 'HIGH',     description: 'Detects obfuscated code patterns (eval, hex escape sequences, packed JS, etc.).' },
+  { id: 'PROMPT_INJECTION',       name: 'Prompt Injection Attempt',       severity: 'CRITICAL', description: 'Detects instructions that attempt to override AI agent behavior or bypass safety controls.' },
+  { id: 'NET_EXFIL_UNRESTRICTED', name: 'Unrestricted Network Exfiltration', severity: 'HIGH', description: 'Detects unrestricted POST requests or file uploads that may exfiltrate data.' },
+  { id: 'WEBHOOK_EXFIL',          name: 'Webhook Exfiltration',           severity: 'CRITICAL', description: 'Detects hardcoded webhook URLs (Discord, Telegram, Slack, ngrok) used for data exfiltration.' },
+  { id: 'TROJAN_DISTRIBUTION',    name: 'Trojan Binary Distribution',     severity: 'CRITICAL', description: 'Detects trojanized binary download patterns (URL + password + execute instructions).' },
+  { id: 'SUSPICIOUS_PASTE_URL',   name: 'Suspicious Paste Site URL',      severity: 'HIGH',     description: 'Detects URLs pointing to paste sites (Pastebin, Hastebin, etc.) used for payload delivery.' },
+  { id: 'SUSPICIOUS_IP',          name: 'Hardcoded Public IP Address',    severity: 'MEDIUM',   description: 'Detects hardcoded public IPv4 addresses that may point to attacker-controlled infrastructure.' },
+  { id: 'SOCIAL_ENGINEERING',     name: 'Social Engineering Pressure',    severity: 'HIGH',     description: 'Detects manipulative language combined with execution instructions targeting agent users.' },
+];
+
+const RULE_INDEX = new Map(RULES.map(r => [r.id, r]));
+
+// ---------------------------------------------------------------------------
+// Severity mapping: AgentGuard → SARIF
+// ---------------------------------------------------------------------------
+
+function toSarifLevel(severity) {
+  switch ((severity || '').toUpperCase()) {
+    case 'CRITICAL': return 'error';
+    case 'HIGH':     return 'warning';
+    case 'MEDIUM':   return 'note';
+    default:         return 'none';
+  }
+}
+
+// Map AgentGuard severity to SARIF security-severity score (CVSS-like, 0.0–10.0)
+function toSecuritySeverity(severity) {
+  switch ((severity || '').toUpperCase()) {
+    case 'CRITICAL': return '9.0';
+    case 'HIGH':     return '7.0';
+    case 'MEDIUM':   return '4.0';
+    default:         return '1.0';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+
+function readInput() {
+  const fileIdx = process.argv.indexOf('--file');
+  if (fileIdx !== -1 && process.argv[fileIdx + 1]) {
+    return JSON.parse(readFileSync(process.argv[fileIdx + 1], 'utf-8'));
+  }
+  return JSON.parse(readFileSync('/dev/stdin', 'utf-8'));
+}
+
+// ---------------------------------------------------------------------------
+// Build SARIF
+// ---------------------------------------------------------------------------
+
+function buildSarif(input) {
+  const findings = input.findings || [];
+
+  // Collect which rules actually fired (for the driver.rules array)
+  const firedRuleIds = new Set(findings.map(f => f.rule_id));
+
+  // Build driver rules — include all fired rules, plus any referenced ones
+  const driverRules = RULES
+    .filter(r => firedRuleIds.has(r.id))
+    .map(r => ({
+      id: r.id,
+      name: r.name,
+      shortDescription: { text: r.name },
+      fullDescription: { text: r.description },
+      defaultConfiguration: {
+        level: toSarifLevel(r.severity),
+      },
+      properties: {
+        tags: ['security'],
+        'security-severity': toSecuritySeverity(r.severity),
+        'problem.severity': r.severity.toLowerCase(),
+      },
+      helpUri: 'https://github.com/GoPlusSecurity/agentguard',
+    }));
+
+  // Build results
+  const results = findings.map(f => {
+    const rule = RULE_INDEX.get(f.rule_id) || { severity: f.severity || 'MEDIUM' };
+    const level = toSarifLevel(f.severity || rule.severity);
+
+    const result = {
+      ruleId: f.rule_id,
+      level,
+      message: {
+        text: f.evidence
+          ? `${f.rule_id}: ${f.evidence}`
+          : (rule.description || f.rule_id),
+      },
+    };
+
+    if (f.file) {
+      result.locations = [{
+        physicalLocation: {
+          artifactLocation: {
+            uri: f.file.replace(/\\/g, '/'),
+            uriBaseId: '%SRCROOT%',
+          },
+          ...(f.line ? { region: { startLine: Number(f.line) } } : {}),
+        },
+      }];
+    }
+
+    return result;
+  });
+
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'GoPlus AgentGuard',
+          version: '1.1',
+          informationUri: 'https://github.com/GoPlusSecurity/agentguard',
+          rules: driverRules,
+        },
+      },
+      invocations: [{
+        executionSuccessful: true,
+        commandLine: `agentguard scan ${input.target || ''}`,
+        startTimeUtc: input.scanned_at || new Date().toISOString(),
+      }],
+      artifacts: input.target ? [{
+        location: { uri: input.target, uriBaseId: '%SRCROOT%' },
+        description: { text: 'Scanned path' },
+      }] : [],
+      results,
+      properties: {
+        riskLevel: input.risk_level || 'UNKNOWN',
+        filesScanned: input.files_scanned || 0,
+        totalFindings: findings.length,
+      },
+    }],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const input = readInput();
+const sarif = buildSarif(input);
+process.stdout.write(JSON.stringify(sarif, null, 2) + '\n');

package/skills/agentguard/scripts/{trust-cli.ts → trust-cli.js}

@@ -4,11 +4,11 @@
  * 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>
+ *   node trust-cli.js lookup --id <id> --source <source> --version <version> --hash <hash>
+ *   node trust-cli.js 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.js revoke  [--source <source>] [--key <record_key>] --reason <reason>
+ *   node trust-cli.js list    [--trust-level <level>] [--status <status>] [--source-pattern <pattern>]
+ *   node trust-cli.js hash    --path <dir>
  */
 
 import { createAgentGuard, CAPABILITY_PRESETS, SkillScanner } from '@goplus/agentguard';
@@ -16,13 +16,13 @@ import { createAgentGuard, CAPABILITY_PRESETS, SkillScanner } from '@goplus/agen
 const args = process.argv.slice(2);
 const command = args[0];
 
-function getArg(name: string): string | undefined {
+function getArg(name) {
   const idx = args.indexOf(`--${name}`);
   if (idx === -1 || idx + 1 >= args.length) return undefined;
   return args[idx + 1];
 }
 
-function hasFlag(name: string): boolean {
+function hasFlag(name) {
   return args.includes(`--${name}`);
 }
 
@@ -50,18 +50,14 @@ async function main() {
         version_ref: getArg('version') || '',
         artifact_hash: getArg('hash') || '',
       };
-      const trustLevel = (getArg('trust-level') || 'restricted') as
-        | 'untrusted'
-        | 'restricted'
-        | 'trusted';
+      const trustLevel = getArg('trust-level') || 'restricted';
 
       let capabilities;
       const preset = getArg('preset');
       if (preset && preset in CAPABILITY_PRESETS) {
-        capabilities =
-          CAPABILITY_PRESETS[preset as keyof typeof CAPABILITY_PRESETS];
+        capabilities = CAPABILITY_PRESETS[preset];
       } else if (getArg('capabilities')) {
-        capabilities = JSON.parse(getArg('capabilities')!);
+        capabilities = JSON.parse(getArg('capabilities'));
       }
 
       const force = hasFlag('force');
@@ -94,7 +90,7 @@ async function main() {
     }
 
     case 'list': {
-      const filters: Record<string, string> = {};
+      const filters = {};
       const trustLevel = getArg('trust-level');
       const status = getArg('status');
       const sourcePattern = getArg('source-pattern');
@@ -121,7 +117,7 @@ async function main() {
 
     default:
       console.error(
-        'Usage: trust-cli.ts <lookup|attest|revoke|list|hash> [options]'
+        'Usage: trust-cli.js <lookup|attest|revoke|list|hash> [options]'
       );
       console.error('Run with --help for details.');
       process.exit(1);

package/skills/agentguard/suppress.example.yaml

@@ -0,0 +1,67 @@
+# .agentguard-suppress.yaml
+#
+# Place this file in the root of your project (or skill directory) to suppress
+# known false-positive findings from /agentguard scan.
+#
+# Rename this file to .agentguard-suppress.yaml to activate it.
+#
+# Fields per entry:
+#   rule     (required) — AgentGuard rule ID to suppress (e.g. PRIVATE_KEY_PATTERN)
+#   paths    (optional) — Glob patterns matched against the finding's file path.
+#                         If omitted, the rule is suppressed across all files.
+#   domains  (optional) — Substring/wildcard patterns matched against the finding's
+#                         evidence text. Useful for WEBHOOK_EXFIL to allowlist known hosts.
+#   reason   (required) — Human-readable explanation; appears in the suppression summary.
+#
+# Matching logic:
+#   - A finding is suppressed when its rule_id matches AND
+#     (paths match the file path  OR  domains match the evidence text).
+#   - If neither paths nor domains are specified, all findings for that rule are suppressed.
+#   - Glob path patterns: * matches within a directory, ** matches across directories.
+#   - Domain patterns: * is a wildcard prefix/suffix (e.g. *.internal.example.com).
+#
+# Suppressed findings are excluded from the report but counted in a summary line
+# at the bottom: "N finding(s) suppressed via .agentguard-suppress.yaml"
+#
+
+suppress:
+  # Example 1: Suppress hardcoded-key findings in test fixture directories.
+  # These are dummy keys used only in unit tests and are never deployed.
+  - rule: PRIVATE_KEY_PATTERN
+    paths:
+      - "tests/fixtures/**"
+      - "test/data/**"
+      - "**/__mocks__/**"
+    reason: "Test fixture dummy keys — not real credentials"
+
+  # Example 2: Suppress mnemonic findings in test directories.
+  - rule: MNEMONIC_PATTERN
+    paths:
+      - "tests/**"
+      - "test/**"
+      - "spec/**"
+    reason: "Test mnemonic phrases — BIP-39 test vectors, not production seeds"
+
+  # Example 3: Allowlist an internal monitoring webhook domain.
+  # The webhook posts to an internal Grafana Oncall instance, not an attacker server.
+  - rule: WEBHOOK_EXFIL
+    domains:
+      - "hooks.monitoring.internal"
+      - "*.ops.example.com"
+    reason: "Internal monitoring webhook — not an exfiltration endpoint"
+
+  # Example 4: Suppress shell execution findings in dev-only tooling scripts.
+  # These scripts are not bundled in the published package.
+  - rule: SHELL_EXEC
+    paths:
+      - "scripts/dev/**"
+      - "tools/**"
+    reason: "Development tooling scripts — excluded from published package"
+
+  # Example 5: Suppress environment variable access in a configuration module
+  # that is specifically designed to read and validate env vars.
+  - rule: READ_ENV_SECRETS
+    paths:
+      - "src/config.ts"
+      - "src/config/**"
+    reason: "Intentional env var access — this module owns config loading"