oscp-companion

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.