🛡️ SOC Log Analyzer

A production-quality Python tool for detecting suspicious activity in Linux auth.log files. Built for SOC analysts, sysadmins, and security-conscious developers.

---

Features

Detection	Description
🔴 Brute-Force SSH	Flags IPs exceeding N failed logins within a time window
🟠 User Enumeration	Detects IPs probing many different usernames
🔴 Privilege Escalation	Catches repeated sudo failures and root session opens
🟡 SSH Scanners	Identifies port-scanning via preauth disconnects
🚨 Compromise Detection	Flags successful logins from previously-attacking IPs

Output:

• Colour-coded terminal report
• JSON alerts file (machine-readable, CI/CD friendly)
• Optional plain-text report file
• Optional Telegram notifications for HIGH/CRITICAL alerts

---

Project Structure

soc-log-analyzer/
├── analyzer.py          # Main CLI entry point
├── parser.py            # Auth.log parsing engine (regex-based)
├── alerts.py            # Detection engine + output functions
├── config.py            # Thresholds, Telegram config, whitelists
├── requirements.txt
└── example_logs/
    └── auth.log         # Sample log for testing

---

Installation

# Clone the repository
git clone https://github.com/ihorbezruchko/soc-log-analyzer.git
cd soc-log-analyzer

# Install dependencies (only 'requests' for Telegram support)
pip install -r requirements.txt

Requirements: Python 3.8+

---

Usage

Basic analysis

python analyzer.py --log /var/log/auth.log

Save alerts to JSON

python analyzer.py --log /var/log/auth.log --output alerts.json

Save text report

python analyzer.py --log /var/log/auth.log --report report.txt

Custom thresholds

# Flag after 3 failures within 60 seconds (more sensitive)
python analyzer.py --log /var/log/auth.log --threshold 3 --window 60

Telegram notifications

export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

python analyzer.py --log /var/log/auth.log --telegram

Test with example log

python analyzer.py --log example_logs/auth.log

All options

usage: analyzer.py [-h] --log FILE [--output FILE] [--report FILE]
                   [--threshold N] [--window SECONDS]
                   [--telegram] [--no-color] [--verbose] [--year YEAR]

options:
  --log, -l FILE        Path to auth.log file
  --output, -o FILE     JSON output file (default: alerts.json)
  --report, -r FILE     Save text report to file
  --threshold, -t N     Failed login threshold (default: 5)
  --window, -w SECONDS  Time window for brute-force detection (default: 300)
  --telegram            Send HIGH/CRITICAL alerts via Telegram
  --no-color            Disable ANSI colours in terminal
  --verbose, -v         Enable debug logging
  --year YEAR           Year for log timestamps (default: current year)

---

Example Output

══════════════════════════════════════════════════════════════════════
  SOC LOG ANALYZER — SECURITY REPORT
  Generated : 2026-03-09 17:06:32
  Log file  : example_logs/auth.log
  Events    : 46
  Alerts    : 6
══════════════════════════════════════════════════════════════════════

  ALERT SUMMARY BY SEVERITY

  [CRITICAL]                      1  ███
  [HIGH]                          1  ███
  [MEDIUM]                        4  ████████████

  TOP ATTACKING IPs

   ⚠  185.234.218.45        2 alert(s)
   ⚠  91.200.12.77          2 alert(s)
   ⚠  10.0.0.50             1 alert(s)

  DETAILED ALERTS

  [006] [CRITICAL]  SUCCESSFUL_LOGIN_FROM_ATTACKER
        CRITICAL: Successful login by 'deploy' from 185.234.218.45 —
        this IP was previously flagged for brute-force activity.
        Possible successful compromise.
        IP     : 185.234.218.45
        User   : deploy
        ...

---

Detection Logic

Brute-Force Detection (Sliding Window)

The analyzer uses a sliding time window algorithm — not just a raw count — to avoid false positives from historical logs spanning many days.

For each IP:
  Sort failed login events by timestamp
  Use a sliding window of N seconds
  If max events in any window >= threshold → ALERT

Severity scaling:
  >= 5  failures  → MEDIUM
  >= 15 failures  → HIGH
  >= 20 failures  → CRITICAL

User Enumeration

If an IP attempts 3+ distinct invalid usernames → USER_ENUMERATION alert
This pattern indicates automated scanning tools (e.g. Hydra, Medusa)

Privilege Escalation

3+ sudo authentication failures for same user → PRIVILEGE_ESCALATION_ATTEMPT
Any root session opened → ROOT_SESSION_OPENED (HIGH severity, review manually)

Compromise Detection

After all alerts are generated:
  If any ACCEPTED_LOGIN event came from an IP that was flagged →
  SUCCESSFUL_LOGIN_FROM_ATTACKER (CRITICAL)

This is the highest-confidence indicator of a real breach.

---

JSON Output Format

{
  "generated_at": "2026-03-09T17:06:32",
  "total_alerts": 6,
  "alerts": [
    {
      "alert_id": 1,
      "alert_type": "BRUTE_FORCE",
      "severity": "MEDIUM",
      "source_ip": "185.234.218.45",
      "username": "root, admin, ubuntu",
      "count": 12,
      "first_seen": "2026-03-01 02:11:01",
      "last_seen": "2026-03-01 02:11:23",
      "description": "Brute-force SSH attack detected...",
      "raw_samples": ["Mar  1 02:11:01 server sshd[3821]: Failed password..."]
    }
  ]
}

---

Telegram Setup

1. Message @BotFather on Telegram → create a bot → copy token
2. Message @userinfobot to get your chat ID
3. Set environment variables:

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
export TELEGRAM_CHAT_ID="987654321"

Alerts at HIGH and CRITICAL severity are sent automatically when --telegram flag is used.

---

Whitelist Trusted IPs

Edit config.py to exclude known safe IPs:

WHITELISTED_IPS = [
    "127.0.0.1",
    "::1",
    "10.0.0.1",   # your router
    "192.168.1.5", # your admin workstation
]

---

Exit Codes

Code	Meaning
0	No HIGH or CRITICAL alerts found
1	One or more HIGH/CRITICAL alerts detected

This allows integration into shell scripts or CI/CD pipelines:

python analyzer.py --log /var/log/auth.log || echo "Security alert triggered!"

---

Tech Stack

• Python 3.8+ — standard library only (except requests for Telegram)
• re — regex-based log parsing
• argparse — CLI interface
• logging — structured log output
• dataclasses — clean data models
• collections — efficient counting and grouping

---

Author

Ihor Bezruchko IT Support Specialist | Junior SOC Analyst Luxembourg

LinkedIn