pentest-kb MCP Server

MCP-Server für die Wissensdatenbank für Penetrationstests. Basierend auf MCP (Model Context Protocol) stellt er Werkzeuge zum Abrufen, Hinzufügen, Auflisten usw. bereit, um praxisnahe Erfahrungen aus Penetrationstests zu sammeln und wiederzuverwenden.

Welches Problem löst dieses Projekt?

Hintergrund und Problemstellung:

• Penetrationstest-Erfahrungen sind über Notizen, Chatverläufe und persönliche Erinnerungen verstreut und schwer zu durchsuchen und wiederzuverwenden. Bei ähnlichen Problemen (z. B. WAF-Umgehung, 403-Umgehung) muss oft neu gesucht werden.

• Der Agent hat standardmäßig keinen Zugriff auf die persönliche Wissensdatenbank und kann sich bei Fragen zu Penetrationstests nur auf allgemeines Wissen stützen. Es fehlt die Unterstützung durch praktische Erfahrung, was leicht zu vagen Empfehlungen führt.

• Erfahrungen können nicht gesammelt und nicht über Szenarien hinweg wiederverwendet werden; das von Einzelpersonen oder Teams angesammelte Wissen lässt sich schwer systematisieren.

Was dieses Projekt löst:

• Penetrationstest-Erfahrungen werden einheitlich in einer PostgreSQL-Datenbank (Supabase) gesammelt und strukturiert gespeichert.

• Über das MCP-Protokoll wird die Wissensdatenbank an den Agenten angebunden, sodass dieser Erfahrungen direkt abrufen (search_experience), hinzufügen (add_experience) und auflisten (list_all_experiences) kann.

• Die Suche basiert auf BM25-Relevanzranking (jieba chinesische Wortsegmentierung) und ist genauer als einfache Fuzzy-Suche.

• Der Agent soll in realen Einsatzszenarien auf Basis der persönlichen Wissensdatenbank antworten, statt sich nur auf allgemeines Wissen zu verlassen.

Related MCP server: Nümtema Private Knowledge MCP

Funktionen

• search_experience(keyword, tags_filter): Durchsucht die Wissensdatenbank basierend auf BM25-Relevanzranking (nur genehmigte Einträge), unterstützt chinesische Wortsegmentierung und gibt die Top 10 zurück; tags_filter filtert präzise nach Szenario-Tags (z. B. ["WAF绕过"]).

• add_experience(title, detail, scenario_tags, tool_code, tool_type, status): Fügt eine Erfahrung hinzu. status='draft' speichert sie als Entwurf mit ausstehender Genehmigung (Standard), status='approved' übernimmt sie direkt in die Datenbank; vor dem Schreiben wird automatisch eine Desensibilisierungsprüfung durchgeführt (erkennt echte IPs, Domains, Anmeldedaten, Cloud-Anbieter-AccessKeys, JWT, private Schlüssel, Telefonnummern und lehnt bei Treffern ab).

• list_all_experiences(limit, offset): Listet seitenweise die Titel aller genehmigten Einträge in der Wissensdatenbank auf (Standard: 50 pro Seite, maximal 200).

• find_similar(title, detail): Prüft auf Duplikate und findet bereits gespeicherte Einträge, die dem angegebenen Inhalt ähneln.

• get_experience(experience_id): Ruft den vollständigen Inhalt einer Erfahrung anhand der id ab (Titel, Details, Tags, Tool-Code, Status usw.).

• update_experience(experience_id, title, detail, scenario_tags, tool_code, tool_type, status): Aktualisiert die Felder einer Erfahrung (nur übergebene Felder werden aktualisiert, nicht übergebene bleiben unverändert; vor der Änderung wird automatisch eine Desensibilisierungsprüfung durchgeführt).

• list_pending_experiences(): Listet Entwürfe mit ausstehender Genehmigung auf und weist auf möglicherweise doppelte bereits gespeicherte Einträge für jeden Entwurf hin.

