🍯 Honeyfile Security Monitor

Real-time intrusion detection system with Discord alerts for Linux environments

Features • Installation • Quick Start • Usage • Deployment

---

🎯 Overview

Honeyfile Security Monitor is a lightweight, Python-based intrusion detection tool that monitors decoy files (honeypots) and sends instant Discord alerts when unauthorized access is detected. Built for Raspberry Pi and home lab security monitoring.

What is a honeyfile? A decoy file designed to look valuable (like "CreditCards_2026.xlsx") that contains fake data. When someone accesses or modifies it, you immediately know there's a potential security breach.

Use Cases

• 🏠 Home Lab Security - Monitor sensitive directories on your Raspberry Pi or home server
• 🔐 Intrusion Detection - Get instant alerts via Discord when files are accessed
• 🎓 Security Learning - Hands-on experience with security monitoring and incident response
• 🔬 Threat Research - Study attacker behavior and file access patterns

---

✨ Features

Real-Time Monitoring

• ✅ Instant Detection - Alerts triggered immediately on file modifications, moves, and deletions
• ✅ Discord Integration - Real-time notifications sent to your security channel ✅ TESTED & WORKING
• ✅ Low Resource Usage - Minimal CPU/memory footprint (~20MB RAM, <1% CPU)
• ✅ 24/7 Operation - Runs as systemd service with automatic restart on failure
• ✅ Multiple Event Types - Tracks MODIFIED, DELETED, MOVED, and CREATED events

Comprehensive Forensic Data Collection

When an intrusion is detected, the system automatically captures:

• 🖥️ System Information

  • Hostname and operating system details
  • OS version and architecture (x86_64, ARM, etc.)
  • System uptime

• 🌐 Network Context

  • Local IP address of the machine
  • MAC address of network interface
  • Count of active network connections

• 👤 User Attribution

  • Username of the file accessor
  • User ID (UID) and Group ID (GID)

• 🔄 Process Context

  • Top 5 running processes at time of access
  • Helps identify malicious processes or scripts

• ⏰ Precise Timestamps

  • Millisecond-accurate event logging
  • ISO 8601 format for easy parsing

Multi-Channel Alerting

• 💬 Discord Webhooks - Instant team notifications with rich embedded messages
• 📝 Structured Logging - Machine-readable logs at /var/log/honeyfile.log
• 🖥️ Console Output - Beautifully formatted terminal alerts with emojis
• 📧 Email Alerts (Optional) - SMTP notifications via Gmail, Outlook, or custom servers

---

🔍 How It Works

┌─────────────────────────────┐
│      Honeypot File          │
│  "CreditCards_2026.xlsx"    │  ← Appears to contain sensitive data
│   (Actually fake data)      │
└──────────┬──────────────────┘
           │
           │ Attacker/Process accesses file
           ↓
┌─────────────────────────────┐
│   Watchdog File Monitor     │  ← Python library monitoring filesystem
│   (inotify on Linux)        │
└──────────┬──────────────────┘
           │
           │ File event detected (modify/move/delete)
           ↓
┌─────────────────────────────┐
│   Forensic Data Collection  │  ← Gather intelligence
│   • IP & MAC addresses      │
│   • Username & UID          │
│   • Running processes       │
│   • System state            │
└──────────┬──────────────────┘
           │
           │ Format alert with forensic data
           ↓
┌─────────────────────────────┐
│    Multi-Channel Alerts     │
├─────────────────────────────┤
│ → Discord (instant)         │
│ → Log file (persistent)     │
│ → Terminal (if running)     │
│ → Email (optional)          │
└─────────────────────────────┘

Key advantage: Unlike simple file monitoring, this system provides full forensic context, making it easy to identify WHO accessed the file, WHEN, and WHAT else was running on the system.

---

🚀 Installation

Prerequisites

# Python 3.7 or higher
python3 --version

# Linux-based OS (tested on Raspberry Pi OS, Ubuntu, Debian)
uname -a

Install Dependencies

# Method 1: pip (recommended for most users)
pip3 install watchdog requests

# Method 2: System packages (for Raspberry Pi)
sudo apt update
sudo apt install python3-watchdog python3-requests -y

Clone Repository

git clone https://github.com/AlexPGAO/honeyfile-monitor.git
cd honeyfile-monitor

---

⚡ Quick Start

