docs/book/src/customization/reporting.rst
=================
Reporting Modules
=================
After the analysis raw results have been processed and abstracted by the
processing modules and the global container is generated (ref. :doc:`processing`),
it is passed over by Cuckoo to all the reporting modules available, which will
make some use of it and will make it accessible and consumable in different
formats.
Getting Started
===============
All reporting modules are and should be placed inside the directory *modules/reporting/*.
Every module should also have a dedicated section in the file *conf/reporting.conf*, for
example if you create a module *module/reporting/foobar.py* you will have to append
the following section to *conf/reporting.conf*::
[foobar]
enabled = on
Every additional option you add to your section will be available to your reporting module
in the ``self.options`` dictionary.
Following is an example of a working JSON reporting module:
.. code-block:: python
:linenos:
import os
import json
from lib.cuckoo.common.abstracts import Report
from lib.cuckoo.common.exceptions import CuckooReportError
class JsonDump(Report):
"""Saves analysis results in JSON format."""
def run(self, results):
"""Writes report.
@param results: Cuckoo results dict.
@raise CuckooReportError: if fails to write report.
"""
try:
report = open(os.path.join(self.reports_path, "report.json"), "w")
report.write(json.dumps(results, sort_keys=False, indent=4))
report.close()
except (TypeError, IOError) as e:
raise CuckooReportError("Failed to generate JSON report: %s" % e)
This code is very simple, it basically just receives the global container produced by the
processing modules, converts it into JSON and writes it to a file.
There are few requirements for writing a valid reporting module:
* Declare your class inheriting ``Report``.
* Have a ``run()`` function performing the main operations.
* Try to catch most exceptions and raise ``CuckooReportError`` to notify the issue.
All reporting modules have access to some attributes:
* ``self.analysis_path``: path to the folder containing the raw analysis results (e.g. *storage/analyses/1/*)
* ``self.reports_path``: path to the folder where the reports should be written (e.g. *storage/analyses/1/reports/*)
* ``self.options``: a dictionary containing all the options specified in the report's configuration section in *conf/reporting.conf*.