Security Hardening + AI Pentest Framework

.agents/pentest/README.md

@@ -0,0 +1,82 @@
+# AI Pentest Framework
+
+This directory contains the infrastructure for AI agents to actively pentest the Queue application.
+
+## Structure
+
+```
+pentest/
+├── harness/          # Execution harness for running attacks
+│   ├── README.md     # This file
+│   ├── index.ts      # Main pentest runner
+│   ├── convex-agent.ts   # Convex API client for agents
+│   └── attack-suite.ts   # Attack templates
+├── inventory/        # Auto-generated API surface inventory
+│   └── CONVEX_INVENTORY.md
+└── templates/        # Attack templates per vulnerability class
+    ├── idor.md
+    ├── rate-limit.md
+    ├── auth-bypass.md
+    ├── data-exposure.md
+    ├── payment-attacks.md
+    └── injection.md
+```
+
+## Quick Start for AI Agents
+
+### 1. Connect to Convex
+
+```typescript
+import { createConvexAgent } from "./harness/convex-agent";
+
+const convex = createConvexAgent({
+  deploymentUrl: process.env.CONVEX_DEPLOYMENT_URL!,
+  adminKey: process.env.CONVEX_ADMIN_KEY!,  // Only for pentest env
+});
+
+// List all attack surfaces
+await convex.listFunctions();
+```
+
+### 2. Run Attack Suite
+
+```typescript
+import { runAttackSuite } from "./harness/attack-suite";
+
+const results = await runAttackSuite(convex, {
+  targets: ["idor", "rate-limit", "auth-bypass", "data-exposure"],
+  testUserA: { email: "attacker@test.com", role: "instructor" },
+  testUserB: { email: "victim@test.com", role: "instructor" },
+});
+```
+
+### 3. Run Individual Attack
+
+```typescript
+import { IDORAttacker } from "./templates/idorttack";
+
+const attacker = new IDORAttacker(convex);
+const results = await attacker.attack({
+  functionName: "getGoogleIntegrationForUser",
+  vulnerableArg: "userId",
+  victimId: await convex.query("users", { email: "victim@test.com" }),
+});
+```
+
+## Environment Variables Required
+
+```env
+CONVEX_DEPLOYMENT_URL=https://your-project.convex.cloud
+CONVEX_ADMIN_KEY=...          # Pentest environment only
+TEST_ATTACKER_EMAIL=attacker@test.com
+TEST_ATTACKER_PASSWORD=...
+TEST_VICTIM_EMAIL=victim@test.com
+TEST_VICTIM_PASSWORD=...
+```
+
+## Security Notes
+
+- **ONLY run against a dedicated pentest/staging environment**
+- Admin key gives full access — never use production credentials
+- Some attacks (rate limiting, DoS) may degrade service for other testers
+- Clean up test data after each run