This repository has been archived and is no longer actively maintained.

Pandora Box was originally designed as a malware detection tool for USB drives, relying on ClamAV and a set of analysis scripts. Over time, the Pandora project has evolved in a different direction — focusing on safe document viewing and text/office file analysis — which no longer aligns with the original scope of this project.

A new project is currently being developed to take over this use case. It will provide USB drive malware detection capabilities, but will likely not be based on Pandora. Stay tuned.

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]
; Curses mode (full text)
CURSES = False

; Set USB_AUTO_MOUNT to True is if the OS automaticaly mount USB keys
USB_AUTO_MOUNT = False

; Set PANDORA_ROOT_URL to the URL of the Pandora server
; the default value is "http://127.0.0.1:6100"
PANDORA_ROOT_URL = http://127.0.0.1:6100

; Set FAKE_SCAN to true to fake the scan process (used during developement only)
FAKE_SCAN = False

; Set to true to copy infected files to the quarantine folder
; in the USB scanning station
QUARANTINE = True

; Set quarantine folder
QUARANTINE_FOLDER = /var/quarantine

; Number of threads used by Pandora
THREADS = 8

; Max File Size (1G)
MAX_FILE_SIZE = 1080000000

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.