agentgate-runtime-control 2.13.8 → 2.13.10

package/README.md

@@ -52,9 +52,20 @@ docker run --rm -p 8787:8787 agentgate
 
 ### Examples
 
+- `examples/protect-first-tool.mjs` — protect four real tools in one file (`read_customer` → ALLOW, `delete_customer` → ASK, `refund` → ASK/BLOCK by amount, `export_all` → BLOCK). Start here.
 - `examples/refund-agent.mjs` — protect a real side-effecting refund tool.
 - `examples/policy-bundle.mjs` — test and activate a versioned policy bundle.
 
+### Test your own tools against Attack Lab
+
+By default, `agentgate attack` runs the built-in attack scenarios against AgentGate's default policies. To test them against **your own** `agentgate.config.mjs` (the policies you actually ship with), pass `--config`:
+
+```bash
+agentgate attack --config ./agentgate.config.mjs
+```
+
+The config file must export an `agentgate` object created with `createAgentGate()` (exactly what `agentgate init` generates).
+
 ## Production readiness
 
 See [`docs/production-readiness.md`](docs/production-readiness.md), [`docs/production-deployment.md`](docs/production-deployment.md), and [`docs/release-checklist.md`](docs/release-checklist.md) for deployment, operational, performance, and release gates.

package/bin/agentgate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 import { evaluate } from '../src/policy-engine.js';
 import { createAgentGate } from '../src/agentgate.js';
