diff --git a/doc/source/about.rst b/doc/source/about.rst index d27c1d1..116ec84 100644 --- a/doc/source/about.rst +++ b/doc/source/about.rst @@ -2,4 +2,8 @@ About Nemesis =============== -This needs fleshing out still. +Nemesis is a project which aims to add a plug-able file analysis API to an OpenStack cloud. Some use cases that come to mind include: + +* Malware Analysis as a Service +* Upload analysis / tagging +* File feature extraction diff --git a/doc/source/installation.rst b/doc/source/installation.rst index bf06238..c635117 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -2,10 +2,30 @@ Installation ============ +Nemesis is a very early development project and hence deploying it to a production cloud is not advised (yet), however it's requirements are quite +minimalistic and hence setting up a small dev / test environment is pretty easy. + + +Prerequisites +------------- + +So far only installation on Ubuntu is described however installation should be very similar and straight forward on other distributions. For a +minimalist installation of Nemesis you'll require: + +* 2 VMs / Physical hosts (1 for the API node, and 1 for a worker node) +* OpenStack Keystone (for user authentication) +* OpenStack Swift (for artifact storage) +* RabbitMQ Server +* MySQL Server + + API Nodes --------- - Worker Nodes ------------ + + +Validating Installation +----------------------- diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst index 55be68a..4756e28 100644 --- a/doc/source/plugins.rst +++ b/doc/source/plugins.rst @@ -4,9 +4,98 @@ Plugins ClamAV ------ -Allows malware scanning via ClamD. +Allows malware scanning of submitted files via ClamAV. + +Prerequisites ++++++++++++++ + +* Worker nodes running ClamAV daemon (http://www.clamav.net/) +* Python ClamD module (https://pypi.org/project/clamd/) + +Installation +++++++++++++ + +* Install ClamAV from OS packages and configure as required +* Rename the clamav.py.plugin file in Nemesis plugin directory to clamav.py +* Reinstall Nemesis via setuptools +* Install Python ClamD module into your Nemesis virtual env +* Update your analysis_plugins list in your nemesis.conf file +* Once compelete restart the Nemsis worker service + +:: + + source /opt/nemesis/bin/activate + cd ~/git/nemesis + cp python_nemesis/plugins/clamav.py.plugin python_nemesis/plugins/clamav.py + python setup.py install + pip install clamd + vi /etc/nemesis/nemesis.conf # Update analysis plugins list to include clamav + service nemesis-worker restart + +Sample Artifacts +++++++++++++++++ + +Malware Detected:: + + { + "success": true, + "result": {"is_malware": true, + "malware_type": "EICAR-Test-File"}, + "message": null + } + +Malware Not Detected:: + + { + "success": true, + "result": {"is_malware": false, + "malware_type": null}, + "message": null + } EXIF ---- Extracts EXIF data from compatible image files. +Prerequisites ++++++++++++++ + +* Python ExifRead module (https://pypi.org/project/ExifRead/) + +Installation +++++++++++++ + +* Rename the exif.py.plugin file in Nemesis plugin directory to exif.py +* Reinstall Nemesis via setuptools +* Install Python ExifRead module into your Nemesis virtual env +* Update your analysis_plugins list in your nemesis.conf file +* Once compelete restart the Nemsis worker service + +:: + + source /opt/nemesis/bin/activate + cd ~/git/nemesis + cp python_nemesis/plugins/exif.py.plugin python_nemesis/plugins/exif.py + python setup.py install + pip install exifread + vi /etc/nemesis/nemesis.conf # Update analysis plugins list to include exif + service nemesis-worker restart + +Sample Artifacts +++++++++++++++++ + +EXIF extracted:: + + { + "success": true, + "result": {"exif_tags": [...]} + "message": null + } + +Unable to extract EXIF data:: + + { + "success": false, + "result": null, + "message": "Unable to extract EXIF from EXE filetype, only able to extract EXIF from JPEG and TIFF file types." + }