Skip to content

andrrei509/security_hub

BranchesTags

Repository files navigation

Kernel Rootkit Detector

Linux kernel integrity monitoring system with real-time scanning, analytics dashboard, and automated threat detection.

Rust Python Django SQLite Docker Bash Nginx Chart.js Tests CI/CD Systemd Make License

Table of Contents

Overview

The Kernel Rootkit Detector is a security monitoring platform that uses the Linux tool chkrootkit to perform automated rootkit scans on the host system. Results are stored in a SQLite database and visualized through a web dashboard built with Django.

This project demonstrates the integration of operating system-level Linux commands with a full-stack web application, combining:

  • Subprocess management for running privileged system commands
  • Background threading for automated periodic scanning
  • Bash scripting for system monitoring and file integrity checking
  • Web-based analytics with real-time data visualization
  • Containerized deployment via Docker and Docker Compose

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        BROWSER                              │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  HTML5 / CSS3 / JavaScript / Chart.js               │   │
│   │  ├── Login Page (glassmorphism UI)                  │   │
│   │  ├── Dashboard (stats, charts, tables, modals)      │   │
│   │  └── Auto-refresh via AJAX polling (30s)            │   │
│   └─────────────────────┬───────────────────────────────┘   │
└─────────────────────────┼───────────────────────────────────┘
                          │ HTTP/HTTPS
┌─────────────────────────┼───────────────────────────────────┐
│  NGINX (Reverse Proxy)  │  Port 80                          │
│  ├── Static file serving │  (/static/)                      │
│  └── Proxy pass          ▼  (/ → Django:8000)               │
├─────────────────────────────────────────────────────────────┤
│  DJANGO WEB SERVER          Port 8000                       │
│  ├── Authentication (login/logout/session)                  │
│  ├── Views (dashboard, API endpoints)                       │
│  ├── ORM (ScanResult model → SQLite)                        │
│  └── Background Scanner Thread (60s interval)               │
├─────────────────────────────────────────────────────────────┤
│  PYTHON SUBPROCESS LAYER                                    │
│  ├── scanner.py → subprocess.run(['sudo', 'chkrootkit'])    │
│  ├── /proc/meminfo, /proc/uptime, /proc/loadavg parsing     │
│  └── platform, shutil modules for system metrics            │
├─────────────────────────────────────────────────────────────┤
│  BASH SCRIPTS (scripts/)                                    │
│  ├── system_monitor.sh   → CPU, RAM, disk, network JSON     │
│  ├── file_integrity_check.sh → SHA-256 baseline/verify      │
│  └── network_audit.sh   → ports, connections, firewall      │
├─────────────────────────────────────────────────────────────┤
│  DATABASE LAYER                                             │
│  └── SQLite3 (db.sqlite3)                                   │
│      ├── dashboard_scanresult (scan history)                │
│      ├── auth_user (admin accounts)                         │
│      └── django_session (session store)                     │
├─────────────────────────────────────────────────────────────┤
│  LINUX KERNEL / OS                                          │
│  ├── chkrootkit (rootkit detection)                         │
│  ├── /proc filesystem (system metrics)                      │
│  ├── ss, ip, df, nproc (network/disk utilities)             │
│  └── sha256sum (file integrity)                             │
└─────────────────────────────────────────────────────────────┘

Technology Stack

Layer Technology Purpose
Backend Python 3.12 Core application language
Integrity Engine Rust High-performance parallel SHA-256 file hashing
Web Framework Django 6.0 MVC architecture, ORM, auth, templating
Database SQLite3 (SQL) Persistent storage for scan results
Frontend HTML5, CSS3, JavaScript Dashboard UI with dark/light theme
Charts Chart.js 4.x Bar charts and doughnut visualizations
Fonts Google Fonts (Inter, JetBrains Mono) Typography
OS Tools chkrootkit Linux rootkit detection scanner
Scripting Bash (.sh) System monitoring, integrity checks, network audit
Containerization Docker, Docker Compose Application deployment
Web Server Nginx Reverse proxy, static file serving
Automation Make (Makefile) Project task automation (20+ targets)
Testing Django TestCase 27 unit tests with mocking
CI/CD GitHub Actions 4-job pipeline (test, lint, bash, docker)
Deployment Systemd, Cron, Logrotate Linux daemon, scheduled tasks, log rotation
Security SHA-256, subprocess File integrity, process isolation

Features

