LightScope Logo

LightScope

Threat intelligence based upon work supported by the U.S. National Science Foundation under Grant No. 2313998 and the University of Southern California Information Sciences Institute.

Home Installation Technical Details FAQs Dashboard

Installation Guide

Ubuntu Installation

Follow these steps to install LightScope on Ubuntu:

1. Install Dependencies and LightScope

sudo apt-get update
sudo apt install -y libpcap-dev
sudo apt-get install python3-virtualenv
python3 -m virtualenv LightScope_virtual_env
source LightScope_virtual_env/bin/activate
pip install lightscope==0.0.60

2. Configure Python Permissions and Run LightScope

sudo setcap 'cap_net_raw,cap_net_admin+eip' "$(readlink -f "$(which python)")"
getcap "$(readlink -f $(which python))"
lightscope &

ℹ️ The getcap command verifies that the proper capabilities were set. The output should show the capabilities that were just set.

Windows Installation

Follow these steps to install LightScope on Windows:

1. Prerequisites

  • Make sure Python 3 is installed (you can download it from python.org)
  • Ensure pip is installed (it should be included with your Python installation)

2. Install Npcap

  1. Download Npcap from https://npcap.com/#download
  2. Select "Npcap 1.81 installer for Windows 7/2008R2, 8/2012, 8.1/2012R2, 10/2016, 2019, 11 (x86, x64, and ARM64)"
  3. During installation, make sure you select "Install Npcap in WinPcap API-compatible Mode" (should be selected by default)

3. Install and Run LightScope

python -m venv here
here\Scripts\activate
pip install lightscope==0.0.60
lightscope

⚠️ After running LightScope, you can minimize the terminal window - just let it continue running!

macOS Installation

Follow these steps to install LightScope on macOS:

1. Create Virtual Environment and Install LightScope

python3 -m venv LightScope_virtual_env
source LightScope_virtual_env/bin/activate
cd LightScope_virtual_env
pip install lightscope==0.0.60

2. Run LightScope

sudo lightscope &

⚠️ LightScope requires sudo privileges to capture network traffic. You will be prompted for your password.

Verifying Installation

To verify that LightScope is running correctly:

  1. After starting LightScope, it will capture unwanted TCP traffic on your network
  2. LightScope runs in the background and sends anonymized data about unwanted traffic to the central server
  3. You can view the collected data on the Dashboard page (you'll need your unique database identifier)

Troubleshooting

  • Ubuntu: If you see "Operation not permitted" errors, make sure you've set the proper capabilities with setcap
  • Windows: If you encounter permission issues, try running the command prompt as Administrator
  • macOS: If you see "Permission denied" errors, ensure you're using sudo when running LightScope
  • All platforms: If LightScope fails to start, check that you have the required dependencies installed

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.