Sign inSign up

dgongut/intrubot

By dgongut

•Updated 9 days ago

Un bot para vigilar quién se conecta a tu red

Image
Networking
Security
3

10K+

dgongut/intrubot repository overview

⁠IntruBot

VERSIÓN EN ESPAÑOL | ENGLISH VERSION⁠

Docker Pulls Docker Stars Docker Image Size Github stars Github forks Github last-commit Github last-commit

Lleva el control de los dispositivos que se conectan a tu red.

  • ✅ Aviso en Telegram cuando se conecta un dispositivo nuevo, con IP, MAC, fabricante y hostname
  • ✅ Dispositivos identificados por su MAC: un cambio de IP por DHCP ya no se confunde con un intruso
  • ✅ Detección de MAC privadas (las direcciones aleatorias de móviles y portátiles)
  • ✅ Panel con el estado de la red y escaneo bajo demanda
  • ✅ Listado de dispositivos con estado (🟢 conectado / ⚪ desconectado), última vez visto y primera detección
  • ✅ Renombrar y olvidar dispositivos desde botones, sin escribir IPs a mano
  • ✅ Primer escaneo silencioso: registra tu red sin bombardearte con un aviso por dispositivo
  • ✅ Escaneo ARP de toda la red en segundos
  • ✅ Rangos, redes CIDR y direcciones sueltas en IP_RANGE
  • ✅ Varias redes o VLAN en un solo bot, cada una con su nombre y con avisos que se pueden silenciar por red
  • ✅ Aviso si el escaneo deja de funcionar (y cuando vuelve)
  • ✅ Imagen multiarquitectura compatible con Raspberry Pi, NAS y servidores estándar
  • ✅ Soporte de idiomas (Spanish, English)

📦 Código fuente, incidencias y documentación completa en GitHub⁠.

⁠Crear tu bot de Telegram

  1. Abre @BotFather⁠ en Telegram y envía /newbot. Sigue las instrucciones (un nombre y un username acabado en bot).
  2. BotFather te devolverá el token del bot. Guárdalo: irá en la variable TELEGRAM_TOKEN.
  3. Para conocer tu propio chat ID (lo necesitas para TELEGRAM_ADMIN), habla con @MissRose_bot⁠ y envíale /id.
  4. (Opcional) Si vas a usar el bot dentro de un grupo, añádelo, hazlo administrador y obtén el chat ID del grupo de la misma forma; ese valor irá en TELEGRAM_GROUP.
  5. (Opcional) Si quieres ponerle el icono oficial al bot, descarga la imagen en alta resolución aquí⁠ y envíasela a @BotFather⁠ usando la opción /setuserpic.

⁠Comandos disponibles

ComandoDescripción
/startPanel con el estado de la red (o de cada red): dispositivos conocidos y conectados, último y próximo escaneo
/listDispositivos conocidos. Con varias redes, primero eliges la red (o todas). Pulsa en un dispositivo para ver sus detalles, renombrarlo u olvidarlo
/scanEscanea la red ahora mismo
/helpLista de comandos
/versionMuestra la versión actual
/donate /donorsDona al desarrollador / lista de donantes

⁠Cómo funciona

Cada HOURS_BETWEEN_SCANS horas el bot lanza una petición ARP a todas las direcciones vigiladas (IP_RANGE, o cada red de NETWORKS). Todo dispositivo IPv4 de la red local tiene que responder a ARP (aunque tenga cortafuegos y no conteste al ping), y la respuesta trae su MAC, que es lo que lo identifica.

Si una red solo es accesible a través del router (o la interfaz que indica la tabla de rutas no existe), el ARP no llega y el bot recurre al ping, como hacía la 1.x. Ver Requisito: una interfaz en cada VLAN⁠.

  • El primer escaneo registra los dispositivos conectados sin avisar de cada uno y te envía un resumen. Es el momento de ponerles nombre.
  • A partir de ahí, cada dispositivo con una MAC nueva genera un aviso con botones para renombrarlo o ver sus detalles.
  • Si en un escaneo aparecen más de 5 dispositivos nuevos, recibes un único resumen en lugar de un mensaje por cada uno.
  • Olvidar un dispositivo lo quita de la lista: si sigue conectado, se avisará de él como nuevo en el siguiente escaneo.

ℹ️ Nota Muchos móviles y portátiles usan una MAC privada (aleatoria) para cada red Wi-Fi. El bot las marca como (privada): en ellas no se puede conocer el fabricante y, si el dispositivo decide cambiarla, aparecerá como uno nuevo.

⁠Configuración en las variables del Docker Compose

