Crad-log-search: la navaja suiza de búsqueda en logs de Core-Admin

core-admin · 2026-09-01 17:23:00 UTC

Introducción

crad-log-search.pyc es la herramienta de línea de comandos de Core-Admin para buscar y analizar en el servidor. Nació como un buscador de logs de correo, pero hoy cubre bastante más terreno:

Búsqueda en logs del sistema (correo, syslog, Roundcube, MyQttHub, KandaduServer, OpenVSwitch), con seguimiento automático de la traza completa de un correo.
Informes de correo por cuenta: accesos, envíos y recepciones, con resolución GeoIP del origen.
Búsqueda dentro del buzón de una cuenta y limpieza masiva de mensajes.
Análisis de ficheros y carpetas: qué ha cambiado últimamente, qué carpeta tiene demasiados ficheros, qué ocupa más.
Análisis de logs HTTP por franja horaria, con estadísticas de tráfico.
Modo corrector (fixer): detecta problemas conocidos de entrega de correo y ofrece aplicar la corrección.

Varias funciones del panel web de Core-Admin son, por dentro, llamadas a esta herramienta. Este artículo repasa todo lo que sabe hacer y cómo se usa desde la línea de comandos.

Requisitos previos

Core-Admin instalado en el servidor, con el agente activo
Acceso root por SSH al servidor que se quiere analizar
La herramienta se invoca como crad-log-search.pyc (está en el PATH del sistema)

Sintaxis general

crad-log-search.pyc [opciones] <texto-a-buscar>

El texto a buscar se pasa como argumento posicional. La búsqueda es literal (no admite expresiones regulares) y no distingue mayúsculas de minúsculas. En los modos que analizan carpetas, el argumento posicional es la ruta en lugar del texto.

La ventana temporal: `-D` y `--startday`

Casi todos los modos trabajan sobre una ventana de días, controlada por -D (por defecto, 10 días):

crad-log-search.pyc --email -D 30 usuario@ejemplo.com

Por defecto la ventana termina hoy. Con --startday se desplaza a una fecha concreta, lo que resulta muy útil para investigar un incidente pasado:

# Busca entre el 2026-03-06 y el 2026-03-16 (ambos incluidos)
crad-log-search.pyc --email --startday 20260316 -D 10 usuario@ejemplo.com

La búsqueda incluye los logs rotados y comprimidos (.gz) que caigan dentro de la ventana.

Búsqueda en logs

Sin más opciones, la búsqueda recorre los logs de correo, syslog, messages y Roundcube. Para acotar la fuente se usa una de estas opciones:

Opción	Fuente consultada
`--email`	`/var/log/mail.log*` y logs de Roundcube
`--syslog`	`/var/log/syslog*`
`--roundcube`	`/var/log/roundcube/logs/` (`userlogins.log`, `sendmail.log`, `errors.log`)
`--kandaduserver`	`/var/log/kandaduspamfighter/kandaduspamfighter.log*`
`--myqtt`	`/var/log/myqtt/myqtt.log*` (plataforma MyQttHub)
`--crad-track`	Base de datos de seguimiento de conexiones `crad-track-mgr`, con GeoIP
`--ovs`	Volcado de las tablas de flujos de OpenVSwitch (`br-int`)

Ejemplos:

crad-log-search.pyc --email usuario@ejemplo.com
crad-log-search.pyc --syslog "out of memory"
crad-log-search.pyc --kandaduserver 203.0.113.25
crad-log-search.pyc --crad-track 203.0.113.25
crad-log-search.pyc --ovs "tcp,nw_dst=10.0.0.5"

Cada línea coincidente se numera y se colorea, precedida de la cabecera del fichero donde se encontró y del número total de coincidencias.

Traza completa de un correo (QueueId)

Ésta es la diferencia principal con un grep a mano. Cuando se busca con --email o --syslog, la herramienta detecta los identificadores de cola de Postfix (QueueId=) presentes en las líneas encontradas y relanza la búsqueda con cada uno. El resultado es la traza completa del mensaje (recepción, filtrado antispam, relay y entrega final), incluidas las líneas que no contienen el texto original buscado. Lo mismo ocurre con las referencias relay= de Postfix.

