Kismet-Ntfy Bridge

A lightweight, stateless bridge that forwards Kismet wireless security alerts to Ntfy for real-time notifications.

---

Table of Contents

• Overview
• Prerequisites
• Usage
  • Native Install
  • Docker
• Configuration
  • Command-Line Arguments
  • Environment Variables
• License

---

Overview

Kismet-Ntfy is a Python application that acts as a real-time notification bridge between Kismet wireless security monitoring system and Ntfy notification service. It listens to Kismet's websocket event stream and forwards security alerts to your Ntfy topic.

Prerequisites

• Python 3.11+
• uv - Fast Python package installer and resolver

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

OR

• Docker

Usage

Native Install

uv sync
uv run kismet-ntfy-bridge --help

Docker

Build or pull the image

docker build -t kismet-ntfy .

OR

docker pull git.zarn.cloud/starkzarn/kismet-ntfy:latest

Stage ENV vars

cp env.example .env

Run the container

docker run -d \
  --name kismet-ntfy \
  --env-file .env \
  --restart unless-stopped \
  kismet-ntfy

Docker Compose

cp env.example .env
docker compose up -d

Configuration

Command-line Arguments

• --help -- Display help menu
• --kismet-server your.kismetserver.tld -- Your kismet server FQDN or IP (Do not include http/https as this will be converted to a websocket address)
• --kismet-api-key 123ABC -- Your API key generated from the Kismet webUI settings menu
• --kismet-port [Optional] 443 -- The port your kismet server is listening on (2501 default)
• --kismet-ssl [Optional] -- Switch to force connection over wss
• --ntfy-server https://ntfy.yourdomain.tld -- Your FQDN with scheme for a Ntfy server
• --ntfy-topic Kismet-Alerts -- A Ntfy topic that you wish to feed all Kismet alerts to
• --ntfy-token [Optional] -- A token for your Ntfy user if you require authentication
• --debug [Optional] -- Verbose logging
• --trace [Optional] -- Include HTTP requests in log output

Environment Variables

All configuration values that are passed as command-line arguments can instead be specified as ENV vars. Take the command-line argument and capitalize it for the equivalent ENV var.

Example:

• --ntfy-topic => NTFY_TOPIC

Secrets

Every environment variable is supported as a a file-based secret as well. Append _FILE to the ENV var name and pass it a path to read from that file.

Example:

• NTFY_TOKEN_FILE=/run/secrets/ntfy-token instead of NTFY_TOKEN=123456

License

GPLv3 -- See License