Getting started =============== If you'd like to work on the Python code that processes files for Circlean, you should take a look at [PyCIRCLean](https://github.com/CIRCL/PyCIRCLean), specifically the filecheck.py script. To get started contributing to Circlean, first, fork the project and `git clone` your fork. Then, follow the instructions in [setup_with_proot.md](doc/setup_with_proot.md) to build an image. To make things easier, you can also download a prebuilt image as mentioned in the README, and then mount and make modifications to this image to test your changes. The issue tracker ================= If you find a bug or see a problem with PyCIRCLean, please open an issue in the Github repo. We'll do our best to respond as quickly as possible. Also, feel free to contribute a solution to any of the open issues - we'll do our best to review your pull request in a timely manner. This project is in active development, so any contributions are welcome! Dependencies ============ * Timidity for playing midi files * Git for installing some Python dependencies * 7Zip for unpacking archives * Pmount and ntfs-3g for mounting usb key partitions * Python 3 and pip for installing and running Python dependencies * Python3-lxml for handling ooxml and other Office files in filecheck.py * libjpeg-dev, libtiff-dev, libwebp-dev, liblcms2-dev, tcl-dev, tk-dev, and python-tk for various image formats (dependencies for pillow) * Exifread for file metadata * Pillow for handling images * Olefile, oletools, and officedissector for handling various Office filetypes * PyCIRCLean for main file handling code Helper scripts ============== Use the scripts in shell_utils/ as examples - do not run them blindly as you will most probably have to change some constants/paths accordingly to your configuration. IN ALL CASES, PLEASE READ THE COMMENTS IN THE SCRIPTS AT LEAST ONCE. * proper_chroot.sh: uses qemu to chroot into a raspbian instance (.img or SD Card) * prepare_rPI.sh: update the system, some configuration * create_user.sh: create the user who will run the scripts, assign the proper sudo rights. * copy_to_final.sh: populate the content of the directory fs/ in the image, contains a sample of dd command to write the image on the SD card. NOTE: TAKE CARE NOT TO USE THE WRONG DESTINATION Running the tests ================= * If you've made changes to the shell scripts, start by installing and running [Shellcheck](https://github.com/koalaman/shellcheck). * To emulate the Raspberry Pi hardware for testing, we'll be using [Qemu](http://wiki.qemu.org/Main_Page), an open source machine emulator. The "qemu" package available for Ubuntu/Debian includes all of the required packages (including qemu-system-arm) except for qemu-user-static, which must be installed separately. ``` sudo apt-get install qemu qemu-user-static expect ``` * Get the qemu kernel for the image you are using: ``` pushd tests; wget https://github.com/dhruvvyas90/qemu-rpi-kernel/raw/master/kernel-qemu; popd ``` * Put some test data from tests/testFiles into tests/content_img_vfat_norm * Comment out the other tests in tests/run.sh or populate those directories as well * Make sure to set the filename of the image and the kernel in `tests/run.sh` * Run the tests: ``` sudo ./run_tests.sh ``` * If the image run processed images correctly but doesn't exit and unmount the images cleanly, look at tests/run.exp and make sure it's waiting for the string your qemu and kernel actually produce.