• approve_experience(experience_id, merge_with_id): Genehmigt einen Entwurf; wenn merge_with_id angegeben ist, wird der Entwurf in den angegebenen Eintrag überführt (Details werden angehängt, Tags zusammengeführt, Tool-Informationen ergänzt) und anschließend gelöscht.

• reject_experience(experience_id): Lehnt einen Entwurf ab (Soft-Delete, der Eintrag bleibt als rejected erhalten und kann wiederhergestellt werden).

• delete_experience(experience_id): Löscht genehmigte Erfahrungen per Soft-Delete (Status wird auf deleted gesetzt, sie nehmen nicht an der Suche teil und können wiederhergestellt werden).

• restore_experience(experience_id): Stellt per Soft-Delete gelöschte Einträge wieder her (abgelehnter Entwurf → draft, gelöschte Erfahrung → approved).

• list_deleted_experiences(): Listet alle per Soft-Delete gelöschten Einträge auf (Papierkorb), um sie wiederherzustellen oder endgültig zu bereinigen.

• purge_experiences(days): Löscht per Soft-Delete gelöschte Einträge physisch, die älter als die angegebene Anzahl Tage sind (Standard: 30 Tage, nicht wiederherstellbar, bitte vorsichtig verwenden).

Erfahrungssammlung und Genehmigung

Um zu vermeiden, dass die automatische Sammlung ausufernde Inhalte und Offenlegung sensibler Informationen erzeugt, wird ein Prozess aus „halbautomatischer Sammlung + erzwungener Desensibilisierung + manueller Genehmigung“ verwendet:

实战结束 → Agent 生成经验草稿（status='draft'，结构化 + 限长 + 脱敏）
        → 草稿进入待审批状态（不直接入库，不参与检索）
        → 用户审批（list_pending 查看 → approve / reject / merge）
        → 通过后才正式入库（status='approved'）

Desensibilisierung als Schutzschicht: Vor dem Schreiben erkennt add_experience automatisch echte IP-Adressen, Domains, E-Mail-Adressen, Anmeldedaten (einschließlich chinesischer Begriffe wie „密码/口令/密钥/账号“), Cloud-Anbieter-AccessKeys (AWS/Aliyun/Tencent), JWT, private Schlüsselblöcke und Telefonnummern. Bei einem Treffer wird das Schreiben abgelehnt und es wird verlangt, die Werte durch Platzhalter zu ersetzen (z. B. <目标URL>, <目标域名>). Spezielle IPs wie private, Loopback- und Link-Local-Adressen sowie Whitelist-Domains (z. B. example.com) dürfen gespeichert werden.

Duplikaterkennung als Schutzschicht: Bei der Genehmigung weist list_pending_experiences automatisch auf möglicherweise doppelte bereits gespeicherte Einträge für jeden Entwurf hin. Der Benutzer kann überspringen, zusammenführen oder dennoch neu hinzufügen.

Direkte Speicherung vs. Entwurfsgenehmigung: add_experience unterstützt die direkte Speicherung mit status='approved', die nur für manuell vom Benutzer bestätigte Eingaben vorgesehen ist. AI-Workflows (siehe SKILL.md) müssen in jedem Fall einen draft-Entwurf erzeugen und genehmigen lassen; eine direkte Speicherung ist nicht erlaubt.

Abhängigkeiten

• Python 3.10+

• mcp (MCP-Python-SDK)

• psycopg2 (PostgreSQL-Treiber)

• jieba (chinesische Wortsegmentierung; lädt beim Start automatisch das Fachwörterbuch pentest_dict.txt im Stammverzeichnis)

• rank_bm25 (BM25-Suchalgorithmus)

• Eine PostgreSQL-Datenbank (z. B. Supabase)

Abhängigkeiten installieren:

pip install -r requirements.txt

Die Liste der Abhängigkeiten ist in requirements.txt zu finden (mit festgelegten Versionsbereichen; beachten Sie, dass mcp Version 2.x sein muss).

