diff --git a/.travis.yml b/.travis.yml index cda02e8..b8b8294 100644 --- a/.travis.yml +++ b/.travis.yml @@ -31,8 +31,7 @@ install: - wget https://didierstevens.com/files/software/pdfid_v0_2_1.zip - unzip pdfid_v0_2_1.zip - pip install -U pip - - pip install lxml exifread pillow olefile - - pip install git+https://github.com/decalage2/oletools.git + - pip install lxml exifread pillow olefile oletools - pip install git+https://github.com/grierforensics/officedissector.git # PyCIRCLean dependencies - pip install -r dev-requirements.txt @@ -74,6 +73,7 @@ install: - unzip -o fraunhoferlibrary.zip - rm fraunhoferlibrary.zip - popd + # Turned off unzipping 42.zip because it isn't included in the file catalog and archivebomb.zip ends up testing the same thing # - pushd tests/dangerous/ # - 7z x -p42 42.zip # - popd diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e514393..4528d09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,12 @@ This project is in active development, so any contributions are welcome! Setting up a dev environment ============================ +* PyCIRCLean requires a working Python 3.3+ install. Before beginning install, it is recommended +to set up a virtualenv to contain Python dependencies. If you don't have experience managing Python virtualenvs, +[pyenv](https://github.com/pyenv/pyenv) and [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) are great +tools. If you're running MacOS or Windows and would like to contribute to filecheck.py, you will need access to a VM using +either a cloud service or something like Virtualbox. + * First, you'll want to get a local copy of PyCIRCLean. If you'd like to make a pull request with your changes at some point, you should fork the project on github, and then `git clone` your fork. @@ -18,22 +24,17 @@ your fork. you can use `pip install dev-requirements.txt` to ensure you download any testing dependencies as well. We recommend that you use a virtualenv when installing dependencies. Note: python-magic has a non-Python dependency, libmagic. It is typically included in Linux distributions, but you might have to install -it with homebrew (`brew install libmagic`) on macOS. +it with homebrew (`brew install libmagic`) on MacOS. -* Some of the example scripts have additional dependencies for handling various filetypes. You'll have to -install these seperately if you want to try out the examples or modify them for your own purposes. -Please open an issue if you have suggestions of good alternatives for the libraries we use for file handling -or if you have an example you'd like to contribute. +* To install the dependencies for filecheck.py on Linux, you can run `make install` or view the [Makefile](./Makefile) and +install the dependencies manually. Note that `pip install lxml` can only be run after `apt-get libxml2-dev`. Running the tests ================= -* Running the tests is fairly straightforward. * First, make sure you've installed the project and testing dependencies. * Then, run `python -m pytest` or just `pytest` in the top level directory of the module. -* Each integration test that runs will generate a timestamped copy of the log for that run -in the tests/testlogs directory. * If you'd like to get information about code coverage, run the tests using `pytest --cov=kittengroomer`. * You can test with multiple versions of Python if you have them installed diff --git a/README.md b/README.md index 534ef45..d89e79c 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,9 @@ PyCIRCLean is the core Python code used by [CIRCLean](https://github.com/CIRCL/Circlean/), an open-source USB key and document sanitizer created by [CIRCL](https://www.circl.lu/). This module has been separated from the device-specific scripts and can be used for dedicated security applications to sanitize documents from hostile environments -to trusted environments. PyCIRCLean is currently Python 3.3+ compatible. Some of its dependencies are Linux-only, and -running the tests will require access to a Linux box or VM. +to trusted environments. PyCIRCLean is currently Python 3.3+ compatible. Also, while [kittengroomer](./kittengroomer) can +run on any platform supported by python-magic/libmagic, [filecheck.py](./bin/filecheck.py) has some dependencies that are +Linux-only, and running the full test suite will require access to a Linux box or VM. # Installation