Si lo que se quiere es el comportamiento clásico de grep —sólo las líneas que coinciden literalmente—, se añade --grep:

crad-log-search.pyc --email --grep usuario@ejemplo.com

Buscar varias direcciones a la vez

Con -e la herramienta lee texto libre de la entrada estándar, extrae todas las direcciones de correo que encuentre y busca cada una. Es la forma cómoda de investigar a partir del texto pegado de un ticket:

cat ticket.txt | crad-log-search.pyc -e -D 15

Ver qué ficheros se han examinado

Por defecto sólo se muestran los logs con coincidencias. Con -x se listan todos los ficheros examinados aunque estén vacíos de resultados, lo que permite confirmar qué rango de fechas se ha cubierto realmente.

Informes de correo por cuenta

Tres opciones generan informes ya elaborados sobre una cuenta, en lugar de un volcado de líneas de log. Todas respetan la ventana -D / --startday e incluyen resolución GeoIP del origen.

Accesos a la cuenta

crad-log-search.pyc --access-mail-report usuario@ejemplo.com -D 30

Reúne las autenticaciones SMTP (Postfix), los accesos IMAP/POP3 (Dovecot) y las sesiones de Webmail (Roundcube). Es el informe de referencia para investigar un posible compromiso de la cuenta: muestra desde qué IPs y países se ha entrado y cuándo.

Correos enviados

crad-log-search.pyc --sent-mail-report usuario@ejemplo.com -D 7

Lista los mensajes enviados por la cuenta con IP de origen, usuario autenticado, remitente, destinatarios y estado de entrega. Con --details se muestra la lista completa de destinatarios de cada mensaje.

Correos recibidos

crad-log-search.pyc --received-mail-report usuario@ejemplo.com -D 7

Lista los mensajes dirigidos a la cuenta con IP de origen, remitente y estado de entrega. Los demás destinatarios del mensaje se ocultan salvo que se use --details.

Filtrar orígenes conocidos

En los tres informes, --skip-sources-from-report elimina de la salida (resumen y líneas de log) las IPs o nombres de máquina que se sabe que son legítimos, para quedarse sólo con lo sospechoso:

crad-log-search.pyc --access-mail-report usuario@ejemplo.com --skip-sources-from-report=127.0.0.1,localhost,203.0.113.10

Los informes de envío son los que utiliza el módulo Mail Ticket Limits para generar sus informes periódicos por correo.

Búsqueda y limpieza dentro del buzón

La opción --mbox busca dentro de los mensajes almacenados en el buzón Dovecot de una cuenta, y sobre ella se apoyan el rescate de falsos positivos (--move-to-inbox) y el borrado masivo (--remove-selected / --confirm-remove-selected):

crad-log-search.pyc --mbox usuario@ejemplo.com -D 30 "factura"
crad-log-search.pyc --mbox usuario@ejemplo.com -D 30 --remove-selected "MAILER-DAEMON"

Este bloque tiene artículo propio, con el detalle de la simulación previa al borrado y las salvaguardas: «Buscar y borrar correos dentro del buzón de una cuenta con crad-log-search».

Análisis de ficheros y carpetas

Cuatro modos no buscan texto, sino que analizan el contenido de una carpeta. En todos ellos el argumento posicional es la ruta (si se omite, la carpeta actual).

Qué ha cambiado últimamente

crad-log-search.pyc --changes -D 30 /var/www

Lista los ficheros modificados dentro de la ventana de días, del más reciente al más antiguo. Es la vía rápida para ver qué se ha tocado tras una actualización o durante un compromiso de seguridad. La exploración usa find -xdev, así que no cruza a otros sistemas de ficheros: si se omite alguna carpeta por estar montada aparte, la herramienta lo avisa.

Qué carpeta tiene demasiados ficheros

crad-log-search.pyc --list-count /var/www/html

Cuenta ficheros y directorios dentro de cada subcarpeta inmediata y ordena de mayor a menor. Sirve para localizar carpetas desbordadas que provocan problemas de rendimiento, agotamiento de inodos o de cuota.

