Journald MCP server

Análisis forense de incidentes mediante archivos de registro

GitHub
1
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Journald

Un servidor MCP para acceder a los registros del diario de systemd.

Características

  • Listar unidades de systemd desde los registros del diario
  • Listar identificadores de syslog desde los registros del diario
  • Obtener la fecha y hora de la primera entrada del diario
  • Filtrar entradas del diario por rango de fechas (desde/hasta)
  • Filtrar por unidad de systemd o identificador de syslog
  • Filtrar por contenido del mensaje (coincidencia de subcadena sin distinción de mayúsculas)
  • Análisis de fechas en lenguaje natural (p. ej., "hace 2 horas", "ayer a las 3pm")
  • Listar unidades e identificadores dentro de rangos de tiempo específicos

Instalación

# Install dependencies
uv sync

Uso

Ejecutar como no root: Dale al usuario acceso al grupo systemd-journal usermod -aG systemd-journal $USER

Ejecuta el servidor con:

uv run server.py [OPTIONS]

Opciones de CLI

  • --transport: Protocolo de transporte a utilizar (stdio, sse o streamable-http). Predeterminado: stdio
  • --port: Puerto para escuchar en el transporte HTTP (ignorado para el transporte stdio). Predeterminado: 3002
  • --log-level: Nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL). Predeterminado: INFO

Ejemplos

  1. Ejecutar con transporte stdio (predeterminado, para clientes MCP que se comunican mediante stdin/stdout):

    python server.py

  2. Ejecutar con transporte HTTP en un puerto personalizado:

    python server.py --transport streamable-http --port 8080

  3. Ejecutar con transporte SSE:

    python server.py --transport sse --port 3000

  4. Ejecutar con registro de depuración:

    python server.py --log-level DEBUG

Integración MCP

El servidor proporciona los siguientes recursos y herramientas MCP:

Recursos

  • journal://units: Listar unidades de systemd únicas desde los registros del diario (todo el tiempo accesible)
  • journal://syslog-identifiers: Listar identificadores de syslog únicos desde los registros del diario (todo el tiempo accesible)
  • journal://first-entry-datetime: Obtener la fecha y hora de la primera entrada del diario
  • journal://units/{since}/{until}: Listar unidades de systemd únicas dentro de un rango de tiempo especificado
  • journal://syslog-identifiers/{since}/{until}: Listar identificadores de syslog únicos dentro de un rango de tiempo especificado

Herramientas

  • get_journal_entries: Obtener entradas del diario con filtrado por fecha y hora

    • Parámetros: since (opcional), until (opcional), unit (opcional), identifier (opcional), message_contains (opcional), limit (predeterminado: 100)
    • Devuelve: Lista de entradas con marca de tiempo, unidad, identificador y mensaje
    • Ejemplo: Obtener registros de las últimas 2 horas que contengan "error": since="2 hours ago", message_contains="error"

  • get_recent_logs: Obtener registros recientes del diario de los últimos N minutos

    • Parámetros: minutes (predeterminado: 60), unit (opcional), limit (predeterminado: 50)
    • Devuelve: Cadena formateada de mensajes de registro recientes

Formato de entrada de fecha y hora

El servidor utiliza análisis de fechas en lenguaje natural mediante la biblioteca dateparser. Los formatos admitidos incluyen:

  • Tiempos relativos: "hace 2 horas", "ayer a las 3pm", "la semana pasada", "ahora"
  • Tiempos absolutos: "2024-01-15 14:30", "2024-01-15T14:30:00"
  • Mixtos: "hoy a las 9am", "mañana a las 3pm"

Todas las horas se interpretan como UTC y se devuelven en formato legible: "YYYY-MM-DD HH:MM:SS UTC"

Desarrollo

Este proyecto utiliza:

  • Python 3.12+
  • MCP FastMCP
  • systemd-python para acceso al diario
  • Click para la interfaz de línea de comandos
  • dateparser para análisis de fechas en lenguaje natural

Estructura del proyecto

journald-mcp-server/
├── journald_mcp_server/     # Main package
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   └── datetime_utils.py   # Datetime parsing and formatting utilities
├── tests/                  # Test suite
│   ├── __init__.py
│   └── test_server.py
├── server.py              # Entry point wrapper
├── pyproject.toml
└── README.md

Ejecutar pruebas

python -m pytest tests/