🛡️ Auth Anomaly Detector

An open-source Python security tool that detects 11 authentication attack patterns using detection engineering principles, MITRE ATT&CK mapping, and risk-based alert scoring — with a live SOC dashboard.

---

🏗️ Architecture

auth_logs.csv (2,600+ events)
      │
      ▼
11 Detection Modules  →  Risk Scoring Engine  →  Alert Generator  →  Streamlit Dashboard
(MITRE ATT&CK mapped)    (0 – 100 score)         (alerts.json)       (SOC triage view)

---

🔍 Detection Coverage

Detector	Attack Pattern	MITRE ATT&CK	Risk Weight
Brute Force	≥5 failed logins, same user/IP, 5-min window	T1110	40
Impossible Travel	Same user, 2 countries, < 60 min apart	T1078	50
Credential Stuffing	1 IP → ≥8 distinct accounts, 10-min window	T1110.004	45
Password Spraying	1 IP → many accounts, 1 attempt each, slow rate	T1110.003	35
MFA Bypass	MFA fatigue or MFA disabled for enrolled user	T1111	60
Privilege Escalation	Admin login from never-before-seen IP	T1078.003	55
Account Takeover	New IP + off-hours + clean login	T1078	65
Suspicious IP	Login from threat-intel flagged country	T1090	30
Off-Hours Login	Successful login 12 AM – 5 AM	T1078	15
New Device	First-ever (username, source_ip) combination	T1078.002	10
Multiple Failed IPs	1 user targeted from ≥3 distinct IPs	T1110	25

---

📊 Sample Alert Output

{
  "alert_id": "ALT-2026-00001",
  "generated_at": "2026-07-06T12:30:00Z",
  "username": "alice",
  "detections": ["brute_force", "impossible_travel", "off_hours"],
  "detection_count": 3,
  "risk_score": 100,
  "severity": "Critical",
  "mitre_attack": ["T1078 - Valid Accounts", "T1110 - Brute Force"],
  "recommended_action": "Lock account immediately; force MFA re-enrollment | Block source IP"
}

---

⚙️ Quick Start

git clone https://github.com/satendra-jaiswal/auth-anomaly-detector.git
cd auth-anomaly-detector
pip install -r requirements.txt

python data/generate_logs.py   # generate 2,600+ synthetic auth events
python main.py                 # run all 11 detectors → alerts.json
streamlit run dashboard/app.py # launch SOC dashboard

With Make:

make install && make run && make dashboard

With Docker:

docker-compose up --build      # dashboard at http://localhost:8501

---

📂 Repository Structure

auth-anomaly-detector/
├── detectors/                    # 11 detection modules
│   ├── brute_force.py            # T1110
│   ├── impossible_travel.py      # T1078
│   ├── credential_stuffing.py    # T1110.004
│   ├── password_spraying.py      # T1110.003
│   ├── mfa_bypass.py             # T1111
│   ├── privilege_escalation.py   # T1078.003
│   ├── account_takeover.py       # T1078
│   ├── suspicious_ip.py          # T1090
│   ├── off_hours.py              # T1078
│   ├── new_device.py             # T1078.002
│   └── multiple_failed_logins.py # T1110
├── engine/
│   ├── risk_scorer.py            # Weighted 0-100 risk score
│   └── alert_generator.py        # SIEM-format JSON alert builder
├── dashboard/app.py              # Streamlit SOC dashboard
├── data/generate_logs.py         # Synthetic log generator (10 attack types)
├── tests/                        # 36 unit tests
├── .github/workflows/ci.yml      # CI — Python 3.10 / 3.11 / 3.12
├── config.yaml                   # All thresholds (no hardcoded values)
├── mitre_mapping.json            # Detector → MITRE ATT&CK mapping
├── main.py                       # Pipeline entry point
├── Dockerfile + docker-compose.yml
└── ARCHITECTURE.md               # Full system design + diagrams

---

🧪 Tests

python -m pytest tests/ -v                              # run all 36 tests
python -m pytest tests/ --cov=. --cov-report=term-missing  # with coverage

---

🛠️ Tech Stack

Tool	Purpose
Python 3.10+	Core language
pandas	Log processing, time-window analysis
Streamlit	SOC dashboard
PyYAML	Configuration management
pytest	Testing
GitHub Actions	CI/CD
Docker	Containerised deployment

---

📄 License

MIT — see LICENSE

---

👤 Author

Satendra Jaiswal