1. Create the Honeyfile

# Create a convincing decoy file
cat > ~/Desktop/CreditCards_2026.xlsx << EOF
Account Number,Cardholder Name,CVV,Expiry Date,Balance
4532-1234-5678-9010,John Doe,123,12/27,$15,234.56
5555-4444-3333-2222,Jane Smith,456,06/28,$8,901.23
6011-7777-8888-9999,Bob Johnson,789,03/29,$42,567.89
3782-822463-10005,Alice Williams,321,09/26,$23,456.78
EOF

Important: This file contains FAKE data. Never use real sensitive information.

2. Configure Discord Webhook

Get your webhook URL:

1. Open Discord → Right-click server → Server Settings
2. Integrations → Webhooks → New Webhook
3. Name: "Honeyfile Security Alert"
4. Channel: Select your security/alerts channel
5. Copy Webhook URL

Update the script:

nano honeyfile.py

Find and update these lines:

# Line 18: Update with your username
HONEYPATH = "/home/YOUR_USERNAME/Desktop/CreditCards_2026.xlsx"

# Line 22: Paste your Discord webhook URL
DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE"

# Line 23: Enable Discord alerts
ENABLE_DISCORD = True  # Change from False to True

Save and exit (Ctrl+O, Enter, Ctrl+X)

3. Run the Monitor

python3 honeyfile.py

You should see:

🍯 Enhanced Honeyfile Watcher Starting...
📁 Monitoring: /home/username/Desktop/CreditCards_2026.xlsx
📝 Log file: /var/log/honeyfile.log
🔔 Discord alerts: ✅ ENABLED
📧 Email alerts: ❌ DISABLED

Press Ctrl+C to stop
==================================================

4. Test the System

Open another terminal and trigger an alert:

echo "9999-8888-7777-6666,Hacker,999,01/30,$999,999.99" >> ~/Desktop/CreditCards_2026.xlsx

You should see:

• 🚨 Detailed alert in the terminal
• 💬 Message appear in your Discord channel
• 📝 Entry written to /var/log/honeyfile.log

---

⚙️ Configuration Options

File Paths

# Line 18: Honeyfile location
HONEYPATH = "/home/username/Desktop/CreditCards_2026.xlsx"

# Line 19: Log file location
LOGFILE = "/var/log/honeyfile.log"
# Note: You may need sudo permissions for /var/log/
# Alternative: LOGFILE = "/home/username/honeyfile.log"

Discord Configuration

# Lines 22-23
DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/1234567890/AbCdEfGhI..."
ENABLE_DISCORD = True  # Set to False to disable Discord alerts

Email Configuration (Optional)

For Gmail:

# Lines 26-31
ENABLE_EMAIL = True
EMAIL_FROM = "your-email@gmail.com"
EMAIL_PASSWORD = "abcd efgh ijkl mnop"  # 16-char App Password
EMAIL_TO = "security-alerts@example.com"
SMTP_SERVER = "smtp.gmail.com"
SMTP_PORT = 587

Gmail setup:

1. Enable 2FA: https://myaccount.google.com/security
2. Generate App Password: https://myaccount.google.com/apppasswords
3. Select "Mail" → Generate → Copy 16-character password

Other providers:

Provider	SMTP Server	Port
Gmail	smtp.gmail.com	587
Outlook	smtp.office365.com	587
Yahoo	smtp.mail.yahoo.com	587

---

💻 Usage

Running Manually

# Start the monitor
python3 honeyfile.py

# Run in background
nohup python3 honeyfile.py &

# Check if running
ps aux | grep honeyfile

# Stop background process
pkill -f honeyfile

Viewing Logs

# View entire log file
sudo cat /var/log/honeyfile.log

# Last 20 alerts
sudo tail -n 20 /var/log/honeyfile.log

# Follow log in real-time (watch for new alerts)
sudo tail -f /var/log/honeyfile.log

# Search for specific username
grep "User: pi" /var/log/honeyfile.log

# Search by event type
grep "MODIFIED" /var/log/honeyfile.log

# Count total alerts
grep -c "ALERT:" /var/log/honeyfile.log

# Alerts from last hour
grep "$(date -d '1 hour ago' '+%Y-%m-%d %H')" /var/log/honeyfile.log

Log Analysis

Log entries are structured for easy parsing:

