Updated python examples and docs

pythonExamples/fileIngestModuleWithGui.py

@@ -0,0 +1,203 @@
+# Sample module in the public domain. Feel free to use this as a template
+# for your modules (and you can remove this header and take complete credit
+# and liability)
+#
+# Contact: Brian Carrier [carrier <at> sleuthkit [dot] org]
+#
+# This is free and unencumbered software released into the public domain.
+#
+# Anyone is free to copy, modify, publish, use, compile, sell, or
+# distribute this software, either in source code form or as a compiled
+# binary, for any purpose, commercial or non-commercial, and by any
+# means.
+#
+# In jurisdictions that recognize copyright laws, the author or authors
+# of this software dedicate any and all copyright interest in the
+# software to the public domain. We make this dedication for the benefit
+# of the public at large and to the detriment of our heirs and
+# successors. We intend this dedication to be an overt act of
+# relinquishment in perpetuity of all present and future rights to this
+# software under copyright law.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+
+# Ingest module for Autopsy with GUI
+#
+# Difference between other modules in this folder is that it has a GUI
+# for user options.  This is not needed for very basic modules. If you
+# don't need a configuration UI, start with the other sample module.
+#
+# Search for TODO for the things that you need to change
+# See http://sleuthkit.org/autopsy/docs/api-docs/3.1/index.html for documentation
+
+
+import jarray
+from java.lang import System
+from javax.swing import JCheckBox
+from javax.swing import BoxLayout
+from org.sleuthkit.autopsy.casemodule import Case
+from org.sleuthkit.autopsy.casemodule.services import Services
+from org.sleuthkit.autopsy.ingest import DataSourceIngestModule
+from org.sleuthkit.autopsy.ingest import FileIngestModule
+from org.sleuthkit.autopsy.ingest import IngestMessage
+from org.sleuthkit.autopsy.ingest import IngestModule
+from org.sleuthkit.autopsy.ingest.IngestModule import IngestModuleException
+from org.sleuthkit.autopsy.ingest import IngestModuleFactoryAdapter
+from org.sleuthkit.autopsy.ingest import IngestModuleIngestJobSettings
+from org.sleuthkit.autopsy.ingest import IngestModuleIngestJobSettingsPanel
+from org.sleuthkit.autopsy.ingest import IngestServices
+from org.sleuthkit.autopsy.ingest import IngestModuleGlobalSettingsPanel
+from org.sleuthkit.datamodel import BlackboardArtifact
+from org.sleuthkit.datamodel import BlackboardAttribute
+from org.sleuthkit.datamodel import ReadContentInputStream
+from org.sleuthkit.autopsy.coreutils import Logger
+from java.lang import IllegalArgumentException
+
+# TODO: Rename this to something more specific
+class SampleFileIngestModuleWithUIFactory(IngestModuleFactoryAdapter):
+    def __init__(self):
+        self.settings = None
+
+    # TODO: give it a unique name.  Will be shown in module list, logs, etc.
+    moduleName = "Sample Data Source Module with UI"
+    
+    def getModuleDisplayName(self):
+        return self.moduleName
+    
+    # TODO: Give it a description
+    def getModuleDescription(self):
+        return "Sample module that does X, Y, and Z."
+
+    def getModuleVersionNumber(self):
+        return "1.0"
+
+    # TODO: Update class name to one that you create below
+    def getDefaultIngestJobSettings(self):
+        return SampleFileIngestModuleWithUISettings()
+
+    # TODO: Keep enabled only if you need ingest job-specific settings UI
+    def hasIngestJobSettingsPanel(self):
+        return True
+
+    # TODO: Update class names to ones that you create below
+    def getIngestJobSettingsPanel(self, settings):
+        if not isinstance(settings, SampleFileIngestModuleWithUISettings):
+            raise IllegalArgumentException("Expected settings argument to be instanceof SampleIngestModuleSettings")
+        self.settings = settings
+        return SampleFileIngestModuleWithUISettingsPanel(self.settings)
+
+
+    def isFileIngestModuleFactory(self):
+        return True
+
+
+    # TODO: Update class name to one that you create below
+    def createFileIngestModule(self, ingestOptions):
+        return SampleFileIngestModuleWithUI(self.settings)
+
+
+# File-level ingest module.  One gets created per thread.
+# TODO: Rename this to something more specific. Could just remove "Factory" from above name.
+# Looks at the attributes of the passed in file.
+class SampleFileIngestModuleWithUI(FileIngestModule):
+
+    # Autopsy will pass in the settings from the UI panel
+    def __init__(self, settings):
+        self.local_settings = settings
+
+
+    # Where any setup and configuration is done
+    # TODO: Add any setup code that you need here.
+    def startUp(self, context):
+        self.logger = Logger.getLogger(SampleFileIngestModuleWithUIFactory.moduleName)
+        
+        # As an example, determine if user configured a flag in UI
+        if self.local_settings.getFlag():
+            self.logger.info("flag is set")
+        else:
+            self.logger.info("flag is not set")
+        
+        # Throw an IngestModule.IngestModuleException exception if there was a problem setting up
+        # raise IngestModuleException(IngestModule(), "Oh No!")
+        pass
+
+    # Where the analysis is done.  Each file will be passed into here.
+    # TODO: Add your analysis code in here.
+    def process(self, file):
+        # See code in pythonExamples/fileIngestModule.py for example code
+        return IngestModule.ProcessResult.OK
+
+    # Where any shutdown code is run and resources are freed.
+    # TODO: Add any shutdown code that you need here.
+    def shutDown(self):
+        pass
+
+# Stores the settings that can be changed for each ingest job
+# All fields in here must be serializable.  It will be written to disk.
+# TODO: Rename this class
+class SampleFileIngestModuleWithUISettings(IngestModuleIngestJobSettings):
+    serialVersionUID = 1L
+
+    def __init__(self):
+        self.flag = False
+
+    def getVersionNumber(self):
+        return serialVersionUID
+
+    # TODO: Define getters and settings for data you want to store from UI
+    def getFlag(self):
+        return self.flag
+
+    def setFlag(self, flag):
+        self.flag = flag
+
+
+# UI that is shown to user for each ingest job so they can configure the job.
+# TODO: Rename this
+class SampleFileIngestModuleWithUISettingsPanel(IngestModuleIngestJobSettingsPanel):
+    # Note, we can't use a self.settings instance variable.
+    # Rather, self.local_settings is used.
+    # https://wiki.python.org/jython/UserGuide#javabean-properties
+    # Jython Introspector generates a property - 'settings' on the basis
+    # of getSettings() defined in this class. Since only getter function
+    # is present, it creates a read-only 'settings' property. This auto-
+    # generated read-only property overshadows the instance-variable -
+    # 'settings'
+    
+    # We get passed in a previous version of the settings so that we can
+    # prepopulate the UI
+    # TODO: Update this for your UI
+    def __init__(self, settings):
+        self.local_settings = settings
+        self.initComponents()
+        self.customizeComponents()
+    
+    # TODO: Update this for your UI
+    def checkBoxEvent(self, event):
+        if self.checkbox.isSelected():
+            self.local_settings.setFlag(True)
+        else:
+            self.local_settings.setFlag(False)
+
+    # TODO: Update this for your UI
+    def initComponents(self):
+        self.setLayout(BoxLayout(self, BoxLayout.Y_AXIS))
+        self.checkbox = JCheckBox("Flag", actionPerformed=self.checkBoxEvent)
+        self.add(self.checkbox)
+
+    # TODO: Update this for your UI
+    def customizeComponents(self):
+        self.checkbox.setSelected(self.local_settings.getFlag())
+
+    # Return the settings used
+    def getSettings(self):
+        return self.local_settings
+
+