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

Related MCP server: pyntra

Quick start

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

MCP tools

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.