2026-02-02 15:42:17,234 - ALERT: MODIFIED | User: username | Host: raspberrypi | IP: 192.168.1.100 | MAC: B8:27:EB:12:34:56

Fields:

• Timestamp (ISO 8601 format)
• Alert type (MODIFIED, MOVED, DELETED, CREATED)
• Username
• Hostname
• IP address
• MAC address

---

📊 Output Examples

Terminal Alert (Console Output)

🚨 HONEYFILE ALERT: MODIFIED 🚨
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⏰ Timestamp: 2026-02-02 15:42:17
📁 File: /home/theshefu/Desktop/CreditCards_2026.xlsx
🔔 Event: MODIFIED

═══ SYSTEM INFORMATION ═══
💻 Hostname: raspberrypi
🖥️  OS: Linux 6.1.0-rpi7-rpi-v8 (aarch64)
📡 Local IP: 192.168.1.100
🔗 MAC Address: B8:27:EB:12:34:56

═══ USER INFORMATION ═══
👤 Username: theshefu
🆔 UID/GID: 1000/1000

═══ SYSTEM STATUS ═══
⏱️  Uptime: 12.45 hours
🌐 Active Connections: 5

═══ TOP PROCESSES ═══
  • python3
  • bash
  • sshd
  • systemd
  • dhcpcd

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  POTENTIAL SECURITY BREACH DETECTED ⚠️

Log File Entry

2026-02-02 15:42:17,234 - ALERT: MODIFIED | User: theshefu | Host: raspberrypi | IP: 192.168.1.100 | MAC: B8:27:EB:12:34:56

Discord Alert

Discord receives a rich embedded message with:

• Red color-coded alert banner
• Full timestamp
• File path and event type
• Complete system information
• User and network context
• Running processes
• @everyone mention for immediate attention

---

🚀 Deployment (Run on Boot)

Setup as Systemd Service

Running as a service ensures the monitor starts automatically on boot and restarts if it crashes.

1. Copy service file:

sudo cp examples/honeyfile.service /etc/systemd/system/

2. Edit service file with your paths:

sudo nano /etc/systemd/system/honeyfile.service

Update these lines:

[Service]
User=YOUR_USERNAME                                    # Your Linux username
WorkingDirectory=/home/YOUR_USERNAME/honeyfile-monitor
ExecStart=/usr/bin/python3 /home/YOUR_USERNAME/honeyfile-monitor/honeyfile.py

3. Enable and start service:

# Reload systemd configuration
sudo systemctl daemon-reload

# Enable service (start on boot)
sudo systemctl enable honeyfile.service

# Start service now
sudo systemctl start honeyfile.service

# Check status
sudo systemctl status honeyfile.service

4. Service management commands:

# Stop service
sudo systemctl stop honeyfile.service

# Restart service
sudo systemctl restart honeyfile.service

# Disable auto-start on boot
sudo systemctl disable honeyfile.service

# View service logs in real-time
sudo journalctl -u honeyfile.service -f

# View last 50 service log entries
sudo journalctl -u honeyfile.service -n 50

---

🧪 Testing

Manual Testing

# Terminal 1: Start the monitor
python3 honeyfile.py

# Terminal 2: Trigger various events
echo "test data" >> ~/Desktop/CreditCards_2026.xlsx    # MODIFIED ✅
mv ~/Desktop/CreditCards_2026.xlsx /tmp/test.xlsx      # MOVED ✅
mv /tmp/test.xlsx ~/Desktop/CreditCards_2026.xlsx      # MOVED ✅
rm ~/Desktop/CreditCards_2026.xlsx                     # DELETED ✅

Automated Test Suite

chmod +x tests/test_honeyfile.sh
./tests/test_honeyfile.sh

The test script will:

• Backup your honeyfile
• Run 8 different test scenarios
• Show which events trigger alerts
• Restore the original honeyfile
• Display expected vs actual results

What Triggers Alerts?

Action	Triggers Alert?	Event Type	Why?
Read file (cat)	❌ No	N/A	Read-only operations don't modify filesystem
Append data (echo >>)	✅ Yes	MODIFIED	File contents changed
Edit file (nano, vim)	✅ Yes	MODIFIED	File saved with changes
Copy file (cp)	❌ No	N/A	Creates new file, doesn't modify original
Move file (mv)	✅ Yes	MOVED	File path changed
Delete file (rm)	✅ Yes	DELETED	File removed from filesystem
Touch file (touch)	✅ Yes	MODIFIED	Timestamp updated (metadata change)
Rename file	✅ Yes	MOVED	Path/name changed

