Skip to content

README.md

Latest commit

 

History

History
355 lines (270 loc) · 10.5 KB

README.md

File metadata and controls

355 lines (270 loc) · 10.5 KB
Raw

🐧 Linux Usage Activity Data Visualizer

A comprehensive real-time system monitoring and data visualization platform for Linux systems with advanced security controls and privacy protection.

Python Django License Platform

🌟 Overview

Transform your Linux system into a powerful activity monitoring dashboard with real-time insights, security monitoring, and beautiful data visualizations. Track application usage, monitor system resources, detect security threats, and analyze productivity patterns - all while maintaining complete privacy and control over your data.

✨ Key Features

📊 Comprehensive Monitoring

  • Real-time Process Tracking - Monitor all running applications with CPU/memory usage
  • Application Usage Analytics - Track time spent in different applications with categorization
  • System Resource Monitoring - CPU, memory, disk, and network usage with live charts
  • Window Activity Detection - X11/Wayland support for active window tracking
  • Network Connection Analysis - Process-to-connection mapping with privacy controls

🔒 Security & Privacy

  • Security Event Detection - Automatic alerts for suspicious processes and activities
  • Privacy-First Design - Sensitive data automatically hashed and protected
  • Local Data Storage - All data stays on your machine, no external communications
  • Configurable Monitoring - Enable/disable specific monitoring features
  • Data Retention Controls - Automatic cleanup with configurable retention periods

🎨 Modern Dashboard

  • Animated Web Interface - Beautiful, responsive dashboard with smooth animations
  • Real-time Visualizations - Interactive charts using Plotly.js and Chart.js
  • Mobile Responsive - Works seamlessly on desktop and mobile devices
  • Dark/Light Themes - Modern glassmorphism design with gradient backgrounds
  • Live Updates - Real-time data refresh every 5-10 seconds

🛠️ Developer Features

  • RESTful API - Comprehensive endpoints for data access and integration
  • Django Framework - Robust backend with SQLite database
  • Extensible Architecture - Easy to add custom monitoring features
  • Multi-Distribution Support - Ubuntu, Fedora, Arch, CentOS, openSUSE
  • Docker Ready - Containerization support for easy deployment

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/Fahad-Al-Maashani/Linux_usageActivity_DataVisualizer.git
cd Linux_usageActivity_DataVisualizer

2. Automated Setup (Recommended)

chmod +x linux_setup.sh
./linux_setup.sh

3. Start Services

# Activate virtual environment
source venv/bin/activate

# Terminal 1: Start web dashboard
python manage.py runserver 0.0.0.0:8000

# Terminal 2: Start system monitoring
python manage.py start_linux_monitor --privacy-mode

4. Access Dashboard

Open your browser and navigate to: http://localhost:8000

📋 System Requirements

Supported Linux Distributions

  • Ubuntu 20.04+ / Debian 11+
  • Fedora 38+ / CentOS 8+
  • Arch Linux / Manjaro
  • openSUSE Leap/Tumbleweed

Dependencies

  • Python 3.8+
  • X11 or Wayland display server
  • xdotool (for X11 window detection)
  • Network tools (net-tools, lsof)

Recommended Specifications

  • 2+ CPU cores
  • 4GB+ RAM
  • 1GB available disk space
  • Active desktop environment

🔧 Installation Methods

Method 1: Automated Setup

The linux_setup.sh script handles everything automatically:

  • Detects your Linux distribution
  • Installs required system dependencies
  • Sets up Python virtual environment
  • Configures permissions and security
  • Creates optional systemd service

Method 2: Manual Installation

Click to expand manual installation steps

Install System Dependencies

Ubuntu/Debian:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv xdotool x11-utils wmctrl net-tools lsof htop build-essential python3-dev libx11-dev libxtst-dev sqlite3

Fedora/CentOS:

sudo dnf install -y python3 python3-pip xdotool x11-utils wmctrl net-tools lsof htop gcc gcc-c++ python3-devel libX11-devel libXtst-devel sqlite

Arch/Manjaro:

sudo pacman -S --noconfirm python python-pip xdotool xorg-utils wmctrl net-tools lsof htop base-devel libx11 libxtst sqlite

Setup Python Environment

python3 -m venv venv
source venv/bin/activate
pip install django psutil pynput requests beautifulsoup4 pandas matplotlib seaborn plotly python-xlib

Configure Permissions

sudo usermod -a -G input $USER
sudo setcap cap_net_raw+ep $(which python3)

🎯 Usage Examples

Basic Monitoring

