Quick guide to writing MISP modules
This blog post will give a short introduction on how to write your own MISP module and is followed by an example standalone module that I quickly wrote for fun as an example for this blog post.
MISP modules are a way to extend the default capabilities of MISP without having to worry too much about whats going on under the hood. That means you should be able to quickly integrate your tools into MISP without having to fork the core code and write PHP. The modules are built using Python and can be written by following a simple clean structure. As a developer you only need to worry about parsing the IoC data handed to you into format that is relevant to your use case.
Modules are divided into three main types: expansion modules that enrich the data that is in MISP, import modules that are used to import new data into MISP and export modules that can be used to export existing MISP data.
The basic expansion module skeleton is as follows:
import json
import dns.resolvermisperrors = {'error' : 'Error'}
mispattributes = {'input': [] , 'output' : []}
moduleinfo = {'version': '', 'author': '', 'description': '', 'module-type': []}
moduleconfig = ['']def handler(q=False):
if q is False:
return False
request = json.loads(q)
r = {'results' : [{'types': [], 'values' :[]}]}
return rdef introspection():
return mispattributesdef version():
return moduleinfo
Simply put whatever your module does, it should do it within the handler function.
Variable mispattributes should contain whatever you wish for your module to accept as an input and output:
mispattributes = {‘input’ : [‘domain’], ‘output’ : [‘text’]}Variable moduleinfo should contain relevant metadata:
moduleinfo = {'version': '0.1', 'author': 'Juha', 'description': 'Standalone expansion to spot URL typosquatting', 'module-type': ['expansion', 'hover']}Finally variable moduleconfig can contain any settings or API keys your tool might need. As an example for my module I decided to give the user an option to configure the ratio how easily the tool interprets the url to be a typosquat of a known domain.
moduleconfig = [‘detection_weight_ratio’]Within the handler function data is handed to you in json.
Error handling can be done in multiple ways, but if you wish for the error message to be visible in the MISP webUI you should return any errors using the misperrors variable.
misperrors[“error”] = “Dependancy pyxDamerauLevenshtein missing, is it installed correctly?”return misperrors
Other than that there is not much else to it, just handle the IoC data appropriately and if your module returns something, make sure it follows the MISP core format.
For my module I wanted to create a hover-over module that quickly informs the user whether domain is a typosquat or not.
The following gist contains the code for this module. Additionally you’ll need to install pyxDamerauLevenshtein python Library (https://pypi.org/project/pyxDamerauLevenshtein/) and pick some list of known common domains (e.g. https://raw.githubusercontent.com/zer0h/top-1000000-domains/master/top-100000-domains).
Installing the module and troubleshooting
Module you have written can be enabled by copying it to relevant folder under misp-modules/misp_modules/modules. You can install the requirements your module requires by hand or simply just add them to the requirements file. Run script ./update_misp_modules.sh under tools folder to automatically install any new modules within the modules folders and restart misp-modules service. Your module should now be visible in MISP plugins or alternatively you can query the server using curl for all modules:
curl -s http://127.0.0.1:6666/modulesIf your module is not visible or has errors that you did not catch you can view the misp-module service errors with the following command:
sudo journalctl -f -u misp-modules.serviceAdditionally MISP itself has handy logs and diagnostic tools available under server settings & maintenance.
This blog post was written as a part of the Cincan project.
One of the goals of the project is to build shareable, repeatable & history preserving malware analysis pipelines using your favorite tools + CI + git + containers.
For more information see our homepage.