---

🔧 Troubleshooting

Discord Alerts Not Appearing

Check if Discord is enabled:

grep "ENABLE_DISCORD" honeyfile.py
# Should show: ENABLE_DISCORD = True

Test webhook URL manually:

curl -X POST -H "Content-Type: application/json" \
  -d '{"content":"Test message from terminal"}' \
  "YOUR_WEBHOOK_URL"

If this works, your webhook is valid. If not, regenerate it in Discord.

Common issues:

• ENABLE_DISCORD = False → Change to True
• Invalid/expired webhook URL → Create new webhook in Discord
• Firewall blocking HTTPS → Check sudo ufw status
• Missing requests library → Run pip3 install requests

Permission Denied on Log File

# Create log file with proper permissions
sudo touch /var/log/honeyfile.log
sudo chown $USER:$USER /var/log/honeyfile.log
sudo chmod 644 /var/log/honeyfile.log

# Alternative: Use home directory
# Edit honeyfile.py line 19:
# LOGFILE = "/home/YOUR_USERNAME/honeyfile.log"

FileNotFoundError

# Verify honeyfile exists
ls -lh ~/Desktop/CreditCards_2026.xlsx

# If missing, recreate it
cat > ~/Desktop/CreditCards_2026.xlsx << EOF
Account,Name,CVV
1234-5678-9012,Test,123
EOF

# Update path in script if needed
nano honeyfile.py
# Edit line 18: HONEYPATH = "..."

Module Not Found Error

# Install missing dependencies
pip3 install watchdog requests

# For Raspberry Pi
sudo apt install python3-watchdog python3-requests

Service Won't Start

# Check service status and errors
sudo systemctl status honeyfile.service

# View detailed error logs
sudo journalctl -xe -u honeyfile.service

# Common fixes:
# 1. Verify Python path
which python3  # Should be /usr/bin/python3

# 2. Test script manually first
python3 /path/to/honeyfile.py

# 3. Check file permissions
ls -l /path/to/honeyfile.py
chmod +x /path/to/honeyfile.py

For more help, see docs/TROUBLESHOOTING.md

---

🎓 Technical Details

Technologies Used

• Python 3.7+ - Core programming language
• Watchdog - Cross-platform file system monitoring library
• Requests - HTTP library for webhook/API calls
• Linux inotify - Kernel subsystem for filesystem event monitoring
• systemd - Service management and auto-restart
• Discord Webhooks - Real-time notification delivery
• SMTP - Email protocol for alert delivery

System Requirements

• RAM: ~20-30 MB
• CPU: <1% on idle, ~2-5% during alert processing
• Disk: <1 MB for script, logs grow ~500 bytes per alert
• Network: Outbound HTTPS (port 443) for Discord/Email

Security Considerations

• Honeyfile contains NO real sensitive data
• Script runs with user-level permissions (not root)
• Logs may contain usernames and IP addresses
• Discord webhooks should be kept private
• Email credentials stored in plaintext (use app passwords)
• Consider using environment variables for credentials

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Ideas for Enhancement

• Slack/Microsoft Teams webhook support
• SMS alerts via Twilio
• Web dashboard for alert visualization
• SQLite database for historical analysis
• Monitor multiple honeyfiles simultaneously
• Geolocation lookup for IP addresses
• Integration with Splunk/ELK Stack
• Automated incident response actions
• Machine learning anomaly detection
• Docker container deployment

---

📄 License

MIT License - see LICENSE file for details.

This project is free and open-source. You may use, modify, and distribute it for any purpose.

---

🔗 Links

• Repository: https://github.com/AlexPGAO/honeyfile-monitor
• Issues: https://github.com/AlexPGAO/honeyfile-monitor/issues
• Discussions: https://github.com/AlexPGAO/honeyfile-monitor/discussions

---

🙏 Acknowledgments

• Watchdog - Python library for file system monitoring
• Discord Developer Documentation - Webhook API reference
• Raspberry Pi Community - Testing environment and feedback

---

⬆ Back to Top

Status: ✅ Active Development | Last Updated: February 2026