A Python based security tool that watches your Linux system for suspicious activity. It monitors important system files for unauthorized changes, scans SSH logs for brute force attacks, checks your command history for dangerous commands, and sends email alerts when something bad is found. Everything is accessible through a clean terminal interface.
File Integrity Monitoring takes a snapshot (called a baseline) of critical files like /etc/passwd, /etc/shadow, and your SSH config. Every time you run a check, it compares the current state of those files against the snapshot. If anything changed or got deleted, it flags it immediately.
SSH Brute Force Detection reads your system's auth logs and counts how many failed login attempts came from the same source. If the count crosses the threshold you set in the config (default is 3), it raises an alert.
Suspicious Command Detection scans your bash history for dangerous commands. Things like rm -rf, nmap, chmod 777, wget, fork bombs, and others that should not be showing up in normal day to day use.
Real Time Monitoring uses Linux's inotify API to watch your monitored files live. The moment a file gets modified, created, or deleted, it logs an alert right away without waiting for you to manually run a check.
Email Alerts sends you an email through Gmail when a critical alert fires. You can also manually send a full summary report of everything that was detected.
HTML Report generates a styled HTML file with all your alerts organized by category, with timestamps and counts. You can open it in a browser to get a clean overview of what happened.
| Layer | What is used |
|---|---|
| Language | Python 3.13 |
| Terminal UI | Textual 6.6.0 |
| UI styling | Rich 14.2 (used internally by Textual) |
| Real time file watching | inotify_simple 2.0.1 (Linux only) |
| Python built in smtplib + Gmail SMTP | |
| File hashing | Python built in hashlib (SHA-256) |
| Config and baseline storage | JSON files |
| Report output | Plain HTML generated as a string |
hids_project/
hids_core.py Core logic: hashing, SSH log parsing, command scanning, alert management
email_alerts.py Email sending via Gmail SMTP (single alert + summary report)
monitor_realtime.py Background thread using inotify to watch files live
report_generator.py Generates a styled HTML report from the alerts list
tui.py Textual app with buttons, alert log, and status bar. Main entry point.
config.json All settings: files to watch, SSH threshold, suspicious commands, email config
baseline.json Saved SHA-256 hashes of monitored files (auto generated, do not edit manually)
You need Python 3.10 or newer and a Linux system (inotify is Linux only).
# Clone or unzip the project, then go into the folder
cd hids_project
# Create a virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install textual inotify_simplepython tui.pyThis opens the terminal interface. From there you press the buttons to run checks.
If you want to run it with access to protected files like /etc/shadow and auth logs, run it with sudo:
sudo python tui.pyWhen the app opens you will see a status bar at the top, an alert log in the middle, and two rows of buttons at the bottom.
Initialize Baseline scans all your monitored files, calculates their SHA-256 hashes, and saves them to baseline.json. Do this first before anything else, and redo it whenever you make legitimate system changes.
Check Integrity compares your current files against the saved baseline and reports any changes.
Check SSH Logs reads /var/log/auth.log (or /var/log/secure on some distros) and looks for repeated failed login attempts.
Check Commands reads ~/.bash_history and scans for anything suspicious.
Start Monitor starts a background thread that watches your files in real time using inotify. Alerts appear in the log automatically every 2 seconds if anything changes.
Stop Monitor stops the background thread.
Generate Report creates hids_report.html in the same folder. Open it in any browser to see a formatted report of all alerts.
Email Summary sends all current alerts to the configured email address. Only works if email is enabled in config.json.
Clear Alerts wipes the current alert list from memory. Does not affect the baseline or the generated report.
Press q to quit.
Open config.json to change settings.
{
"monitored_files": [
"/etc/passwd",
"/etc/group",
"/etc/shadow",
"/etc/hosts",
"/etc/ssh/sshd_config"
],
"ssh_threshold": 3,
"suspicious_commands": [
"rm -rf",
"nmap",
"chmod 777",
"curl http",
"wget",
"nc -l",
"mkfs",
"dd if=",
":(){ :|:& };:"
],
"email_alerts": true,
"email_config": {
"smtp_server": "smtp.gmail.com",
"smtp_port": 587,
"sender_email": "your@gmail.com",
"sender_password": "your_app_password",
"recipient_email": "your@gmail.com"
},
"system_name": "My Server"
}For email to work you need to use a Gmail App Password, not your regular Gmail password. Go to your Google Account, then Security, then 2 Step Verification, then App Passwords, and generate one there.
Set "email_alerts": false to turn off all email sending without removing the config.
This tool runs on Linux only. The real time monitoring feature uses inotify which is a Linux kernel API. The file integrity and SSH log checks will work on any Linux system, but you need read permission on the relevant files. Running with sudo gives the widest access.
The baseline file stores SHA-256 hashes in plain JSON. If an attacker can modify baseline.json, they can hide their tracks. For a real deployment you would want to store the baseline somewhere write protected or signed.
The config file currently contains an email address and a plaintext app password. This was probably used for testing. Before pushing to GitHub, remove the real credentials from config.json and replace them with placeholder values or load them from environment variables.
This project was built as an academic project.