CyberSentinel 🛡️

Defensive IDS/SIEM — Log monitoring, threat detection and alert dashboard for Linux systems.

---

Overview

CyberSentinel is an open-source defensive security tool that monitors Linux system logs, detects suspicious behavior, and exposes alerts through a REST API and a real-time web dashboard.

It is designed for system administrators, security students, and blue-team practitioners who want visibility into what is happening on their Linux machine without deploying a full enterprise SIEM.

What it detects

Detection Rule	Level	Description
SSH Brute-Force	high	N failed SSH logins from the same IP
Invalid User Login	medium	Login attempt with a non-existent username
Sudo Fail	high	Unauthorized or failed sudo command
Sudo Exec	low	Privileged command executed via sudo
Password Change	medium	System password modification detected
Event Spike	critical	Abnormal event density in a short time window

---

Architecture

┌──────────────────────────────────────────────────────┐
│                      CyberSentinel                   │
│                                                      │
│  ┌─────────────┐    ┌──────────────┐                 │
│  │  log_parser │───▶│   detector   │                 │
│  │  (regex)    │    │  (5 rules)   │                 │
│  └─────────────┘    └──────┬───────┘                 │
│                            │ AlertCreate              │
│                     ┌──────▼───────┐                 │
│                     │  file_monitor│                 │
│                     │  (DB writer) │                 │
│                     └──────┬───────┘                 │
│                            │                         │
│              ┌─────────────▼──────────────┐          │
│              │         SQLite DB          │          │
│              └─────────────┬──────────────┘          │
│                            │                         │
│              ┌─────────────▼──────────────┐          │
│              │       FastAPI REST API      │          │
│              │  /alerts  /stats  /health  │          │
│              └─────────────┬──────────────┘          │
│                            │                         │
│              ┌─────────────▼──────────────┐          │
│              │     Dashboard (Jinja2 +     │          │
│              │     TailwindCSS + JS)       │          │
│              └────────────────────────────┘          │
│                                                      │
│  Optional: Discord webhook notifier                  │
└──────────────────────────────────────────────────────┘

---

Stack

• Backend: Python 3.12 + FastAPI + Uvicorn
• Database: SQLite (via SQLAlchemy ORM)
• Dashboard: Jinja2 + TailwindCSS CDN + Vanilla JS
• Detection: Pure Python regex rules, no external dependencies
• Notifications: Discord webhook (optional)
• Tests: pytest
• Deploy: Docker + docker-compose

---

Installation — Local

Requirements

• Python 3.12+
• pip

Steps

# 1. Clone the repository
git clone https://github.com/K413MP3R4/CyberSentinel.git
cd CyberSentinel

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\activate           # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment (optional)
cp .env.example .env
# Edit .env to set LOG_FILE_PATH, DISCORD_WEBHOOK_URL, etc.

# 5. Start the API + dashboard
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser.

---

Demo Mode

The repository includes sample_logs/auth.log — a realistic synthetic log file with SSH brute-force attempts, invalid user logins, sudo commands, and an event spike.

# Run analysis on the sample log file
curl -X POST http://localhost:8000/alerts/analyze

# Or click "Run Analysis" in the dashboard

This generates several realistic alerts immediately.

---

Installation — Docker

# Build and start
docker-compose up --build -d

# Follow logs
docker-compose logs -f

# Stop
docker-compose down

The container exposes port 8000. The SQLite database and log files are mounted as volumes for persistence.

Optional Discord notifications:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx docker-compose up -d

---

API Endpoints

Method	Endpoint	Description
GET	/	Web dashboard
GET	/health/	Service health check
GET	/alerts/	List all alerts (supports ?level=high&status=new&limit=50)
GET	/alerts/{id}	Get alert by ID
POST	/alerts/{id}/review	Mark alert as reviewed
POST	/alerts/{id}/ignore	Mark alert as ignored
POST	/alerts/analyze	Trigger log analysis (generates new alerts)
GET	/stats/	Aggregated statistics
GET	/docs	Interactive Swagger UI

Example API calls

# Get all high-severity alerts
curl http://localhost:8000/alerts/?level=high

# Get statistics
curl http://localhost:8000/stats/

# Trigger analysis
curl -X POST http://localhost:8000/alerts/analyze

# Mark alert #3 as reviewed
curl -X POST http://localhost:8000/alerts/3/review

Example alert payload

