The processor script is responsible for taking analysis results and elaborate them, as explained in the processing
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 ../usage/results
chapter.
The reporting engine, called ReportProcessor
, is designed to load all reporting modules specified in configuration file reporting.conf (see ../installation/host/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.
This module generates a human-readable report in plain text format.
This module generates a human-readable report in HTML format. These reports are also served by the built-in web server as explained in ../usage/web
.
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.
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 yourupdate()
method passing the analysis results as a parameter.
A sample custom reporting module would look like following:
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.