autopsy-flatpak/docs/doxygen/platformConcepts.dox

/*! \page platform_page Platform Concepts

\section platform_basics Basic Concepts

These are the basic concepts that you should be aware of before writing a module:

- <b>Phases:</b> The platform has been design to support different phases in the investigation process:
 - Case Creation: Use wizards to create a new case.
 - Data Source Adding: Where disk images and logical files are added to a case and file systems in disk images are analyzed to populate the database.  The end result of this phase is that the central database has a basic record of each file so that it can be analyzed.  This happens in the Add Image Wizard.
 - Ingest Module Analysis: A variety of analysis modules then run on the  files referenced in the database to perform specific tasks.
 - Browsing and searching: User manually browses and searches the data using the user interface.  They can browse through the results from the ingest modules that may still be running in the background. 
 - Report: A final report is generated at the end of the case.
- <b>Central Database</b>: All data except for the disk image is stored in a SQLite database.  This includes information about what files exist in a disk image and the output from modules. 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. The services and data model classes will interact with it. 
- <b>Case</b>: A case class (org.sleuthkit.autopsy.casemodule.Case) is the top-level object for the data being analyzed.  From here, you can access all of the files and query it. 
- <b>Blackboard:</b> The platform uses the blackboard to enable modules to communicate with each other and to display data in the GUI. See the \ref platform_blackboard section for more details. 
- <b>Services</b>: There are services provided by the platform. See the \ref mod_dev_other_services section for more details.
- <b>Utilities</b>: There are core utilities that the platform provides to modules. See the \ref mod_dev_other_utilities section for more details. 
- <b>Single tree:</b> Results from the various modules can generally be found in a single tree. This makes it easy for users to find their results. 


\section platform_frameworks Frameworks in the Platform
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 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 image.  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. 
 - 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. 
See \ref mod_ingest_page for details on building these modules. 
- <b>Report Modules:</b> These modules create different types of outputs that contain the analysis results. See \ref mod_report_page for details on creating these modules. 
- <b>Content Viewers:</b> These modules show information about a specific file. 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.  See \ref mod_result_page for details on creating these modules. 



\section platform_services Services
The platform provides a variety of services and utilities that you need to be familiar with.  This section outlines the basic ones and additional ones are described at the end of the document in \ref mod_dev_adv.

\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. 

- Details on the blackboard concepts (artifacts versus attributes) can be found at http://sleuthkit.org/sleuthkit/docs/framework-docs/mod_bbpage.html. These documents are about the C++ implementation of the blackboard, but it is the same concepts.  
- Details of the Java classes can be found in \ref jni_blackboard section of the The Sleuth Kit JNI documents (http://sleuthkit.org/sleuthkit/docs/jni-docs/). 


\subsection mod_dev_other_services Framework Services

The followig are basic services that are available. 

- 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 because the other modules are passed in a reference to a specific file to do something with. 
- org.sleuthkit.autopsy.coreutils.Logger - Use this class to log error and informational messages to the central Autopsy log file.
- 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.
- IngestModules also have a class that provides additional services.  See \ref ingest_modules_services_ingest. 


\subsection mod_dev_other_utilities Framework Utilities

In addition to the services previously listed, there are some general utilities that could be useful to modules.  These include: 
- org.sleuthkit.autopsy.coreutils.PlatformUtil - platform-specific methods to determine available disk space, memory, etc.
- org.sleuthkit.autopsy.coreutils.ModuleSettings - to persist module configuration and settings
- org.sleuthkit.autopsy.coreutils.FileUtil - to delete and add folders, etc.

*/