Merge pull request #5 from caido-community/dev

V1.0.2

Author: Corb3nik

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  check:
+    name: Verification
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Tools (mise)
+        uses: jdx/mise-action@v2
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Knip (Dead Code)
+        run: pnpm knip

.mise/config.toml

@@ -0,0 +1,3 @@
+[tools]
+node = "22"
+pnpm = "9"

caido.config.ts

@@ -12,7 +12,7 @@ export default defineConfig({
   id,
   name: "GraphQL Analyzer",
   description: "Plugin for GraphQL schema discovery, visualization, and advanced security",
-  version: "1.0.1",
+  version: "1.0.2",
   author: {
     name: "Amr Elsagaei",
     email: "info@amrelsagaei.com",

eslint.config.mjs

@@ -1,6 +1,16 @@
 import { defaultConfig } from "@caido/eslint-config";
+import globals from "globals";
 
-/** @type {import('eslint').Linter.Config } */
 export default [
-  ...defaultConfig(),
-]
+  ...defaultConfig({
+    compat: false,
+  }),
+  {
+    files: ["packages/frontend/**/*.{ts,vue}"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+  },
+];

knip.ts

@@ -0,0 +1,20 @@
+import type { RawConfigurationOrFn } from "knip/dist/types/config.js";
+
+const config: RawConfigurationOrFn = {
+  workspaces: {
+    ".": {
+      entry: ["caido.config.ts"],
+    },
+    "packages/backend": {
+      project: ["src/**/*.ts"],
+      ignoreDependencies: ["caido"],
+    },
+    "packages/frontend": {
+      entry: ["src/index.ts"],
+      project: ["src/**/*.{ts,tsx,vue}"],
+    },
+  },
+};
+
+export default config;
+

package.json

@@ -4,7 +4,8 @@
   "private": true,
   "scripts": {
     "typecheck": "pnpm -r typecheck",
-    "lint": "eslint ./packages/**/src --fix",
+    "lint": "eslint --fix packages/*/src",
+    "knip": "knip",
     "build": "caido-dev build",
     "watch": "caido-dev watch"
   },
@@ -13,6 +14,9 @@
     "@caido/eslint-config": "^0.5.0",
     "@caido/tailwindcss": "0.0.1",
     "@vitejs/plugin-vue": "5.2.1",
+    "eslint": "^9.36.0",
+    "globals": "^16.5.0",
+    "knip": "^5.73.4",
     "postcss-prefixwrap": "1.51.0",
     "tailwindcss": "3.4.13",
     "tailwindcss-primeui": "0.3.4",

packages/backend/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# Backend Architecture
+
+## Overview
+
+The GraphQL Analyzer backend follows a layered architecture with clear separation of concerns:
+
+```
+┌──────────────────────────────────────┐
+│             API Layer                │  ← External interface
+├──────────────────────────────────────┤
+│          Services Layer              │  ← Business logic
+├──────────────────────────────────────┤
+│     Models   │    Validation         │  ← Domain objects & schemas
+└──────────────────────────────────────┘
+```
+
+## Directory Structure
+
+```
+packages/backend/src/
+├── api/              # API handlers (thin layer)
+│   ├── attacks.ts    # Attack execution APIs
+│   └── graphql.ts    # GraphQL endpoint APIs
+├── models/           # Domain models
+│   └── AttackSession.ts  # Discriminated union state types
+├── services/         # Business logic
+│   ├── attacks/      # Attack modules
+│   │   ├── AttackService.ts        # Main orchestrator
+│   │   ├── IntrospectionAttack.ts  # Schema introspection
+│   │   ├── DepthAttack.ts          # Query depth limits
+│   │   ├── ComplexityAttack.ts     # Query complexity
+│   │   ├── BatchAttack.ts          # Batch queries
+│   │   ├── FieldSuggestionAttack.ts # Field suggestion disclosure
+│   │   ├── headerUtils.ts          # Header utilities (SDK getHeaders)
+│   │   ├── sessionManager.ts       # Attack session state
+│   │   └── types.ts                # Shared attack types
+│   └── graphql/
+│       └── GraphQLService.ts       # GraphQL introspection service
+├── validation/       # Zod schemas
+│   └── schemas.ts    # JSON response validation
+├── index.ts          # Main entry point
+├── sdk.ts            # SDK singleton
+└── types.ts          # Backend event types
+```
+
+## Key Design Patterns
+
+### Discriminated Unions
+
+Attack session states use discriminated unions for type safety:
+
+```typescript
+type AttackSessionState =
+  | AttackSessionRunning // status: "running"
+  | AttackSessionCompleted // status: "completed"
+  | AttackSessionFailed // status: "failed"
+  | AttackSessionCancelled; // status: "cancelled"
+```
+
+Benefits:
+
+- No optional fields
+- Type narrowing on status
+- Cleaner state transitions
+
+### Zod Validation
+
+JSON responses are validated using Zod schemas instead of type casting:
+
+```typescript
+const parsed = parseGraphQLResponse(responseBody);
+if (parsed.kind === "Ok" && parsed.value.data) {
+  // Type-safe access to validated data
+}
+```
+
+### SDK Headers API
+
+Uses the SDK's `getHeaders()` method instead of manually parsing raw requests:
+
+```typescript
+const rawHeaders = result.request.getHeaders();
+for (const [name, values] of Object.entries(rawHeaders)) {
+  headers[name] = values[0] ?? "";
+}
+```
+
+## Data Flow
+
+```
+1. API Request (index.ts)
+   ↓
+2. API Handler (api/attacks.ts)
+   ↓
+3. Attack Service (services/attacks/AttackService.ts)
+   ↓
+4. Individual Attack Module (e.g., IntrospectionAttack.ts)
+   ↓
+5. Response Validation (validation/schemas.ts)
+   ↓
+6. Result returned
+```

packages/backend/package.json

@@ -6,6 +6,10 @@
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
+  "dependencies": {
+    "shared": "workspace:*",
+    "zod": "4.3.6"
+  },
   "devDependencies": {
     "@caido/sdk-backend": "^0.51.0"
   }

packages/backend/src/api/attacks.ts

@@ -0,0 +1,92 @@
+import type { SDK } from "caido:plugin";
+import type { AttackConfig, AttackResult, AttackType, Result } from "shared";
+
+import {
+  cancelAttackSession as cancelSession,
+  executeAttacks as executeAttacksService,
+  getAttackStatus as getStatus,
+  generateAttackTemplates as getTemplates,
+  startAttacksAsync as startAsync,
+} from "../services/attacks";
+
+export async function executeGraphQLAttacks(
+  sdk: SDK,
+  config: AttackConfig,
+): Promise<Result<AttackResult[]>> {
+  return executeAttacksService(sdk, config);
+}
+
+export function startGraphQLAttacks(
+  sdk: SDK,
+  config: AttackConfig,
+): Promise<Result<string>> {
+  return Promise.resolve(startAsync(sdk, config));
+}
+
+export function getAttackStatus(
+  _sdk: SDK,
+  sessionId: string,
+): Promise<
+  Result<{
+    status: string;
+    progress: number;
+    results: AttackResult[];
+    totalAttacks: number;
+    completedAttacks: number;
+    isComplete: boolean;
+  }>
+> {
+  return Promise.resolve(getStatus(sessionId));
+}
+
+export function cancelAttackSession(
+  _sdk: SDK,
+  sessionId: string,
+): Promise<Result<void>> {
+  return Promise.resolve(cancelSession(sessionId));
+}
+
+export function getAttackTemplates(
+  _sdk: SDK,
+): Record<AttackType, { name: string; description: string; query: string }> {
+  return getTemplates();
+}
+
+export async function createCaidoFinding(
+  sdk: SDK,
+  findingData: { title: string; description: string },
+  requestId: string,
+): Promise<Result<void>> {
+  try {
+    if (!requestId) {
+      return { kind: "Error", error: "No request ID provided" };
+    }
+
+    const result = await sdk.requests.get(requestId);
+    if (!result) {
+      return { kind: "Error", error: "Request not found in Caido storage" };
+    }
+
+    let dedupeKey = `graphql-${findingData.title}`;
+    try {
+      dedupeKey += `-${result.request.getUrl()}`;
+    } catch {
+      dedupeKey += `-${Date.now()}`;
+    }
+
+    await sdk.findings.create({
+      title: findingData.title,
+      description: findingData.description,
+      reporter: "GraphQL Analyzer",
+      request: result.request,
+      dedupeKey: dedupeKey,
+    });
+
+    return { kind: "Ok", value: undefined };
+  } catch (error) {
+    return {
+      kind: "Error",
+      error: `Failed to create Caido finding: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}