CIRCLean
Malware regularly uses 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 an independent hardware solution to clean documents from untrusted (obtained) USB keys / USB sticks. The device automatically converts untrusted documents into a readable but disarmed format and stores these clean files on a trusted (user owned) USB key/stick.
The focus of CIRCLean is to establish document exchange even if the used transport layer (the USB stick) cannot be trusted or if there is a suspicion about whether the contained documents are free of malware or not. In the worst case, only the CIRCLean would be compromised, but not the computer reading the target (trusted) USB key/stick.
The code runs on a Raspberry Pi (a small hardware device), which also means it is not required to plug the original USB key into a computer. CIRCLean can be seen as a 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 all organizations to actively reuse CIRCLean in their own products or contribute to the project.
Usage
CIRCLean is designed to be used by everyone and the following visual shows how to use it in 8 easy steps.
The visual instructions how to use CIRCLean is available in vertical PDF format and horizontal PDF format.
Step 1
Unplug the device:
Step 2
Plug the untrusted key into the top usb slot of the Raspberry Pi:
Step 3
Plug your own, trusted key into the bottom usb slot:
Note: Make sure your own key is bigger than the untrusted one. The extracted documents are sometimes 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:
Otherwise, plug a headset and listen to the music that is played 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 onto an SD card are available.
If you prefer to use a pre-build image (last update: 2020-01-16), you can use:
2020-01-16_CIRCLean.img.gz - SHA256: 6d72aab7eb5e04b73409bf36aac7a52093d4865456e894b2d8fb07c41cac1157
Please make sure you received the right file by checking the hash.
You can also verify the integrity of this web page by checking the PGP detached signature.
Feedback is more than welcome.
Copying the pre-built image to an SD card
While copying the pre-built image, make sure the destination disk is the SD card and not your disk.
MacOS
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 formatted 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=2020-01-16_CIRCLean.img of=/dev/diskN
Linux
Find the raw disk identifying your SD card (something like /dev/sdX1 where X is a character):
df -h
The disk is most probably mounted and needs to be unmounted before the copy:
umount /dev/sdX1
Now you can copy the image to the SD card using dd:
dd bs=1M if=2020-01-16_CIRCLean.img of=/dev/sdX
Windows
As recommended by the RaspberryPi, use the Win32DiskImager utility to copy the file image to the SD card. You can also use dd for Windows.
Technical details
The sanitization 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 find more details in the README.md file of the git repository. Also, a short description of all the conversion scripts is available in the same file.
Changelog
You can also find a detailed changelog of the PyCIRCLean library, and of CIRCLean/KittenGroomer itself.
Version 2.6 - 2020-01-16
- Add support for exFAT
Version 2.5 - 2019-08-30
- Bump Raspbian => Support of every RaspberryPi versions up to 4
- Bump PyCIRCLean dependencies
- Update PyCIRCLean
Version 2.4.1 - 2018-07-23
- Bump Raspbian
- Sleep 30s before starting the process (give time to the rPi to detect the USB keys)
Version 2.4 - 2018-01-29
- Bump Raspbian
- Bump PyCIRCLean
- Wait 15s before shutdown (simplify debug)
Version 2.3.1 - 2017-10-25
- Bugfix for Raspberry Pi 3 that was causing rc.local to fail to boot
- Turned off several networking related services: startup is much faster
Version 2.3 - 2017-09-08
- Updated to the newest version of Raspbian Stretch lite (2017-08-16 release)
- Using the newest version of PyCIRCLean, including several vulnerability and bug fixes
- Refactored CIRCLean bash scripts according to Defensive Bash Programming
- Added IN_PROGRESS.txt canary file that gets added and then deleted from destination key
- Various smaller bug fixes
Version 2.2.1 - 2017-09-08
Fixes:
- Switched back to released version of oletools
- Use set of malicious extensions from Chrome
- Check for XML Forms Architectures in PDFs
- Symlinks were being followed
- Prevent copying MacOS hidden files
- Fixes for several filetypes that were incorrectly being identified as dangerous
- Fix support for .rar archives
- Turn off executable bit on copied files
Version 2.2 - 2017-04-18
New features: - Filecheck.py configuration information is now conveniently held in a Config object instead of in globals - New easier to read text-based logger (removed twiggy dependency) - Various filetypes in filecheck.py now have improved descriptions for log - Improved the interface for adding file descriptions to files
Version 2.1.1 - 2017-02-28
- Fix copying PDF documents to the destination key
Version 2.1 - 2017-02-02
- Updated to the newest version of Raspbian Jessie lite (January 11th 2017 release)
- NTFS files can now be mounted as source or destination keys
- Added udev rules that ensure the USB ports map deterministically to source and destination keys
- New debug flag and debug logging functionality to make working on CIRClean without a monitor easier
- Turned off automatic display sleep
Version 2.0.2 - 2016-05-12
- Improve filename encoding.
Version 2.0.1 - 2016-04-26
- Re-add timidity so the MIDI files are played properly.
Version 2.0 - 2016-04-26
- No critical bugs have been identified, this release uses the latest version of Raspbian Jessie lite, with all system updates.
Version 2.0-BETA - 2015-11-06
- 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. The new code base of CIRCLean is now based on PyCIRCLean.
Version 1.3 - 2015-05-27
- Fix a critical security bug related to polyglot files - thanks to the reporters (Jann Horn, seclab-solutions)
- Use the PyCIRCLean for the conversion
- Convert PDF files to PDF/A before converting to HTML
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
- NTFS support added for USB key
- Updated to Debian Jessie including patches for bash vulnerabilities CVE-2014-6271 - CVE-2014-7169
- CIRCLean user are now removed from the sudoer
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