# Start with privacy protection
python manage.py start_linux_monitor --privacy-mode

# Disable specific monitoring
python manage.py start_linux_monitor --no-network --no-input

# Custom data retention (7 days)
python manage.py start_linux_monitor --retention-days 7

Production Deployment

# Install as systemd service
sudo systemctl enable activity-monitor
sudo systemctl start activity-monitor

# Use gunicorn for production
pip install gunicorn
gunicorn data_visualization_website.wsgi:application --bind 0.0.0.0:8000

📊 Dashboard Screenshots

Main Dashboard

  • Real-time system resource monitoring
  • Application usage analytics with beautiful charts
  • Network activity visualization
  • Productivity trends and insights

Security Dashboard

  • Live security event monitoring
  • Suspicious process detection
  • Network connection analysis
  • Resource abuse alerts

🔌 API Documentation

Core Endpoints

# System monitoring data
GET /api/linux-system-data/

# Security dashboard
GET /api/linux-security-dashboard/

# Real-time statistics  
GET /api/real-time-stats/

# Usage overview
GET /api/usage-overview/

# Productivity analysis
GET /api/productivity-analysis/

Example API Usage

import requests

# Get system monitoring data
response = requests.get('http://localhost:8000/api/linux-system-data/')
data = response.json()

print(f"Monitoring {data['summary']['total_apps']} applications")
print(f"Security events: {data['summary']['security_events']}")

🔒 Security & Privacy

Privacy Controls

  • Data Hashing: Sensitive URLs and file paths automatically hashed
  • Local Storage: No data transmitted to external servers
  • User Permissions: Runs with standard user privileges only
  • Selective Monitoring: Choose exactly what to monitor
  • Data Retention: Automatic cleanup of old data

Security Features

  • Threat Detection: Identifies suspicious processes and activities
  • Resource Monitoring: Alerts for unusual CPU/memory usage
  • Network Analysis: Monitors connections for anomalies
  • Audit Logging: Comprehensive activity logging
  • Access Control: File permissions and group-based security

🛠️ Configuration

Monitoring Settings

# In analytics/linux_system_monitor.py
monitor = LinuxSystemMonitor(
    privacy_mode=True,          # Enable data hashing
    monitor_network=True,       # Track network connections
    monitor_input=True,         # Monitor keyboard/mouse
    max_data_retention_days=30  # Data cleanup period
)

Custom Application Categories

# Add custom categories
self.app_categories = {
    'development': ['code', 'vim', 'pycharm', 'your-custom-app'],
    'work': ['slack', 'teams', 'your-work-apps'],
    'entertainment': ['spotify', 'netflix', 'games'],
    # Add your categories here
}

🐛 Troubleshooting

Common Issues

Permission Errors:

# Add user to required groups
sudo usermod -a -G input,adm $USER
newgrp input  # Refresh group membership

X11 Window Detection Not Working:

# Test X11 access
echo $DISPLAY
xdotool getactivewindow getwindowname

Network Monitoring Issues:

# Set network capabilities
sudo setcap cap_net_raw+ep $(which python3)

Wayland Support:

# Install Wayland tools (for Sway)
sudo apt install sway-utils  # Ubuntu/Debian

Log Files

  • Monitor logs: analytics/linux_monitor.log
  • Django logs: Console output
  • System logs: /var/log/syslog (for system events)

🤝 Contributing

We welcome contributions! Here's how to get started:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and test thoroughly
  4. Commit your changes: git commit -m 'Add amazing feature'
  5. Push to the branch: git push origin feature/amazing-feature
  6. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/your-username/Linux_usageActivity_DataVisualizer.git

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python manage.py test

# Start development server
python manage.py runserver

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚖️ Legal & Privacy Notice

This software is designed for legitimate system monitoring and administration purposes. Users are responsible for:

  • ✅ Obtaining proper authorization before monitoring any system
  • ✅ Complying with local privacy and data protection laws
  • ✅ Using the software ethically and responsibly
  • ❌ Not using it for unauthorized surveillance or data collection

🙏 Acknowledgments

  • Django Framework - Web application framework
  • Plotly.js - Interactive data visualization
  • psutil - System and process monitoring
  • pynput - Input device monitoring
  • Linux Community - For the amazing open-source ecosystem

📞 Support

  • Documentation: Check the LINUX_README.md for detailed setup instructions
  • Issues: Report bugs and request features via GitHub Issues
  • Discussions: Join community discussions for help and ideas

🔗 Related Projects

⭐ Star this repository if you find it useful!

Made with ❤️ for the Linux community

🚀 Generated with Claude Code