🛡️ tinySIEM

A lightweight, real-time Sysmon event monitor and web dashboard for Windows.

tinySIEM reads from the Windows Event Log (Microsoft-Windows-Sysmon/Operational), streams events via Server-Sent Events to a modern browser-based dashboard, and lets you filter, search, and analyze system activity in real time.

---

✨ Features

Feature	Description
Real-time Streaming	Events are pushed to the browser via SSE — no polling, no refresh needed.
Interactive Event Table	Sortable, paginated table with per-column filters for Event ID, Process, User, and Event Info.
Event Volume Chart	Live Chart.js visualization of event frequency over time.
Global Search	Full-text filter across all event fields.
Dark / Light Mode	Toggle between themes with system preference detection.
Quick Start Modal	Configure how much history to load — by event count or timeframe.
Restart Monitor	Reconfigure and restart the monitor without reloading the page.
One-Click Launch	run.ps1 handles admin elevation, venv creation, dependency install, and browser launch.

---

📋 Prerequisites

• Windows 10 / 11 / Server — relies on the Windows Event Log API.
• Sysmon installed and running.
• Python 3.8+ — installed and available in your PATH.
• Administrator Privileges — required to read the Sysmon event channel.

---

🚀 Quick Start

# Clone the repository
git clone https://github.com/yourusername/tinysiem.git
cd tinysiem

# Run the app (handles everything automatically)
.\run.ps1

That's it. The script will:

1. ⬆️ Request Administrator privileges (UAC prompt)
2. 📦 Create a Python virtual environment if one doesn't exist
3. 📥 Install dependencies from requirements.txt
4. 🌐 Launch the Flask server on http://localhost:5000
5. 🖥️ Open your default browser after 5 seconds

Tip

On subsequent runs, the venv is reused — startup is near-instant.

---

🖥️ Usage

1. Start Monitoring — when the app launches, a Quick Start modal lets you choose:

   • Event Count — load the last N events (default: 500)
   • Timeframe — load events from the last N minutes/hours/days (e.g. 30m, 2h, 1d)

2. Filter Events — click the ⏷ filter icon on any column header to filter by specific values, or use the Global Filter search box in the top bar.

3. Toggle Live Mode — use the Live toggle in the nav bar to pause/resume the real-time event stream.

4. Chart — toggle the event volume chart on/off with the Chart switch.

5. Restart — click Restart to reconfigure the monitor (change count/timeframe) without a full page reload.

---

🏗️ Architecture

tinySIEM
├── server/                # Python backend package
│   ├── __init__.py        # Flask app factory
│   ├── __main__.py        # Entry point (python -m server)
│   ├── config.py          # App configuration constants
│   ├── monitor.py         # Sysmon event reader & subscriber (win32evtlog)
│   ├── event_parser.py    # XML → dict event parser
│   ├── client_manager.py  # SSE client manager with broadcast & history buffer
│   ├── routes.py          # Flask routes (Blueprint)
│   └── utils.py           # Admin privilege check utilities
├── run.ps1                # One-click launcher (elevation + venv + deps)
├── requirements.txt       # Runtime dependencies (Flask, pywin32)
├── requirements-dev.txt   # Build tool dependencies
├── templates/
│   └── index.html         # Dashboard SPA (Tailwind CSS + Chart.js)
└── static/
    ├── css/style.css      # Custom styles
    ├── js/                # Modular frontend (app, chart, constants, events, filters, table, tooltip, startup, stats, processtree, utils)
    └── lib/               # Vendored libraries (Tailwind, Chart.js, D3.js, Font Awesome, Google Fonts)

Data Flow

┌──────────────────────────────────────────────────────────────────────────────┐
│  Windows Event Log                                                         │
│  Microsoft-Windows-Sysmon/Operational                                      │
└──────────────┬───────────────────────────────────┬───────────────────────── ┘
               │ Historical events                 │ New events (subscription)
               │ (EvtQuery + EvtNext)              │ (EvtSubscribe callback)
               ▼                                   ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  SysmonMonitor  (monitor.py)                                               │
