r2innovation/ssh_notify - Codeberg.org

Codeberg has changed its Terms of Use. View complete changes.

LLM-generated content is being restricted. View change or read the blog post

Cryptocurrency projects are no longer allowed. View change

Dismiss

This website requires JavaScript.

r2innovation/ssh_notify

Watch

Star

Fork

Code

Issues

Pull requests

Activity

No description

3 commits

1 branch

0 tags

41 KiB

Python

100%

main

Find a file

HTTPS

Download ZIP<br>Download TAR.GZ<br>Download BUNDLE

Open with VS Code

Open with VSCodium

Open with Intellij IDEA

Repository files (latest commit first)

Filename<br>Latest commit message<br>Latest commit date

mou7664

c1ce22a8c6

Add LISENCE

2026-07-08 00:20:29 +02:00

LISENCE

Add LISENCE

2026-07-08 00:20:29 +02:00

README.md

Add README.md

2026-07-07 23:45:11 +02:00

ssh_notify.py

Add ssh_notify.py

2026-07-08 00:19:48 +02:00

README.md

SSH Monitor (Bidirectional)

A lightweight, real-time Python script for Debian (and other Linux distributions) that monitors incoming and outgoing SSH connections, logs activity to the terminal, and sends desktop GUI notifications for new connections.

Features

✅ Monitors both directions – detects incoming SSH connections (others connecting to you) and outgoing SSH connections (you connecting to others).

✅ Real‑time notifications – logs new connections to the terminal with timestamps and shows desktop pop‑ups via notify-send.

✅ Whitelist support – ignore specific IP addresses (no terminal or GUI alerts for them).

✅ Runs as a normal user – no sudo required for basic monitoring (uses ss). Optionally run with sudo to see process names/PIDs.

✅ Configurable – easily change the SSH port, check interval, and whitelist file path.

✅ Tracks active sessions – displays a list of currently connected peers on startup and alerts you only when a new connection appears.

Requirements

Debian / Ubuntu (or any system with ss from iproute2)

Python 3.6+

libnotify-bin – for GUI desktop notifications (optional; the script works without it, but notifications will be silent).

Install the required package:

sudo apt update<br>sudo apt install libnotify-bin

Installation

Download the script – save the Python code as ssh_monitor.py in a directory of your choice (e.g., ~/scripts/).

Make it executable (optional but convenient):

chmod +x ssh_monitor.py

Create a whitelist file (optional) – name it whitelist.txt and place it in the same folder as the script. Add one IP address per line. Lines starting with # are ignored.

Example whitelist.txt:

# My trusted devices<br>192.168.1.100<br>10.0.0.5

Configuration

Edit the variables at the top of ssh_monitor.py to suit your setup:

Variable<br>Default<br>Description

SSH_PORT<br>22<br>The port your SSH server listens on (for incoming detection). Outgoing detection also uses this port to identify SSH traffic leaving your machine.

WHITELIST_FILE<br>"whitelist.txt"<br>Path to the whitelist file (relative or absolute).

CHECK_INTERVAL<br>How often (in seconds) to check for new connections.

Usage

1. Run as a normal user (recommended)

python3 ssh_monitor.py<br>or if you made it executable:

./ssh_monitor.py<br>2. Run with sudo (optional)

Running with sudo enables the -p flag for the ss command, which provides process names and PIDs in the raw output (though the script currently does not display them, this can be useful for debugging). Monitoring functionality remains identical.

sudo python3 ssh_monitor.py<br>3. Stop the monitor

Press Ctrl + C at any time to exit gracefully.

What the Output Looks Like

Terminal Log

SSH Connection Monitor (Bidirectional)<br>SSH Server Port: 22<br>Whitelist file: whitelist.txt<br>Running as root: No<br>Press Ctrl+C to stop.<br>[*] Whitelisted IPs: 192.168.1.100, 10.0.0.5<br>[14:23:10] Initial Connected Sessions:<br>└─ [IN] 203.0.113.5:54321 (local 192.168.1.10:22)<br>└─ [OUT] 8.8.8.8:22 (local 192.168.1.10:51234)<br>[14:23:15] 🚨 NEW INCOMING connection: 203.0.113.45:55123<br>[14:23:20] 🚨 NEW OUTGOING connection: 1.1.1.1:22<br>[14:23:25] ⚠️ Whitelisted 192.168.1.100 ignored.

[IN] – someone connected to your SSH server.

[OUT] – you (or a process on your machine) connected to an external SSH server.

Whitelisted – the connection was made, but alerts were suppressed (only a quiet log entry appears).

GUI Notification

When a non‑whitelisted connection is detected, a desktop popup appears (if notify-send is installed):

Direction<br>Icon<br>Title<br>Body

INCOMING<br>🔐<br>SSH Connection (INCOMING)<br>INCOMING from/to :

OUTGOING<br>🚀<br>SSH Connection (OUTGOING)<br>OUTGOING from/to :

Whitelist

The whitelist allows you to suppress alerts for specific IP addresses – useful for your own trusted machines, jump hosts, or monitoring scripts.

Format: one IP per line, plain or with a # comment.

# Home desktop<br>192.168.1.100<br># Office jump server<br>10.0.0.5

Case‑sensitive? No, IPs are matched exactly as strings. Both IPv4 and IPv6 are supported.

Empty lines are ignored.

Troubleshooting

Q: The ss command shows nothing or the script reports no connections.

A: Run...