Skip to content

SETUP.md

Latest commit

 

History

History
315 lines (220 loc) · 7.21 KB

SETUP.md

File metadata and controls

315 lines (220 loc) · 7.21 KB

Security Log Monitor - Setup Guide

Complete installation and configuration guide for security-log-monitor.

Table of Contents

  1. Prerequisites
  2. Installation
  3. Telegram Configuration
  4. systemd Setup
  5. Verification
  6. Optional Components

Prerequisites

Required Dependencies

  1. bash-production-toolkit
# Install bash-production-toolkit
git clone https://github.com/fidpa/bash-production-toolkit.git
cd bash-production-toolkit
sudo make install

# Verify installation
ls -la /usr/local/lib/bash-production-toolkit/src/
  1. systemd (included in Ubuntu 22.04+)
systemctl --version
  1. journalctl (included in systemd)
journalctl --version

Optional Dependencies

Install the security tools you want to monitor:

# AIDE (file integrity monitoring)
sudo apt install aide aide-common

# rkhunter (rootkit detection)
sudo apt install rkhunter

# auditd (kernel auditing)
sudo apt install auditd audispd-plugins

Installation

1. Deploy Script

# Copy script to /usr/local/bin
sudo cp security-monitoring/scripts/security-log-monitor.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/security-log-monitor.sh

# Verify
/usr/local/bin/security-log-monitor.sh --dry-run

2. Create State Directory

# Create state directory (systemd will do this automatically, but manual works too)
sudo mkdir -p /var/lib/security-monitoring
sudo chown root:root /var/lib/security-monitoring
sudo chmod 755 /var/lib/security-monitoring

Telegram Configuration

Option 1: Simple Configuration (Environment Variables)

Create /etc/default/security-log-monitor:

sudo nano /etc/default/security-log-monitor

Add the following:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
TELEGRAM_CHAT_ID="-1001234567890"

# Optional: Customize alert prefix
TELEGRAM_PREFIX="[🔐 MyServer]"

# Optional: Adjust thresholds
SSH_FAILURE_THRESHOLD=10
UFW_BLOCK_THRESHOLD=20

Option 2: Vaultwarden Integration

If you use Vaultwarden/Bitwarden for credential management:

  1. Store Telegram Bot Token in Vaultwarden as Secure Note named "Telegram Bot Token"
  2. Store Chat ID in /etc/default/security-log-monitor:
TELEGRAM_CHAT_ID="-1001234567890"

The script will automatically use bash-production-toolkit's Vaultwarden integration.

How to Get Telegram Credentials

  1. Create Bot: Message @BotFather on Telegram

    • Send /newbot
    • Follow prompts to get your TELEGRAM_BOT_TOKEN

  2. Get Chat ID:

    • Add bot to your group/channel
    • Send a message to the group
    • Visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
    • Look for "chat":{"id":-1234567890} in the response

systemd Setup

1. Deploy systemd Units

# Copy service and timer
sudo cp security-monitoring/systemd/security-log-monitor.service.template \
    /etc/systemd/system/security-log-monitor.service

sudo cp security-monitoring/systemd/security-log-monitor.timer.template \
    /etc/systemd/system/security-log-monitor.timer

# Reload systemd
sudo systemctl daemon-reload

2. Enable Timer

# Enable timer (starts automatically on boot)
sudo systemctl enable security-log-monitor.timer

# Start timer immediately
sudo systemctl start security-log-monitor.timer

3. Optional: Adjust Timer Schedule

Edit /etc/systemd/system/security-log-monitor.timer to change interval:

[Timer]
# Run every 30 minutes instead of 15
OnCalendar=*:0/30

Then reload:

sudo systemctl daemon-reload
sudo systemctl restart security-log-monitor.timer

Verification

Check Timer Status

# Verify timer is active
sudo systemctl status security-log-monitor.timer

# List timers
sudo systemctl list-timers security-log-monitor.timer

Expected output:

● security-log-monitor.timer - Security Log Monitor Timer
     Loaded: loaded (/etc/systemd/system/security-log-monitor.timer; enabled)
     Active: active (waiting) since Wed 2026-01-15 10:00:00 CET; 1min ago
    Trigger: Wed 2026-01-15 10:15:00 CET; 13min left

Run Manual Test

# Test script with dry-run
sudo /usr/local/bin/security-log-monitor.sh --dry-run

# Run actual check
sudo systemctl start security-log-monitor.service

# View logs
sudo journalctl -u security-log-monitor.service -n 50

Expected Log Output

Jan 15 10:00:00 myserver systemd[1]: Starting Security Log Monitor...
Jan 15 10:00:00 myserver security-log-monitor.sh[12345]: ====================================================
Jan 15 10:00:00 myserver security-log-monitor.sh[12345]: Security Log Monitor v1.3.0 starting...
Jan 15 10:00:00 myserver security-log-monitor.sh[12345]: Hostname: myserver.example.com
Jan 15 10:00:00 myserver security-log-monitor.sh[12345]: Check interval: 15 minutes
Jan 15 10:00:00 myserver security-log-monitor.sh[12345]: ====================================================
Jan 15 10:00:01 myserver security-log-monitor.sh[12345]: Checking fail2ban events...
Jan 15 10:00:01 myserver security-log-monitor.sh[12345]: fail2ban: No new bans detected
Jan 15 10:00:01 myserver security-log-monitor.sh[12345]: Checking SSH failed login attempts...
Jan 15 10:00:01 myserver security-log-monitor.sh[12345]: SSH: 3 failures (below threshold of 5)
...
Jan 15 10:00:02 myserver security-log-monitor.sh[12345]: No new security events to report
Jan 15 10:00:02 myserver security-log-monitor.sh[12345]: ====================================================
Jan 15 10:00:02 myserver security-log-monitor.sh[12345]: Security Log Monitor completed successfully
Jan 15 10:00:02 myserver security-log-monitor.sh[12345]: ====================================================
Jan 15 10:00:02 myserver systemd[1]: security-log-monitor.service: Succeeded.

Test Telegram Alerting

Generate a test event to trigger an alert:

# Trigger fail2ban ban (will reverse immediately)
sudo fail2ban-client set sshd banip 1.2.3.4
sleep 2
sudo fail2ban-client set sshd unbanip 1.2.3.4

# Run monitor
sudo systemctl start security-log-monitor.service

# Check for Telegram message

You should receive a Telegram alert like:

🔐 Security Alert

🚨 fail2ban: 1 new ban(s)
• 1.2.3.4

Optional Components

Enable Additional Security Tools

AIDE (File Integrity Monitoring)

# Install AIDE
sudo apt install aide aide-common

# Initialize database
sudo aideinit

# Enable daily checks
sudo systemctl enable --now aide-update.timer

rkhunter (Rootkit Detection)

# Install rkhunter
sudo apt install rkhunter

# Update database
sudo rkhunter --propupd

# Enable daily scans
sudo systemctl enable --now rkhunter.timer

auditd (Kernel Auditing)

# Install auditd
sudo apt install auditd audispd-plugins

# Enable service
sudo systemctl enable --now auditd

# Verify
sudo auditctl -l

Next Steps

Last Updated: 15. Januar 2026