│  ┌─────────────────────┐    ┌──────────────────────────┐                   │
│  │  read_past_events() │    │  _on_event() callback    │                   │
│  │  (count / timeframe)│    │  (real-time push)        │                   │
│  └─────────┬───────────┘    └────────────┬─────────────┘                   │
│            └──────────────┬──────────────┘                                 │
│                           ▼                                                │
│              ┌────────────────────────┐                                    │
│              │  EventParser.parse()   │                                    │
│              │  XML ──► Python dict   │                                    │
│              └────────────┬───────────┘                                    │
└───────────────────────────┼────────────────────────────────────────────────┘
                            ▼
               ┌────────────────────────┐
               │  Thread-Safe Queue     │
               │  (maxsize=5000)        │
               └────────────┬───────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  Distributor Thread  (app.py)                                              │
│  Moves events from queue ──► ClientManager                                 │
└───────────────────────────┬──────────────────────────────────────────────── ┘
                            ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  ClientManager  (socket_service.py)                                        │
│  ┌──────────────────┐    ┌─────────────────────────────────────────┐       │
│  │  History Buffer   │    │  Broadcast to connected clients        │       │
│  │  (deque, last 500)│    │                                        │       │
│  └──────────────────┘    │  Client 1 Queue ──► SSE /stream ──► 🌐 │       │
│                          │  Client 2 Queue ──► SSE /stream ──► 🌐 │       │
│                          │  Client N Queue ──► SSE /stream ──► 🌐 │       │
│                          └─────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  Browser Dashboard  (index.html + JS modules)                              │
│  ┌──────────┐  ┌──────────────┐  ┌──────────┐  ┌───────────────────────┐  │
│  │ EventSrc │  │ Event Table  │  │ Chart.js │  │ Filters / Search      │  │
│  │ listener │─►│ (paginated)  │  │ (volume) │  │ (ID, Process, User…)  │  │
│  └──────────┘  └──────────────┘  └──────────┘  └───────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘

1. SysmonMonitor reads historical events and subscribes to new ones via win32evtlog.
2. Parsed events are placed into a thread-safe queue.
3. A distributor thread moves events from the queue to ClientManager.
4. ClientManager broadcasts to all connected SSE clients and maintains a history ring buffer so new clients receive recent events immediately.

---

⚙️ Configuration

Edit config.py to adjust defaults:

class Config:
    LOG_TYPE = 'Microsoft-Windows-Sysmon/Operational'  # Event channel
    HISTORY_SIZE = 500          # Events kept in memory for new clients
    MONITOR_QUEUE_SIZE = 5000   # Internal queue capacity
    DEBUG = True                # Flask debug mode
    HOST = '0.0.0.0'           # Listen on all interfaces
    PORT = 5000                 # Web server port

---

🛠️ Development

# Manual setup (if not using run.ps1)
python -m venv venv
.\venv\Scripts\Activate
pip install -r requirements.txt

# Run with auto-reload disabled (required for threading)
python -m server

Note

The Flask reloader is intentionally disabled (use_reloader=False) because the app uses background threads for event monitoring. Hot-reload would restart those threads unexpectedly.

---

📦 Building a Standalone Executable

The project includes build scripts for packaging as a standalone .exe:

Script	Tool
build_pyinstaller.ps1	PyInstaller
build_nuitka.ps1	Nuitka
build_cx.ps1	cx_Freeze

---

🐛 Troubleshooting

Problem	Solution
UAC prompt denied	Right-click run.ps1 → Run with PowerShell, then accept the elevation prompt.
"Python is not installed or not in PATH"	Install Python 3.8+ and ensure Add to PATH is checked.
"App script not found"	Make sure you're running run.ps1 from the project root directory.
No events appear	Verify Sysmon is installed and running: sc query Sysmon or sc query Sysmon64.
Port 5000 already in use	Change PORT in config.py or stop the other process using port 5000.
pip install fails with connection error	Check your internet connection. A firewall or proxy may be blocking PyPI.

---

📄 License

This project is licensed under the MIT License.