CLAVEOBLIGATORIOVALOR
TELEGRAM_TOKEN✅Token del bot
TELEGRAM_ADMIN✅ChatId del administrador (se puede obtener hablándole al bot Rose⁠ escribiendo /id). Admite múltiples administradores separados por comas. Por ejemplo 12345,54431,55944
TELEGRAM_GROUP❌ChatId del grupo. Si este bot va a formar parte de un grupo, es necesario especificar el chatId de dicho grupo. Es necesario que el bot sea administrador del grupo
TELEGRAM_THREAD❌Thread del tema dentro de un supergrupo; valor numérico (2,3,4..). Por defecto 1. Se utiliza en conjunción con la variable TELEGRAM_GROUP
TZ✅Timezone (Por ejemplo Europe/Madrid)
IP_RANGE✅*Direcciones a vigilar. Admite rangos (192.168.1.1-192.168.1.254), redes (192.168.1.0/24) y direcciones sueltas, separados por comas. Máximo 65536 direcciones
NETWORKS✅*En lugar de IP_RANGE, para vigilar varias redes o VLAN: nombre=rango[@interfaz] separados por ;. Por ejemplo Casa=192.168.1.0/24; IoT=192.168.20.0/[email protected]. Ver Varias redes o VLAN⁠
HOURS_BETWEEN_SCANS❌Horas entre escaneos; admite decimales (0.5 = 30 minutos). Mínimo un minuto. Por defecto 1
NETWORK_INTERFACE❌Interfaz de red por la que escanear IP_RANGE (por ejemplo eth0). Por defecto, la que tenga la ruta hacia esas direcciones. Con NETWORKS se usa @interfaz en cada red
LANGUAGE❌Idioma, puede ser ES / EN. Por defecto ES (Spanish)

* Hace falta IP_RANGE o NETWORKS. Si están las dos, manda NETWORKS.

⁠Ejemplo de Docker-Compose para su ejecución normal

services:
    intrubot:
        environment:
            - TELEGRAM_TOKEN=
            - TELEGRAM_ADMIN=
            - TZ=Europe/Madrid
            - IP_RANGE=192.168.1.0/24
            #- NETWORKS=Casa=192.168.1.0/24; IoT=192.168.20.0/24 # En lugar de IP_RANGE, para varias redes
            #- TELEGRAM_GROUP=
            #- TELEGRAM_THREAD=1
            #- HOURS_BETWEEN_SCANS=1
            #- NETWORK_INTERFACE=
            #- LANGUAGE=ES
        volumes:
            - /ruta/para/guardar/los/datos:/app/data # CAMBIAR LA PARTE IZQUIERDA
        image: dgongut/intrubot:latest
        container_name: intrubot
        restart: always
        network_mode: host

⁠Anotaciones

  • network_mode: host es imprescindible (o bien redes macvlan, ver Varias redes o VLAN⁠): el escaneo ARP solo funciona si el contenedor ve directamente la red local. Con la red bridge de Docker solo vería otros contenedores.
  • El escaneo usa sockets raw (capacidad NET_RAW), que Docker concede por defecto. Si la has quitado con cap_drop, añádela con cap_add: [NET_RAW].
  • La lista de dispositivos se guarda en /app/data/devices.json, así que hay que mapear ese volumen para no perderla al recrear el contenedor.
  • La imagen incluye un HEALTHCHECK: el contenedor aparece como unhealthy si el bot deja de hablar con Telegram.

⁠Varias redes o VLAN

Un solo bot puede vigilar varias redes a la vez. Usa NETWORKS en lugar de IP_RANGE, con una entrada nombre=rango por red separadas por ; y, opcionalmente, @interfaz:

- NETWORKS=Casa=192.168.1.0/24; IoT=192.168.20.0/[email protected]; Invitados=192.168.30.0/24
  • El rango de cada red admite lo mismo que IP_RANGE: rangos, redes CIDR y direcciones sueltas separadas por comas. Una dirección no puede estar en dos redes, y entre todas no pueden pasar de 65536 direcciones.
  • Sin @interfaz, el bot escanea cada dirección por la interfaz que indique la tabla de rutas. Pon @interfaz cuando la pata de esa VLAN no tenga IP propia en el equipo.
  • Todas las redes se escanean a la vez, así que añadir redes apenas alarga el escaneo.
⁠Requisito: una interfaz en cada VLAN

