Reporting Modules

After the raw analysis results have been processed and abstracted by the processing modules and the global container is generated (ref. Processing Modules), it is passed over by Cuckoo to all the reporting modules available, which will make use of it and will make it accessible and consumable in different formats.

Getting Started

All reporting modules must be placed inside the cuckoo/cuckoo/reporting/ directory (which translates to the cuckoo.reporting module).

Every module must also have a dedicated section in the $CWD/conf/reporting.conf file: for example if you create a module cuckoo/cuckoo/reporting/foobar.py you will have to append the following section to $CWD/conf/reporting.conf (and thus cuckoo/data/conf/reporting.conf in the Git repository):

[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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import os
import json
import codecs

from cuckoo.common.abstracts import Report
from 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 = codecs.open(os.path.join(self.reports_path, "report.json"), "w", "utf-8")
            json.dump(results, report, sort_keys=False, indent=4)
            report.close()
        except (UnicodeError, TypeError, IOError) as e:
            raise CuckooReportError("Failed to generate JSON report: %s" % e)

This code is very simple, it 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 from 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.