https://github.com/ethanc/leash

Monitor the OPNsense DHCPv4 service and notify about new leases.
https://github.com/ethanc/leash

api bot device dhcp dhcpv4 discord ip ip-address lease leases mac mac-address monitor notification notify opnsense python script watcher webhook

Last synced: 4 months ago
JSON representation

Monitor the OPNsense DHCPv4 service and notify about new leases.

• Host: GitHub
• URL: https://github.com/ethanc/leash
• Owner: EthanC
• License: mit
• Archived: true
• Created: 2024-04-11T04:10:50.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2024-08-25T04:23:37.000Z (over 1 year ago)
• Last Synced: 2024-10-05T04:05:57.710Z (over 1 year ago)
• Topics: api, bot, device, dhcp, dhcpv4, discord, ip, ip-address, lease, leases, mac, mac-address, monitor, notification, notify, opnsense, python, script, watcher, webhook
• Language: Python
• Homepage: https://hub.docker.com/repository/docker/ethanchrisp/leash
• Size: 66.4 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Leash

![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/EthanC/Leash/ci.yaml?branch=main) ![Docker Pulls](https://img.shields.io/docker/pulls/ethanchrisp/leash?label=Docker%20Pulls) ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/ethanchrisp/leash/latest?label=Docker%20Image%20Size)

Leash monitors the OPNsense DHCPv4 service and notifies about new leases via Discord.



    



## Setup

Although not required, a [Discord Webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) is recommended for notifications.

Regardless of your chosen setup method, Leash is intended for use with a task scheduler, such as [cron](https://crontab.guru/).

**Environment Variables:**

-   `LOG_LEVEL`: [Loguru](https://loguru.readthedocs.io/en/stable/api/logger.html) severity level to write to the console.

-   `LOG_DISCORD_WEBHOOK_URL`: [Discord Webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) URL to receive log events.

-   `LOG_DISCORD_WEBHOOK_LEVEL`: Minimum [Loguru](https://loguru.readthedocs.io/en/stable/api/logger.html) severity level to forward to Discord.

-   `OPNSENSE_ADDRESS` (Required): IP or URL for the local OPNsense instance.

-   `OPNSENSE_KEY` (Required): Key for the local OPNsense instance.

-   `OPNSENSE_SECRET` (Required): Secret for the local OPNsense instance.

-   `DISCORD_WEBHOOK_URL`: [Discord Webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) URL to receive OPNsense DHCPv4 Lease notifications.

### Docker (Recommended)

Modify the following `compose.yaml` example file, then run `docker compose up`.

```yml

services:

  leash:

    container_name: leash

    image: ethanchrisp/leash:latest

    environment:

      LOG_LEVEL: INFO

      LOG_DISCORD_WEBHOOK_URL: https://discord.com/api/webhooks/YYYYYYYY/YYYYYYYY

      LOG_DISCORD_WEBHOOK_LEVEL: WARNING

      OPNSENSE_ADDRESS: https://192.168.1.1

      OPNSENSE_KEY: XXXXXXXX

      OPNSENSE_SECRET: XXXXXXXX

      DISCORD_WEBHOOK_URL: https://discord.com/api/webhooks/XXXXXXXX/XXXXXXXX

```

### Standalone

Leash is built for [Python 3.12](https://www.python.org/) or greater.

1. Install required dependencies using [uv](https://github.com/astral-sh/uv): `uv sync`

2. Rename `.env.example` to `.env`, then provide the environment variables.

3. Start Leash: `python leash.py`