Merge pull request #268 from caido-community/ae-plugin-api

Scanner API

Author: Sytten

.github/workflows/release.yml

@@ -7,12 +7,14 @@ env:
   NODE_VERSION: 20
   PNPM_VERSION: 9
 
+permissions:
+  id-token: write
+  contents: write
+
 jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
 
     steps:
       - name: Verify main branch
@@ -29,6 +31,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ env.NODE_VERSION }}
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
@@ -57,6 +60,13 @@ jobs:
           VERSION=$(unzip -p plugin_package.zip manifest.json | jq -r .version)
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
 
+      - name: Publish package
+        working-directory: packages/shared
+        run: |
+          pnpm run build
+          npm pkg set "version=${{ steps.meta.outputs.version }}"
+          npm publish --access public --provenance
+
       - name: Create release
         uses: caido/action-release@v1
         with:

AGENTS.md

@@ -20,12 +20,20 @@ pnpm vitest run --coverage packages/backend/src/checks/<check-name>/index.spec.t
 
 This is a **Caido vulnerability scanner plugin** organized as a pnpm monorepo with four packages:
 
-- **`packages/engine`** — Core scanning engine. Defines the check execution model (step-based), types (`CheckDefinition`, `Finding`, `Severity`), and test utilities (`runCheck`, `createMockRequest`, `createMockResponse`). Imported as `"engine"` by other packages.
-- **`packages/backend`** — Backend plugin. Contains 40+ vulnerability checks in `src/checks/`, plus services, stores, and storage layers. Registers API endpoints and hooks into Caido SDK events (intercepted responses for passive scanning, `sdk.requests.send()` for active scanning).
-- **`packages/frontend`** — Vue 3 + Pinia + PrimeVue + TailwindCSS frontend. Registers a sidebar page at `/scanner` and a keyboard shortcut (Ctrl+Shift+S) for active scanning.
-- **`packages/shared`** — Shared TypeScript types between frontend and backend.
+- **`packages/shared`** — Published as `@caido-community/scanner` on NPM. Type-only contract: `API`, `Events`, `Spec`, plus all public types (`Session`, `UserConfig`, `Finding`, `Severity`, `ScanConfig`, `CheckMetadata`, ...). Self-contained, zero workspace deps. Built with `tsdown` via the `prepare` script. Backend, frontend, and external CI/CD clients all consume `Spec`.
+- **`packages/engine`** — Core scanning engine. Defines the check execution model (step-based), runtime helpers (`defineCheck`, `defineCheckV2`, `runCheck`, `createRegistry`, `createScheduler`, `keyStrategy`, `createMockRequest`, `createMockResponse`). Imports its public types from `shared` and re-exports them for backwards compatibility with existing checks.
+- **`packages/backend`** — Backend plugin. Contains 40+ vulnerability checks in `src/checks/`. RPC handlers live in `src/api/{checks,config,queue,scanner}.ts` and delegate to services in `src/services/`. The SDK is set once via `setSDK(sdk)` in `src/sdk.ts`; services pull it via `requireSDK()`. Hooks into Caido SDK events (intercepted responses for passive scanning, `sdk.requests.send()` for active scanning).
+- **`packages/frontend`** — Vue 3 + Pinia + PrimeVue + TailwindCSS frontend. Depends on `shared` only — never on `backend` or `engine`. Registers a sidebar page at `/scanner` and a keyboard shortcut (Ctrl+Shift+S) for active scanning.
 
-Plugin configuration lives in `caido.config.ts`. The plugin is built using `@caido-community/dev`.
+The frontend↔backend contract is `Spec = DefinePluginPackageSpec<{ manifestId: "scanner"; api: API; events: Events }>` from `packages/shared/src/index.ts`. Backend uses `SDK<Spec>`, frontend uses `Caido<Spec>`. Plugin configuration lives in `caido.config.ts`. The plugin is built using `@caido-community/dev`.
+
+### Adding an API endpoint
+
+1. Add the method signature to `packages/shared/src/api.ts` (no `SDK` first param — args only).
+2. Implement the service in `packages/backend/src/services/<domain>.ts`. Call `requireSDK()` if you need the SDK; never accept it as a parameter.
+3. Add the wrapper in `packages/backend/src/api/<domain>.ts` (`(_sdk: SDK, ...args) => service(...args)`) and re-export from `src/api/index.ts`.
+4. Register it in `packages/backend/src/index.ts` via `sdk.api.register("methodName", api.apiMethodName)`.
+5. Add a unit test in `packages/backend/src/api/<domain>.test.ts` that mocks the relevant store and asserts the result.
 
 ## Check Architecture
 

