pandora-box/README.md

PandoraBox

PandoraBox is a USB scanning station designed to detect and remove malware from USB disks. It is based on Pandora by CIRCL and is distributed under the GPLv3 license.

Key Features

• Detects USB insertion/removal in real time
• Automatically or manually mounts USB devices
• Multithreaded scanning using pypandora
• Automatic quarantine of infected files
• Manual file removal after user confirmation
• Interactive terminal interface (curses) or graphical feedback using images
• Uses well-known malware detection tools:
  • ClamAV
  • Comodo Antivirus
  • Hashlookup
  • Yara Rules

Other malware detection tools can be configured using Pandora antivirus-workers.

Interface

PandoraBox supports:

Graphical Feedback

Text Interface (Advanced Users)

Installation

PandoraBox runs on Ubuntu 24.04 server LTS.

Dependencies

• Python 3.8+
• Python modules: psutil, pyudev, pypandora, curses, logging, subprocess

Install dependencies:

pip install psutil pyudev pypandora

Configuration

Edit pandora-box.ini at the root of the project:

[DEFAULT]
FAKE_SCAN = false
USB_AUTO_MOUNT = true
PANDORA_ROOT_URL = http://localhost
QUARANTINE = true
QUARANTINE_FOLDER = /var/quarantine
CURSES = true
THREADS = 4

Setup & Usage

More details in the installation guide.

Application States

• START: Initialization and config loading
• WAIT: Wait for USB insertion
• SCAN: Scan device contents
• CLEAN: Prompt for infected file removal
• STOP: Application ends or error

Roadmap

If you'd like to contribute, check the roadmap.

Architecture

PandoraBox is implemented as a Python class (PandoraBox) which handles:

• Configuration parsing
• Device detection with pyudev
• File scanning using pypandora
• Logging and progress tracking
• Interactive interface handling

Security and Customization

• Uses a system lock to prevent multiple instances
• Can be integrated with additional tools or security measures
• Easily extendable to new malware detection engines or logging systems

Author

• Didier Barzin — @dbarzin

License

PandoraBox is open source software released under the GPLv3 license.