forensic-mcp

Servidor MCP (Model Context Protocol) de solo lectura para el triaje forense de imágenes de disco Windows, desarrollado como Trabajo Final de Máster en el Máster Universitario en Ciberseguridad y Privacidad de la Universitat Oberta de Catalunya (UOC).

Qué lo distingue

Impone un contrato de seguridad verificable en código sobre la evidencia y adjunta un bloque de procedencia de seis campos a cada hallazgo devuelto al agente.

Related MCP server: sift-mcp

Estado actual

Versión actual: v0.1.0.

• Implementado: servidor MCP sobre transporte stdio, modelo central de procedencia (Provenance), guardián de lectura exclusiva (open_evidence_readonly), registro de auditoría JSONL append-only, suite de verificación del contrato de seguridad y la primera herramienta funcional (hash_evidence_file para cálculo y verificación de hashes MD5 y SHA-256).

• No existe todavía en esta versión: las otras cuatro herramientas forenses previstas (extracción de metadatos, generación y consulta de líneas temporales, parsing de registros y ejecución de scripts preaprobados), el adaptador de The Sleuth Kit para ficheros internos de una imagen, la integración con el agente de IA, la interfaz web de revisión y el empaquetado en Docker.

Requisitos

• Python 3.11 o superior.

• Linux o WSL2 (Ubuntu).

Windows nativo no se soporta en esta fase porque la verificación de hashes contra la utilidad estándar del sistema (sha256sum) y las futuras herramientas forenses de línea de comandos (The Sleuth Kit) dependen de un entorno POSIX.

Evidencias forenses

Las imágenes forenses no forman parte del repositorio ni deben almacenarse dentro de él. Se mantienen en un directorio externo indicado mediante la variable de entorno FORENSIC_MCP_EVIDENCE_ROOT, y el servidor confina todos los accesos a esa raíz rechazando cualquier ruta externa.

Ejemplo de configuración antes de arrancar el servidor:

export FORENSIC_MCP_EVIDENCE_ROOT=/ruta/a/evidence
forensic-mcp

En el caso de estudio utilizado en el TFM, las evidencias corresponden a los segmentos SCHARDT.001 a SCHARDT.005 del NIST CFReDS Hacking Case, mantenidos fuera del repositorio.

Instalación

1. Crear el entorno virtual en la raíz del proyecto:

python3 -m venv .venv

2. Activar el entorno virtual:

source .venv/bin/activate

3. Instalar el paquete y las dependencias de desarrollo:

pip install -e ".[dev]"

Uso

Arrancar el servidor MCP en transporte stdio:

forensic-mcp

Variables de entorno opcionales: FORENSIC_MCP_AUDIT_LOG (ruta del fichero JSONL de auditoría, por defecto audit/audit.jsonl) y FORENSIC_MCP_EVIDENCE_ROOT (directorio raíz permitido para las evidencias).

Ejecutar la suite de pruebas:

pytest -v

Estructura del repositorio

• pyproject.toml: definición del paquete, dependencias y punto de entrada forensic-mcp.

• LICENSE: licencia MIT del proyecto.

• README.md: documentación principal del repositorio.

• CHANGELOG.md: historial de cambios y elementos pendientes por versión.

• docs/adr/: registros de decisiones de arquitectura (ADR).

• src/forensic_mcp/models.py: modelos Pydantic de procedencia (Provenance), resultado de hashes (HashResult) y errores estructurados (StructuredError).

• src/forensic_mcp/evidence.py: guardián de acceso de solo lectura (open_evidence_readonly) y confinamiento de rutas (resolve_evidence_path).

• src/forensic_mcp/audit.py: registrador de auditoría JSONL append-only aislado del directorio de evidencias.

• src/forensic_mcp/tools/hashing.py: implementación de cálculo y verificación de hashes MD5 y SHA-256 en modo lectura.

• src/forensic_mcp/server.py: servidor MCPServer sobre stdio, exposición de hash_evidence_file y captura controlada de errores.

• tests/: fixtures sintéticas y pruebas automatizadas de hashing y del contrato de seguridad.

Contrato de seguridad

• Solo lectura verificable: las evidencias se abren exclusivamente mediante os.O_RDONLY en modo 'rb'; cualquier intento de apertura en modo de escritura falla de forma explícita.

• Operación sin red en tiempo de ejecución: el transporte stdio no abre sockets durante el análisis, verificado mediante prueba automatizada que intercepta socket.socket.

• Sin construcción de comandos de shell: no se concatenan cadenas para invocar intérpretes ni binarios externos.

• Errores estructurados y auditoría completa: toda llamada genera un rpc_call_id único registrado en audit.jsonl (solo metadatos, nunca contenido de ficheros) y los errores se devuelven como JSON estructurado sin stack traces.

Licencia y citación

El código de este repositorio se distribuye bajo licencia MIT; consúltese el fichero LICENSE.

Para citar este trabajo en contexto académico, remítase a la memoria del Trabajo Final de Máster: MCP Server para la Automatización de Análisis Forense asistido por IA mediante agentes agénticos, Paulo Ricardo de Oliveira, Máster Universitario en Ciberseguridad y Privacidad, Universitat Oberta de Catalunya (UOC), 2026–2027.

La memoria del Trabajo Final de Máster se distribuye bajo la licencia Creative Commons Reconocimiento-NoComercial-CompartirIgual 3.0 España, conforme a la plantilla de la Universitat Oberta de Catalunya.