# OSCP Companion

Structured pentesting methodology knowledge base with a web UI and MCP server for AI agents.

**Educational / authorized testing only.** Use only on systems you own or have explicit permission to test.

## Architecture

- **Content**: Markdown + YAML frontmatter in [`content/`](content/)
- **Build**: `scripts/ingest.ts` compiles content → `public/kb.json` with Zod validation and secret scanning
- **Engine**: In-memory MiniSearch index with synonym expansion (no vector DB, no RAG)
- **Web UI**: Next.js search + faceted filters + entry detail pages
- **MCP**: 7 read-only tools via HTTP (`/api/mcp`) and local stdio

```text
content/*.md  →  ingest  →  public/kb.json  →  MethodologyEngine
                                                    ├─ Web UI
                                                    └─ MCP server
```

## Quick start

```bash
npm install
npm run ingest   # compile knowledge base
npm run dev      # http://localhost:3000
npm test         # verify sample queries
```

## MCP tools

| Tool | Purpose |
|------|---------|
| `search_plays` | Keyword search with optional phase/os/type filters |
| `port_playbook` | Port/service playbook (e.g. `445`, `smb`) |
| `ad_paths` | AD attack paths for a BloodHound primitive (e.g. `GenericWrite`) |
| `checklist` | Ordered checklist steps for a phase + OS |
| `tool` | Commands and notes for a pentest tool |
| `technique` | Look up entries by technique name |
| `list_filters` | Discover valid phases, OS, types, services, primitives, etc. |

### Local MCP (Cursor / Claude Desktop)

```json
{
  "mcpServers": {
    "oscp-companion": {
      "command": "npx",
      "args": ["tsx", "mcp/stdio.ts"],
      "cwd": "/path/to/oscp-companion"
    }
  }
}
```

Run `npm run ingest` before starting the MCP server so `public/kb.json` exists.

### Remote MCP (after deploy)

Point your MCP client at:

```text
https://your-app.vercel.app/api/mcp
```

## Adding content

1. Add a Markdown file under `content/` with YAML frontmatter matching the schema in [`lib/kb/schema.ts`](lib/kb/schema.ts).
2. Use placeholders: `<IP>`, `<USER>`, `<PASS>`, `<DOMAIN>` — never commit real creds or lab secrets.
3. Run `npm run ingest`. The secret scanner fails the build if AWS keys, NTLM hashes, or HTB-style IPs slip through.

Raw unsanitized notes belong in `data/raw/` (gitignored).

## Deploy (Vercel free tier)

```bash
npm run build   # runs ingest + next build
```

Connect the repo to Vercel. No database or env vars required for the default setup.