Skip to content

Commit 6d3b93a

Browse files
oksuzkayraoksuzkayra
committed
init
0 parents  commit 6d3b93a

31 files changed

+6041
-0
lines changed

‎.cursor/rules/caido-backend.mdc‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
globs:
3+
- "**/packages/backend/**"
4+
alwaysApply: true
5+
description: Caido Backend SDK Rules and Patterns
6+
---
7+
8+
## Caido Backend SDK
9+
10+
### Overview
11+
12+
The Caido Backend SDK is used for server-side logic, data processing, and creating API endpoints that can be called from frontend plugins.
13+
14+
### Entry Point
15+
16+
Backend plugins are initialized via `packages/backend/src/index.ts`:
17+
18+
```typescript
19+
import { SDK, DefineAPI } from "caido:plugin";
20+
21+
// Define your API functions
22+
function myCustomFunction(sdk: SDK, param: string) {
23+
sdk.console.log(`Called with: ${param}`);
24+
return `Processed: ${param}`;
25+
}
26+
27+
// Export the API type definition
28+
export type API = DefineAPI<{
29+
myCustomFunction: typeof myCustomFunction;
30+
}>;
31+
32+
// Plugin initialization
33+
export function init(sdk: SDK<API>) {
34+
// Register API endpoints
35+
sdk.api.register("myCustomFunction", myCustomFunction);
36+
}
37+
```
38+
39+
### SDK Type Definitions
40+
41+
#### Backend SDK with events:
42+
```typescript
43+
import { DefineEvents, SDK } from "caido:plugin";
44+
45+
export type BackendEvents = DefineEvents<{
46+
"data-updated": { message: string };
47+
"status-changed": { status: "active" | "inactive" };
48+
}>;
49+
50+
export type CaidoBackendSDK = SDK<never, BackendEvents>;
51+
```
52+
53+
### Best Practices
54+
55+
When building API endpoints in the backend and calling them from the frontend, use Result types to handle errors gracefully without throwing exceptions:
56+
57+
```typescript
58+
// Define the Result type
59+
export type Result<T> =
60+
| { kind: "Error"; error: string }
61+
| { kind: "Ok"; value: T };
62+
63+
// Backend API function returning Result
64+
function processData(sdk: SDK, input: string): Result<ProcessedData> {
65+
try {
66+
// Your processing logic here
67+
const processed = doSomeProcessing(input);
68+
return { kind: "Ok", value: processed };
69+
} catch (error) {
70+
return { kind: "Error", error: error.message };
71+
}
72+
}
73+
74+
// Frontend usage - no try/catch needed
75+
const handleProcess = async () => {
76+
const result = await sdk.backend.processData(inputValue);
77+
78+
if (result.kind === "Error") {
79+
sdk.window.showToast(result.error, { variant: "error" });
80+
return;
81+
}
82+
83+
// Handle successful result
84+
const data = result.value;
85+
sdk.window.showToast("Processing completed!", { variant: "success" });
86+
};
87+
```
88+
89+
90+
#### Registering Multiple API Endpoints
91+
92+
```typescript
93+
// Define multiple API functions
94+
function getData(sdk: SDK, id: string): Result<Data> {
95+
// Implementation
96+
}
97+
98+
function saveData(sdk: SDK, data: Data): Result<void> {
99+
// Implementation
100+
}
101+
102+
function deleteData(sdk: SDK, id: string): Result<boolean> {
103+
// Implementation
104+
}
105+
106+
// Export Caido Backend API
107+
export type API = DefineAPI<{
108+
getData: typeof getData;
109+
saveData: typeof saveData;
110+
deleteData: typeof deleteData;
111+
}>;
112+
113+
// Register all endpoints
114+
export function init(sdk: SDK<API>) {
115+
sdk.api.register("getData", getData);
116+
sdk.api.register("saveData", saveData);
117+
sdk.api.register("deleteData", deleteData);
118+
}
119+
```

