CIRCLean - USB key sanitizer


CIRCLean logo

Malware regularly use USB sticks to infect victims and the abuse of USB sticks is a common vector of infection (as an example Lost USB keys have 66% chance of malware).

CIRCLean is a independent hardware solution to clean documents from untrusted (obtained) USB keys / USB sticks. The device converts automatically untrusted documents into a readable format and stores these clean files on a trusted (user owned) USB key/stick.

The code runs on a Raspberry Pi (a small hardware device), which also means it is not required to plug or open the original USB key on a computer. CIRCLean can be seen as kind of air gap between the untrusted USB key and your operational computer.

CIRCLean does not require any technical prerequisites of any kind and can be used by anyone. CIRCLean is free software which can be audited and analyzed by third-parties. We also invite any organizations to actively reuse CIRCLean in their own products or contribute to the project.


CIRCLean is designed to be used by everyone and the following visual shows how to use in 8 easy steps.

Simple visual explanation of the USB cleaner

The visual usage HOWTO of CIRCLean is available in vertical PDF format and horizontal PDF format.

Step 1

Unplug the device:

Step 2

Plug the untrusted key in the top usb slot of the Raspberry Pi:

Step 3

Plug your own key in the bottom usb slot:

Note: Make sure your own key is bigger than the untrusted one. The extracted documents might be bigger than the original ones.

Step 4

Connect the power to the micro USB:

Step 5

If you have a Raspberry Pi with a diode, wait until the blinking stops:

Else, plug a headset and listen to some music during the conversion. When the music stops, the conversion is finished.

Step 6

Unplug the device and remove the USB keys:

How to get your own instance

The source code with all the sources to convert the content and the scripts needed to build your own image to write on a SD card are available.

If you prefer to use a pre-build image (last update: 2015-03-10), you can use CIRCLean (2015-05-27).

Please make sure you received the right file by checking the hash:

  • MD5: c8d0210e831b2a1dcc52e361e9188197
  • SHA1: c4807053d87108a3d8577f4738b07e3e7a4fd751
  • SHA256: a603ce09c8cf41b8351f4626b4db9237a2460c56d88a801227403bd433119ab2

You can also verify the integrity of this web page by checking the PGP detached signature.

Beta version of the improved CIRCLean using PyCIRCLean

There a new beta version of CIRCLean which is a significant improvement from the latest version in term of speed and efficiency on low-end hardware like the first version of the Raspberry Pi.

2015-11-06-CIRCLean.img.gz - SHA1: 20691556c0874119addd2bb10c6368c17dc8cfbd

Feedback is more than welcome on the beta version.

Copying the pre-build image to an SD card

While copying the pre-build image, make sure the destination disk is the SD card and not your disk.


Find the raw disk identifying your SD card (something like diskN where N is the higher value) :

diskutil list

If the SD card is already formated and mounted, you need to unmount it (replace N with the value found):

diskutil unmountDisk /dev/diskN

Then you can copy the image to the SD card using dd:

sudo dd bs=1M if=2015-05-27_CIRCLean.img of=/dev/diskN


Find the raw disk identifying your SD card (something like /dev/sdX1 where X is character):

df -h

The disk is most probably mounted and need to be unmounted before the copy:

umount /dev/sdX1

Then you can copy the image to the SD card using dd:

dd bs=1M if=2015-05-27_CIRCLean.img of=/dev/sdX


As recommended by the RaspberryPi, Win32DiskImager utility to copy the file image to the SD card. You can also use dd for Windows.

Technical details

The sanitizing is done by converting and copying the content of the untrusted key to the trusted one. It is based on the mime type of the files, you can have more details in the file of the git repository. Also, a short description of all the scripts is available in the same file.


Version 1.3 - 2015-05-27

Version 1.2 - 2015-03-10

  • Rollback the migration to Jessie and use Wheezy again: the only important dependency from Jessie was poppler, which is available in the backports
  • Use the most recent security patches
  • Do not wait for user input in case of password protected archive

Version 1.1.1 - 2014-10-26

  • General upgrade of Debian to avoid the system to fail in case there is no HDMI cable connected.

Version 1.1 - 2014-10-01

Version 1.0 - 2014-05-20

  • Based on Raspbian Jessie
  • Fully automated tests with Qemu
  • Mimetype: support of PDF, Office documents, archives, windows executables
  • Filesystem: USB keys have to be formated in vfat
  • Support of multiple partitions
  • Renaming of autorun.inf on the source key
  • Operating system is read only
  • Use pdf2htmlEX v0.11