drift

KO | EN

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #deepseek-harness #dsh-plugin #react #windows #developer-tools

★ 38 Open GitHub ↗

Security AI helper for Caido: pipes your local Claude Code / Gemini / Codex / Copilot CLI through 18 MCP tools for manual web security testing. Local-first, no API keys.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Drift - Security copilot / MCP assistant for Caido

Drift runs locally-installed AI CLI tools (Claude Code, Gemini CLI, Codex CLI, Copilot CLI) inside Caido with live access to your Caido session via an embedded MCP server.

**No API keys needed** — Drift uses CLI tools already authenticated on your machine. Every chat turn runs against a local CLI; traffic never leaves your box for a remote LLM-hosting service.

## Features

- **4 CLI backends**: Claude Code (with session resume), Gemini CLI, Codex CLI, Copilot CLI
- **MCP tools**: 18 Caido tools exposed to every provider via stdio
- **Caido integration**: command palette, context menus on requests/responses ("Review Request", "Build Test Plan", "Review Response", "Inspect JavaScript")
- **Structured HTTP handoff**: analysis actions keep the visible prompt short and attach raw request/response material as a separate chat attachment
- **Context visibility**: the header shows the current Caido UI context plus any explicit MCP project override
- **Tool safety**: per-group enables plus optional confirmation for sensitive MCP actions (`send_request`, `create_finding`, `set_environment`, intercept controls, `run_workflow`)
- **MCP activity trace**: assistant replies show which Caido tools were called and how they ended
- **Live MCP test**: Settings can verify tool discovery plus live `get_environment` and `search_history` calls before you trust a provider session
- **Chat persistence**: conversations saved via SQLite with JSON backup; persistence failures surfaced rather than silently swallowed
- **Streaming output** with real cancellation, a spawn-time timeout watchdog, and per-chat session lifecycle status
- **Cancel-safe turns**: pressing Stop never duplicates the assistant message even if the provider resolves after SIGTERM
- **Context-menu queue**: a context-menu action fired while another turn is streaming is queued with a toast, drained when the current turn finishes, and cleared if you press Stop
- **In-app Help tab**: prerequisites, setup walkthrough, troubleshooting, prompt examples
- **Diagnostics report**: one-click copy/download of a redacted diagnostics bundle for bug reports
- **Session debug log (opt-in)**: a checkbox in Settings > Process streams per-session provider lifecycle events to `/tmp/drift-session-<id>.log` and deletes the file when the session ends

## Installation

```bash
pnpm install
pnpm build
```

Install `dist/drift.zip` in Caido via Plugins > Install from file.

## Configuration

### CLI Providers

In Settings, set the command path for each CLI tool. Drift first tries the configured command via Caido's inherited `PATH`, then probes common install locations (Homebrew, `~/.local/bin`, Volta, asdf, nvm, fnm). Use a full path (for example `/Users/you/.local/bin/claude`) to pin a specific binary explicitly.

| Provider | Resume | MCP | Status |
|----------|--------|-----|--------|
| Claude Code | Yes (`--session-id`/`--resume`) | Yes (per-invocation stdio config) | **Stable** — structured `stream-json` parser, dedicated tests, watchdog recovery |
| Gemini CLI | No | Yes (registered wrapper) | **Experimental** — text output, mutates `~/.gemini/settings.json` on start/stop |
| Codex CLI | No | Yes (pre-registered via `codex mcp add`) | **Experimental** — text output, thin wiring |
| Copilot CLI | No | Yes (`--additional-mcp-config`) | **Experimental** — text output, per-chat MCP config file |

All four providers share the same MCP/runtime contract: if a provider is enabled and installed, Drift exposes the same 18 MCP tools, the same effective Caido context model, and the same live-test semantics. The **Experimental** providers are functional today but depend on their upstream CLI's text output; an upstream change can break parsing silently. Run **Settings → MCP Server → Run Self-Test** against each provider before trusting it for production work.

### MCP Server