Datenbankinitialisierung

Führen Sie in PostgreSQL (z. B. Supabase) die Datei schema.sql im Stammverzeichnis des Repositorys aus (idempotent, kann wiederholt ausgeführt werden):

# 方式一：Supabase 控制台 → SQL Editor → 粘贴 schema.sql 内容执行
# 方式二：命令行（需已配置 psql）
psql "$PENTEST_KB_DB_CONNECTION_STRING" -f schema.sql

Die Tabellenstruktur ist wie folgt (schema.sql ist die einzige Pflegequelle; das README enthält das SQL nicht erneut):

Optional: Spalte für semantische Suche (derzeit nicht vom Code verwendet, vorbehalten) Wenn Sie eine vektorielle semantische Suche anbinden möchten, entfernen Sie die Kommentare am Ende von schema.sql und führen Sie sie aus (zuvor muss die pgvector-Erweiterung aktiviert werden).

Konfiguration

Die Datenbankverbindungsinformationen werden über Umgebungsvariablen injiziert. Bitte kodieren Sie keine Anmeldedaten fest im Code:

MCP-Client-Konfiguration

Registrieren Sie den Server im MCP-Client; siehe mcp.example.json:

{
  "mcpServers": {
    "pentest-kb": {
      "command": "python",
      "args": ["/absolute/path/to/pentest_kb_mcp.py"],
      "env": {
        "PENTEST_KB_DB_HOST": "your-supabase-host.pooler.supabase.com",
        "PENTEST_KB_DB_PORT": "5432",
        "PENTEST_KB_DB_NAME": "postgres",
        "PENTEST_KB_DB_USER": "postgres.your-project-ref",
        "PENTEST_KB_DB_PASSWORD": "your-database-password"
      }
    }
  }
}

Verwendung

Rufen Sie die Tools einfach im MCP-Client auf, zum Beispiel:

搜索：search_experience(keyword="WAF绕过")   # BM25 相关性排序
搜索+标签过滤：search_experience(keyword="绕过", tags_filter=["WAF绕过"])   # 只看 WAF 相关
新增（直接入库，仅手动操作）：add_experience(title="Nginx 403 绕过", detail="...", scenario_tags=["WAF绕过"], tool_type="burp", status="approved")
新增草稿：add_experience(title="...", detail="...")   # 默认 status='draft'，待审批
查重：find_similar(title="...", detail="...")
查看单条：get_experience(experience_id="...")
修改：update_experience(experience_id="...", detail="...")   # 只更新传入字段
查看草稿：list_pending_experiences()
审批：approve_experience(experience_id="...")   # 或 merge_with_id 合并
拒绝：reject_experience(experience_id="...")   # 软删除，可恢复
删除：delete_experience(experience_id="...")   # 软删除已审批经验
恢复：restore_experience(experience_id="...")
回收站：list_deleted_experiences()
清理：purge_experiences(days=30)   # 物理删除超期软删记录
列出：list_all_experiences(limit=50, offset=0)   # 分页

Skill-Kapselung

Wurde als benutzerdefinierter Skill gekapselt; die Datei befindet sich im Stammverzeichnis des Projekts unter SKILL.md und ist entlang des Ausführungsablaufs in sechs Phasen gegliedert:

• Phase 1: Absichtserkennung

• Phase 2: Informationssammlung zuerst

• Phase 3: Datenbankabfrage auslösen

• Phase 4: Ergebniszitate und Antwort

• Phase 5: Ausführungs- und Freistellungsregeln

• Phase 6: Erfahrungssammlung

Legen Sie SKILL.md in das Verzeichnis für benutzerdefinierte Skills, um es zu laden.

Sicherheitshinweise

• Datenbank-Anmeldedaten werden ausschließlich über Umgebungsvariablen injiziert; das Repository enthält keine echten Verbindungsinformationen.

• Bitte rotieren Sie das Datenbank-Passwort regelmäßig und vermeiden Sie schwache Passwörter.