Installation Guide
LightScope is available for multiple operating systems
Choose Your Operating System
Linux Installation
LightScope is available as pre-built packages for all major Linux distributions:
Linux Downloads
Download the latest LightScope packages for Linux:
After downloading, install using the commands below or your package manager.Debian/Ubuntu (.deb)
wget https://thelightscope.com/latest/lightscope_latest.deb && sudo apt install -v -y ./lightscope_latest.deb
ℹ️ The -v
flag provides verbose output and -y
automatically confirms installation. This will install all dependencies and start the LightScope service.
RHEL/Fedora/CentOS (.rpm)
wget https://thelightscope.com/latest/lightscope_latest.rpm && sudo dnf install -v -y ./lightscope_latest.rpm
ℹ️ For older systems without DNF, use: sudo yum install -y ./lightscope_latest.rpm
. The -v
flag provides verbose output and -y
automatically confirms installation. This will install all dependencies and start the LightScope service.
After Installation (If Needed)
- Service Status:
sudo systemctl status lightscope
- View Logs:
sudo journalctl -u lightscope -f
- Restart Service:
sudo systemctl restart lightscope
- Find Your Database Name & Dashboard URL:
sudo systemctl status lightscope
- look for your dashboard URL in the Docs line!
✅ LightScope runs securely as a system service with minimal privileges.
systemctl status
:
● lightscope.service - LightScope Network Security Monitor
Docs: https://thelightscope.com
https://thelightscope.com/tables/20250629_gvzdkbinpryhdrszsdzufpoeejxmoyhngrrjrjrxodfsuwf
Verifying Linux Installation
To verify that LightScope is running correctly on Linux:
- Check service status:
sudo systemctl status lightscope
should show "active (running)" - Monitor network activity: LightScope automatically captures unwanted TCP traffic on your network
- View logs: Use
sudo journalctl -u lightscope -f
to see live activity - Dashboard access: Visit the Dashboard page to enter your unique database name and access your personalized threat intelligence
✅ LightScope automatically starts after installation and runs securely as a system service with minimal privileges.
How Does Linux Installation Work?
Security was our top priority when designing LightScope's installation and operation. Here's what happens during installation:
🔒 Security-First Architecture
- Dedicated System User: Creates a low-privilege system user called
lightscope
with no shell access - No Root Privileges: LightScope never runs as root - the service operates with minimal system privileges
- Linux Capabilities: Instead of root access, we grant only the specific network capabilities needed:
CAP_NET_RAW
- Raw socket access for packet captureCAP_NET_ADMIN
- Network interface managementCAP_NET_BIND_SERVICE
- Bind to network services
- Filesystem Isolation: Protected system files, isolated temporary directories, and restricted file access
⚙️ Installation Process
- System Dependencies: Installs required libraries (libpcap-devel, python3-devel, etc.)
- User Creation: Creates the
lightscope
system user with home directory/opt/lightscope
- Directory Structure: Sets up secure directories for configuration, logs, and updates
- Python Environment: Configures Python with network capabilities (no root needed)
- Systemd Service: Installs and enables the
lightscope
service for automatic startup - Security Hardening: Applies filesystem protections and capability restrictions
- Service Start: Automatically starts monitoring network traffic
🛡️ Runtime Security Features
- Privilege Separation: Runs as unprivileged
lightscope
user, not root - Minimal Attack Surface: Only network inspection capabilities, no system administration rights
- Automatic Restart: Systemd monitors and restarts the service if needed
- Secure Logging: All activity logged to systemd journal with proper permissions
- Resource Limits: Built-in limits on memory, file handles, and system resources
🔄 Secure Automatic Updates
LightScope includes a secure automatic update system designed with security as the top priority:
- Hourly Update Checks: Automatically checks for new versions every hour from
https://thelightscope.com
- Cryptographic Signatures: All updates are signed with RSA-4096 cryptographic signatures before distribution
- Signature Verification: Every update is cryptographically verified before installation - unsigned updates are rejected
- HTTPS-Only Downloads: All update downloads use encrypted HTTPS connections to prevent tampering
- Public Key Pinning: The public verification key is stored locally and validated to prevent key substitution attacks
- Backup System: Previous versions are automatically backed up before applying updates
- Rollback Protection: If an update fails verification or causes issues, the system can rollback to the previous version
- Update Logs: All update activity is logged to the systemd journal for audit purposes
lightscope
user and cannot modify system files outside of /opt/lightscope
.
🛑 Stopping and Uninstalling LightScope
To stop LightScope temporarily:
sudo systemctl stop lightscope
To disable auto-start (but keep installed):
sudo systemctl disable lightscope
To completely uninstall LightScope:
sudo systemctl stop lightscope
sudo apt remove lightscope
sudo apt purge lightscope # Removes config files too
sudo systemctl stop lightscope
sudo yum remove lightscope
# or: sudo dnf remove lightscope
Manual cleanup (if needed):
# Remove user and home directory
sudo userdel -r lightscope
# Clean up any remaining files
sudo rm -rf /opt/lightscope
ℹ️ The package manager handles cleanup automatically, but manual commands are provided for reference.
🔧 Linux Troubleshooting
- Service not starting: Check service status with
sudo systemctl status lightscope
- Permission issues: The package automatically configures proper permissions and capabilities
- Package conflicts: If installation fails, try
sudo apt update
(Debian/Ubuntu) orsudo yum update
(RHEL/CentOS) - Network issues: Ensure your firewall allows the LightScope service to monitor network traffic
- View detailed logs: Use
sudo journalctl -u lightscope -f
to see real-time service logs
Windows Installation
LightScope is available as a Windows installer that automatically configures all dependencies:
Windows Download
Download the latest LightScope installer for Windows:
Compatible with Windows 10 and Windows 11. Follow the installation steps below.Prerequisites
Before running the LightScope installer, please ensure you have:
- Python 3.8+: Download from python.org
- ⚠️ Important: During Python installation, make sure to check the "Add Python to PATH" option
- This allows LightScope to find Python automatically
- Npcap: Download from nmap.org/npcap
- Required for network packet capture on Windows
- Install with default settings
Installation Steps
- Download: Get the Windows installer from the Direct Downloads section above
- Run Installer: Double-click
lightscope_latest.exe
to launch the installer - Follow Wizard: The installer will guide you through the setup process
- Automatic Start: LightScope will automatically start running in the background
- Firewall Permission: Allow LightScope through Windows Firewall when prompted
✅ LightScope automatically starts with Windows and runs in the background.
Windows Capabilities
- No Administrator Permissions Required: LightScope runs as a standard user application
- No Special Permissions: No special system permissions need to be granted
- Firewall Access Only: The only permission required is allowing through Windows Firewall (happens automatically during installation)
- User-Level Operation: Runs safely in user space without system-level access
Using LightScope on Windows
- Automatic Startup: LightScope runs automatically when Windows starts
- System Tray: Look for the LightScope icon in your system tray (bottom-right corner)
- Access Dashboard: Right-click the LightScope icon and select "View Dashboard" to open your personalized dashboard
- Status Monitoring: The tray icon indicates LightScope is running and monitoring your network
- Quit LightScope: Right-click the tray icon and select "Quit" to stop LightScope
Visual Guide:

Step 1: Look for the LightScope icon in your system tray

Step 2: Right-click to access dashboard or quit LightScope
Uninstalling LightScope on Windows
- Open Settings: Go to Windows Settings > Apps > Apps & features
- Find LightScope: Search for "LightScope" in the app list
- Uninstall: Click on LightScope and select "Uninstall"
- Complete Removal: LightScope will be completely removed from your system
ℹ️ Alternative: Go to Control Panel > Programs and Features > Uninstall a program, then select LightScope.
macOS Installation
LightScope for macOS is currently in development and will be available soon.
Coming Soon
Need Help?
If you encounter any issues during installation or have questions about LightScope, we're here to help!
Contact Support
Email: e@alumni.usc.edu
Response Time: We typically respond within 24 hours

This material is based upon work supported by the U.S. National Science Foundation under Grant No. 2313998. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the U.S. National Science Foundation.