1. Open Drift inside an authenticated Caido UI session — Drift picks up your active Caido session token automatically, no manual auth setup required.
2. Click Settings > MCP Server > Start.
3. Open a new chat after MCP is running. Drift mirrors the currently selected Caido project plus the active HTTP History preset/query/scope for history searches, and exposes an explicit project override when an MCP tool selects a different project.
4. Use **Run Self-Test** in Settings if you want Drift to verify tool discovery plus live `get_environment` and `search_history` calls before chatting.
5. Use **Health check** in Settings to run the preflight checklist, and **Diagnostics** to copy or download a redacted diagnostics report if something fails.

Registration of the Drift MCP server into each external tool's config file (Gemini, Codex) respects the command path you configured and the provider's `enabled` flag, and Drift tracks what it actually wrote so the cleanup on stop never leaks stale `mcpServers.drift` entries in `~/.gemini/settings.json` etc. The diagnostics report surfaces both the registered CLI paths and any CLIs Drift intentionally skipped.

### Operational UX

- **Health check** checks provider resolution, Caido auth, MCP runtime state, live-test results, and current Caido context sync in one place.
- **Tool safety** lets you disable MCP capability groups and require confirmation before sensitive actions such as findings, environment changes, replay, intercept, or workflow mutations.
- **Diagnostics report** exports provider status, MCP status, registered CLI paths, effective Caido context, persistence issues, and chat/session summaries without including tokens or secrets.
- **Session lifecycle** in chat makes it visible whether the current chat has a live provider session, whether MCP was attached to the last turn, and why the last turn stopped or failed.
- **Chat workflows** emphasize review, validation, and reporting instead of broad scan-style prompts, with better automatic titles for request/response-driven chats.
- **Chat polish** includes rename, copy/export, delete confirmation, and workflow-oriented empty states and composer presets.
- **Session debug log (opt-in)** Settings > Process exposes a checkbox that, when enabled, streams per-line provider lifecycle events to `/tmp/drift-session-<id>.log` and deletes the file when the session ends. Off by default — no trace is written and nothing is buffered in memory until you flip it on.

### Prompt examples

- `Review this HTTP request as a manual security tester. Summarize what it does and propose the next 3 tests to run in Caido.`
- `Help me validate a security hypothesis in the active Caido context. Build a focused test plan with payloads and confirmation criteria.`
- `Draft a structured security finding from the current hypothesis or evidence.`
- `I'm not seeing the expected Caido tools or context. Summarize the MCP/session state and tell me the next recovery step.`

### Live test semantics

A passed live test means Drift could start the selected provider against the real MCP contract, discover tools, call `get_environment`, and run `search_history(limit: 1)` with the current auth/context. It does **not** prove every mutating tool, every approval flow, or every provider prompt shape.

### Context override semantics

Drift mirrors the active Caido UI project/filter/query/scope by default. If an MCP tool explicitly selects a different project, Drift keeps using that override until it is cleared. While the override is active, the override project wins and any incompatible history scope is cleared rather than guessed.

### Common recovery paths

| Symptom | Next step |
|---------|-----------|
| Provider unavailable | Fix the command path in Settings > CLI Providers or disable that provider |
| MCP auth failed | Open any Caido page to refresh the session token and retry |
| History/context looks wrong | Run `get_current_context`, clear any override, and rerun the Health check |
| Provider session feels stuck | Restart or close the chat session from the chat header |
| You need support evidence | Export the diagnostics report from Settings > Diagnostics |

### MCP Tools

| Tool | Description |
|------|-------------|
| `search_history` | Search HTTP history with HTTPQL filters while applying the effective Drift context (Caido UI context plus any active override) |
| `get_current_context` | Show the current UI context, override context, and effective context Drift is using |
| `list_projects` | List Caido projects and indicate the current UI-selected project |
| `select_project` | Set an explicit Drift project override for MCP tool calls |
| `clear_context_override` | Clear the explicit Drift project override and return to the Caido UI context |
| `get_request` | Get full raw request/response by ID |
| `send_request` | Send HTTP request via Caido replay |
| `create_replay_session` | Create replay session from request ID |
| `create_finding` | Create a security finding |
| `list_findings` | List all findings |
| `get_scope` | List scope definitions |
| `check_scope` | Check if URL is in scope |
| `get_environment` | List environments and variables |
| `set_environment` | Set environment variables |
| `run_workflow` | Execute a convert workflow |
| `intercept_status` | Get intercept proxy status |
| `intercept_pause` | Pause HTTP intercept |
| `intercept_resume` | Resume HTTP intercept |

