Skip to main content
Glama

Servidor MCP pentest-kb

Servidor MCP del repositorio de experiencias de pruebas de penetración. Basado en MCP (Model Context Protocol), proporciona herramientas de búsqueda, creación y listado, entre otras, para consolidar y reutilizar experiencias prácticas de pruebas de penetración.

¿Qué problema resuelve este proyecto?

Problemas de fondo:

  • Las experiencias de pruebas de penetración están dispersas en notas, registros de chat y la memoria personal; son difíciles de localizar y reutilizar. Ante problemas similares (como evasión de WAF o evasión de 403), a menudo hay que volver a buscar desde cero.

  • El Agent no tiene acceso al repositorio personal de experiencias por defecto; al responder preguntas de pruebas de penetración solo puede depender del conocimiento general y, al carecer del respaldo de experiencia práctica, tiende a dar consejos genéricos.

  • Las experiencias no se pueden consolidar ni reutilizar entre escenarios; el conocimiento acumulado por una persona o un equipo difícilmente llega a articularse como un sistema.

Lo que resuelve este proyecto:

  • Consolidar de forma unificada las experiencias de pruebas de penetración en una base de datos PostgreSQL (Supabase) con almacenamiento estructurado.

  • Conectar el repositorio de experiencias al Agent mediante el protocolo MCP, de modo que el Agent pueda buscar (search_experience), añadir (add_experience) y listar (list_all_experiences) experiencias directamente.

  • La búsqueda se basa en el orden de relevancia BM25 (segmentación de chino con jieba), más precisa que una simple coincidencia difusa.

  • Permitir que el Agent responda en escenarios reales basándose en el repositorio personal de experiencias, en lugar de depender únicamente del conocimiento general.

Related MCP server: mcp-rag-bridge

Funciones

  • search_experience(keyword, tags_filter): busca en el repositorio de experiencias mediante el orden de relevancia BM25 (solo registros aprobados), admite segmentación de chino y devuelve el Top 10; tags_filter permite filtrar con precisión por etiquetas de escenario (p. ej., ["WAF绕过"]).

  • add_experience(title, detail, scenario_tags, tool_code, tool_type, status): añade una experiencia. Con status='draft' se guarda como borrador pendiente de aprobación (por defecto); con status='approved' se guarda directamente en el repositorio. Antes de escribir, realiza automáticamente una validación de desensibilización (detecta IP reales, dominios, credenciales, AccessKey de proveedores cloud, JWT, claves privadas y números de teléfono; si hay coincidencia, lo rechaza).

  • list_all_experiences(limit, offset): lista paginada de los títulos de todos los registros aprobados en el repositorio (50 por página por defecto, máximo 200).

  • find_similar(title, detail): comprueba duplicados: busca registros ya almacenados similares al contenido proporcionado.

  • get_experience(experience_id): obtiene el contenido completo de una experiencia por su id (título, detalle, etiquetas, código de herramienta, estado, etc.).

  • update_experience(experience_id, title, detail, scenario_tags, tool_code, tool_type, status): actualiza los campos de una experiencia (solo actualiza los campos recibidos; los no recibidos permanecen igual; antes de modificar realiza una validación automática de desensibilización).

  • list_pending_experiences(): lista los borradores pendientes de aprobación e indica para cada borrador los registros ya almacenados que podrían estar duplicados.

  • approve_experience(experience_id, merge_with_id): aprueba un borrador. Si se proporciona merge_with_id, lo fusiona en el registro indicado (el detalle se añade al final, se combinan las etiquetas y se completa la información de la herramienta) y después elimina el borrador.

  • reject_experience(experience_id): rechaza un borrador (borrado lógico; el registro se conserva como rejected y se puede recuperar).

  • delete_experience(experience_id): borrado lógico de una experiencia aprobada (el estado pasa a deleted, no participa en las búsquedas y se puede recuperar).

  • restore_experience(experience_id): restaura registros eliminados lógicamente (borrador rechazado → draft, experiencia eliminada → approved).

  • list_deleted_experiences(): lista todos los registros con borrado lógico (papelera de reciclaje) para facilitar su recuperación o su limpieza definitiva.

  • purge_experiences(days): elimina físicamente los registros que llevan en borrado lógico más de los días indicados (30 días por defecto; no se pueden recuperar; actuar con precaución).

Consolidación de experiencias y aprobación

Para evitar que la consolidación automática genere contenido redundante y fugas de información sensible, se adopta el proceso de "consolidación semiautomática + desensibilización obligatoria + aprobación manual":

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

Línea de defensa de desensibilización: antes de escribir, add_experience detecta automáticamente direcciones IP reales, dominios, correos electrónicos, credenciales (incluidas expresiones en chino como "密码/口令/密钥/账号"), AccessKey de proveedores cloud (AWS/Aliyun/Tencent), JWT, bloques de claves privadas y números de teléfono. Si hay coincidencia, rechaza la escritura y exige sustituirlos por placeholders (como <目标URL>, <目标域名>). Las IP especiales de red privada/bucle local/enlace local y los dominios de la lista blanca (como example.com) sí pueden almacenarse.

Línea de defensa contra duplicados: durante la aprobación, list_pending_experiences indica automáticamente para cada borrador los registros ya almacenados que podrían estar duplicados; el usuario puede elegir omitirlo, fusionarlo o añadirlo igualmente.

Inserción directa vs. aprobación de borradores: add_experience admite status='approved' para insertar directamente en el repositorio, pero solo debe usarse en escenarios de registro confirmados manualmente por el usuario; los flujos de trabajo de IA (consulte SKILL.md) deben generar siempre borradores draft y pasar por el proceso de aprobación; no pueden insertarse directamente.

Dependencias

  • Python 3.10+

  • mcp (MCP Python SDK)

  • psycopg2 (driver de PostgreSQL)

  • jieba (segmentación de chino; al iniciar, carga automáticamente el diccionario de dominio pentest_dict.txt de la raíz)

  • rank_bm25 (algoritmo de búsqueda BM25)

  • Una base de datos PostgreSQL (como Supabase)

Instalación de dependencias:

pip install -r requirements.txt

La lista de dependencias se encuentra en requirements.txt (rangos de versión fijados; tenga en cuenta que mcp debe ser 2.x).

Inicialización de la base de datos

Ejecute el schema.sql de la raíz del repositorio en PostgreSQL (como Supabase) (es idempotente y puede ejecutarse repetidamente):

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

La estructura de la tabla es la siguiente (schema.sql es la única fuente de mantenimiento; el README no vuelve a incluir el SQL):

Campo

Tipo

Descripción

id

uuid PK

Clave primaria, por defecto gen_random_uuid()

created_at

timestamptz

Fecha de creación

title

text

Título de la experiencia

scenario_tags

jsonb

Matriz de etiquetas de escenario, p. ej., ["WAF绕过","SQL注入"]

experience_detail

text

Detalle de la experiencia

tool_code

text

Código de explotación/herramienta

tool_type

text

Tipo de herramienta, p. ej., sqlmap, burp

status

text

approved (aprobado) / draft (borrador pendiente) / rejected (rechazado, borrado lógico) / deleted (borrado lógico)

deleted_at

timestamptz

Fecha del borrado lógico (se registra al pasar a rejected/deleted; se usa para la limpieza tras el periodo de retención)

Opcional: columna de búsqueda semántica (el código actual no la usa; reservada). Si desea incorporar búsqueda semántica vectorial, descomente la parte final de schema.sql y ejecútela (primero debe habilitar la extensión pgvector).

Configuración

La información de conexión a la base de datos se inyecta mediante variables de entorno; no codifique credenciales de forma fija en el código:

Variable de entorno

Descripción

PENTEST_KB_DB_HOST

Dirección del host de la base de datos

PENTEST_KB_DB_PORT

Puerto (por defecto 5432)

PENTEST_KB_DB_NAME

Nombre de la base de datos (por defecto postgres)

PENTEST_KB_DB_USER

Usuario de la base de datos

PENTEST_KB_DB_PASSWORD

Contraseña de la base de datos

PENTEST_KB_DB_MAXCONN

Número máximo de conexiones del grupo de conexiones (opcional, por defecto 10)

Configuración del cliente MCP

Registre el servidor en el cliente MCP; consulte 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"
      }
    }
  }
}

Uso

Invoque las herramientas en el cliente MCP, por ejemplo:

搜索: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)   # 分页

Encapsulación como Skill

Está encapsulado como un Skill personalizado; el archivo se encuentra en la raíz del proyecto, SKILL.md, y se organiza en seis fases según el flujo de ejecución:

  • Fase 1: Juicio de intención

  • Fase 2: Priorizar la recopilación de información

  • Fase 3: Activación de la consulta al repositorio

  • Fase 4: Citación de resultados y respuesta

  • Fase 5: Normas de ejecución y exenciones

  • Fase 6: Consolidación de experiencias

Para cargarlo, basta con colocar SKILL.md en el directorio de Skills personalizados.

Notas de seguridad

  • Las credenciales de la base de datos se inyectan únicamente mediante variables de entorno; el repositorio no contiene ninguna información de conexión real.

  • Rote periódicamente la contraseña de la base de datos y evite usar contraseñas débiles.

Available Tools

13 tools
add_experienceB

往经验库中新增一条渗透测试经验。 参数: title: 经验标题,如 'Nginx 403 绕过' detail: 详细描述,包括漏洞类型、利用过程、关键payload等 scenario_tags: 场景标签列表(可选),如 ['WAF绕过', 'SQL注入'] tool_code: 利用/工具代码(可选) tool_type: 工具类型(可选),如 'sqlmap'、'burp' status: 'draft'(存为待审批草稿,默认)或 'approved'(直接入库)

