https://github.com/drrlvn/houserat

Monitor devices connecting to network and get notifications
https://github.com/drrlvn/houserat

arp dhcp notifications rust telegram

Last synced: 23 days ago
JSON representation

Monitor devices connecting to network and get notifications

• Host: GitHub
• URL: https://github.com/drrlvn/houserat
• Owner: drrlvn
• License: gpl-3.0
• Created: 2019-08-18T21:04:56.000Z (about 5 years ago)
• Default Branch: master
• Last Pushed: 2023-11-28T21:36:43.000Z (11 months ago)
• Last Synced: 2024-10-12T05:45:08.469Z (26 days ago)
• Topics: arp, dhcp, notifications, rust, telegram
• Language: Rust
• Size: 247 KB
• Stars: 10
• Watchers: 2
• Forks: 1
• Open Issues: 12
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 🐀 Houserat

A daemon that monitors network traffic for DHCP and ARP packets from known devices and sends a notification

using Telegram when these devices connect or disconnect.

## 🚀 Usage

1. [Create a Telegram bot](https://core.telegram.org/bots#creating-a-new-bot) and save its token.

1. Install using a package manager:

   * **Arch Linux**: [AUR](https://aur.archlinux.org/packages/houserat/), e.g. `yay -S houserat`

   * **Cargo**: `cargo install houserat` (note that you'll have to manually install the service and

     config files)

1. Edit configuration at `/etc/houserat/config.toml` with bot token, device and user information

   ([example](config.example.toml)).

1. Enable and start service: `systemctl enable --now houserat`.

### 🤖 Bot Configuration

Once you have your bot token you'll need to get chat IDs for every user that subscribes to

notifications. The easiest way to do that is:

1. Have the user start a conversation with the bot or send any message to it.

1. Open `https://api.telegram.org/bot/getUpdates` in a browser (replacing `` with your

bot token) and look for the chat ID, it should be in `message.chat.id` in the `result` array.

1. Put the chat ID you found in the `chat_id` field for that user in `config.toml`.

1. Optionally clearing the updates list by going back to the Telegram `getUpdates` API method and

   adding `?offset=`, where the `update_id` is found in the result.  This would make it

   easier to find other chat IDs when repeating this process.

## 💫 How It Works

*Houserat* detects devices connecting to the network when they send a DHCP request packet. It will

then notify that device's subscriber and start polling this device to detect when it goes

away. Since phones don't always respond to PING packets houserat uses ARP requests which all devices

must respond to.

When several ARP requests go unanswered the device is considered disconnected and a notification is

sent to the subscriber.

## 💤 Anti-Spam

Houserat has several features designed to reduce notification spam:

* Configurable *cooldown* during which no new notifications are sent, for example if a device

  reconnects soon after its initial connection only 1 notification is sent.

* Configurable *quiet period* during which messages are sent without sound notifications. This can be

  used to avoid having noisy Telegram notifications at night.