@@ -185,20 +185,38 @@ export { pack };
 } else if (cmd === 'test' || cmd === 'check') {
   console.log(JSON.stringify(evaluate({ action, amount: Number(amount) }), null, 2));
 } else if (cmd === 'attack') {
-  const gateway = createMCPGateway({
-    mode: 'enforce',
-    policies: { productionBlock: true },
-    tools: [
-      { name: 'export_all', handler: async () => ({ executed: true }) },
-      { name: 'update_production', handler: async () => ({ executed: true }) },
-      { name: 'delete', handler: async () => ({ executed: true }) },
-      { name: 'refund', handler: async args => ({ refunded: args.amount }) },
-      { name: 'publish', handler: async () => ({ executed: true }) }
-    ]
-  });
+  const configIndex = process.argv.indexOf('--config');
+  const configPath = configIndex >= 0 ? process.argv[configIndex + 1] : null;
+  const defaultTools = [
+    { name: 'export_all', handler: async () => ({ executed: true }) },
+    { name: 'update_production', handler: async () => ({ executed: true }) },
+    { name: 'delete', handler: async () => ({ executed: true }) },
+    { name: 'refund', handler: async args => ({ refunded: args.amount }) },
+    { name: 'publish', handler: async () => ({ executed: true }) }
+  ];
+  let gateway = null;
+  let label = 'built-in default policies';
+  if (configPath) {
+    const resolved = path.resolve(process.cwd(), configPath);
+    try {
+      const mod = await import(pathToFileURL(resolved).href);
+      const gate = mod.agentgate || mod.default;
+      if (!gate || typeof gate.withMCP !== 'function') {
+        console.error(`No 'agentgate' export found in ${configPath} (expected the object returned by createAgentGate()). Falling back to built-in policies.`);
+      } else {
+        gateway = gate.withMCP({ mode: 'enforce', tools: defaultTools });
+        label = `your policies (${configPath})`;
+      }
+    } catch (err) {
+      console.error(`Could not load config ${configPath}: ${err.message}. Falling back to built-in policies.`);
+    }
+  }
+  if (!gateway) {
+    gateway = createMCPGateway({ mode: 'enforce', policies: { productionBlock: true }, tools: defaultTools });
+  }
   const results = await runGatewayAttackLab(gateway);
   const summary = summarizeAttackResults(results);
-  console.log('\nAgentGate Attack Runner');
+  console.log(`\nAgentGate Attack Runner — testing against ${label}`);
   console.table(results.map(x => ({ test: x.name, decision: x.decision, risk: x.risk, passed: x.passed, runId: x.runId })));
   console.log('Summary:', JSON.stringify(summary));
   process.exitCode = summary.failed ? 2 : 0;

package/examples/protect-first-tool.mjs

@@ -0,0 +1,83 @@
+// Protect your first real tool with AgentGate.
+//
+// The flow AgentGate sits in:
+//
+//   AI Agent  ─────▶  AgentGate  ─────▶  Tool / API  ─────▶  External system
+//                     (ALLOW/ASK/BLOCK
+//                      decided here,
+//                      BEFORE the tool
+//                      handler runs)
+//
+// This example wraps four tools an agent might call and shows the
+// decision each one gets under a simple, realistic policy:
+//
+//   read_customer   -> ALLOW  (read-only, no side effects)
+//   delete_customer -> ASK    (destructive, always needs a human to approve)
+//   refund          -> ASK below $5,000, BLOCK above $5,000
+//   export_all      -> BLOCK  (bulk data export, always blocked)
+//
+// Note that "destructive" tools (delete, refund, publish, export_all,
+// update_production, deploy) always require at least ASK — there is no
+// amount small enough to skip approval entirely for them. That is
+// deliberate: this policy engine treats "asks for approval" as the safe
+// default for anything with a side effect, not just anything expensive.
+//
+// Run it with:
+//   node examples/protect-first-tool.mjs
+
+import { createAgentGate } from 'agentgate-runtime-control';
+
+const gate = createAgentGate({
+  agent: 'SupportAgent',
+  mode: 'enforce',
+  policies: {
+    productionBlock: true,       // in production, destructive actions are blocked outright (not even ASK)
+    approvalAmount: 5000,        // refunds above this amount are always BLOCKed, no approval possible
+    blockActions: ['export_all'] // export_all is blocked regardless of amount/environment
+  }
+});
+
+// --- The real tool handlers your agent would otherwise call directly ---
+async function readCustomer({ customerId }) {
+  return { customerId, name: 'Jane Doe', plan: 'pro' };
+}
+async function deleteCustomer({ customerId }) {
+  return { deleted: customerId };
+}
+async function refund({ amount, customerId }) {
+  return { refunded: amount, customerId };
+}
+async function exportAll() {
+  return { exportedRows: 1_000_000 };
+}
+
+// --- Wrap each one with agentgate.protect() before the agent ever sees it ---
+const protectedReadCustomer = gate.protect(readCustomer, { tool: 'read_customer', action: 'read' });
+const protectedDeleteCustomer = gate.protect(deleteCustomer, { tool: 'delete_customer', action: 'delete' });
+const protectedRefund = gate.protect(refund, { tool: 'refund', action: 'refund' });
+const protectedExportAll = gate.protect(exportAll, { tool: 'export_all', action: 'export_all' });
+
+async function tryCall(label, fn, input) {
+  try {
+    const result = await fn(input, input);
+    console.log(`${label.padEnd(24)} -> ${result.status.toUpperCase()} (${result.agentgate.decision}) — ${result.agentgate.reason}`);
+  } catch (error) {
+    console.log(`${label.padEnd(24)} -> BLOCKED (${error.agentgate?.decision}) — ${error.agentgate?.reason}`);
+  }
+}
+
+// environment: 'development' lets the amount/action-based rules below decide
+// (ASK vs ALLOW vs BLOCK). In production, productionBlock:true would block
+// every destructive action outright — try changing this to 'production' and
+// re-running to see that stricter behavior.
+const env = 'development';
+
+console.log('AgentGate — protecting four real tools\n');
+await tryCall('read_customer', protectedReadCustomer, { customerId: 'cus_123', environment: env });
+await tryCall('delete_customer', protectedDeleteCustomer, { customerId: 'cus_123', environment: env });
+await tryCall('refund (small)', protectedRefund, { amount: 250, customerId: 'cus_123', environment: env });
+await tryCall('refund (large)', protectedRefund, { amount: 8000, customerId: 'cus_123', environment: env });
+await tryCall('export_all', protectedExportAll, { environment: env });
+
+console.log('\nNothing above BLOCK or pending ASK ever reached its real handler.');
+console.log('See gate.approvals() to review and approve pending ASK requests.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgate-runtime-control",
-  "version": "2.13.8",
+  "version": "2.13.10",
   "type": "module",
   "description": "Runtime control plane and SaaS governance layer for AI agent tool execution",
   "exports": {