Inputs: title (required), detail (required), status, tool_code, +2 more. Returns: result

approve_experienceB

审批通过一条待审批草稿。 参数: experience_id: 草稿的 id merge_with_id: 可选。提供时,将草稿内容合并进指定记录(详情追加、标签合并、工具信息补全),然后删除草稿

Inputs: experience_id (required), merge_with_id. Returns: result

delete_experienceA

软删除一条已审批经验(状态置为 deleted,不参与检索,可恢复)。 参数: experience_id: 经验的 id

Inputs: experience_id (required). Returns: result

find_similarA

查重:查找与给定标题/详情相似的已入库经验,用于避免重复录入。 参数: title: 待查重的标题 detail: 待查重的详情(可选)

Inputs: title (required), detail. Returns: result

get_experienceC

按 id 获取一条经验的完整内容(标题、详情、标签、工具代码、状态等)。 参数: experience_id: 经验的 id

Inputs: experience_id (required). Returns: result

list_all_experiencesA

分页列出经验库中所有已审批记录的标题。 参数: limit: 每页条数(默认 50,最大 200) offset: 偏移量(默认 0)

Inputs: limit, offset. Returns: result

list_deleted_experiencesA

列出所有软删除的记录(被拒绝的草稿 + 被删除的经验),便于恢复或彻底清理。

Inputs: no named parameters. Returns: result

list_pending_experiencesA

列出待审批的经验草稿,并提示每条草稿可能重复的已入库记录。

Inputs: no named parameters. Returns: result

purge_experiencesA

彻底删除软删除超过指定天数的记录(物理删除,不可恢复,请谨慎)。 参数: days: 保留天数,软删除超过该天数的记录将被物理删除(默认 30)

Inputs: days. Returns: result

reject_experienceA

拒绝一条待审批草稿(软删除:记录保留,状态置为 rejected,可恢复)。 参数: experience_id: 草稿的 id

Inputs: experience_id (required). Returns: result

restore_experienceB

恢复一条软删除的记录:被拒绝的草稿恢复为 draft,被删除的经验恢复为 approved。 参数: experience_id: 记录的 id

Inputs: experience_id (required). Returns: result

search_experienceA

搜索渗透测试经验库(仅已审批记录)。基于 BM25 相关性排序,支持中文分词。 参数: keyword: 搜索关键词,如 'WAF绕过'、'SQL注入'、'403' tags_filter: 场景标签过滤(可选),如 ['WAF绕过'],仅返回包含全部指定标签的记录

Inputs: keyword (required), tags_filter. Returns: result

update_experienceB

更新一条经验的字段(只更新传入的字段,未传字段保持不变)。修改前自动做脱敏校验。 参数: experience_id: 经验的 id title: 新标题(可选) detail: 新详情(可选) scenario_tags: 新标签列表(可选) tool_code: 新工具代码(可选) tool_type: 新工具类型(可选) status: 新状态(可选,approved/draft/rejected/deleted)

Inputs: experience_id (required), title, detail, status, +3 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: the three list_* tools are scoped by status (all/pending/deleted), and search vs. list vs. find_similar are distinguishable. However, update_experience can also set status to approved/rejected, overlapping with the dedicated approve_experience and reject_experience tools, and the delete/reject/purge triad requires careful reading to tell apart.

    Naming Consistency5/5

    All 13 tools follow a consistent snake_case verb_noun pattern (list_*, get_*, add_*, update_*, delete_*, restore_*, approve_*, reject_*, search_experience, find_similar, purge_experiences). No convention mixing.

    Tool Count5/5

    13 tools is well-scoped for a knowledge base with CRUD, search, moderation workflow, dedup, and soft-delete lifecycle. Each tool earns its place with a distinct role.

    Completeness5/5

    Full lifecycle is covered: create/add, get, update, search, paginated listing, approval/rejection moderation, dedup checking, soft-delete, restore, and physical purge. No obvious dead ends for the stated domain.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI agents with persistent knowledge storage, enabling them to store, search, and retrieve text, documents, and files using semantic and keyword search via MCP tools.
      34
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to query and manage a document knowledge base via MCP, with RAG-powered search and grounded answers with citations.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A knowledge base MCP server that aggregates team knowledge from multiple sources into Postgres. It provides hybrid search (full-text + vector + RRF) via MCP tools, and enables direct recording of decisions, learnings, and pitfalls.
      15
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents and MCP clients to search, retrieve, and read documents across unified knowledge sources including ShowDoc, GitHub, Gitee, ZenTao, Evernote, and Tencent Docs. It also supports connecting external MCP servers as additional knowledge sources.
      MIT