Qué carpeta tiene más código

crad-log-search.pyc --count-lines-by-folder /var/www/html/wp-content/plugins

Cuenta las líneas de todos los ficheros de cada subcarpeta inmediata, ordenadas de mayor a menor. Útil para comparar el tamaño real de los plugins de un WordPress.

Contenido en orden cronológico

crad-log-search.pyc --list-by-date /var/spool/dovecot/mail/ejemplo.com/usuario

Lista todo el contenido de la carpeta recursivamente, del más antiguo al más reciente, mostrando fecha, tipo (f fichero, d directorio, l enlace), tamaño y ruta. A diferencia de --changes, no aplica el filtro de días y ordena al revés.

Franja horaria y estadísticas HTTP

--range extrae de un fichero de log las líneas comprendidas en una franja horaria y las devuelve ordenadas cronológicamente, aunque el fichero original esté desordenado. Reconoce los formatos de fecha de Apache, ISO 8601 (syslog-ng) y syslog tradicional, y admite ficheros planos o .gz:

crad-log-search.pyc --range 17:04-17:12 /var/webs/sitio.com/logs/access.log
crad-log-search.pyc --range 00:00-23:59 /var/log/syslog

Sobre logs en formato Apache Combined, --http-stats añade un bloque de estadísticas: distribución de códigos de estado, IPs con país, URLs más solicitadas, métodos, clasificación de agentes (bots frente a humanos), ancho de banda, peticiones por minuto y referers.

crad-log-search.pyc --range 03:00-04:00 --http-stats /var/webs/sitio.com/logs/access.log

Cuando el log es muy largo, --stats-first imprime primero el análisis y después las líneas, para no tener que subir por el terminal:

crad-log-search.pyc --range 00:00-23:59 --http-stats --stats-first /var/webs/sitio.com/logs/access.log

Esta funcionalidad es la que se ofrece desde el botón Access logs and stats del módulo Webhosting Management.

Modo corrector (fixer)

Además de mostrar los problemas, la herramienta sabe corregir una serie de causas conocidas de correo rechazado o marcado como spam.

# Detecta y pregunta antes de aplicar cada corrección
crad-log-search.pyc --email --fix usuario@ejemplo.com

# Detecta y aplica sin preguntar
crad-log-search.pyc --email --fix -y usuario@ejemplo.com

# Sólo informa de lo que se podría corregir (no cambia nada)
crad-log-search.pyc --email --fixable usuario@ejemplo.com

# Igual que el anterior, en JSON para consumo programático
crad-log-search.pyc --email --fixable --json usuario@ejemplo.com

Para cada caso detectado se muestra el problema, la acción propuesta y el resultado, en español o inglés según el idioma del sistema. El informe distingue las correcciones pendientes de las que ya estaban aplicadas.

Correcciones cubiertas actualmente:

Familia	Situación detectada
SPF SoftFail / Fail / None	El mensaje se clasifica como spam porque el SPF del remitente falla, falla de forma estricta o no existe
SPF Perm Error	La comprobación SPF da error permanente (por ejemplo, se supera el límite de consultas DNS del registro del remitente)
DMARC Fail	El mensaje se rechaza por fallo de alineación DMARC aun pasando el SPF
Kandadu: greylisting (GLD y tarpit)	Aplazamiento aplicado por política de plataforma
Kandadu: dominio bloqueado	Rechazo porque el dominio remitente está bloqueado
Kandadu: reject-url	Rechazo por una URL presente en el cuerpo del mensaje
Kandadu: sin DNS inverso	Rechazo por falta de DNS inverso en la conexión SMTP de origen
Kandadu: frase puntuada	Una o varias frases del mensaje puntúan o rechazan por contenido
ContentFilter: extensión	Adjunto rechazado por extensión de fichero en lista negra
ContentFilter: expresión	Adjunto rechazado por una expresión presente en el nombre del fichero
Error MIME	El mensaje no se pudo analizar por un problema de formato MIME

La detección de estos patrones está cubierta por una suite de pruebas de regresión incluida en la propia herramienta, que se ejecuta sin tocar ningún log ni aplicar cambio alguno:

crad-log-search.pyc --run-reg-tests

Resumen de opciones

Opción	Descripción
`-D <días>`, `--days-back`	Ventana de búsqueda en días (10 por defecto)
`--startday YYYYMMDD`	Fecha final de la ventana (hoy por defecto)
`--email`, `--syslog`, `--roundcube`, `--kandaduserver`, `--myqtt`, `--crad-track`, `--ovs`	Acotan la fuente consultada
`-e`	Extrae las direcciones de correo de la entrada estándar y busca cada una
`--grep`	Desactiva el seguimiento automático de QueueId y relay
`-x`	Muestra también los logs examinados sin coincidencias
`--access-mail-report`, `--sent-mail-report`, `--received-mail-report`	Informes por cuenta de accesos, envíos y recepciones
`--details`	Amplía el detalle de los informes (destinatarios completos)
`--skip-sources-from-report`	Excluye IPs o máquinas conocidas de los informes
`--mbox <cuenta>`	Busca dentro del buzón Dovecot de la cuenta
`--remove-selected` / `--confirm-remove-selected`	Simulación y borrado masivo de los mensajes encontrados
`--move-to-inbox <ruta>`	Devuelve un mensaje a la bandeja de entrada de su cuenta
`--changes`, `--list-count`, `--count-lines-by-folder`, `--list-by-date`	Análisis de ficheros y carpetas
`--range HH:MM-HH:MM`	Extrae y ordena una franja horaria de un log
`--http-stats`, `--stats-first`	Estadísticas HTTP sobre logs Apache Combined
`--fix`, `-y`, `--fixable`, `--json`	Modo corrector: aplicar, aplicar sin preguntar, sólo informar, informar en JSON
`--run-reg-tests`	Ejecuta la suite de pruebas interna y termina
`-v`, `-d`	Salida detallada y modo depuración

Detalles técnicos

Logs rotados: la búsqueda se hace con zgrep, por lo que los ficheros .gz se examinan igual que los planos, sin descomprimirlos a mano.
Ficheros temporales: los modos que necesitan un paso intermedio (buzones, cambios en ficheros, volcados de OpenVSwitch…) generan un fichero temporal en /var/log/core-admin-*.log que se elimina al terminar.
Colores: la salida va coloreada para leerla cómodamente en el terminal. Cuando el resultado se incorpora a un informe del panel web, las secuencias de color se eliminan antes de mostrarlo.
Idioma: los informes y el modo corrector se muestran en español o en inglés según la configuración del sistema.
Uso desde el panel web: varias funciones del panel se apoyan en esta herramienta —el botón Access logs and stats (--range --http-stats --stats-first), el informe de cambios de ficheros de un alojamiento (--changes) y los informes periódicos de Mail Ticket Limits (--sent-mail-report)—, de modo que lo que se ve en el panel se puede reproducir y afinar por línea de comandos.

Preguntas frecuentes

¿Por qué aparecen líneas que no contienen el texto que he buscado?
Es el seguimiento automático de QueueId: al encontrar el identificador de cola de un mensaje, la herramienta trae el resto de su traza para que se vea el ciclo completo. Con --grep se desactiva.

He buscado y no encuentro nada, pero sé que el correo existe.
Lo más probable es que quede fuera de la ventana temporal. Amplía con -D 30 (o lo que haga falta) y, si el caso es antiguo, sitúa la ventana con --startday. Con -x se confirma qué ficheros se han examinado realmente.

¿Puedo usar expresiones regulares?
No: la búsqueda es de texto literal. Para casos que requieran patrones, lo habitual es buscar una parte literal característica y afinar después.

¿Modifica algo la herramienta?
Sólo en tres casos, todos explícitos: el modo corrector (--fix), el traslado de un mensaje al INBOX (--move-to-inbox) y el borrado de mensajes del buzón (--confirm-remove-selected). El resto de opciones son de sólo lectura.

¿Cómo compruebo qué correcciones se podrían aplicar sin tocar nada?
Con --fixable, que ejecuta la misma detección que --fix pero se limita a informar, indicando además cuáles estaban ya aplicadas.