El ARP no atraviesa routers. Si en una red no responde nadie por ARP y, según la tabla de rutas, solo se llega a ella a través del router, el bot hace ping a sus direcciones. Funciona sin tocar nada, pero con límites:

  • A través del router no llega la MAC, así que esos dispositivos se identifican por su IP: si el DHCP le cambia la IP a uno, se avisará como nuevo. Tampoco se conoce su fabricante.
  • Los dispositivos que no responden al ping (móviles en reposo, equipos con cortafuegos) no se ven.
  • Si en esa red no responde nadie ni al ping, el bot te avisa de que no la puede ver.

Para verlo todo, con su MAC, el contenedor necesita una interfaz dentro de esa red. Cuando la tenga, los dispositivos que ya conocía por IP pasan a identificarse por su MAC sin perder el nombre y sin volver a avisar. Hay dos formas de darle esas interfaces:

1. network_mode: host y una subinterfaz por VLAN en el equipo. El puerto del switch al que va conectado el servidor tiene que llevar esas VLAN etiquetadas (modo trunk). En Linux, por ejemplo, para la VLAN 20:

ip link add link eth0 name eth0.20 type vlan id 20
ip addr add 192.168.20.5/24 dev eth0.20
ip link set eth0.20 up

Esto no sobrevive a un reinicio: hazlo persistente con la herramienta de red de tu sistema (netplan, /etc/network/interfaces, NetworkManager…). En Unraid basta con activar las VLAN en Settings → Network Settings, que crea br0.20 y similares.

2. Una red macvlan de Docker por VLAN, sin network_mode: host y sin tocar el equipo. Docker crea la subinterfaz eth0.20 si no existe. Reserva para el contenedor una IP fuera del rango de tu DHCP:

services:
    intrubot:
        environment:
            - TELEGRAM_TOKEN=
            - TELEGRAM_ADMIN=
            - TZ=Europe/Madrid
            - NETWORKS=Casa=192.168.1.0/24; IoT=192.168.20.0/24
        volumes:
            - /ruta/para/guardar/los/datos:/app/data
        image: dgongut/intrubot:latest
        container_name: intrubot
        restart: always
        networks:
            casa:
                ipv4_address: 192.168.1.250
            iot:
                ipv4_address: 192.168.20.250

networks:
    casa:
        driver: macvlan
        driver_opts:
            parent: eth0
        ipam:
            config:
                - subnet: 192.168.1.0/24
                  gateway: 192.168.1.1
    iot:
        driver: macvlan
        driver_opts:
            parent: eth0.20
        ipam:
            config:
                - subnet: 192.168.20.0/24

ℹ️ Nota Con macvlan el equipo que ejecuta Docker no se ve desde sus propios contenedores (es una limitación de macvlan), así que ese equipo no aparecerá en la lista.

⁠Cómo se ven varias redes en el bot
  • El panel de /start muestra cada red con sus dispositivos conocidos y conectados, y avisa si su último escaneo falló.
  • /list empieza preguntando qué red quieres ver, o todas.
  • Los avisos y las fichas de los dispositivos indican su red.
  • 🔔 Avisos por red (en el panel) silencia o reactiva los avisos de dispositivos nuevos de cada red. Viene bien para la red de invitados, que suele ser un desfile de MAC privadas. Una red silenciada se sigue escaneando y sus dispositivos siguen en la lista. La preferencia se guarda en /app/data.
  • Un mismo dispositivo en dos redes cuenta como dos: los routers suelen responder con la misma MAC en todas las VLAN, y que tu portátil aparezca de repente en la red IoT es algo que quieres saber.
  • Si renombras una red en NETWORKS, o pasas de IP_RANGE a NETWORKS, cada dispositivo pasa a la red que contiene su IP, sin perder su nombre y sin volver a avisar de él.
⁠Actualizar desde la versión 1.x

La 2.0 se ha reescrito por completo. Mantén el mismo volumen /app/data y el bot migrará solo tu known_devices.json (lo renombra a known_devices.json.bak):

  • Los dispositivos ya conocidos no se notificarán como nuevos y recuperan el nombre que les pusiste en cuanto aparecen en un escaneo.
  • Los comandos /delete, /deleteall y /rename desaparecen: ahora todo se hace con botones desde /list.
  • tty: true ya no hace falta. Hasta la 1.x el compose lo llevaba para que los logs del bot salieran en docker logs; desde la 2.0 la imagen los escribe al momento sin él. Puedes quitarlo, o dejarlo: no molesta.
  • Las variables IP_RANGE y HOURS_BETWEEN_SCANS siguen funcionando igual. IP_RANGE acepta además redes CIDR y varias entradas separadas por comas, y si tienes varias VLAN puedes pasarte a NETWORKS.

Tag summary

Content type

Image

Digest

sha256:19cbbce9a…

Size

33.5 MB

Last updated

9 days ago

docker pull dgongut/intrubot