Security & Scanning

  • Automated chkrootkit scans every 60 seconds via background thread (hardened against memory leaks and race conditions)
  • Instant Webhook Alerts: Real-time HTTP POST notifications triggered on INFECTED scan detection
  • Rust Integrity Engine: High-performance, multi-threaded binary compiled in Rust (rayon + sha2) to perform rapid SHA-256 baseline generation and continuous verification of critical Linux binaries.
  • Network security auditing: open ports, suspicious activity (Bash)
  • Active Threat Defense: Automated port scan detection and real-time IP blocking using iptables
  • Automated Network Quarantine: Immediately drops all non-essential traffic (allowing only SSH and Dashboard) upon INFECTED scan detection using iptables
  • System metrics collection from /proc filesystem (Bash)

Dashboard & Analytics

  • Live Terminal Streaming: Interactive dashboard console executing and streaming manual chkrootkit scans in real-time
  • Interactive Process Forensics Graph: Uses vis-network to visualize a live, perpetually animated hierarchy of the system's process tree with four visual classifications: suspicious (red), user-owned (cyan), critical (amber), and system/root (grey)
  • Process Executioner: Targeted threat elimination. Only processes matching the suspicious signature whitelist (nc, ncat, netcat, socat, cryptominer, xmrig, miner) can be terminated via SIGKILL. All other processes are view-only with appropriate shield/lock indicators. Features dust particle disintegration animation on successful kill
  • Advanced CSV Export: Intercepted options modal for dataset filtering and custom file naming
  • 5 Summary stat cards with animated counters
  • Bar chart showing scan history timeline (Chart.js)
  • Doughnut chart for clean vs infected ratio
  • Live system info panel with memory/disk progress bars
  • Paginated data table with search and status filter
  • Modal viewer for historical raw chkrootkit terminal output

UI/UX

  • Dark mode with cyber-security color palette
  • Light theme toggle with localStorage persistence
  • Glassmorphism cards with backdrop blur effects
  • Critical Threat Alert Modal with dynamic pulsing animations for active infections
  • Animated background grid
  • Toast notifications for user actions
  • Keyboard shortcuts (R, S, F, E, T, Esc)
  • Live clock showing DD-MON-YYYY format
  • Fully responsive design (desktop → mobile)

Authentication

  • GitHub OAuth SSO: Enterprise-grade Single Sign-On integration via social-auth-app-django
  • Secure credential management via .env files
  • Django session-based login system
  • Login-protected dashboard and API endpoints
  • Admin user management via Django admin panel

Project Structure

security_hub/
├── manage.py                          # Django management script
├── Makefile                           # Project automation (make commands)
├── Dockerfile                         # Container image definition
├── docker-compose.yml                 # Multi-container orchestration
├── nginx.conf                         # Nginx reverse proxy config
├── requirements.txt                   # Python dependencies
├── .dockerignore                      # Docker build exclusions
├── db.sqlite3                         # SQLite database (auto-generated)
│
├── security_hub/                      # Django project config
│   ├── settings.py                    # Project settings
│   ├── urls.py                        # Root URL routing
│   ├── wsgi.py                        # WSGI entry point
│   └── asgi.py                        # ASGI entry point
│
├── dashboard/                         # Main Django application
│   ├── models.py                      # ScanResult database model
│   ├── views.py                       # View functions & API endpoints
│   ├── urls.py                        # App URL routing
│   ├── scanner.py                     # chkrootkit subprocess wrapper
│   ├── apps.py                        # Background scheduler thread
│   ├── admin.py                       # Django admin registration
│   ├── fix_dates.py                   # Database seeding script
│   ├── static/
│   │   └── dashboard/
│   │       ├── css/style.css          # Complete design system (900+ lines)
│   │       └── js/dashboard.js        # Charts, AJAX, themes, shortcuts
│   └── templates/
│       └── dashboard/
│           ├── login.html             # Animated login page
│           └── dashboard.html         # Main analytics dashboard
│
└── scripts/                           # Bash security scripts
    ├── system_monitor.sh              # OS metrics collector (JSON output)
    ├── file_integrity_check.sh        # SHA-256 binary integrity checker
    └── network_audit.sh               # Network security auditor

Quick Start

Prerequisites

  • Python 3.10+
  • Linux (Ubuntu/WSL recommended)
  • chkrootkit installed: sudo apt install chkrootkit

Installation

# Clone or navigate to the project
cd ~/security_hub

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install django

# Full setup (migrate + create admin + seed data)
make setup

# Start the server
make run

Then open http://localhost:8000/dashboard/ and log in with admin / admin123.

