USB-Threat-Monitoring-Tool

A Windows-based USB Threat Monitoring Tool developed to detect and monitor malicious USB activities. below is the dashboard of the tool.

Overview

The USB Threat Monitoring Tool is a Windows-based cybersecurity solution designed to monitor, detect, and respond to potential USB-borne threats in computer laboratory environments. Developed as part of a Bachelor of Science in Cyber Security research project at Kapasa Makasa University (KMU), the system enhances endpoint security by detecting suspicious USB activities using metadata-only analysis, ensuring that file contents are never accessed or scanned.

The application provides monitoring, automated threat detection, secure quarantine capabilities, centralized management, and comprehensive reporting to help administrators protect laboratory computers against removable media threats.

---

Key Features

• Real-time USB device connection and removal detection using Windows hardware events.
• Continuous monitoring of file activities on removable storage devices, including file creation, modification, and movement.
• Rule-based threat detection engine with composite risk scoring, event correlation, and false-positive suppression.
• Unknown-threat detection for identifying suspicious behaviors beyond predefined rules.
• Secure and reversible file quarantine with encrypted audit manifests.
• Encrypted local event logging using Windows DPAPI.
• Centralized server mode for monitoring multiple laboratory workstations.
• SOC-style administrative dashboard built with Tkinter.
• Desktop notifications for high-risk security events.
• Supervisor adjudication workflow for reviewing unknown threats.
• Automated generation of HTML, CSV, and PDF audit reports.

---

System Requirements

Requirement	Details
Operating System	Windows 10 / Windows 11
Python Version	Python 3.10 or later
Dependencies	pywin32 >= 306, watchdog >= 4.0.0, reportlab >= 4.0.0

---

Quick Start

1. Install Dependencies

Using the provided installation script:

scripts\install_deps.bat

Or install manually:

pip install -r requirements.txt

---

2. Select a Deployment Mode

Mode	Command	Description
Server Mode	python main.py server	Starts the central monitoring server for laboratory environments.
Agent Mode	python main.py agent --server http://192.168.10.5:8750	Connects a workstation to the central monitoring server.
Local Mode	python main.py local	Runs the application as a standalone workstation.
Report Mode	python main.py report --format pdf --days 7	Generates security reports in PDF, HTML, or CSV format.

Windows Launcher Scripts

The following batch scripts are included for simplified deployment:

• start_server.bat – Launches the central server.
• start_agent.bat – Starts a workstation agent (configure SERVER_IP first).
• start_local.bat – Launches the standalone monitoring system.
• generate_report.bat – Generates security reports for the previous seven days.
• test_connection.bat – Verifies communication between an agent and the server.

---

Project Structure

usb-threat-monitor/
├── main.py
├── rules_config.json
├── requirements.txt
├── core/
│   ├── monitor_service.py
│   ├── threat_engine.py
│   ├── unknown_threat.py
│   ├── usb_listener.py
│   └── file_watcher.py
├── server/
│   ├── hub.py
│   └── central_store.py
├── agent/
│   └── relay_client.py
├── services/
│   ├── logger.py
│   ├── isolation.py
│   ├── adjudication.py
│   └── report_generator.py
├── gui/
│   ├── dashboard.py
│   ├── notifications.py
│   └── theme.py
├── scripts/
├── tests/
└── docs/
    └── DOCUMENTATION.md

---

Documentation

Detailed project documentation is available in:

docs/DOCUMENTATION.md

The documentation includes:

• System architecture
• Data flow
• Deployment procedures
• Detection rules
• Threat scoring methodology
• Unknown-threat analysis
• HTTP API documentation
• Configuration guide
• Dashboard user guide
• Data storage locations
• Testing procedures
• Troubleshooting guide

---

Testing

Run the threat detection simulation:

python tests\run_simulation.py --verbose

Run the server integration test:

python tests\run_server_test.py

---

Security Design

The USB Threat Monitoring Tool was developed with privacy and security as primary objectives.

• Uses metadata-only analysis without inspecting file contents.
• Protects logs and quarantine manifests using Windows DPAPI encryption.
• Requires authentication through the X-Lab-Token header for server communication.
• Supports secure quarantine and restoration of suspicious files.
• Maintains a complete audit trail for forensic investigations and compliance.

---

Research Contribution

This project was developed as part of an undergraduate research study in Cyber Security at Kapasa Makasa University.

The research focuses on improving laboratory endpoint security by providing an intelligent USB monitoring solution capable of detecting suspicious removable media activities while preserving user privacy through metadata-based analysis.

---

Future Enhancements

Planned improvements include:

• Machine Learning–based threat detection
• Malware hash reputation checking
• SIEM integration
• Email and SMS alerting
• Multi-user role management
• Cloud-based monitoring dashboard
• Real-time analytics and visualization

---

Author

George Mwape

Bachelor of Science in Cyber Security
Kapasa Makasa University
Zambia

GitHub: https://github.com/GeorgeMwape contributors: madam kaela kapapula | project supervisor

Copyright

© 2026 George Mwape. All Rights Reserved.

This software was developed for academic research purposes.

No part of this project may be copied, modified, distributed, reproduced, or used without the prior written permission of the author.

Unauthorized use, reproduction, or redistribution of this software is strictly prohibited.