autopsy-flatpak/docs/doxygen/platformConcepts.dox

/*! \page platform_page Module Development Overview



This page covers the motivation for and basics of Autopsy modules.  It applies to both Java and Python modules.  Later pages will focus on getting the development environment setup and how to write specific modules. 

\section platform_motivation Why Write Modules?

When writing digital forensics programs, the developer often has to focus on three areas:
- What types of data will the user be giving you (disk image, logical files, etc.).
- How to do the analysis that you want to do.
- How to show the results to the user and include the results into a report.

The main reason for considering writing an Autopsy module instead of a stand-alone tool is that Autopsy will deal with the various data inputs and showing the user the results. All you need to do is focus on the analytics. 


\section platform_frameworks Types of Modules
Autopsy was designed to be an extensible platform for other developers to leverage. There are several places in the platform where plug-in modules can be applied. 
- <b>Ingest Modules:</b> These modules are run when a new data source (such as a disk image) is added to a case (and can be re-run afterwards too).  These modules come in two forms:
 - File Ingest Modules are called for every file in the data source.  Use this type of module if you want to examine the contents of all or most of the files.  Examples include hash calculation, hash lookup, file type identification, and entropy calculation.  These modules are passed in a reference to a file to analyze. 
 - Data Source Ingest Modules are called once for every image or set of logical files.  These modules can use the database to query for one or more files and perform analysis on them.  Examples include web artifact analysis and searches that can rely only file names and extensions.  Note that these modules will not have access to the contents of ZIP files.  These modules are also often used when wrapping an executable that takes a disk image in as input. 
See \ref mod_ingest_page for details on building these modules. 
- <b>Report Modules:</b> These modules are (typically) run after the user has reviewed results and tagged files.  Their intention is to create an output report of the results, but they can also be used to perform analysis. See \ref mod_report_page for details on creating these modules. 
- <b>Content Viewers:</b> These modules are graphical and focus on displaying a specific file in some unique way. These are the modules in the lower right of the interface.  The platform comes with viewers to view the file in hexadecimal, extract the strings from the file, and view images and movies.  See \ref mod_content_page for details on creating these modules. 
- <b>Result Viewers:</b> These modules show information about a set of files. These modules are in the upper right of the interface. The platform comes with viewers to view the set of files in a table and thumbnails. These are not commonly built and extended.  See \ref mod_result_page for details on creating these modules.


\section platform_languages Languages

Autopsy is written in Java and all of previously listed modules can also be written in Java. The \ref mod_dev_page page covers setup of a Java environment.

You can also write some of the modules in Python, namely ingest an report modules.  The setup for Python is far easier than Java, so it is the easiest way to get started.  See \ref mod_dev_py_page for setup details. Python modules have access to all of the same services as Java modules do, except they cannot currently make UI elements.  Therefore, you really should read all of this document (even though it is Java-focused) because it can all be used in Python.


\section platform_basics Basic Concepts

Before we focus on the development environment or module details, let's cover some basic Autopsy concepts. 

- <b>Data Source</b>: Data source is the term used in Autopsy to refer to disk images and logical files that are added to a case.  Data sources are represented in Autopsy using several types of classes from the org.sleuthkit.datamodel package. 
- <b>Case</b>: A case is a container for one or more data sources in Autopsy.  A case is represented by a  org.sleuthkit.autopsy.casemodule.Case class. Only one case can be open at a time.  You can get the current case using org.sleuthkit.autopsy.casemodule.Case.getCurrentCase().
- <b>Central Database</b>: A central SQLite or PostgreSQL database exists and stores all file metadata and analysis results. Access to this database can be found from the org.sleuthkit.datamodel.SleuthkitCase class, but you'll probably never need to directly interact with it. All modules can query it for information, though many do not need to.  For example, file-level ingest modules will be passed in a reference to a specific file to analyze and may never need to directly go to the database for more information. 
- <b>Blackboard:</b> The blackboard is how modules communicate back and forth.  Modules post their results to the blackboard in the form of artifacts and the UI will display them.  See the \ref platform_blackboard section for more details. 
- <b>Services and Utilities</b>: There are a lot of convenience services and utilities that are provided to developers.  Refer to the \ref mod_dev_other_services section for more details.


\subsection platform_blackboard The Blackboard

The blackboard allows modules to communicate with each other and the UI. It has three main uses in Autopsy:
- Ingest modules can communicate with each other. For example, one module can calculate a MD5 hash of a file and post it to the blackboard.  Then another module can retrieve the hash value from the blackboard and not need to calculate it again.
- The tree in the right-hand side of the UI uses the blackboard to populate its Results section.  The bookmarks, hashset hits, etc. are all populated from Ingest modules that created blackboard entries. 
- The report modules query the blackboard to identify what they should report on.

The blackboard is not unique to Autopsy.  It is part of The Sleuth Kit datamodel and The Sleuth Kit Framework.  In the name of reducing the amount of documentation that we need to maintain, we provide links here to those documentation sources. 

- \ref mod_bbpage (http://sleuthkit.org/sleuthkit/docs/jni-docs/4.3/mod_bbpage.html)


\subsection mod_dev_other_services Framework Services and Utilities

Autopsy provides services and utilities to make it easier to write modules. Unfortunately, the utilities and services are scattered in various packages. Below is a list of things commonly used in modules.  If you don't find something in here that you think should be a framework service, let us know and we'll talk about adding it for other writers to benefit. 


- FileManager: the org.sleuthkit.autopsy.casemodule.services.FileManager service provides an API to access any file in the case. You can access FileManager by calling org.sleuthkit.autopsy.casemodule.services.Services.getFileManager().  Data Source-level Ingest modules and Report modules typically use this service. 
- Logging: the org.sleuthkit.autopsy.coreutils.Logger class can be used to log error and informational messages to the central Autopsy log file.
- Pop-up Windows: If you have a background task that needs the provide the user with feedback, you can use the org.sleuthkit.autopsy.coreutils.MessageNotifyUtil.Notify.show() method to make a message in the lower right hand area.
- Module Settings: If you want to persist settings between invocations of Autopsy, you can use org.sleuthkit.autopsy.coreutils.ModuleSettings.
- Content Utilities: The org.sleuthkit.autopsy.datamodel.ContentUtils class has utility methods to write files from Autopsy to local disk. Specifically the org.sleuthkit.autopsy.datamodel.ContentUtils.writeToFile() method. 
- Platform Utilities: The org.sleuthkit.autopsy.coreutils.PlatformUtil class allows you to save resources into the user folder and determine paths for the user folders.  Specifically:
 - PlatformUtil.extractResourceToUserConfigDir()
 - PlatformUtil.isWindowsOS()
- File Utilities: The org.sleuthkit.autopsy.coreutils.FileUtil class assists with creating and deleting folders, etc.
- IngestModules also have a class that provides additional services unique to their needs.  See \ref ingest_modules_services_ingest. 

*/