mirror of
https://github.com/overcuriousity/autopsy-flatpak.git
synced 2025-07-12 16:06:15 +00:00
Merge branch 'master' of https://github.com/sleuthkit/autopsy
This commit is contained in:
adam-m
commit
8cfd800077
@ -24,17 +24,20 @@ import org.sleuthkit.autopsy.datamodel.KeyValue;
|
||||
import org.sleuthkit.datamodel.BlackboardArtifact;
|
||||
|
||||
/**
|
||||
* Representation of subject posted by ingest modules
|
||||
*
|
||||
* Message should have a unique ID within context of originating source
|
||||
*
|
||||
* Message that ingestmodule wants to send to IngetInbox to notify
|
||||
* user about something.
|
||||
* Submitted to user via IngestServices.
|
||||
* Create using factory methods.
|
||||
*/
|
||||
public class IngestMessage {
|
||||
|
||||
/**
|
||||
* Level of message.
|
||||
*/
|
||||
public enum MessageType {
|
||||
|
||||
DATA, INFO, WARNING, ERROR
|
||||
};
|
||||
|
||||
private long ID;
|
||||
private MessageType messageType;
|
||||
private IngestModuleAbstract source;
|
||||
@ -46,6 +49,9 @@ public class IngestMessage {
|
||||
private static SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
|
||||
private static int managerMessageId = 0;
|
||||
|
||||
/**
|
||||
* Private constructor used by factory methods
|
||||
*/
|
||||
private IngestMessage(long ID, MessageType messageType, IngestModuleAbstract source, String subject, String detailsHtml, String uniqueKey) {
|
||||
this.ID = ID;
|
||||
this.source = source;
|
||||
@ -160,7 +166,7 @@ public class IngestMessage {
|
||||
//factory methods
|
||||
|
||||
/**
|
||||
* Create a simple message with a subject only
|
||||
* Create a message of specified type
|
||||
* @param ID ID of the message, unique in the context of module that generated it
|
||||
* @param messageType message type
|
||||
* @param source originating module
|
||||
@ -224,8 +230,8 @@ public class IngestMessage {
|
||||
* @param source originating module
|
||||
* @param subject message subject to be displayed
|
||||
* @param detailsHtml html formatted detailed message (without leading and closing <html> tags), for instance, a human-readable representation of the data.
|
||||
* @param uniqueKey unique key determining uniqueness of the message, or null. Helps grouping similar messages and determine their importance. Subsequent messages with the same uniqueKey will be treated with lower priority.
|
||||
* @param data data blackboard artifact associated with the message, the same as fired in ModuleDataEvent by the module
|
||||
* @param uniqueKey Key used to group similar messages together. Shoudl be unique to the analysis. For example, hits for the same keyword in a keyword search would use the keyword as this unique value so that they can be grouped.
|
||||
* @param data blackboard artifact associated with the message, the same as fired in ModuleDataEvent by the module
|
||||
* @return
|
||||
*/
|
||||
public static IngestMessage createDataMessage(long ID, IngestModuleAbstract source, String subject, String detailsHtml, String uniqueKey, BlackboardArtifact data) {
|
||||
@ -238,10 +244,16 @@ public class IngestMessage {
|
||||
return im;
|
||||
}
|
||||
|
||||
/**
|
||||
* Used by IngestMager to post status messages.
|
||||
*/
|
||||
static IngestMessage createManagerMessage(String subject, String detailsHtml) {
|
||||
return new IngestMessage(++managerMessageId, MessageType.INFO, null, subject, detailsHtml, null);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Used by IngestMager to post error messages.
|
||||
*/
|
||||
static IngestMessage createManagerErrorMessage(String subject, String detailsHtml) {
|
||||
return new IngestMessage(++managerMessageId, MessageType.ERROR, null, subject, detailsHtml, null);
|
||||
}
|
||||
|
||||
@ -21,10 +21,10 @@ package org.sleuthkit.autopsy.ingest;
|
||||
import org.sleuthkit.datamodel.Content;
|
||||
|
||||
/**
|
||||
* Ingest module that acts on entire image.
|
||||
* These modules are for analysis tasks that do not operate on all files in the disk image.
|
||||
* A new instance of this module will be created for each image.
|
||||
* Therefore, image-level modules can assume that the process() method will be called at most once after init() is called.
|
||||
* Ingest module that acts on entire image or set of logical files.
|
||||
* These modules are for analysis tasks that do not operate on all files in the disk image or set of logical files.
|
||||
* A new instance of this module will be created for each data source that is added.
|
||||
* Therefore, data source-level modules can assume that the process() method will be called at most once after init() is called.
|
||||
*/
|
||||
public abstract class IngestModuleDataSource extends IngestModuleAbstract {
|
||||
|
||||
@ -45,7 +45,7 @@ public abstract class IngestModuleDataSource extends IngestModuleAbstract {
|
||||
* The module will have its own progress bar while it is running and it should update it with the IngestDataSourceWorkerController object.
|
||||
*
|
||||
* @param pipelineContext Context in which the ingest pipeline is running (Settings, modules, etc)
|
||||
* @param dataSource data source to process (such as Image, VirtualDirectory for file etc, etc)
|
||||
* @param dataSource data source to process (such as Image, VirtualDirectory for logical files etc, etc)
|
||||
* @param controller Used to update progress bar and to check if the task has been canceled.
|
||||
*/
|
||||
abstract public void process(PipelineContext<IngestModuleDataSource>pipelineContext, Content dataSource, IngestDataSourceWorkerController controller);
|
||||
|
||||
@ -30,12 +30,9 @@ import org.sleuthkit.datamodel.SleuthkitCase;
|
||||
|
||||
|
||||
/**
|
||||
* Services available to ingest modules via singleton instance,
|
||||
* for:
|
||||
* logging, interacting with the ingest manager
|
||||
* sending data events notifications, sending ingest inbox messages,
|
||||
* getting and setting module configurations
|
||||
*
|
||||
* Singleton class that provides services for ingest modules.
|
||||
* These exist to make it easier to write modules. Use the getDefault()
|
||||
* method to get the singleton instance.
|
||||
*/
|
||||
public class IngestServices {
|
||||
|
||||
@ -50,7 +47,7 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Get handle to module services
|
||||
* Get handle to singletone module services
|
||||
* @return the services handle
|
||||
*/
|
||||
public static synchronized IngestServices getDefault() {
|
||||
@ -62,9 +59,9 @@ public class IngestServices {
|
||||
|
||||
/**
|
||||
* Get access to the current Case handle.
|
||||
* Note: When storing the Case database handle as a member variable,
|
||||
* this method needs to be called within module init() method
|
||||
* and the handle member variable needs to be updated,
|
||||
* Note: When storing the Case database handle as a member variable in a module,
|
||||
* this method needs to be called within the module's init() method and the
|
||||
* member variable needs to be updated at each init(),
|
||||
* to ensure the correct Case handle is being used if the Case is changed.
|
||||
*
|
||||
* @return current Case
|
||||
@ -74,11 +71,9 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Get access to the current Case database handle for using the blackboard.
|
||||
* Note: When storing the Case database handle as a member variable,
|
||||
* this method needs to be called within module init() method
|
||||
* and the handle member variable needs to be updated,
|
||||
* to ensure the correct Case database handle is being used if the Case is changed.
|
||||
* Get access to the current Case database handle. Like storing
|
||||
* the Case handle, call this method and update member variables for each
|
||||
* call to the module's init() method to ensure it is correct.
|
||||
*
|
||||
* @return current Case database
|
||||
*/
|
||||
@ -87,7 +82,7 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a logger to be used by the module to log messages to log files
|
||||
* Get a logger to be used by the module to log messages to log files.
|
||||
* @param module module to get the logger for
|
||||
* @return logger object
|
||||
*/
|
||||
@ -96,7 +91,8 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Post ingest message
|
||||
* Post ingest message to the inbox. This should be done for
|
||||
* analysis messages.
|
||||
* @param message ingest message to be posted by ingest module
|
||||
*/
|
||||
public void postMessage(final IngestMessage message) {
|
||||
@ -131,9 +127,9 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Schedule a file for ingest.
|
||||
* The file is usually a product of a recently ran ingest.
|
||||
* Now we want to process this file with the same ingest context.
|
||||
* Schedule a new file for ingest with the same settings as the file
|
||||
* being analyzed. This is used, for example, when opening an archive file.
|
||||
* File needs to have already been added to the database.
|
||||
*
|
||||
* @param file file to be scheduled
|
||||
* @param pipelineContext the ingest context for the file ingest pipeline
|
||||
@ -147,7 +143,6 @@ public class IngestServices {
|
||||
/**
|
||||
* Get free disk space of a drive where ingest data are written to
|
||||
* That drive is being monitored by IngestMonitor thread when ingest is running.
|
||||
* Use this method to get amount of free disk space anytime.
|
||||
*
|
||||
* @return amount of disk space, -1 if unknown
|
||||
*/
|
||||
@ -158,8 +153,8 @@ public class IngestServices {
|
||||
|
||||
|
||||
/**
|
||||
* Facility for a file ingest module to check a return value from another file ingest module
|
||||
* that executed for the same file earlier in the file ingest pipeline
|
||||
* Facility for a file ingest module to check a return value from a previously run file ingest module
|
||||
* that executed for the same file.
|
||||
* The module return value can be used as a guideline to skip processing the file
|
||||
*
|
||||
* @param moduleName registered module name of the module to check the return value of
|
||||
@ -170,7 +165,7 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets a configuration setting for a module
|
||||
* Gets a specific name/value configuration setting for a module
|
||||
* @param moduleName moduleName identifier unique to that module
|
||||
* @param settingName setting name to retrieve
|
||||
* @return setting value for the module / setting name, or null if not found
|
||||
@ -180,7 +175,7 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets a configuration setting for a module
|
||||
* Sets a specific name/value configuration setting for a module
|
||||
* @param moduleName moduleName identifier unique to that module
|
||||
* @param settingName setting name to set
|
||||
* @param settingVal setting value to set
|
||||
@ -190,7 +185,7 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets configuration settings for a module
|
||||
* Gets all name/value configuration settings for a module
|
||||
* @param moduleName moduleName identifier unique to that module
|
||||
* @return settings for the module / setting name
|
||||
*/
|
||||
@ -199,8 +194,7 @@ public class IngestServices {
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets configuration settings for a module, while preserving the module settings not specified
|
||||
* to be set.
|
||||
* Sets all name/value configuration setting for a module. Names not in the list will have settings preserved.
|
||||
* @param moduleName moduleName identifier unique to that module
|
||||
* @param settings settings to set and replace old settings, keeping settings not specified in the map.
|
||||
*
|
||||
@ -208,9 +202,4 @@ public class IngestServices {
|
||||
public void setConfigSettings(String moduleName, Map<String,String>settings) {
|
||||
ModuleSettings.setConfigSettings(moduleName, settings);
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
}
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
/*! \page mod_content_page Developing Content Viewer Modules
|
||||
|
||||
|
||||
Note that this needs cleanup and updating. it has been copied from the CoreComponentInterfaces package description.
|
||||
NOTE: This needs cleanup and updating. it has been copied from the CoreComponentInterfaces package description.
|
||||
|
||||
<h3>Creating a DataContentViewer</h3>
|
||||
|
||||
DataContentTopComponent is the high-level window in the DataContent area. Each instance of this loads up all instances of DataContentViewers that have been registered with the system. Example viewers include the strings and hexdump views. If you want to make your own type of viewer, follow the steps below.
|
||||
DataContentViewer modules exist in the lower-right area of the Autopsy interface. They allow the user to examine a single file in different ways. For example, the default Autopsy installation comes with a viewer for Hex, strings, and image viewing. You would make a new DataContentViewer if you have a unique way of displaying a single file. These modules are passed in a reference to a file to display.
|
||||
|
||||
|
||||
<ol>
|
||||
<li>Create a module from within NetBeans. It must be dependent on these modules:
|
||||
|
||||
@ -120,6 +120,7 @@ Autopsy provides basic services to its modules. These were created to make it e
|
||||
services are provided:
|
||||
|
||||
- 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().
|
||||
- IngestModules also have a class that provides additional services. See \ref ingestmodule_services.
|
||||
|
||||
\subsection mod_dev_other_utilities Autopsy Utilities
|
||||
|
||||
@ -128,18 +129,10 @@ Autopsy-Core module contains the core Autopsy application and also the framework
|
||||
Among the Core APIs there are general utilities available to the Autopsy modules. The relevant packages include:
|
||||
|
||||
- org.sleuthkit.autopsy.casemodule.Case class - for the module to access Case data (TSK database) and subscribe to Case change events
|
||||
- org.sleuthkit.autopsy.coreutils package has classes providing utilities for getting access to Autopsy loggers, configuration persistance API,
|
||||
getting information about the Platform (such as locations of files and folders, info about the runtime environment),
|
||||
extracting default settings files from the jar file to a user settings folder, etc.
|
||||
Relevant service classes are org.sleuthkit.autopsy.coreutils.Version,
|
||||
org.sleuthkit.autopsy.coreutils.PlatformUtil, org.sleuthkit.autopsy.coreutils.ModuleSettings,
|
||||
org.sleuthkit.autopsy.coreutils.Logger and org.sleuthkit.autopsy.coreutils.FileUtil.
|
||||
|
||||
TODO: Add additional info about utility classes (log, Case, database, etc.) Similar to the C++ section about services (http://sleuthkit.org/sleuthkit/docs/framework-docs/mod_devpage.html)
|
||||
|
||||
TODO: Move the log content from the wiki (http://wiki.sleuthkit.org/index.php?title=Autopsy_3_Logging_and_Error_Checking) to here.
|
||||
|
||||
Note: org.sleuthkit.autopsy.ingest.IngestServices provides services specifically for the ingest modules.
|
||||
- org.sleuthkit.autopsy.coreutils.Logger - for adding log messages to central logger
|
||||
- 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.
|
||||
|
||||
|
||||
\section mod_dev_adv Advanced Concepts
|
||||
@ -147,16 +140,7 @@ Note: org.sleuthkit.autopsy.ingest.IngestServices provides services specifically
|
||||
These aren't really advanced, but you don't need to know them in detail when you start your first module. You'll want to refer back to them after you get started and wonder, "how do I do X".
|
||||
|
||||
|
||||
\section mod_dev_adv_bb Black Board
|
||||
|
||||
@@@ TODO
|
||||
|
||||
\section mod_dev_adv_inbox Ingest Inbox Messages
|
||||
|
||||
@@@ TODO: Sending messages, etc.
|
||||
|
||||
\section mod_dev_adv_options Option Panels
|
||||
|
||||
\subsection mod_dev_adv_options Option Panels
|
||||
|
||||
|
||||
Some modules may have configuration settings that uses can change. We recommend that you use the infrastructure provided by Autopsy and NetBeans to do this so that all module condiguration is done in a single place.
|
||||
@ -173,9 +157,7 @@ Second, in the source code of the panel, there are two important methods: \c loa
|
||||
|
||||
If one wishes to make any additional panels within the original options panel, or panels which the original opens, Autopsy provides the org.sleuthkit.autopsy.corecomponents.OptionsPanel interface to help. This interface requires the \c store() and \c load() functions also be provided in the separate panels, allowing for easier child storing and loading.
|
||||
|
||||
Any storing or loading of settings or properties should be done in the \c store() and \c load() methods. Continue to \ref mod_dev_properties for more details.
|
||||
|
||||
|
||||
Any storing or loading of settings or properties should be done in the \c store() and \c load() methods. The next section, \ref mod_dev_adv_properties, has more details on doing this.
|
||||
|
||||
|
||||
\subsection mod_dev_adv_properties Saving Settings and Properties
|
||||
|
||||
@ -3,15 +3,17 @@
|
||||
|
||||
\section ingestmodule_modules Ingest Module Basics
|
||||
|
||||
This section tells you how to make an Ingest Module.
|
||||
Ingest modules analyze data from a disk image.
|
||||
They typically focus on a specific type of data analysis.
|
||||
The modules are loaded each time that Autopsy starts.
|
||||
The user can choose to enable each module when they add an image to the case. It assumes you have already setup your development environment as described in \ref mod_dev_page.
|
||||
This section tells you how to make an Ingest Module. Ingest modules
|
||||
analyze data from a data source (a disk image or set of logical
|
||||
files). They typically focus on a specific type of data analysis.
|
||||
The modules are loaded each time that Autopsy starts. The user can
|
||||
choose to enable each module when they add an image to the case.
|
||||
It assumes you have already setup your development environment as
|
||||
described in \ref mod_dev_page.
|
||||
|
||||
First, you need to choose the type of Ingest Module.
|
||||
|
||||
- Image-level modules are passed in a reference to an image and perform general analysis on it.
|
||||
- Data Source-level modules are passed in a reference to a top-level data source, such as an Image or folder of logical files.
|
||||
These modules may query the database for a small set of specific files. For example, a Windows registry module that runs on the hive files. It is interested in only a small subset of the hard drive files.
|
||||
|
||||
- File-level modules are passed in a reference to each file.
|
||||
@ -36,20 +38,22 @@ Refer to the documentation for each method for its use.
|
||||
- org.sleuthkit.autopsy.ingest.IngestModuleAbstract.getVersion() returns the version of the module.
|
||||
|
||||
|
||||
The process() method is invoked to analyze the data. This is where the analysis is done. The specific method depends on the module type; it is passed
|
||||
either an Image or a File to process. We'll cover this in later sections. This method will post results to the blackboard
|
||||
and with inbox messages to the user.
|
||||
The process() method is invoked to analyze the data. This is where
|
||||
the analysis is done. The specific method depends on the module
|
||||
type; it is passed either a data source or a file to process. We'll
|
||||
cover this in later sections. This method will post results to the
|
||||
blackboard and with inbox messages to the user.
|
||||
|
||||
|
||||
\section ingest_image Image-level Modules
|
||||
\section ingest_datasrc Data Source-level Modules
|
||||
|
||||
To make an Image-level module, make a new Java class either manually or using the NetBeans wizards. Edit the class to extend "org.sleuthkit.autopsy.ingest.IngestModuleImage". NetBeans will likely complain that you have not implemented the necessary methods and you can use its "hints" to automatically generate stubs for them. Use the documentation for the org.sleuthkit.autopsy.ingest.IngestModuleImage class for details on what each needs to do.
|
||||
To make a data source-level module, make a new Java class either manually or using the NetBeans wizards. Edit the class to extend "org.sleuthkit.autopsy.ingest.IngestModuleDataSource". NetBeans will likely complain that you have not implemented the necessary methods and you can use its "hints" to automatically generate stubs for them. Use the documentation for the org.sleuthkit.autopsy.ingest.IngestModuleDataSource class for details on what each needs to do.
|
||||
|
||||
Example snippet of an ingest-level module process() method:
|
||||
|
||||
\code
|
||||
@Override
|
||||
public void process(Image image, IngestImageWorkerController controller) {
|
||||
public void process(Content dataSource, IngestDataSourceWorkerController controller) {
|
||||
|
||||
//we have some number workunits / sub-tasks to execute
|
||||
//in this case, we know the number of total tasks in advance
|
||||
@ -84,10 +88,10 @@ public void process(Image image, IngestImageWorkerController controller) {
|
||||
|
||||
To make a File-level module, make a new Java class either manually or using the NetBeans wizards. Edit the class to extend "org.sleuthkit.autopsy.ingest.IngestModuleAbstractFile". NetBeans will likely complain that you have not implemented the necessary methods and you can use its "hints" to automatically generate stubs for them. Use the method documentation in the org.sleuthkit.autopsy.ingest.IngestModuleAbstractFile class to fill in the details.
|
||||
|
||||
Unlike Image-level modules, file-level modules are singletons. Only a single instance is created for all files.
|
||||
Unlike Data Source-level modules, file-level modules are singletons. Only a single instance is created for all files.
|
||||
The same file-level module instance will be used for files in different images and even different cases if new cases are opened.
|
||||
|
||||
Every file-level module should support multiple init() -> process() -> complete(), and init() -> process() -> stop() invocations. It should also support init() -> complete() sequences.
|
||||
Every file-level module should support multiple init() -> process() -> complete(), and init() -> process() -> stop() invocations. It should also support init() -> complete() sequences. A new case could be open for each call of init().
|
||||
|
||||
Currently (and this is likely to change in the future), File-level ingest modules are Singletons (meaning that only a single instance is created for the runtime of Autopsy).
|
||||
You will need to implement a public static getDefault() method that returns a static instance of the module. Note that if you skip this step, you will not see an error until Autopsy tries to load your module and the log will say that it does not have a getDefault method.
|
||||
@ -108,86 +112,35 @@ public static synchronized MyIngestModule getDefault() {
|
||||
|
||||
You should also make the constructor private to ensure the singleton status.
|
||||
|
||||
As a result of the singleton design, init() will be called multiple times and even for different cases. Ensure that you update local member variables accordingly each time init() is called. Again, this design will likely change, but it is what it is for now.
|
||||
|
||||
----- ENDED HERE ----
|
||||
|
||||
\subsection ingestmodule_making_registration Module Registration
|
||||
\section ingestmodule_registration Module Registration
|
||||
|
||||
Modules are automatically discovered and registered when \ref mod_dev_plugin "added as a plugin to Autopsy".
|
||||
Currently, a restart of Autopsy is required for the newly discovered ingest module to be fully registered and functional.
|
||||
All you need to worry about is to implement the ingest module interface and the required methods and the module will be
|
||||
automatically discovered by the framework.
|
||||
Modules are automatically discovered if they implement the proper interface.
|
||||
Currently, a restart of Autopsy is required after a module is installed before it is discovered.
|
||||
|
||||
\subsubsection ingestmodule_making_registration_pipeline_config Pipeline Configuration
|
||||
By default, modules that do not come with a standard Autopsy installation will run after the standard modules. No order
|
||||
is implied. This design will likely change in the future, but currently manual configuration is needed to enforce order.
|
||||
|
||||
Autopsy maintains an ordered list of autodiscovered modules. The order of a module in the pipeline determines
|
||||
when it will be run relative to other modules. The order can be important for some modules and it can be adjusted.
|
||||
|
||||
When a module is installed using the plugin installer, it is automatically discovered and validated.
|
||||
The validation process ensures that the module meets the inter-module dependencies, implements the right interfaces and methods
|
||||
and meets constrains enforced by the schema. If the module is valid, it is registered and added to the right pipeline
|
||||
based on the interfaces it implements, and the pipeline configuration is updated with the new module.
|
||||
If the module is not already known to the pipeline configuration, it gets the default order assigned --
|
||||
it is added to the end of the pipeline.
|
||||
|
||||
If the module is invalid, it will still be added to the pipeline configuration, but it will not be instantiated.
|
||||
It will be re-validated again next time the module discovery runs. The validation process logs its results to the main
|
||||
Autopsy log files.
|
||||
|
||||
The pipeline configuration is an XML file with currently discovered modules
|
||||
and the modules that were discovered in the past but are not currently loaded.
|
||||
Autopsy maintains that file in the Autopsy user configuration directory.
|
||||
The XML file defines the module location, its place in the ingest pipeline, along with optional configuration arguments.
|
||||
The example of the pipeline configuration is given below:
|
||||
|
||||
\code
|
||||
<PIPELINE_CONFIG>
|
||||
<PIPELINE type="FileAnalysis">
|
||||
<MODULE order="1" type="plugin" location="org.sleuthkit.autopsy.hashdatabase.HashDbIngestModule" arguments="" />
|
||||
<MODULE order="2" type="plugin" location="org.sleuthkit.autopsy.exifparser.ExifParserFileIngestModule"/>
|
||||
</PIPELINE>
|
||||
|
||||
<PIPELINE type="ImageAnalysis">
|
||||
<MODULE order="1" type="plugin" location="org.sleuthkit.autopsy.recentactivity.RAImageIngestModule" arguments=""/>
|
||||
</PIPELINE>
|
||||
</PIPELINE_CONFIG>
|
||||
\endcode
|
||||
|
||||
There is an XML pipeline configuration that contains the standard modules and specifies the order that they are run in.
|
||||
If you need to specify the order of modules, then they needed to be manually addded to this file in the correct order.
|
||||
This file is the same format as The Sleuth Kit Framework configuration file.
|
||||
Refer to http://sleuthkit.org/sleuthkit/docs/framework-docs/pipeline_config_page.html which is an official documentation
|
||||
for the pipeline configuration schema.
|
||||
|
||||
The pipeline configuration file should not be directly edited by a regular user,
|
||||
but it can be edited by a developer to test their module.
|
||||
|
||||
Autopsy will provide tools for reconfiguring the ingest pipeline in the near future,
|
||||
and user/developer will be able to reload current view of discovered modules,
|
||||
reorder modules in the pipeline and set their arguments using GUI.
|
||||
|
||||
|
||||
\subsection ingestmodule_using_services Using Ingest Services
|
||||
\section ingestmodule_services Ingest Services
|
||||
|
||||
Class org.sleuthkit.autopsy.ingest.IngestModuleServices provides services specifically for the ingest modules
|
||||
and a module developer should use these utilities.
|
||||
Class org.sleuthkit.autopsy.ingest.IngestServices provides services specifically for the ingest modules
|
||||
and a module developer should use these utilities to send messages, get current case, etc. Refer to its documentation for method details.
|
||||
|
||||
The class has methods for ingest modules to:
|
||||
- send ingest messages to the inbox,
|
||||
- send new data events to registered listeners (such as viewers),
|
||||
- check for errors in the file-level pipeline,
|
||||
- getting access to org.sleuthkit.datamodel.SleuthkitCase database and the blackboard,
|
||||
- getting loggers,
|
||||
- getting and setting module settings.
|
||||
|
||||
To use it, a handle to org.sleuthkit.autopsy.ingest.IngestServices singleton object should be initialized
|
||||
in the module's \c init() method. For example:
|
||||
|
||||
\code
|
||||
services = IngestServices.getDefault()
|
||||
\endcode
|
||||
|
||||
It is safe to store handle to services in your module private member variable.
|
||||
|
||||
However, DO NOT initialize the services handle statically in the member variable declaration.
|
||||
Use the init() method to do that to ensure proper order of initialization of objects in the platform.
|
||||
Remember, update references to IngestServices and Cases with each call to init() inside of the module.
|
||||
|
||||
Module developers are encouraged to use Autopsy's org.sleuthkit.autopsy.coreutils.Logger
|
||||
infrastructure to log errors to the Autopsy log.
|
||||
@ -198,28 +151,15 @@ module configurations or state.
|
||||
The ModuleSettings API can be used also via org.sleuthkit.autopsy.ingest.IngestServices class.
|
||||
|
||||
|
||||
\subsection ingestmodule_making_results Posting Results
|
||||
\section ingestmodule_making_results Posting Results
|
||||
|
||||
<!-- @@@ -->
|
||||
NOTE: This needs to be made more in sync with the \ref platform_blackboard. This section (or one near this) needs to be the sole source of ingest inbox API information.
|
||||
Ingest modules run in the background. There are three ways to send messages and save results:
|
||||
- Blackboard for long-term storage of analysis results and display in the results tree.
|
||||
- Ingest Inbox to notify user of high-value analysis results that were also posted to blackboard.
|
||||
- Error messages.
|
||||
|
||||
Users will see the results from ingest modules in one of two ways:
|
||||
- Results are posted to the blackboard and will be displayed in the navigation tree
|
||||
- For selected results, messages are sent to the Ingest Inbox to notify a user of what has recently been found.
|
||||
|
||||
\subsubsection ingestmodule_making_results_bb Posting Results to Blackboard
|
||||
|
||||
See the Blackboard (REFERENCE) documentation for posting results to it.
|
||||
|
||||
Modules are free to immediately post results when they find them
|
||||
or they can wait until they are ready to post the results or until ingest is done.
|
||||
|
||||
An example of waiting to post results is the keyword search module.
|
||||
It is resource intensive to commit the keyword index and do a keyword search.
|
||||
Therefore, when its process() method is invoked,
|
||||
it checks if it is internal timer and result posting frequency setting
|
||||
to check if it is close to it since the last time it did a keyword search.
|
||||
If it is, then it commits the index and performs the search.
|
||||
\subsection ingestmodule_making_results_bb Posting Results to Blackboard
|
||||
The blackboard is used to store results so that they are displayed in the results tree. See \ref platform_blackboard for details on posting results to it.
|
||||
|
||||
When modules add data to the blackboard,
|
||||
modules should notify listeners of the new data by
|
||||
@ -229,10 +169,18 @@ This allows other modules (and the main UI) to know when to query the blackboard
|
||||
However, if you are writing a larger number of blackboard artifacts in a loop, it is better to invoke
|
||||
IngestServices.fireModuleDataEvent() only once after the bulk write, not to flood the system with events.
|
||||
|
||||
\subsubsection ingestmodule_making_results_inbox Posting Results to Message Inbox
|
||||
\subsection ingestmodule_making_results_inbox Posting Results to Message Inbox
|
||||
|
||||
Modules should post messages to the inbox when interesting data is found that has also been posted to the blackboard.
|
||||
The idea behind these messages are that they are presented in chronological order so that users can see what was
|
||||
found while they were focusing on something else.
|
||||
|
||||
|
||||
These messages should only be sent if the result has a low false positive rate and will likely be relevant.
|
||||
For example, the hash lookup module will send messages if known bad (notable) files are found,
|
||||
but not if known good (NSRL) files are found. You can provide options to the users on when to make messages.
|
||||
|
||||
|
||||
Modules should post messages to the inbox when interesting data is found and has been posted to the blackboard.
|
||||
|
||||
A single message includes the module name, message subject, message details,
|
||||
a unique message id (in the context of the originating module), and a uniqueness attribute.
|
||||
The uniqueness attribute is used to group similar messages together
|
||||
@ -241,71 +189,41 @@ and to determine the overall importance priority of the message
|
||||
|
||||
For example, for a keyword search module, the uniqueness attribute would the keyword that was hit.
|
||||
|
||||
It is important though to not fill up the inbox with messages. Do not post an inbox message for every
|
||||
result artifact written to the blackboard.
|
||||
|
||||
These messages should only be sent if the result has a low false positive rate and will likely be relevant.
|
||||
For example, the hash lookup module will send messages if known bad (notable) files are found,
|
||||
but not if known good (NSRL) files are found.
|
||||
The keyword search module will send messages if a specific keyword matches,
|
||||
but will not send messages (by default) if a regular expression match for a URL has matches
|
||||
(because a lot of the URL hits will be false positives and can generate thousands of messages on a typical system).
|
||||
Messages are created using the org.sleuthkit.autopsy.ingest.IngestMessage class and posted
|
||||
using methods in \ref ingestmodule_services.
|
||||
|
||||
|
||||
Ingest messages have different types:
|
||||
there are info messages, warning messages, error messages and data messages.
|
||||
\section ingestmodule_making_configuration Module Configuration
|
||||
|
||||
Modules will mostly post data messages about the most relevant results.
|
||||
The data messages contain encapsulated blackboard artifacts and attributes.
|
||||
The passed in data is used by the ingest inbox GUI widget to navigate
|
||||
to the artifact view in the directory tree, if requested by the user.
|
||||
Ingest modules may require user configuration. In \ref mod_dev_adv_options, you learned about Autopsy-wide settings. There are some
|
||||
settings that are specific to ingest modules as well.
|
||||
|
||||
Ingest message API is defined in IngestMessage class.
|
||||
The class also contains factory methods to create new messages.
|
||||
Messages are posted using IngestServices.postMessage() method,
|
||||
which accepts a message object created using one of the factory methods.
|
||||
The framework
|
||||
supports two levels of configuration: simple and advanced. Simple settings enable the user to enable and disable basic things at run-time (using check boxes and such).
|
||||
Advanced settings require more in-depth configuration with more powerful interface.
|
||||
|
||||
Modules should post info messages (with no data) to the inbox
|
||||
at minimum when stop() or complete() is invoked (refer to the examples).
|
||||
It is recommended to populate the description field of the complete inbox message to provide feedback to the user
|
||||
summarizing the module ingest run and if any errors were encountered.
|
||||
|
||||
Modules should also post high-level error messages (e.g. without flooding the inbox
|
||||
when the same error encountered for a large number of files).
|
||||
|
||||
|
||||
\subsection ingestmodule_making_configuration Module Configuration
|
||||
|
||||
<!-- @@@ -->
|
||||
NOTE: Make sure we update this to reflect \ref mod_dev_properties and reduce duplicate comments.
|
||||
|
||||
Ingest modules may require user configuration. The framework
|
||||
supports two levels of configuration: run-time and general. Run-time configuration
|
||||
occurs when the user selects which ingest modules to run when an image is added. This level
|
||||
of configuration should allow the user to enable or disable settings. General configuration is more in-depth and
|
||||
may require an interface that is more powerful than simple check boxes.
|
||||
|
||||
As an example, the keyword search module uses both configuration methods. The run-time configuration allows the user
|
||||
to choose which lists of keywords to search for. However, if the user wants to edit the lists or create lists, they
|
||||
need to do go the general configuration window.
|
||||
|
||||
Module configuration is module-specific: every module maintains its own configuration state and is responsible for implementing the graphical interface. However, Autopsy does provide \ref mod_dev_configuration "a centralized location to display your settings to the user".
|
||||
|
||||
The run-time configuration (also called simple configuration), is achieved by each
|
||||
ingest module providing a JPanel. The IngestModuleAbstract.hasSimpleConfiguration(),
|
||||
IngestModuleAbstract.getSimpleConfiguration(), and IngestModuleAbstract.saveSimpleConfiguration()
|
||||
methods should be used for run-time configuration.
|
||||
|
||||
The general configuration is also achieved by the module returning a JPanel. A link will be provided to the general configuration from the ingest manager if it exists.
|
||||
The IngestModuleAbstract.hasAdvancedConfiguration(),
|
||||
IngestModuleAbstract.getAdvancedConfiguration(), and IngestModuleAbstract.saveAdvancedConfiguration()
|
||||
methods should be used for general configuration.
|
||||
As an example, the advanced configuration for the keyword search module allows you to add and create keyword lists, choose encodings, etc. The simple interface allows
|
||||
you to enable and disable lists.
|
||||
|
||||
Module configuration is module-specific: every module maintains its own configuration state and is responsible for implementing the graphical interface.
|
||||
If a module needs simple or advanced configuration, it needs to implement methods in its interface.
|
||||
The org.sleuthkit.autopsy.ingest.IngestModuleAbstract.hasSimpleConfiguration(),
|
||||
org.sleuthkit.autopsy.ingest.IngestModuleAbstract.getSimpleConfiguration(), and org.sleuthkit.autopsy.ingest.IngestModuleAbstract.saveSimpleConfiguration()
|
||||
methods should be used for simple configuration. This panel will be shown when the user chooses which ingest modules to enable.
|
||||
|
||||
The advanced configuration is implemented with the
|
||||
org.sleuthkit.autopsy.ingest.IngestModuleAbstract.hasAdvancedConfiguration(),
|
||||
org.sleuthkit.autopsy.ingest.IngestModuleAbstract.getAdvancedConfiguration(), and
|
||||
org.sleuthkit.autopsy.ingest.IngestModuleAbstract.saveAdvancedConfiguration()
|
||||
methods. This panel can be accessed from the "Advanced" button when the user chooses which ingest modules to enable.
|
||||
It is recommended that the advanced panel be the same panel that is used in the Options area (see \ref mod_dev_adv_options).
|
||||
|
||||
Refer to \ref mod_dev_adv_properties for details on saving properties from these panels.
|
||||
|
||||
|
||||
<!-- @@@ MOVE THIS TO ADVANED -- I"M NOT SURE WHO NEEDS THIS..
|
||||
\section ingestmodule_events Getting Ingest Status and Events
|
||||
|
||||
<!-- @@@ -->
|
||||
NOTE: Sync this up with \ref mod_dev_events.
|
||||
|
||||
Other modules and core Autopsy classes may want to get the overall ingest status from the ingest manager.
|
||||
@ -324,62 +242,6 @@ The event is an indication for listeners to perform the final data refresh by qu
|
||||
Module developers are encouraged to generate periodic IngestModuleEvent.DATA
|
||||
ModuleDataEvent events when they post data to the blackboard,
|
||||
but the IngestManager will make a final event to handle scenarios where the module did not notify listeners while it was running.
|
||||
|
||||
|
||||
|
||||
|
||||
---- MERGE THIS IN -----
|
||||
\subsection mod_dev_configuration_ingest Ingest Dialog Panel
|
||||
|
||||
Each ingest module has a small configuration panel when the user
|
||||
|
||||
The ingest configuration dialog panel is displayed anytime ingest is to be started/restarted.
|
||||
It provides framework for two-levels of settings: "simple panel" as well as an "advanced panel".
|
||||
The simple panel is shown directly in the ingest configuration panel on the right-hand side when a specific module is selected.
|
||||
The advanced panel is opened in a new window if the user presses the Advanced button in the ingest configuration dialog.
|
||||
|
||||
Both of these panels can be created as a standard \c JPanel, and returned by your ingest module using
|
||||
of the the ingest module methods implemented, that are declared in the ingest module interface.
|
||||
|
||||
It is recommended when making an ingest module to have the advanced panel also be accessible also via the main Options panel,
|
||||
allowing the user access to the settings from Tools > Options and not only via the ingest module configuration.
|
||||
|
||||
See \ref ingestmodule_making_configuration how to implement hooks for having your ingest module configurations registered.
|
||||
|
||||
|
||||
----- MERGE THIS IN ----
|
||||
When developing Ingest modules specifically - their life cycle is managed by ingest manager
|
||||
and an ingest module does not need to listen for case change events
|
||||
or other general system-wide events.
|
||||
However, it should make sure that it gets a new handle to the current Case every time the module's init() is invoked.
|
||||
|
||||
|
||||
---- MERGE
|
||||
\section ingestmodule_relevant_api Relevant APIs
|
||||
|
||||
Relevant APIs to a ingest module writer are:
|
||||
|
||||
- The org.sleuthkit.autopsy.ingest.IngestServices class, which contains methods to post ingest results and
|
||||
to get access to services in the framework (Case and blackboard, logging, configuration , and others).
|
||||
- Interfaces org.sleuthkit.autopsy.ingest.IngestModuleAbstractFile and org.sleuthkit.autopsy.ingest.IngestModuleImage, one of which needs to be implemented by the module.
|
||||
There is also a parent interface, org.sleuthkit.autopsy.ingest.IngestModuleAbstract, common to all ingest modules.
|
||||
- Additional utilities in the Autopsy \ref org.sleuthkit.autopsy.coreutils module for getting information about the platform,
|
||||
versions and for file operations.
|
||||
|
||||
|
||||
|
||||
-------
|
||||
Some notes:
|
||||
- File-level modules will be called on each file in an order determined by the org.sleuthkit.autopsy.ingest.IngestManager.
|
||||
Each module is free to quickly ignore a file based on name, signature, etc.
|
||||
|
||||
- If a module wants to know the return value from a previously run module on this file,
|
||||
it should use the org.sleuthkit.autopsy.ingest.IngestServices.getAbstractFileModuleResult() method.
|
||||
|
||||
- Image-level modules are not passed in specific files and are expected to query the database
|
||||
to find the files that they are interested in. They can use the org.sleuthkit.datamodel.SleuthkitCase object handle (initialized in the init() method) to query the database.
|
||||
|
||||
- File-level module could be passed in files from different images in consecutive calls to process().
|
||||
|
||||
-->
|
||||
|
||||
*/
|
||||
|
||||
@ -1,7 +1,11 @@
|
||||
/*! \page mod_report_page Developing Report Modules
|
||||
|
||||
\section report_summary Summary
|
||||
There are two types of reporting modules: table report modules and general report modules.
|
||||
Report modules allow you to create different report types. Autopsy comes with moules to generate HTML and a body file for timeline creation. You can made additional modules to create custom output formats.
|
||||
|
||||
There are two types of reporting modules that differ in how the data is organized.
|
||||
- General report modules are free form and you are allowed to organize the output however you want.
|
||||
- Table report modules organize the data into tables. If your output is in table format, this type of module will be easier to make the module because Autopsy does a lot of the organizing work for you.
|
||||
|
||||
Each reporting submodule implements either the org.sleuthkit.autopsy.report.TableReportModule interface or the org.sleuthkit.autopsy.report.GeneralReportModule interface, and registers itself in layer.xml
|
||||
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
/*! \page mod_result_page Developing Result Viewer Modules
|
||||
|
||||
NOTE: This has been moved from a package-level description and needs cleanup.
|
||||
NOTE: This has been moved from a package-level description and needs cleanup and updating.
|
||||
|
||||
<h3>Creating a DataResultViewer</h3>
|
||||
<p>DataResultTopComponent is the high-level window in the DataResult area. Each instance of this loads up all instances of DataResultViewers that have been registered with the system. Example viewers include the table and thumbnail views. If you want to make your own type of viewer, follow the steps below.
|
||||
<p>DataResultTopComponent is the high-level window in the DataResult area. The DataResult area is in the upper right of Autopsy and shows a set of nodes (i.e. in table form or thumbnail, by default). You will want to create a new module in this area if you have a new way to display a set of files or nodes. For example, in a graph form or different layout beyond the simple table.
|
||||
|
||||
<ol>
|
||||
<li>Create a module from within NetBeans. It must be dependent on these modules:
|
||||
@ -24,7 +24,7 @@ NOTE: This has been moved from a package-level description and needs cleanup.
|
||||
|
||||
<li>Make a class that extends org.sleuthkit.autopsy.corecomponents.AbstractDataResultViewer and is registered as a service provider for the org.sleuthkit.autopsy.corecomponentinterfaces.DataResultViewer class by specifying "@ServiceProvider(service = DataResultViewer.class)" or by using layer.xml. This class will extend JPanel. </li>
|
||||
|
||||
<li>See the previous sections on default actions. (note that this refers to the CoreComponentINterfaces package-level description, which I think is now in \ref design_data_flow).</li>
|
||||
<li>See the previous sections on default actions. (note that this refers to the CoreComponentINterfaces package-level description).</li>
|
||||
|
||||
</ol>
|
||||
|
||||
|
||||
@ -11,17 +11,17 @@ These are the basic concepts that you should be aware of before writing a module
|
||||
- Browsing and searching: User can manually browse and search the data using the user interface.
|
||||
- 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 the disk image and the output from modules. Access to this database can be found from the SleuthKitCase class, but you'll probably never need to directly interact with it. <!-- @@@ IS THAT CORRECT -->
|
||||
- <b>Utilities</b>: There are core utilities that the platform provides to modules. See the \ref mod_dev_utilities section for more details.
|
||||
- <b>Services</b>: There are services provided by the platform. See the \ref mod_dev_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>Services</b>: There are services provided by the platform. See the \ref mod_dev_other_services section for more details.
|
||||
- <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>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
|
||||
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 image is added to a case (and can be re-run afterwards too). See \ref mod_ingest_page for details on building these modules. These modules come in two forms:
|
||||
- <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). See \ref mod_ingest_page for details on building these modules. 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.
|
||||
- Image Ingest Modules are called once for every image. 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.
|
||||
- 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.
|
||||
- <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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user