Funcionamiento del agente para Linux
Los comandos y sus códigos de salida, qué hacen las tres unidades de systemd, cómo encajan status y doctor en la monitorización, test en lugar de fail2ban-regex, y la tabla de resolución de problemas: síntoma, causa, comando.
Comandos
| Comando | Efecto | Salida |
|---|---|---|
REPORTEDIP_KEY=K install [--accept-terms] [--admin-ip IP|CIDR] [--ssh-port N] [--mode log|drop] [--ban|--no-ban] [--notify-email A] [--log-level L] [--expert] | Detecta los servicios, escribe la configuración, la lista blanca automática y el identificador de instalación, instala y activa las unidades y verifica la clave. La clave viene del entorno; --key sigue funcionando y avisa de que su valor está en la lista de procesos. Nunca sobrescribe una configuración existente. Solo como root. --expert pregunta además por la escala de bloqueos, los umbrales, los límites y un servidor SMTP. | 0, 2 si la clave se rechaza antes de escribir nada o si hay un problema de configuración, 1 si falla la comprobación de la clave tras la instalación |
sync | Una pasada del feed: reconstruir el conjunto de la lista blanca, descargar cada lista de forma condicional, intercambiar lo que ha pasado la comprobación de tamaño, reconstruir la cadena, restaurar los bloqueos locales que falten, hacer la limpieza, buscar una actualización cada seis horas. Es lo que ejecuta el temporizador, y lo que se ejecuta al arrancar. | 0, 1 degradado, también 0 si otra sincronización tiene el lock |
watch | El demonio. Sigue cada fuente, cuenta, notifica y bloquea si eso está activado. Termina con SIGTERM. | 1 si el lock de la cola sigue retenido tras un minuto o si el demonio termina por un error, 2 si hay un problema de configuración |
report-queue | Envía una vez los informes en espera. Útil tras una caída de la API, o en un host donde el demonio no se ejecuta. | 0, 1 degradado |
status | Versión, backend, modo, herramientas, cantidad y último éxito por lista, lista blanca, comprobación de la cadena, posiciones de lectura y coincidencias por fuente, cola y emisor, cuenta y licencia, el grupo de esta clave, la reputación de la dirección desde la que este host notifica, disco, bloqueos locales, condiciones de salud abiertas. | 0 sano, 1 degradado, 2 configuración |
doctor | Lo que ofrece el host y lo que falta, incluido un registro que este host escribe y que ninguna fuente lee. No cambia nada, funciona sin configuración. | 0, 1 con limitaciones, 2 si no puede ejecutarse |
test <file>... [--type T] [--rule ID] [--lines] | Hace pasar los detectores por archivos de registro reales. No notifica nada, no bloquea nada, no escribe nada. --rule ejecuta una sola regla de un archivo de reglas. | 0, 2 si hay un problema de archivo o de tipo |
ban list | add <ip> [minutes] | rm <ip> | Muestra los bloqueos locales frente a lo que el núcleo tiene realmente, pone uno a mano, levanta uno. | 0, 1 si falla el núcleo, 2 si un argumento es erróneo o mientras una sincronización retiene el lock; add también con una dirección de la lista blanca o cuando el host no tiene backend de cortafuegos |
unban <ip> | Lo mismo que ban rm, bajo la palabra que teclea un operador cuando hay un incendio. | como arriba |
whitelist add <ip|cidr> [comment] | list | rm <ip|cidr> [--auto] | Gestiona la lista de «nunca bloquear, nunca notificar». add escribe el archivo y el conjunto del núcleo de una vez. list muestra tu archivo, la lista blanca automática y la lista blanca de tu grupo, esta última en líneas marcadas con group: con sus notas. --auto retira una entrada escrita por el instalador. | 0, 1 si el archivo cambió y el conjunto no, 2 si la dirección es errónea o mientras una sincronización retiene el lock |
update [--check] | Comprueba el punto de distribución, sustituye este binario y después reinicia el servicio watch. --check solo informa. Es el único comando que lee la configuración de forma laxa, así que funciona también en un host cuya configuración es más reciente que su binario. | 0, 1 si la comprobación o la instalación falló, 2 si la configuración no se puede leer o el directorio de estado no se puede crear |
housekeeping | Retira los restos propios del agente y muestra las cifras. La sincronización hace lo mismo en silencio. | 0, 2 si hay un problema de configuración o de estado |
rules list | show <id> | check [file...] | export <id> | status | enable <id> | disable <id> | Las reglas de detección: las incluidas y los archivos en /etc/reportedip-agent/rules.d que las anulan o las amplían. check prueba un archivo antes de ponerlo en marcha, export muestra una regla como punto de partida, status añade los aciertos y qué reglas son jóvenes, enable y disable activan o desactivan una regla. | 0, 1 si se omitió un archivo o no se usan las reglas del operador, 2 si un argumento es erróneo o si check encuentra un problema |
version | Muestra la versión y nada más. | 0 |
help | La lista de comandos, con las rutas de configuración y de estado. | 0 |
test, en lugar de fail2ban-regex
test hace pasar la cadena de detectores por un archivo de registro que ya tienes, con los
umbrales y la lista blanca de este host, y muestra qué direcciones habrían superado un umbral y en qué
punto del archivo. No notifica nada, no bloquea nada y no escribe nada, así que es seguro en un host
de producción y es la respuesta honesta a la pregunta de si esto habría cazado el ataque de la semana
pasada.
# A configured source: the type is taken from the config
reportedip-agent test /var/log/auth.log
# Any other file: name the type yourself
reportedip-agent test --type postfix /var/log/mail.log.1
# A rotated log and its successor as one stream, in this order,
# so a window that spans the rotation counts like the daemon saw it.
# A .gz is read inflated.
reportedip-agent test /var/log/mail.log.2.gz /var/log/mail.log.1 /var/log/mail.log
# Every single hit, with line number, address and timestamp
reportedip-agent test --lines /var/log/auth.logLa línea de resumen indica las líneas leídas, cuántas coincidieron, cuántas no llevaban una marca de tiempo utilizable y cuántas se omitieron por ser demasiado largas. Después, una fila por dirección con sus coincidencias, sus reinicios, si habría sido bloqueada y cuántas veces, la hora de la primera coincidencia y el umbral aplicado. Una dirección que esté en tu lista blanca se muestra con la capa que respondió y marcada como nunca bloqueada y nunca notificada, lo que hace de este comando la vía más rápida para demostrar que una entrada de la lista blanca funciona de verdad.
Dos cosas que test no hace. No adivina ningún formato: sin --type el archivo
tiene que ser una de las rutas de fuente configuradas, y, si no, lo dice y enumera los tipos válidos. Y
no aplica la ponderación del historial de bloqueos, así que el demonio necesita menos coincidencias
para una dirección con bloqueos anteriores de las que sugiere esta relectura.
Funcionamiento
Tres unidades de systemd, escritas y activadas por install y puestas al nivel de la
versión en curso por cada sincronización. Pon tus propios cambios en un drop-in bajo
/etc/systemd/system/<unit>.d/, donde sobreviven a una actualización. Una unidad que
hayas editado directamente se reemplaza, la versión anterior queda al lado como
<unit>.bak, y el journal nombra las dos.
| Unidad | Cuándo se ejecuta | Detalles |
|---|---|---|
reportedip-agent-sync.timer | Cada 15 minutos, más un retardo aleatorio fijo de hasta 2 minutos | Tiene que dispararse al ritmo más rápido que pueda pedir cualquier licencia, porque es lo único que lanza una sincronización. Cuántas de esas ejecuciones descargan de verdad lo decide la licencia, y una ejecución que llega demasiado pronto para su plan no descarga nada. |
reportedip-agent-sync.service | Al arrancar y en cada tic del temporizador | Activado para multi-user.target, después de network-online.target y después de cada servicio de cortafuegos, sin retardo aleatorio. Una pasada de sincronización: el conjunto de la lista blanca, las seis listas, la cadena, la restauración de los bloqueos locales que falten, el mantenimiento, y una comprobación de actualización cada seis horas. |
reportedip-agent.service | De forma continua | El demonio watch. Se reinicia tras un fallo a los diez segundos, como máximo cinco veces en cinco minutos, y nunca con el código 2, así que un host mal configurado se detiene con un motivo legible en vez de reintentarse para siempre. |
Los dos servicios corren con NoNewPrivileges, ProtectHome,
PrivateTmp, una personalidad bloqueada y un conjunto restringido de familias de
direcciones.
| Qué funciona por sí solo | Con qué frecuencia | Qué hace |
|---|---|---|
| Rotación del registro | En cada escritura | El agente rota log_file al llegar a log_max_mb y conserva log_keep generaciones. No depende de logrotate. Cada línea va también a stderr y, con ello, al journal de la unidad. |
housekeeping | En cada sincronización | Archivos de cola antiguos, entradas de deduplicación caducadas, posiciones de lectura obsoletas, archivos temporales y de lock sobrantes, entradas caducadas del almacén de bloqueos, generaciones sobrantes del propio registro del agente, archivos del espejo de las reglas incluidas que el binario ya no trae, y el binario anterior en cuanto cumple un mes. Ejecutado a mano muestra las cifras. |
| Autoactualización | Cada seis horas | Una versión nueva se verifica contra una firma Ed25519 con la clave pública compilada en el binario antes de instalarse, así que una descarga manipulada falla en tu máquina en vez de resultar de fiar por haber llegado por HTTPS. Si el cambio falla, el binario en ejecución vuelve a su sitio, de modo que una actualización fallida deja al host en la versión que tenía. |
| Correo de estado | Por condición, con notify.cooldown_hours | Un correo cuando algo va mal, otro cuando se arregla. Desde Professional puede salir por el relé de reportedip.com. |
| El suelo de disco | En cada escritura en la cola | Por debajo de disk_min_mb el agente no encola informes nuevos y lo dice, mientras la detección y el bloqueo siguen. |
systemctl list-timers reportedip-agent-sync.timer
systemctl status reportedip-agent.service --no-pager
journalctl -u reportedip-agent.service -n 50 --no-pager
journalctl -u reportedip-agent-sync.service -n 50 --no-pager
tail -n 100 /var/log/reportedip-agent.logCódigos de salida
| Código | Significado | Qué hacer |
|---|---|---|
0 | Sano | Nada. |
1 | Degradado, pero volverá a intentarlo | Leer la salida. Un nuevo intento puede arreglarlo perfectamente. Una condición de error abierta en el registro de salud tiñe el código de salida incluso si la ejecución en sí salió bien, porque un código 0 junto a un error anotado no es una señal para una monitorización. En status, un demonio watch detenido es uno de esos motivos. |
2 | No repetible sin una persona | La configuración, los permisos de archivo, una herramienta ausente, un lock retenido por otro proceso. Ejecutar doctor. systemd no reinicia el servicio watch con un 2. |
Con eso, reportedip-agent status se puede usar directamente como comprobación de
monitorización, sin script envoltorio y sin analizar la salida. status --json imprime el
mismo resultado como documento JSON; la configuración para Zabbix, Nagios, Icinga, Checkmk y
Prometheus está en Monitorización.
La reputación de la propia dirección de este host
La sincronización pregunta al servidor, al menos una vez al día y en cada pasada mientras la condición de abajo esté abierta, qué opina de la dirección desde la que este host notifica.
Si esa dirección está ella misma listada en la base de datos comunitaria,
status avisa y termina con código 1. Con una confianza de 75 o más queda abierta además la condición de salud reputation, con la confianza, el número de informes y el
enlace a la página de retirada en su texto. Es un aviso y no un error, porque una
dirección listada dice algo de la red en la que está el host y no necesariamente del host: una
dirección compartida, un NAT de operador o un vecino tras el mismo proxy pueden ponerla ahí. Aun
así merece un vistazo, porque un host que notifica desde una dirección listada es, visto desde
fuera, lo que parece un host comprometido. Comprueba qué sale de la máquina, solicita la retirada
cuando esté limpia, y la condición desaparece con la siguiente sincronización tras la retirada; en el
host no hay nada que restablecer. Por debajo de 75 no se abre ninguna condición de salud: un puñado de informes
antiguos son datos honestos y no algo sobre lo que un operador pueda actuar, y ningún feed sirve una
dirección con esa puntuación.
Resolución de problemas
Un síntoma, una causa probable, un comando. reportedip-agent doctor y
reportedip-agent status responden entre los dos a la mayoría de estos casos, y son las
dos cosas que el soporte pide primero.
| Síntoma | Causa | Comando |
|---|---|---|
| No arranca y nombra su archivo de configuración | El archivo es legible por el grupo o por otros, y contiene tu clave API. | chmod 0600 /etc/reportedip-agent/config.yaml && chown root:root /etc/reportedip-agent/config.yaml |
| Código 2 con «field ... not found in type» | Una clave desconocida en la configuración. El analizador es estricto a propósito. | Retirar o corregir la clave que nombra el mensaje. La lista de claves válidas está más arriba. |
| Cada comando termina con código 2 tras una vuelta atrás | El binario es más antiguo que la configuración y no puede leer un bloque más reciente. | reportedip-agent update, el único comando que lee el archivo de forma laxa y nombra las claves que no conoce. |
Un binario más antiguo termina con código 2 con una configuración que lleva notify.relay | Esa clave es más nueva que el binario. La misma clase de trampa que la fila de arriba, y ya ha dejado hosts sin protección dos veces. | Quitar la línea relay: del bloque notify, o avanzar en vez de retroceder: reportedip-agent update. |
| Los conjuntos existen pero están vacíos | O el feed se rechazó, o la lista falló en la comprobación de tamaño. | reportedip-agent status dice cuál de las dos, y la línea de la lista lleva el último error. |
status indica unlicensed | La cuenta no tiene ninguna licencia libre para este host. | Añadir una en Agent Servers. La lista del núcleo sigue trabajando mientras tanto. |
| Nunca se notifica nada | La fuente que habría reaccionado no se detectó nunca, o no se alcanza su umbral. | reportedip-agent test /path/to/log, luego reportedip-agent status y leer la sección sources. |
| Nunca se bloquea nada, aunque salen informes | ban.enabled se puso en false, o mode en log (de fábrica, los dos bloquean). Dos interruptores. | reportedip-agent ban list dice cuál de los dos en sus últimas líneas. |
| Ningún estado de fuente en absoluto | El demonio watch no se ha ejecutado nunca. | systemctl enable --now reportedip-agent.service |
Una fuente muestra files=0 | La ruta o el patrón no se resuelve en nada en este host. | reportedip-agent doctor nombra la fuente y el patrón que intentó. |
| Un servicio instalado después del agente no notifica nada | La detección se ejecuta una sola vez, en la instalación, y eso es a propósito: un servicio detenido por mantenimiento nunca debe desactivar una fuente. En el sentido contrario tampoco pasa nada por sí solo, así que un servidor de correo añadido a un host que antes no tenía ninguno no se recoge. | reportedip-agent doctor nombra el registro que escribe ese servicio, avisa de que ninguna fuente lo lee y termina con el código 1. Añade la fuente a config.yaml y reinicia el servicio watch. |
| Una fuente de registro aparece como ilegible | El archivo no es legible ni para root. Suele ser un panel de control que pone el modo 000 al rotar. | ls -l sobre la ruta, y corregir la rotación que lo ha producido. |
| Una fuente tiene coincidencias pero nunca notifica | Sus marcas de tiempo están a más de un minuto del reloj del sistema, así que la ventana de recuento nunca se llena. | reportedip-agent doctor, las líneas de desviación en sources. Corregir la zona horaria de ese registro. |
| Tu propia dirección ha sido bloqueada | No estaba en la lista blanca. | reportedip-agent whitelist add <address>. Efecto inmediato, porque la regla de la lista blanca va delante de la de bloqueo. |
Un bloqueo está en bans.json pero no en el núcleo | Un reinicio sin sincronización, o una recarga del cortafuegos que se llevó el conjunto. | reportedip-agent sync lo restaura con el tiempo restante. |
Una entrada del núcleo con el registro none | Alguien bloqueó a mano con ipset o nft, o se perdió el almacén de bloqueos. Caduca, pero ningún reinicio la trae de vuelta. | reportedip-agent ban list |
| Un conjunto existe con el tipo equivocado o sin timeout | Un resto del script de shell documentado o de otra herramienta. | ipset destroy <set> y después reportedip-agent sync, que lo vuelve a crear correctamente. |
Las dos cadenas de herramientas tienen objetos rip- | El backend se cambió sin migración. | reportedip-agent sync --migrate-backend, y status muestra los comandos exactos de eliminación para el otro lado. |
| El cortafuegos ha desaparecido tras un reinicio | Un juego de reglas guardado hace referencia a un conjunto rip-, e iptables-restore descarta todo el archivo ante un conjunto desconocido. | grep -n rip- /etc/iptables/rules.v4 /etc/iptables/rules.v6 y retirar esas líneas. El agente no necesita nada guardado. |
| Una fuente retirada se sigue leyendo | Un systemctl restart no basta para una fuente retirada. | systemctl stop reportedip-agent.service && systemctl start reportedip-agent.service |
| Los informes se detienen, la detección sigue | Se alcanzó el mínimo de disco. | Liberar espacio, luego reportedip-agent housekeeping. |
| HTTP 429 en los informes | El límite diario de informes de tu plan. | Los límites están en Autenticación. |
| La cola no deja de crecer | El emisor está en pausa tras un fallo, con una espera progresiva. | reportedip-agent status muestra la pausa y el motivo; si el demonio está en marcha, envía él mismo, y reportedip-agent report-queue solo envía cuando el demonio no está en marcha. |
| Cada coincidencia web es el mismo puñado de direcciones | nginx ve un proxy o Cloudflare y no al visitante. | Configurar set_real_ip_from. reportedip-agent install advierte precisamente de este caso. |
| «more addresses than the counter tracks at once» | Un barrido más amplio que el contador por fuente. No es un defecto. | Nada. Un barrido tan amplio es un caso para la lista comunitaria y no para bloqueos locales. |
status dice que el host va atrasado de versión | La actualización automática no llega, o auto_update está desactivada. | reportedip-agent update --check, luego reportedip-agent update. |
status dice group=none | La clave de este host no está en ningún grupo. No es un fallo: el conjunto rip-group se queda vacío. | Crea un grupo en Groups en tu cuenta y mete en él las claves de los hosts; la siguiente sincronización llena el conjunto. |
status avisa de la reputación de la dirección de este host | La dirección desde la que este host notifica está listada en la base de datos comunitaria. | Comprueba qué sale de la máquina y solicita después la retirada. La condición desaparece con la siguiente sincronización tras la retirada. |
No hay líneas rip-scan: en el registro del núcleo | No hay fuente scan en la configuración, o la sincronización que construye la regla no se ha ejecutado desde que se añadió. | Añade - type: scan bajo sources, reinicia el servicio watch y después reportedip-agent sync. Las direcciones en la lista blanca y las ya descartadas nunca producen una línea. |
Última actualización: · Mantenido por el equipo de ReportedIP