reptor-mcp: Un servidor MCP para Reptor/SysReptor

Este proyecto transforma la herramienta CLI reptor en un servidor MCP (Model-Context-Protocol), exponiendo sus potentes funciones de automatización y generación de informes de pentest como un servicio programable.

Permite que otras herramientas, scripts o agentes de IA interactúen programáticamente con SysReptor a través del protocolo MCP, facilitando la integración en flujos de trabajo automatizados.

WARNING

Software Alpha: La herramienta CLI subyacente reptor está en fase alpha. Su API puede cambiar, lo que podría romper reptor-mcp.

CAUTION

Sin autenticación: Este servidor no tiene autenticación ni autorización. Está diseñado solo para uso local. NO LO EXPONGAS A INTERNET NI A REDES NO CONFIABLES.

IMPORTANT

Sensibilidad de los datos: Si manejas datos de proyectos confidenciales, considera las implicaciones de enviarlos a LLMs a través de este servidor. Usa REPTOR_MCP_EXCLUDE_FIELDS para eliminar campos sensibles antes de que lleguen al LLM.

Características

Generación dinámica de herramientas: Crea automáticamente herramientas MCP a partir de todos los plugins de reptor disponibles (nmap, nessus, burp, zap, sslyze, etc.).
Herramientas de API directa: Proporciona herramientas estructuradas para CRUD de hallazgos, descubrimiento de esquemas y gestión de plantillas utilizando directamente la API de Python de reptor.
Exclusión de campos: Elimina campos sensibles de los datos antes de devolverlos a los clientes LLM (configurable mediante variable de entorno).
Seguro para asincronía: Bucle de eventos sin bloqueo con ejecución de plugins serializada y segura para hilos.

Requisitos previos

Python 3.10+
uv (recomendado) o pip
Una instancia de SysReptor en ejecución con un token de API

Instalación

git clone https://github.com/slvnlrt/reptor-mcp.git
cd reptor-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

Esto instala reptor y fastmcp automáticamente desde PyPI. No es necesario clonar el repositorio de reptor por separado.

Si necesitas trabajar con una copia local de reptor (por ejemplo, para probar cambios no publicados):

uv pip install -e /path/to/reptor-source
uv pip install -e .

Alternativamente, establece REPTOR_MAIN_PATH=/path/to/reptor-source en tiempo de ejecución para inyectarlo en sys.path.

Configuración

El servidor se configura mediante variables de entorno:

Variable	Requerido	Descripción
`REPTOR_SERVER`	Sí	URL de tu instancia de SysReptor
`REPTOR_TOKEN`	Sí	Tu token de API de SysReptor
`REPTOR_PROJECT_ID`	No	ID de proyecto predeterminado para operaciones
`REPTOR_MCP_INSECURE`	No	Establecer en `true` para deshabilitar la verificación SSL
`REQUESTS_CA_BUNDLE`	No	Ruta a un archivo de paquete CA personalizado
`REPTOR_MCP_EXCLUDE_FIELDS`	No	Nombres de campos separados por comas para eliminar de las respuestas del LLM (ej. `internal_notes,api_token`)
`REPTOR_MCP_DEBUG`	No	Establecer en `true` para registro de depuración detallado

Ejecución del servidor

fastmcp run mcp_server.py:mcp --transport streamable-http --port 8008

El servidor será accesible en http://localhost:8008/mcp/.

Conexión del cliente

Conecta un cliente MCP usando una configuración como esta (por ejemplo, en mcp_settings.json):

{
  "mcpServers": {
    "reptor-mcp": {
      "type": "streamable-http",
      "url": "http://localhost:8008/mcp/"
    }
  }
}

Herramientas disponibles

Herramientas personalizadas (API directa)

Estas herramientas utilizan la API de Python de reptor directamente para operaciones estructuradas y conscientes del esquema:

Herramienta	Descripción
`list_findings`	Lista hallazgos con filtros (estado, severidad, título).
`get_finding_details`	Obtiene todos los detalles de un hallazgo por ID.
`get_finding_schema`	Descubre los campos, tipos y restricciones de hallazgos disponibles para un proyecto. Llama antes de `create_finding` o `patch_finding`.
`create_finding`	Crea un nuevo hallazgo a partir de un diccionario de datos plano.
`patch_finding`	Actualiza un solo campo en un hallazgo.
`delete_finding`	Elimina un hallazgo por ID (requiere confirmación explícita).
`upload_template`	Sube una plantilla de hallazgo desde JSON o TOML.

Herramientas de plugin (Envoltorios dinámicos)

El servidor envuelve dinámicamente todos los plugins de la CLI de reptor como herramientas MCP:

Categoría	Herramientas
Importadores de vulnerabilidades	`nessus`, `burp`, `nmap`, `openvas`, `zap`, `qualys`, `sslyze`
Gestión de hallazgos	`finding`, `findingfromtemplate`, `deletefindings`, `exportfindings`
Gestión de proyectos	`project`, `createproject`, `deleteprojects`, `pushproject`
Plantillas	`template`
Notas y archivos	`note`, `file`
Traducción	`translate` (vía DeepL)
Importar/Exportar	`ghostwriter`, `defectdojo`, `importers`, `packarchive`, `unpackarchive`

Los argumentos exactos para cada herramienta pueden inspeccionarse a través de un cliente MCP conectado.

Relación con el servidor MCP nativo de reptor

Desde reptor v0.33, reptor incluye su propio servidor MCP integrado (reptor mcp). Los dos servidores son complementarios:

Capacidad	reptor-mcp	`reptor mcp` nativo
CRUD de hallazgos	:white_check_mark:	:white_check_mark:
Descubrimiento de esquema de hallazgos	:white_check_mark:	:white_check_mark:
CRUD de secciones de informe	:x:	:white_check_mark:
Importadores de vulnerabilidades (nmap, nessus, burp, etc.)	:white_check_mark:	:x:
Gestión de proyectos (buscar, crear, exportar, duplicar)	:white_check_mark:	:x:
Notas, archivos, traducción	:white_check_mark:	:x:
Gestión de plantillas	:white_check_mark:	:white_check_mark:
Exclusión de campos	:white_check_mark:	:white_check_mark:

Arquitectura

mcp_server.py           # Server entry point, lifespan, configuration
├── tool_generator.py   # Dynamic MCP tool generation from plugin argparse definitions
│   ├── signature_utils.py  # argparse → Python function signature translation
│   └── wrapper_utils.py    # Plugin execution, stdin/stdout capture, config handling
├── custom_tools.py     # Direct API tools (findings CRUD, schema, templates)
└── tool_config.py      # Plugin exclusions, stdin consumers, config overwrite mappings

Decisiones clave de diseño:

Los envoltorios de plugins se ejecutan en hilos con un bloqueo de serialización, manteniendo el bucle de eventos asíncrono receptivo mientras se protege el estado compartido.
Las herramientas personalizadas utilizan asyncio.to_thread() para llamadas a la API sin bloqueo.
La exclusión de campos elimina recursivamente los campos especificados de todas las estructuras de datos anidadas antes de devolverlos al cliente.

Licencia

Este proyecto está bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

Este proyecto no sería posible sin la herramienta CLI original de reptor desarrollada por el equipo de SysReptor y sus colaboradores. reptor-mcp se basa en su excelente trabajo para proporcionar una interfaz MCP.

reptor-mcp