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 directory modules/reporting/.

Every module must 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:

 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 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 = 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 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 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.conf_path: path to the analysis.conf file of the current analysis (e.g. storage/analyses/1/analysis.conf)
  • self.options: a dictionary containing all the options specified in the report’s configuration section in conf/reporting.conf.