{
  "id": 1,
  "title": "SSH Brute-Force detected from 172.16.254.1",
  "description": "22 failed SSH login attempts from 172.16.254.1. Possible brute-force attack.",
  "level": "high",
  "event_type": "ssh_bruteforce",
  "source_ip": "172.16.254.1",
  "timestamp": "2026-05-17T09:00:21",
  "status": "new",
  "raw_line": "May 17 09:00:21 webserver sshd[4020]: Failed password for root from 172.16.254.1 port 11129 ssh2"
}

---

Running Tests

pytest tests/ -v

Expected output:

tests/test_parser.py::test_parse_valid_ssh_fail    PASSED
tests/test_parser.py::test_parse_invalid_user      PASSED
tests/test_parser.py::test_parse_sudo              PASSED
tests/test_parser.py::test_parse_empty_line        PASSED
tests/test_parser.py::test_parse_malformed_line    PASSED
tests/test_parser.py::test_parse_file_demo         PASSED
tests/test_detector.py::test_detect_ssh_bruteforce PASSED
tests/test_detector.py::test_detect_invalid_user   PASSED
tests/test_detector.py::test_detect_sudo_fail      PASSED
tests/test_detector.py::test_no_bruteforce_below_threshold PASSED
tests/test_detector.py::test_detect_from_sample_logs       PASSED
tests/test_api.py::test_health                     PASSED
tests/test_api.py::test_get_alerts_empty           PASSED
tests/test_api.py::test_stats_empty                PASSED
tests/test_api.py::test_get_alert_not_found        PASSED
tests/test_api.py::test_analyze_and_get_alerts     PASSED

---

Configuration

All settings are loaded from .env (see .env.example):

Variable	Default	Description
LOG_FILE_PATH	sample_logs/auth.log	Path to the log file to monitor
DISCORD_WEBHOOK_URL	(empty)	Discord webhook URL for notifications
SSH_FAIL_THRESHOLD	5	SSH failures before triggering brute-force alert
EVENT_SPIKE_THRESHOLD	20	Events in window before spike alert
EVENT_SPIKE_WINDOW_SECONDS	60	Time window for spike detection (seconds)
DATABASE_URL	sqlite:///./cybersentinel.db	SQLAlchemy database URL
API_PORT	8000	Listening port

---

Project Structure

cybersentinel/
├── app/
│   ├── main.py              # FastAPI entrypoint
│   ├── config.py            # Settings (pydantic-settings)
│   ├── database.py          # SQLAlchemy engine + session
│   ├── models.py            # Alert ORM model
│   ├── schemas.py           # Pydantic schemas
│   ├── services/
│   │   ├── log_parser.py    # Regex-based auth.log parser
│   │   ├── detector.py      # Detection rules engine
│   │   ├── notifier.py      # Discord webhook notifier
│   │   └── file_monitor.py  # Analysis orchestrator
│   ├── routes/
│   │   ├── alerts.py        # /alerts endpoints
│   │   ├── stats.py         # /stats endpoint
│   │   └── health.py        # /health endpoint
│   └── templates/
│       └── dashboard.html   # Web UI
├── sample_logs/
│   └── auth.log             # Demo log file
├── tests/
│   ├── test_parser.py
│   ├── test_detector.py
│   └── test_api.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── LICENSE

---

Roadmap

• V1 — Log parsing, detection, REST API, dashboard, Docker, Discord notifications
• V2 — Real-time file watching (watchdog) with automatic analysis on new log lines
• V3 — Firewall integration (iptables/ufw) — optional IP blocking with admin confirmation
• V4 — PDF report generation per time period
• V5 — Risk scoring per IP/user across sessions
• V6 — Admin authentication (JWT)
• V7 — Multi-agent support (monitor several machines from one dashboard)
• V8 — MITRE ATT&CK tactic tagging per alert

---

Legal & Ethical Disclaimer

CyberSentinel is a strictly defensive security tool.

• It only reads log files — it does not modify system state, send network packets, or interact with other machines.
• It does not perform brute-force, scanning, exploitation, or any offensive security operation.
• It is intended for use on systems you own or are authorized to monitor.
• Unauthorized use on systems you do not own may violate local laws (CFAA, GDPR, etc.).

The author accepts no liability for misuse of this software.

---

License

MIT License — Copyright (c) 2026 K413MP3R4

See LICENSE for full text.