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/
• 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

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

Quick start

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)

{
  "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:

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.
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)

npm run build   # runs ingest + next build

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

Why no RAG?

The corpus is small and keyed by ports, AD primitives, phases, and tool names. Keyword search + facets + synonyms is faster, free, and more precise for queries like “port 445” or “GenericWrite”. The calling LLM provides reasoning; this server provides structured retrieval.