caido.config.ts

@@ -12,7 +12,7 @@ export default defineConfig({
   id,
   name: "Scanner",
   description: "Passive and active vulnerability scanner",
-  version: "1.0.7",
+  version: "1.0.8",
   author: {
     name: "Caido Labs Inc.",
     email: "dev@caido.io",

knip.ts

@@ -4,18 +4,24 @@ const config: RawConfigurationOrFn = {
   workspaces: {
     ".": {
       entry: ["caido.config.ts"],
-      ignoreDependencies: ["@caido/sdk-backend", "@vitest/coverage-v8", "rollup-plugin-dts"],
+      ignoreDependencies: ["@vitest/coverage-v8", "rollup-plugin-dts"],
     },
     "packages/backend": {
       project: ["src/**/*.ts"],
-      ignoreDependencies: ["caido", "@lezer/common", "@lezer/generator"],
+      ignoreDependencies: [
+        "caido",
+        "shared",
+        "@lezer/common",
+        "@lezer/generator",
+      ],
       ignore: [
         "src/parsers/**/__generated__*",
         "src/checks/sql-injection/mysql-time-based/**",
       ],
     },
     "packages/frontend": {
       project: ["src/**/*.{ts,tsx,vue}"],
+      ignoreDependencies: ["shared"],
       ignore: [
         "src/views/Queue.vue",
         "src/components/queue/**",
@@ -27,7 +33,7 @@ const config: RawConfigurationOrFn = {
     },
     "packages/engine": {
       project: ["src/**/*.ts"],
-      ignoreDependencies: ["caido"],
+      ignoreDependencies: ["caido", "shared"],
       ignore: ["src/__tests__/**"],
     },
     "packages/trace-viewer": {

package.json

@@ -8,6 +8,7 @@
   "scripts": {
     "typecheck": "pnpm -r typecheck",
     "build": "caido-dev build",
+    "build:shared": "pnpm --filter @caido-community/scanner run build",
     "watch": "caido-dev watch",
     "lint": "eslint --fix packages/*/src",
     "knip": "knip",
@@ -19,7 +20,7 @@
   "devDependencies": {
     "@caido-community/dev": "0.1.6",
     "@caido/eslint-config": "0.8.0",
-    "@caido/sdk-backend": "0.55.3",
+    "@caido/sdk-backend": "0.56.0",
     "@caido/tailwindcss": "0.0.1",
     "@types/node": "25.2.1",
     "@vitejs/plugin-vue": "6.0.1",
@@ -34,5 +35,10 @@
     "typescript": "5.8.3",
     "vite": "6.3.5",
     "vitest": "3.2.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "@caido/sdk-shared": "0.2.2"
+    }
   }
 }

packages/backend/package.json

@@ -9,8 +9,7 @@
     "generate:parsers": "bash scripts/generate-parsers.sh"
   },
   "devDependencies": {
-    "@caido/sdk-backend": "0.55.3",
-    "shared": "workspace:*",
+    "@caido/sdk-backend": "0.56.0",
     "vitest": "3.2.3"
   },
   "dependencies": {
@@ -19,6 +18,7 @@
     "@lezer/lr": "1.4.8",
     "engine": "workspace:*",
     "mutative": "1.3.0",
+    "shared": "workspace:@caido-community/scanner@*",
     "zod": "4.3.6"
   }
 }

packages/backend/src/__tests__/mockSdk.ts

@@ -0,0 +1,44 @@
+import { vi } from "vitest";
+
+export const createMockSDK = () => ({
+  console: {
+    log: vi.fn(),
+    error: vi.fn(),
+  },
+  meta: {
+    path: vi.fn().mockReturnValue("/tmp/scanner-test"),
+    id: vi.fn().mockReturnValue("scanner"),
+    db: vi.fn(),
+    assetsPath: vi.fn(),
+    version: vi.fn().mockReturnValue("0.0.0"),
+    updateAvailable: vi.fn(),
+  },
+  api: {
+    send: vi.fn(),
+    register: vi.fn(),
+  },
+  env: {
+    getVar: vi.fn(),
+    getVars: vi.fn().mockReturnValue([]),
+    setVar: vi.fn().mockResolvedValue(undefined),
+  },
+  events: {
+    onInterceptRequest: vi.fn(),
+    onInterceptResponse: vi.fn(),
+    onProjectChange: vi.fn(),
+    onUpstream: vi.fn(),
+  },
+  findings: { create: vi.fn() },
+  requests: {
+    send: vi.fn(),
+    get: vi.fn(),
+    inScope: vi.fn(),
+  },
+  replay: {},
+  projects: { getCurrent: vi.fn() },
+  scope: {},
+  runtime: {},
+  graphql: {},
+  hostedFile: {},
+  net: {},
+});

packages/backend/src/api/checks.test.ts

@@ -0,0 +1,37 @@
+import type { CheckMetadata } from "shared";
+import { describe, expect, it, vi } from "vitest";
+
+import { createMockSDK } from "../__tests__/mockSdk";
+import { ChecksStore } from "../stores/checks";
+
+import { apiGetChecks } from "./checks";
+
+describe("apiGetChecks", () => {
+  it("returns metadata from the store", () => {
+    const metadata: CheckMetadata = {
+      id: "demo",
+      name: "Demo",
+      description: "",
+      tags: [],
+      type: "active",
+      aggressivity: { minRequests: 1, maxRequests: 1 },
+      severities: ["info"],
+    };
+    vi.spyOn(ChecksStore, "get").mockReturnValue({
+      select: () => [metadata],
+    } as unknown as ChecksStore);
+
+    const result = apiGetChecks(createMockSDK() as never);
+
+    expect(result).toEqual({ kind: "Ok", value: [metadata] });
+  });
+
+  it("returns Error on invalid options", () => {
+    const result = apiGetChecks(
+      createMockSDK() as never,
+      { include: "not-an-array" } as never,
+    );
+
+    expect(result.kind).toBe("Error");
+  });
+});

packages/backend/src/api/checks.ts

@@ -0,0 +1,9 @@
+import type { SDK } from "caido:plugin";
+import type { CheckMetadata, GetChecksOptions, Result } from "shared";
+
+import { getChecks } from "../services/checks";
+
+export const apiGetChecks = (
+  _sdk: SDK,
+  options?: GetChecksOptions,
+): Result<CheckMetadata[]> => getChecks(options);

packages/backend/src/api/config.test.ts

@@ -0,0 +1,54 @@
+import type { UserConfig } from "shared";
+import { describe, expect, it, vi } from "vitest";
+
+import { createMockSDK } from "../__tests__/mockSdk";
+import { ConfigStore } from "../stores/config";
+
+import { apiGetUserConfig, apiUpdateUserConfig } from "./config";
+
+vi.mock("caido:utils", () => ({
+  RequestSpec: class {},
+}));
+
+const baseConfig: UserConfig = {
+  passive: {
+    enabled: false,
+    aggressivity: "medium",
+    scopeIDs: [],
+    concurrentTargets: 1,
+    concurrentRequests: 1,
+    overrides: [],
+    severities: ["info"],
+  },
+  active: { overrides: [] },
+  presets: [],
+};
+
+describe("apiGetUserConfig", () => {
+  it("returns the current user config", () => {
+    vi.spyOn(ConfigStore, "get").mockReturnValue({
+      getUserConfig: () => baseConfig,
+    } as unknown as ConfigStore);
+
+    const result = apiGetUserConfig(createMockSDK() as never);
+
+    expect(result).toEqual({ kind: "Ok", value: baseConfig });
+  });
+});
+
+describe("apiUpdateUserConfig", () => {
+  it("forwards the patch to the store", () => {
+    const updateUserConfig = vi.fn();
+    vi.spyOn(ConfigStore, "get").mockReturnValue({
+      updateUserConfig,
+    } as unknown as ConfigStore);
+
+    const patch: Partial<UserConfig> = {
+      defaultPresetName: "Light",
+    };
+    const result = apiUpdateUserConfig(createMockSDK() as never, patch);
+
+    expect(result).toEqual({ kind: "Ok", value: undefined });
+    expect(updateUserConfig).toHaveBeenCalledWith(patch);
+  });
+});