pentest-kb
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_filterpermite 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. Constatus='draft'se guarda como borrador pendiente de aprobación (por defecto); constatus='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 proporcionamerge_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 comorejectedy se puede recuperar).delete_experience(experience_id): borrado lógico de una experiencia aprobada (el estado pasa adeleted, 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_experienceadmitestatus='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 borradoresdrafty 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 dominiopentest_dict.txtde 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.txtLa 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.sqlLa 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 |
| uuid PK | Clave primaria, por defecto |
| timestamptz | Fecha de creación |
| text | Título de la experiencia |
| jsonb | Matriz de etiquetas de escenario, p. ej., |
| text | Detalle de la experiencia |
| text | Código de explotación/herramienta |
| text | Tipo de herramienta, p. ej., sqlmap, burp |
| text |
|
| timestamptz | Fecha del borrado lógico (se registra al pasar a |
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.sqly 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 |
| Dirección del host de la base de datos |
| Puerto (por defecto 5432) |
| Nombre de la base de datos (por defecto postgres) |
| Usuario de la base de datos |
| Contraseña de la base de datos |
| 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 toolsadd_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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Search and manage your team's knowledge from MCP clients.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
A shared team wiki your coding agents read and write — across every repo and every MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides 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.34Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to query and manage a document knowledge base via MCP, with RAG-powered search and grounded answers with citations.MIT
- AlicenseAqualityDmaintenanceA 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.151MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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