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: Nümtema Private Knowledge MCP

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):

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:

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.