## Caido Integration

- **Command Palette** (Ctrl/Cmd+Shift+P): "Open Drift"
- **Request context menu**: "Review Request", "Build Test Plan"
- **Response context menu**: "Review Response", "Inspect JavaScript"
- **Request row context menu** (history, sitemap): "Review Request", "Build Test Plan"

The analysis actions keep the visible user prompt short and send the raw HTTP request/response as a structured attachment for provider analysis. If you trigger an action while another turn is already streaming, Drift queues it (with a toast) and fires it as soon as the current turn finishes; pressing Stop drops anything still queued so it cannot fire after a cancel.

## Known Limitations

- Settings persist via SQLite when available, with JSON file backup
- Session resume only works with Claude Code
- Caido's QuickJS backend runtime restricts available Node.js modules

## Screenshots

## Development

```bash
pnpm install
pnpm build              # Build plugin (produces dist/drift.zip)
pnpm watch              # Caido dev watch mode
pnpm -r typecheck       # Type-check shared, backend, and frontend workspaces
pnpm exec vitest run    # Run the full unit + Vue mount test suite
```

The frontend tests use `@vue/test-utils` with `happy-dom` to mount `ChatView` against a stubbed Caido SDK and Pinia stores. Coverage includes the cancel-race guard, the context-menu queue drain, and the queue-clear-on-cancel path.

Backend tests cover Claude print-mode parsing, command resolution, MCP runtime, persistence, and live MCP transport semantics.

## Release QA checklist

1. **Provider resolution:** in Settings, confirm Claude, Gemini, Codex, and Copilot resolve correctly or are intentionally disabled.
2. **Health check:** run Health check and verify provider checks, Caido auth, MCP runtime, live-test state, and context sync.
3. **Per-provider chat smoke:** for each enabled provider, start a fresh chat and verify a review or validation prompt returns the expected project/filter/scope-aware answer and that MCP activity is shown on the reply.
4. **Structured HTTP handoff:** use a request/response context-menu review action and verify the attachment chip appears in chat and the reply reflects the attached material.
5. **Cancel race:** start a long-running turn, press Stop mid-stream, and confirm only a single `[Cancelled]` assistant message appears (no late duplicate when the provider eventually exits).
6. **Context-menu queue:** while a turn is streaming, fire two analysis actions on different requests; confirm the toast, that queued prompts run sequentially after the active turn, and that pressing Stop drops anything still queued.
7. **Session debug log:** with the flag off (default), confirm `/tmp/drift-session-*.log` is not created during a turn. Toggle it on, run a turn, end the session, and confirm the log file is removed.
8. **MCP registration footprint:** with Gemini disabled, start MCP and confirm `~/.gemini/settings.json` is not mutated. Enable Gemini with a specific command path, start MCP, confirm `mcpServers.drift` was registered against that exact path. Disable Gemini, stop MCP, and confirm the entry is cleaned up (the tracked-paths map ignores the current `enabled` flag).
9. **Diagnostics:** export a diagnostics report and confirm it contains provider/MCP/registered-paths/chat data without secrets.
10. **Tests:** `pnpm -r typecheck` and `pnpm exec vitest run` both pass.

## Documentation

- **[docs/SECURITY.md](docs/SECURITY.md)** — threat model, data flow, attack surface, and how to report vulnerabilities.
- **[docs/cookbook.md](docs/cookbook.md)** — 7 real workflow recipes (IDOR, auth bypass, data-leak audit, JS endpoint discovery, race conditions, finding → report).

## License

MIT

drift

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README