Developing Report Modules

Overview

Report modules allow Autopsy users to create different report types. Autopsy comes with modules to generate HTML and Excel artifact reports, a tab delimited File report, a Keyhole Markup Language (KML) report for Google Earth data, and a body file for timeline creation. You can make additional modules to create custom output formats.

All custom report modules will be general report modules. General report modules have a single method to generate the report. This method gives the module freedom to find and process any data it so chooses. General modules also have the ability to provide a configuration panel, allowing the user to choose from various displayed settings. The report module may then use the user's selection to generate a more specific report.

General modules are also given the responsibility of updating their report's progress bar and processing label in the UI. A progress panel is given to every general report module. It defines a basic API to start, stop, and increment the progress bar and to update the processing label. The module is also expected to check the progress bar's status occasionally to see if the user has manually canceled the report.

Creating a Report Module

To create a report module, start off by creating a new Java or Python (Jython) class and implementing (Java) or inheriting (Jython) from org.sleuthkit.autopsy.report.GeneralReportModule. You'll need to override multiple methods including the following:

• org.sleuthkit.autopsy.report.ReportModule.getName()
• org.sleuthkit.autopsy.report.ReportModule.getDescription()
• org.sleuthkit.autopsy.report.ReportModule.getRelativeFilePath()
• org.sleuthkit.autopsy.report.GeneralReportModule.generateReport(String reportPath, ReportProgressPanel progressPanel)

If your report module requires configuration, you'll need to override:

• org.sleuthkit.autopsy.report.GeneralReportModule.getConfigurationPanel()

For general report modules, Autopsy will simply call the generateReport(String reportPath, ReportProgressPanel progressPanel) method and leave it up to the module to acquire and report data in its desired format. The only requirements are that the module saves to the given report path and updates the org.sleuthkit.autopsy.report.ReportProgressPanel as the report progresses.

When updating the progress panel, it is recommended to update it as infrequently as possible, while still keeping the user informed. If your report processes 100,000 files and you chose to update the UI each time a file is reviewed, the UI would freeze when trying to process all your requests. This would cause problems to not only your reporting module, but to other modules running in parallel. A safer approach would be to update the UI every 1,000 files, or when a certain "category" of the files being processed has changed. For example, the HTML report module increments the progress bar and changes the processing label every time a new Blackboard Artifact Type is being processed.

Autopsy will also display the panel returned by getConfigurationPanel() in the generate report wizard. This panel can be used to allow the user to customize the report. To make this panel, use NetBeans to make a new JPanel class and use its layout interface to put the UI widgets in the places that you want them. Then, your getConfigurationPanel() method should create an instance of that class and return it.

Typically a general report module should interact with both the Blackboard API in the org.sleuthkit.datamodel.SleuthkitCase class, in addition to an API (possibly external/thirdparty) to convert Blackboard Artifacts to the desired reporting format.

Showing Results

You should call org.sleuthkit.autopsy.casemodule.Case.addReport() with the path to your report so that it is shown in the Autopsy tree. You can specify a specific file or folder and the user can then view it later.

Indexing Reports

After you have called org.sleuthkit.autopsy.casemodule.Case.addReport() and created a report, you can pass it to org.sleuthkit.autopsy.keywordsearchservice.KeywordSearchService.index() so that the report text is indexed for keyword search. This is most commonly used when an Ingest Module runs a 3rd party tool and the output of that tool is added back into Autopsy as a report. Here is some example code:

KeywordSearchService searchService = Lookup.getDefault().lookup(KeywordSearchService.class);
if (null == searchService) {
    logger.log(Level.WARNING, "Keyword search service not found. Report will not be indexed");
} else {
    searchService.index(report);
}

Installing your Report Module

Adding a service provider annotation allows Autopsy to find your report module.

@ServiceProvider(service = GeneralReportModule.class)
public class SampleReportModule implements GeneralReportModule {

It is also important to remember to include a getDefault() method in your report module. As shown in the code above, the instance to each report module is accessed via its getDefault() method. For example:

// Static instance of this report
private static MyReport instance;

// Get the default instance of this report
public static synchronized MyReport getDefault() {
    if (instance == null) {
        instance = new MyReport();
    }
    return instance;
}

Report modules developed using Jython are installed in Autopsy by placing them in their own subdirectory of the python_modules directory. A window into the python_modules directory can be opened through the Autopsy's Tools -> Python Plugins menu item. Create a folder in this directory and create or place your Python scripts in this folder.

Persisting your Report Module Configuration

Both Java and Python report modules can have their configurations persisted to disk. In order to do so, the report module must do two things:

1. The report module must have a class that defines the configuration for the module (for example, org.sleuthkit.autopsy.report.modules.html.HTMLReportModuleSettings). This class must implement the ReportModuleSettings interface. Note that the ReportModuleSettings interface extends Serializable, therefore the report settings class must contain serialVersionUID variable:

   class HTMLReportModuleSettings implements ReportModuleSettings {
       
       private static final long serialVersionUID = 1L;
       
       HTMLReportModuleSettings() {
       }
       
       @Override
       public long getVersionNumber() {
           return serialVersionUID;
       }
   }

2. The report module implementation class (e.g. ReportHTML) must implement the following methods of the ReportModule interface:
   • getDefaultConfiguration()
   • getConfiguration()
   • setConfiguration(ReportModuleSettings settings)

The use case scenario for this API when the configuration of a report module is occurring is as follows (using HTMLReport as example):

1. User clicks "Generate Reports" button in the Autopsy UI.
2. Report Configuration UI attempts to load the persisted reporting configuration from disk.
3. For each existing report module, if a persisted ReportModuleSettings (i.e. HTMLReportModuleSettings) configuration exists, Configuration UI calls HTMLReport.setConfiguration() with the persisted settings; Otherwise the Configuration UI calls HTMLReport.getDefaultConfiguration(), then HTMLReport.setConfiguration().
4. Configuration UI calls HTMLReport.getConfigurationPanel(). The report module loads the settings into its configuration panel and returns the panel.
5. Configuration UI presents the panel to the user.
6. User interacts with the panel to modify the current settings of the report module.
7. Configuration UI calls HTMLReport.getConfiguration() and obtains the latest report module configuration.
8. Configuration UI persists the module settings.