‎.cursor/rules/caido-frontend.mdc‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
globs:
3+
- "**/packages/frontend/**"
4+
alwaysApply: true
5+
description: Caido Frontend SDK Rules and Patterns
6+
---
7+
8+
## Caido Frontend SDK
9+
10+
### Overview
11+
12+
The Caido Frontend SDK is used for creating UI components, pages, and handling user interactions in Caido plugins.
13+
14+
### Entry Point
15+
16+
Frontend plugins are initialized via `packages/frontend/src/index.ts`:
17+
18+
```typescript
19+
import { Caido } from "@caido/sdk-frontend";
20+
import { API, BackendEvents } from "backend";
21+
22+
// Define SDK type with backend API
23+
export type FrontendSDK = Caido<API, BackendEvents>;
24+
25+
// Plugin initialization
26+
export const init = (sdk: FrontendSDK) => {
27+
// Create pages and UI
28+
createPage(sdk);
29+
30+
// Register sidebar items
31+
sdk.sidebar.registerItem("My Plugin", "/my-plugin-page", {
32+
icon: "fas fa-rocket"
33+
});
34+
35+
// Register commands
36+
sdk.commands.register("my-command", {
37+
name: "My Custom Command",
38+
run: () => sdk.backend.myCustomFunction("Hello"),
39+
});
40+
};
41+
```
42+
43+
### SDK Type Definitions
44+
45+
#### For plugins WITHOUT backend, this is fine:
46+
```typescript
47+
export type FrontendSDK = Caido<Record<string, never>, Record<string, never>>;
48+
```
49+
50+
#### For plugins WITH backend:
51+
```typescript
52+
import { Caido } from "@caido/sdk-frontend";
53+
import { API, BackendEvents } from "backend";
54+
55+
export type FrontendSDK = Caido<API, BackendEvents>;
56+
```
57+
58+
### Command Pattern
59+
60+
Commands provide a unified way to register actions that can be triggered from:
61+
- Command palette (Ctrl/Cmd+Shift+P)
62+
- Context menus (right-click)
63+
- UI buttons
64+
- Keyboard shortcuts
65+
66+
Commands is a frontend-only concept.
67+
68+
```typescript
69+
// Define command IDs as constants
70+
const Commands = {
71+
processData: "my-plugin.process-data",
72+
exportResults: "my-plugin.export-results",
73+
} as const;
74+
75+
// Register commands
76+
sdk.commands.register(Commands.processData, {
77+
name: "Process Data",
78+
run: async () => {
79+
const result = await sdk.backend.processData();
80+
sdk.window.showToast(`Processed ${result.count} items`, {
81+
variant: "success"
82+
});
83+
},
84+
group: "My Plugin",
85+
});
86+
87+
// Add to command palette
88+
sdk.commandPalette.register(Commands.processData);
89+
90+
// Add to context menus
91+
sdk.menu.registerItem({
92+
type: "Request",
93+
commandId: Commands.processData,
94+
leadingIcon: "fas fa-cog",
95+
});
96+
```
97+
98+
### Working with Requests and Responses
99+
100+
#### Creating and Sending Requests
101+
102+
```typescript
103+
import { RequestSpec } from "caido:utils";
104+
import { type Request, type Response } from "caido:utils";
105+
106+
// Create a new request
107+
const spec = new RequestSpec("https://api.example.com/data");
108+
spec.setMethod("POST");
109+
spec.setHeader("Content-Type", "application/json");
110+
spec.setBody(JSON.stringify({ key: "value" }));
111+
112+
// Send the request
113+
const result = await sdk.requests.send(spec);
114+
if (result.response) {
115+
const statusCode = result.response.getCode();
116+
const responseBody = result.response.getBody()?.toText();
117+
}
118+
```
119+
120+
#### Working with Request/Response Editors
121+
122+
```typescript
123+
// Create editors for viewing/editing HTTP data
124+
const reqEditor = sdk.ui.httpRequestEditor();
125+
const respEditor = sdk.ui.httpResponseEditor();
126+
127+
// Get DOM elements
128+
const reqElement = reqEditor.getElement();
129+
const respElement = respEditor.getElement();
130+
131+
// Style and layout
132+
reqElement.style.width = "50%";
133+
respElement.style.width = "50%";
134+
135+
const editorsContainer = document.createElement("div");
136+
editorsContainer.style.display = "flex";
137+
editorsContainer.appendChild(reqElement);
138+
editorsContainer.appendChild(respElement);
139+
```
140+
141+
### Frontend Error Handling
142+
143+
When calling backend APIs from the frontend, handle Result types gracefully:
144+
145+
```typescript
146+
// Frontend usage - no try/catch needed
147+
const handleProcess = async () => {
148+
const result = await sdk.backend.processData(inputValue);
149+
150+
if (result.kind === "Error") {
151+
sdk.window.showToast(result.error, { variant: "error" });
152+
return;
153+
}
154+
155+
// Handle successful result
156+
const data = result.value;
157+
sdk.window.showToast("Processing completed!", { variant: "success" });
158+
};
159+
```