Accessing on Other Devices (Local Network)

To test the dashboard on your phone or other devices connected to the same Wi-Fi network, you have two options depending on your OS.

Option A: Direct Local IP

  1. Find your computer's local network IP address:
    • On Linux/macOS: Run hostname -I or ip addr (e.g., 192.168.1.10)
    • On Windows: Run ipconfig in Command Prompt and look for the Wi-Fi IPv4 Address.
  2. Ensure your firewall allows inbound traffic on port 8000.
  3. Open the browser on your phone/device and navigate to: http://<YOUR_IP_ADDRESS>:8000/dashboard/

Option B: For WSL (Windows Subsystem for Linux) Users

Because WSL runs in an isolated virtual network behind NAT, your phone cannot connect directly to the WSL IP. The easiest way to test from your phone is to expose the local server using a secure public tunnel via npx:

  1. Keep your Django server running (make run) in one terminal.
  2. Open a new terminal window in the same folder and run: 
    npx localtunnel --port 8000
  3. It will generate a public URL (e.g., https://random-words.loca.lt).
  4. Open that URL on your phone to view your dashboard!

Note: If your server is already running, you will need to restart make run so the new ALLOWED_HOSTS configuration is loaded.

Docker Deployment

# Build and run with Docker Compose
make docker-up

# Or manually:
docker compose up --build -d

# View logs
make docker-logs

# Stop
make docker-down

The app will be available at:

Makefile Commands

Command Description
make help Show all available commands
make setup Full project setup (migrate + superuser + seed)
make run Start Django development server
make migrate Create and apply database migrations
make seed Seed database with sample scan data
make superuser Create admin superuser
make resetdb Delete and recreate database from scratch
make scan Run a manual chkrootkit scan
make monitor Run system monitoring script (Bash)
make integrity-baseline Generate file integrity baseline
make integrity-check Check file integrity against baseline
make network Run network security audit
make docker-up Build and start Docker containers
make docker-down Stop Docker containers
make info Display project tech stack summary
make clean Remove cache and build artifacts

Bash Security Scripts

System Monitor

bash scripts/system_monitor.sh
# Outputs JSON: hostname, kernel, CPU, memory, disk, network, processes

Rust File Integrity Checker

cd scripts/rust_integrity
cargo build --release

# Create a baseline of critical binary checksums
./target/release/rust_integrity --baseline

# Verify binaries against the baseline
./target/release/rust_integrity --check

Network Auditor

bash scripts/network_audit.sh
# Checks: open ports, connections, promiscuous mode, suspicious ports, firewall
# Actively detects port scans (>15 ports/IP) and automatically deploys iptables DROP rules (with safe-listing)

API Endpoints

Method Endpoint Description
GET /dashboard/ Main dashboard page
GET /dashboard/login/ Login page
POST /dashboard/login/ Authenticate user
GET /dashboard/logout/ Logout and redirect
GET /dashboard/api/stats/ Dashboard summary stats (JSON)
GET /dashboard/api/chart-data/ Chart.js dataset (JSON)
GET /dashboard/api/scan/<id>/ Individual scan details (JSON)
GET /dashboard/api/system-info/ Live system metrics (JSON)
GET /dashboard/export-csv/ Download scan history as CSV
POST /dashboard/trigger-scan/ Manually trigger a scan
GET /dashboard/api/forensics/ Process tree graph data (JSON)
POST /dashboard/api/forensics/kill/ Send SIGKILL to a process by PID

Demo: Simulating a Suspicious Process

To demonstrate the Process Executioner and suspicious process detection in the Forensics Graph, spawn a fake threat process in a separate terminal:

# Spawns a harmless sleep process disguised as 'nc' (netcat)
# The forensics graph will flag it as SUSPICIOUS (red node)
(exec -a nc sleep 300) &

# Or simulate a crypto miner signature
(exec -a cryptominer sleep 300) &

# Or a reverse shell indicator
(exec -a ncat sleep 300) &

Then open the Forensics Graph (press F) and you will see the red suspicious node. Click it and hit Terminate (SIGKILL) to watch the dust particle disintegration.

Date Format

All dates throughout the application use the format DD-MON-YYYY as required:

10-MAY-2026
10-MAY-2026 14:32:07

Authors

University Operating Systems Project

License

This project is developed for educational purposes.

About

An OS security platform. Integrates native Linux tools (chkrootkit, iptables, inotify) with a containerized Django analytics dashboard.

Topics

bash docker django python3 webapp

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages