mirror of
https://github.com/dbarzin/pandora-box.git
synced 2025-07-18 21:09:41 +02:00
122 lines
3.4 KiB
Markdown
122 lines
3.4 KiB
Markdown
# PandoraBox
|
|
|
|
PandoraBox is a USB scanning station designed to detect and remove malware from USB disks. It is based on [Pandora](https://github.com/pandora-analysis) by [CIRCL](https://www.circl.lu) and is distributed under the [GPLv3 license](https://www.gnu.org/licenses/licenses.html).
|
|
|
|
## Key Features
|
|
|
|
- Detects USB insertion/removal in real time
|
|
- Automatically or manually mounts USB devices
|
|
- Multithreaded scanning using [pypandora](https://github.com/pandora-analysis/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](http://www.clamav.net/)
|
|
- [Comodo Antivirus](https://antivirus.comodo.com/)
|
|
- [Hashlookup](https://circl.lu/services/hashlookup/)
|
|
- [Yara Rules](https://github.com/Neo23x0/signature-base)
|
|
|
|
Other malware detection tools can be configured using [Pandora antivirus-workers](https://github.com/pandora-analysis/pandora#antivirus-workers).
|
|
|
|
## Interface
|
|
|
|
PandoraBox supports:
|
|
|
|
### Graphical Feedback
|
|
|
|
[<img src="images/key1.png" width="400">](images/key1.png)
|
|
[<img src="images/wait1.png" width="400">](images/wait1.png)
|
|
[<img src="images/ok.png" width="400">](images/ok.png)
|
|
[<img src="images/bad.png" width="400">](images/bad.png)
|
|
|
|
### Text Interface (Advanced Users)
|
|
|
|
[<img src="images/pandora-curses.png" width="400">](images/pandora-curses.png)
|
|
|
|
## Installation
|
|
|
|
PandoraBox runs on [Ubuntu 24.04 server LTS](https://ubuntu.com/download/server).
|
|
|
|
### Dependencies
|
|
|
|
- Python 3.8+
|
|
- Python modules: `psutil`, `pyudev`, `pypandora`, `curses`, `logging`, `subprocess`
|
|
|
|
Install dependencies:
|
|
|
|
```bash
|
|
pip install psutil pyudev pypandora
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Edit `pandora-box.ini` at the root of the project:
|
|
|
|
```ini
|
|
[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](INSTALL.md).
|
|
|
|
## 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](ROADMAP.md).
|
|
|
|
## 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](https://github.com/dbarzin)
|
|
|
|
## License
|
|
|
|
PandoraBox is open source software released under the [GPLv3 license](https://www.gnu.org/licenses/licenses.html).
|