sentinel — Auth Log Security Analyzer

A command-line tool that parses Linux /var/log/auth.log files and surfaces security threats: brute force attacks, credential stuffing, username enumeration, privilege escalation, and backdoor account creation.

Zero external dependencies — pure Python 3.8+ standard library. Runs anywhere Python runs.

---

What It Detects

Detection	Severity	How
SSH brute force	HIGH	Sliding-window threshold on failed attempts per source IP
Successful login after failures	CRITICAL	IP that failed N times then authenticated — credential stuffing signal
Username enumeration	MEDIUM	Multiple distinct invalid usernames probed from one IP
New local account creation	MEDIUM	useradd events — common attacker persistence technique
Privilege escalation (sudo)	HIGH / LOW	All sudo events; HIGH if command is shell, credential file, or network tool

---

Quick Start

# Clone and run immediately — no install needed
git clone https://github.com/BrandoBank/sentinel.git
cd sentinel

# Analyze the included sample log
python3 sentinel.py sample-logs/sample-auth.log

# Analyze your own auth.log (requires read access)
sudo python3 sentinel.py /var/log/auth.log

# Pipe directly from a remote server
ssh user@host 'sudo cat /var/log/auth.log' | python3 sentinel.py -

# Export findings as JSON (for SIEM ingestion or scripting)
python3 sentinel.py auth.log --json > findings.json

# Tune detection sensitivity
python3 sentinel.py auth.log --brute-threshold 3 --window 30

---

Sample Output

Running against the included sample-logs/sample-auth.log:

──────────────────────────────────────────────────────────────
  SENTINEL — Auth Log Security Report
──────────────────────────────────────────────────────────────
  Lines analyzed : 25
  Events parsed  : 25
  Findings       : 6  (1 critical  2 high  2 medium  1 low)
──────────────────────────────────────────────────────────────

[CRITICAL] Successful Login After Failures
  IP had 6 failed attempt(s) before successful login as 'ec2-user'
  ip: 185.220.101.45
  user: ec2-user
  failure_count: 6
  login_time: 2025-04-19T03:14:26

[HIGH] Brute Force Attempt
  14 failed attempts total; 6 within 60s window starting 03:12:01
  ip: 185.220.101.45
  count: 14
  window_hits: 6

[HIGH] Privilege Escalation (sudo)
  'ec2-user' executed sudo: /bin/bash
  user: ec2-user
  command: /bin/bash

[MEDIUM] New Local Account Created
  New OS account created: 'svc_backup' — verify this was intentional

[MEDIUM] Username Enumeration
  8 attempts with 8 distinct invalid usernames from 185.220.101.45

[LOW] Privilege Escalation (sudo)
  'alice' executed sudo: /usr/bin/apt update

---

Exit Codes

Code	Meaning
0	No CRITICAL or HIGH findings
1	One or more CRITICAL or HIGH findings exist
2	File not found or argument error

This makes sentinel composable in shell scripts and CI pipelines:

python3 sentinel.py /var/log/auth.log || alert_security_team.sh

---

Detection Logic

Brute Force (sliding window)

Fails-by-IP are sorted by timestamp. A window of --window seconds (default: 60) slides forward. If --brute-threshold or more failures (default: 5) fall within one window, it's a finding.

This avoids false positives from users who genuinely forget their password over days — it only fires when failures are temporally concentrated.

Login After Failure

All source IPs with Accepted events are cross-referenced against the failure set. Any match is CRITICAL — even a single prior failure from an IP that then succeeds is worth investigation.

Username Enumeration

Distinct invalid usernames per IP are counted. Three or more different invalid names from one IP suggests a wordlist scan. The finding lists the top attempted names.

---

JSON Output

The --json flag outputs machine-readable results suitable for SIEM ingestion, Splunk, or scripting:

{
  "stats": {
    "lines": 25,
    "events": 25
  },
  "findings": [
    {
      "severity": "CRITICAL",
      "type": "Successful Login After Failures",
      "ip": "185.220.101.45",
      "user": "ec2-user",
      "failure_count": 6,
      "login_time": "2025-04-19T03:14:26",
      "detail": "IP had 6 failed attempt(s) before successful login as 'ec2-user'"
    }
  ]
}

---

Real-World Usage

# Cron job: run nightly, alert if critical findings
0 2 * * * python3 /opt/sentinel/sentinel.py /var/log/auth.log --json \
  | jq '.findings[] | select(.severity == "CRITICAL")' \
  | mail -s "sentinel alert" security@company.com

# Live monitoring (tail mode)
tail -f /var/log/auth.log | python3 sentinel.py -

# Check multiple servers
for host in web01 web02 db01; do
  echo "=== $host ===" && ssh $host 'sudo cat /var/log/auth.log' | python3 sentinel.py -
done

---

Tested Log Formats

• Ubuntu / Debian: /var/log/auth.log
• RHEL / CentOS / Amazon Linux: /var/log/secure (same format)
• macOS: /var/log/system.log (partial — sshd events only)

---

Why I Built This

Wanted a lightweight, dependency-free alternative to shipping logs to a full SIEM just to answer "was this server probed last night?" Built it to understand log-based threat detection from first principles, then used it on actual servers.

---

License

MIT