Reporting Results

The processor script is responsible for taking analysis results and elaborate them, as explained in the Processing of results chapter.

Since version 0.3, Cuckoo Sandbox provides also a reporting engine that can be used to generate consumable reports (as done by the default processor script): it takes the analysis results as input and stores the produced reports in the dedicated folder as explained in the Analysis Results chapter.

The reporting engine, called ReportProcessor, is designed to load all reporting modules specified in configuration file reporting.conf (see Configuration chapter) and execute them.

A reporting module is a simple Python script which aggregates, normalizes and correlates analysis data in order to generate a report out of it. Cuckoo comes with several built-in reporting modules described below, but writing your own modules is incredibly simple.

Built-in Reports

Report TXT

This module generates a human-readable report in plain text format.

Report HTML

This module generates a human-readable report in HTML format. These reports are also served by the built-in web server as explained in Web Interface.

JSON Dump

This module dumps all Cuckoo’s analysis results in JSON format. This is useful when you need to export Cuckoo’s data to other tools or services.

Writing your own reporting module

As said, reporting tasks are handled by the ReportProcessor class: it loads all reporting modules from cuckoo/reporting/tasks folder, checks if they are enabled in the configuration file and then execute them.

If you want to write your own reporting module you have to:

  • Create a Python file inside the reporting module folder (cuckoo/reporting/tasks), e.g. foo.py.

  • Append an option inside the reporting configuration file (reporting.conf) with the lowercase name of the file and enable it, like following:

    foo = on

  • Inside your Python script you have to implement the BaseObserver interface in a class named “Report”. When new analysis results are available, Cuckoo calls your update() method passing the analysis results as a parameter.

A sample custom reporting module would look like following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from cuckoo.reporting.observers import BaseObserver

class Report(BaseObserver):
    def __init__(self):
        # Put here your initialization or leave a pass.
        pass

    def update(self, results):
        # Here you get analysis results as parameter.
        # Now do your stuff.
        print "My report!"

Whatever operation you might want to run, remember to place it inside the update() method or invoke it from there, so that Cuckoo will be able to execute it when needed.