‎.cursor/rules/caido.mdc‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
globs:
3+
alwaysApply: true
4+
description: Caido HTTP Proxy Overview
5+
---
6+
7+
## What is Caido
8+
9+
Caido is a lightweight web application security auditing toolkit designed to help security professionals audit web applications with efficiency and ease
10+
11+
Key features include:
12+
- HTTP proxy for intercepting and viewing requests in real-time
13+
- Replay functionality for resending and modifying requests to test endpoints
14+
- Automate feature for testing requests against wordlists
15+
- Match & Replace for automatically modifying requests with regex rules
16+
- HTTPQL query language for filtering through HTTP traffic
17+
- Workflow system for creating custom encoders/decoders and plugins
18+
- Project management for organizing different security assessments
19+
20+
## Environment
21+
22+
We are running in a plugin environment where we can interact with Caido through the Caido Backend or Frontend SDK.
23+
24+
### Plugin Structure
25+
26+
- `packages/backend` → Backend plugin code - handles server-side logic, data processing, and API endpoints
27+
- `packages/frontend` → Frontend plugin code - handles UI components, user interactions, and calls to backend
28+
29+
### Plugin Development
30+
31+
Plugins consist of:
32+
- A `caido.config.ts` configuration file
33+
- Frontend plugin (optional) - provides UI using Caido Frontend SDK
34+
- Backend plugin (optional) - provides server-side functionality using Caido Backend SDK
35+
36+
These are packaged together as a single plugin package that can be installed in Caido.
37+
38+
### Key Development Concepts
39+
40+
- Frontend plugins create pages, UI components, and handle user interactions
41+
- Backend plugins register API endpoints that can be called from frontend
42+
- Communication between frontend and backend happens through registered API calls
43+
44+
### Caido Findings SDK
45+
46+
Findings allow you to create alerts when Caido detects notable characteristics in requests/responses based on conditional statements. When triggered, they generate alerts to draw attention to interesting traffic.
47+
48+
Example - Create a finding for successful responses:
49+
```typescript
50+
await sdk.findings.create({
51+
title: `Success Response ${response.getCode()}`,
52+
description: `Request ID: ${request.getId()}\nResponse Code: ${response.getCode()}`,
53+
reporter: "Response Logger Plugin",
54+
request: request,
55+
dedupeKey: `${request.getPath()}-${response.getCode()}` // Prevents duplicates
56+
});
57+
```
58+
59+
### Important Caido SDK Types
60+
61+
```typescript
62+
export type Request = {
63+
getId(): ID;
64+
getHost(): string;
65+
getPort(): number;
66+
getTls(): boolean;
67+
getMethod(): string;
68+
getPath(): string;
69+
getQuery(): string;
70+
getUrl(): string;
71+
getHeaders(): Record<string, Array<string>>;
72+
getHeader(name: string): Array<string> | undefined;
73+
getBody(): Body | undefined;
74+
getRaw(): RequestRaw;
75+
getCreatedAt(): Date;
76+
toSpec(): RequestSpec;
77+
toSpecRaw(): RequestSpecRaw;
78+
};
79+
80+
export type Response = {
81+
getId(): ID;
82+
getCode(): number;
83+
getHeaders(): Record<string, Array<string>>;
84+
getHeader(name: string): Array<string> | undefined;
85+
getBody(): Body | undefined;
86+
getRaw(): ResponseRaw;
87+
getRoundtripTime(): number;
88+
getCreatedAt(): Date;
89+
};
90+
```
91+
92+
For Body and Raw you can use methods like `getBody()?.toText()` to extract text content.
93+
94+
These types can be imported by:
95+
```
96+
import { type Request, type Response } from "caido:utils";
97+
```

0 commit comments

Comments
 (0)