Skip to main content
Glama

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

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to orchestrate 100+ security tools over MCP for authorized penetration testing, including recon, scanning, exploitation, attack-chain planning, and knowledge-base retrieval.
      7
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables authorized penetration testers to run reconnaissance, scanning, brute-force, traffic-capture, and exploitation tools through MCP clients, with authentication, engagement recordkeeping, and client report generation.
      164 npm
      GPL 3.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables professional penetration testers to run reconnaissance, exploitation, password cracking, web fuzzing, vulnerability scanning, traffic capture, and client-reporting workflows through MCP transports with auth support.
      164 npm
      GPL 3.0