pentest-kb MCP Server

MCP-сервер базы знаний по пентесту. Предоставляет инструменты поиска, добавления, перечисления и другие на основе MCP (Model Context Protocol) для накопления и повторного использования практического опыта тестирования на проникновение.

Какую проблему решает этот проект

Болевые точки:

• Опыт пентеста разбросан по заметкам, чатам и личной памяти; его сложно искать и повторно использовать. При столкновении с однотипными задачами (например, обход WAF, обход 403) часто приходится искать заново.

• Агент по умолчанию не имеет доступа к личной базе знаний; отвечая на вопросы по пентесту, он опирается только на общие знания, не имея поддержки практического опыта, и легко даёт поверхностные рекомендации.

• Опыт невозможно накапливать и применять в разных сценариях; знания, накопленные человеком или командой, сложно систематизировать.

Что решает этот проект:

• Единообразно накапливает опыт пентеста в базе данных PostgreSQL (Supabase) и хранит его в структурированном виде.

• Подключает базу знаний к агенту через протокол MCP, позволяя агенту напрямую искать (search_experience), добавлять (add_experience) и получать список (list_all_experiences) записей.

• Поиск основан на ранжировании по релевантности BM25 (китайская сегментация слов jieba), что точнее простого нечёткого сопоставления.

• Позволяет агенту в реальных сценариях отвечать на основе личной базы знаний, а не только на общих знаниях.

Related MCP server: Nümtema Private Knowledge MCP

Функции

• search_experience(keyword, tags_filter): ищет в базе знаний на основе ранжирования по релевантности BM25 (только утверждённые записи), поддерживает китайскую сегментацию слов, возвращает Top-10; tags_filter позволяет точно фильтровать по тегам сценария (например, ["WAF绕过"]).

• add_experience(title, detail, scenario_tags, tool_code, tool_type, status): добавляет запись. status='draft' сохраняет её как черновик, ожидающий утверждения (по умолчанию), status='approved' добавляет напрямую в базу; перед записью автоматически выполняется проверка обезличивания (обнаруживает реальные IP-адреса, домены, учётные данные, AccessKey облачных провайдеров, JWT, закрытые ключи, номера телефонов; при совпадении запись отклоняется).

• list_all_experiences(limit, offset): постранично выводит заголовки всех утверждённых записей в базе знаний (по умолчанию 50 записей на страницу, максимум 200).

• find_similar(title, detail): проверка на дубликаты; ищет уже сохранённые записи, похожие на заданное содержимое.

• get_experience(experience_id): получает полное содержимое записи по id (заголовок, детали, теги, код инструмента, статус и т.д.).

• update_experience(experience_id, title, detail, scenario_tags, tool_code, tool_type, status): обновляет поля записи (обновляются только переданные поля, остальные остаются без изменений; перед изменением автоматически выполняется проверка обезличивания).

• list_pending_experiences(): выводит черновики, ожидающие утверждения, и подсказывает для каждого черновика возможные дубликаты уже сохранённых записей.

• approve_experience(experience_id, merge_with_id): утверждает черновик; если указан merge_with_id, объединяет его с указанной записью (дополняет детали, объединяет теги, заполняет информацию об инструменте) и затем удаляет черновик.

• reject_experience(experience_id): отклоняет черновик (мягкое удаление: запись сохраняется со статусом rejected, её можно восстановить).

• delete_experience(experience_id): мягко удаляет утверждённую запись (статус становится deleted, запись не участвует в поиске, её можно восстановить).

• restore_experience(experience_id): восстанавливает мягко удалённые записи (отклонённый черновик → draft, удалённая запись → approved).

• list_deleted_experiences(): выводит все мягко удалённые записи (корзину) для восстановления или полной очистки.

• purge_experiences(days): физически удаляет записи, находящиеся в мягком удалении дольше указанного числа дней (по умолчанию 30 дней, восстановление невозможно, действуйте осторожно).

Накопление опыта и утверждение

Чтобы автоматическое накопление не создавало громоздкого контента и не приводило к утечке конфиденциальной информации, используется процесс «полуавтоматическое накопление + обязательное обезличивание + ручное утверждение»:

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

Барьер обезличивания: add_experience перед записью автоматически обнаруживает реальные IP-адреса, домены, email, учётные данные (включая китайские слова «密码/口令/密钥/账号»), AccessKey облачных провайдеров (AWS/Aliyun/Tencent), JWT, блоки закрытых ключей, номера телефонов; при совпадении запись отклоняется и требует замены на заполнители (например, <目标URL>, <目标域名>). Частные, loopback, link-local и другие специальные IP-адреса, а также домены из белого списка (например, example.com) разрешено сохранять.

Барьер проверки дубликатов: при утверждении list_pending_experiences автоматически подсказывает для каждого черновика возможные дубликаты уже сохранённых записей; пользователь может выбрать: пропустить, объединить или всё же добавить.

Прямое добавление vs утверждение черновика: add_experience поддерживает status='approved' для прямого добавления в базу, но только в сценариях ручного подтверждения пользователем; AI-рабочий процесс (см. SKILL.md) во всех случаях требует создавать черновик draft и проходить утверждение, прямое добавление в базу запрещено.

Зависимости

• Python 3.10+

• mcp (MCP Python SDK)

• psycopg2 (драйвер PostgreSQL)

• jieba (китайская сегментация слов; при запуске автоматически загружает отраслевой словарь pentest_dict.txt из корневого каталога)

• rank_bm25 (алгоритм поиска BM25)

• база данных PostgreSQL (например, Supabase)

Установка зависимостей:

pip install -r requirements.txt

Список зависимостей приведён в requirements.txt (диапазоны версий зафиксированы; обратите внимание: mcp должен быть версии 2.x).

Инициализация базы данных

В PostgreSQL (например, Supabase) выполните schema.sql из корневого каталога репозитория (идемпотентный, можно выполнять повторно):

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

Структура таблиц приведена ниже (schema.sql — единственный поддерживаемый источник; README больше не дублирует SQL):

Опционально: колонка для семантического поиска (в текущем коде не используется, зарезервировано) Чтобы подключить векторный семантический поиск, раскомментируйте код в конце schema.sql и выполните его (предварительно нужно включить расширение pgvector).

Конфигурация

Данные для подключения к базе данных передаются через переменные окружения; не зашивайте учётные данные в код:

Конфигурация MCP-клиента

Зарегистрируйте сервер в MCP-клиенте, руководствуясь 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"
      }
    }
  }
}

Использование

Вызывайте инструменты в MCP-клиенте, например:

搜索：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

Упаковано в виде пользовательского Skill; файл находится в корневом каталоге проекта SKILL.md и организован по процессу выполнения в шесть этапов:

• Этап 1: Определение намерения

• Этап 2: Приоритетный сбор информации

• Этап 3: Запуск поиска по базе знаний

• Этап 4: Цитирование результатов и ответ

• Этап 5: Правила выполнения и исключений

• Этап 6: Накопление опыта

Поместите SKILL.md в каталог пользовательских Skill, и он будет загружен.

Примечания по безопасности

• Учётные данные базы данных передаются только через переменные окружения; в репозитории нет никакой реальной информации для подключения.

• Регулярно меняйте пароль базы данных и избегайте использования слабых паролей.