Quick start guide german translation

Dies ist die gekürzte und übersetzte Fassung der englischen Schnellstartanleitung zu Lehrzwecken für die Nestor School 2016.

Installation

PET ist ein Java Programm, muss daher nicht installiert werden und läuft auf allen gängigen Betriebssystemen. Es benötigt aber Java 7 (oder höher) welches hier heruntergeladen werden kann: http://www.java.com/download

Lade die neuste Version von PET hier runter und extrahiere das ZIP Archiv: https://github.com/pericles-project/pet/releases/latest

Führe die .jar Datei aus (Windows: Doppelklick, Linux/OS X: java -jar PeriCAT.jar).

Erste Schritte

Lerne die grafische Benutzeroberfläche kennen

Beim ersten Start von PET wird sich die grafische Benutzeroberfläche (GUI "Graphical User Interface") öffnen.

Die GUI ist in Registerkarten ("Tabs") organisiert, wie in folgendem Bildschirmschnappschuss zu sehen ist:

1. Der “Monitored files”-Tab zeigt eine Liste von Dateien die mit PET untersucht werden sollen
2. In dem “Modules”-Tab können Module zum Sammeln von Informationen hinzugefügt und konfiguriert werden
3. Der “Environment information”-Tab zeigt die gesammelten Umgebungsinformationen die für alle Dateien der Umgebung gleichermaßen gültig sind
4. Der “Events”-Tab führt alle aufgezeichneten Umgebungsereignisse auf, die von dem Tool erkannt wurden
5. Die gesammelten Umgebungsinformationen die zu einer bestimmten Datei gehören (und somit nicht für alle untersuchten Dateien gültig sind) können in dem "Monitored files"-Tab angesehen werden, indem die dazugehörige Datei ausgewählt wird.
6. Profile erlauben es die Module und die zu untersuchenden Dateien zu ordnen. So können mehrere Szenarien in PET konfiguriert werden.
7. Unten in der Benutzeroberfläche sind Knöpfe um das Sammeln der Informationen zu steuern

Füge eine Datei hinzu

Öffnen Sie den "Monitored files"-Tab und fügen Sie mit dem "Add Files"-Knopf eine Datei hinzu, die von PET untersucht werden soll. Es wird sich ein Dialog zum Hinzufügen der Datei öffnen. Beim Sammeln von Umgebungsinformationen werden Informationen gesammelt die für diese Dateien wichtig sind. Die Dateien werden dabei nicht von PET verändert.

Selektieren Sie ein Modul zum Sammeln von Informationen

Öffnen sie den "Modules"-Tab. Dieser verwaltet die Liste von Modulen die definieren welche Informationen gesammelt werden sollen. Klicken Sie den "Add new modules"-Knopf, um Module dieser Liste hinzuzufügen. Eine Oberfläche zum Konfigurieren der Module öffnet sich, wenn dieses in der Liste ausgewählt wird.

Starten Sie einen Schnappschusssammelvorgang

Klicken Sie den "Snapshot"-Knopf unten links in der Benutzeroberfläche. Dies wird einen einzelnen Sammelvorgang starten, bei dem jedes Modul einmal ausgeführt wird.

Betrachten Sie die Ergebnisse

Sie können die gesammelten Umgebungsinformationen im "Environment information"-Tab betrachten. Die Datei abhängigien Informationen können in dem "Monitored files"-Tab betrachtet werden.

PET verstehen

Es folgt ein tieferer Blick in die Funktionalitäten von PET.

Profile und Entwurfsvorlagen

PET organisiert die Dateien und Module zum Sammeln von Informationen in Profilen, um verschiedene Konfigurationen für verschiedene Szenarien laden zu können. Beim Start des Tools wird ein leeres Profil geladen. Existierende Profile können mit der "Select profile:"-Combobox oben in der Benutzeroberfläche ausgewählt werden.

Der Knopf "New profile (from template)" erlaubt das Erstellen von Profilen basierend auf vorkonfigurierten Entwurfsvorlagen für spezielle Szenarien. Es ist auch möglich Profile als Entwurfsvorlagen zu exportieren, um sie anderen PET-Benutzern zu schicken die dann Profile aus diesen Vorlagen erstellen können.

Eine Entwurfsvorlage beinhaltet die vorkonfigurierten Module, aber nicht die Dateien, da diese auf anderen Computern wahrscheinlich nicht vorhanden sind.

Die gespeicherten Entwurfsvorlagen können in folgendem Ordner gefunden werden: .../PET_data/config/profile_templates/ Es ist auch möglich diese JSON Konfigurationsdateien manuell zu ändern. Alle Vorlagen aus diesem Ordner können vom laufenden Programm aus als Profile geladen werden.

Zwei verschiedene Modi zum Sammeln von Informationen

PET bietet zwei Modi zum Sammeln von Informationen an:

1. Schnappschuss Modus: In diesem Modus wird jedes Modul zum Sammeln von Informationen einmal gestartet. Die Module zum Beobachten von Umgebungsereignissen werden in diesem Modus nicht ausgeführt. Der Sammelvorgang kann duch Klicken auf den "Snapshot"-Knopf ausgeführt werden.

2. Kontinuierlicher Sammelmodus: Dieser Modus kann in einem Sheer-Curation-Szenario verwendet werden. Die Module zum Beobachten der Umgebung werden gestartet und basierend auf den beobachteten Ereignissen werden kontinuierlich Informationen über die Umgebung gesammelt. Der Modus kann gestartet oder gestoppt werden, indem der "Start/Stop monitor"-Knopf unten in der Benutzeroberfläche geklickt wird.

Datei abhängige Informationen und Datei unabhängige Umgebungsinformationen

Die Umgebungsinformationen die gesammelt werden können entweder Datei abhängig sein und sich für jede beobachtete Datei ändern, oder sie sind Datei unabhängig und bleiben für alle Dateien gültig.

TODO --- under construction...

Extraction modules and environment monitoring daemons

There are three types of Extraction Modules: Modules that extract file dependent information, modules that extract file independent information, and environment monitoring daemons, which don’t extract any information, but observe the environment for occurring events to trigger the extraction of other modules. The available modules can be browsed in the “modules”-tab by clicking the “Add new modules”-button, or by entering the command “modules” into the CLI. Each module provides a detailed description about the information that it extracts and about configuration possibilities.

Configuration of a module or a daemon

The Extraction Modules including the daemons can be configured in the “Modules”-tab by editing their JSON configuration files. The configuration has to follow strictly the JSON syntax. By clicking the “Save and use configuration”-button the syntax will be verified and a message will be shown in case of an error. You can use the “Reload config file”-button to restore the old configuration.

• The “class” option shows the java class which is associated with the displayed configuration and shouldn’t be changed. It is needed for the deserialization of the configuration.
• “moduleName” is the module type name and shouldn’t be changed either. If you want to change the displayed name of the module, you can edit “moduleDisplayName” instead.
• “moduleVersion” displays the development version of the module and shouldn’t be changed manually.
• The “enabled” option shows if a module is currently used for extraction or not. You can also use the radio button at the top-right of the configuration area for fast changing this option. Some modules might disable themselves if they need further configurations before an execution. *“recordEvents” TODO: Is it to write occurring events also to a file?
• “supportedSystems” lists the operating systems on that the module will run. “SYSTEM_INDEPENDENT” is the default option. If you configure a module in a way that it can only be executed on a specific operating system, change this variable to one or more of these: "OS_X", "SOLARIS", "BSD", "LINUX", and / or "WINDOWS".
• “fileFilter” lets you restrict the file types on that a file-dependent module is executed, or that a daemon module is looking for. It can also be important for some file-independent modules that operate on system files. The five options are described in the following
  • “fileExtensionFilter”: Define a regex to filter the file extensions. Therefore use the java regex syntax
  • “inclusiveMimeType”: Consider only files of a specific mime type. For example “application/pdf”
  • “inclusiveMediaType”: Consider only files of the specific media type. For example “text”
  • “exclusiveMediaType”: Consider files of all media types, except that ones that are added here.
  • “exclusiveMimeType”: Consider files of all mime types, except that ones that are added here.
• “eventAddToProfile” TODO: is this the option to write events to a file?

These are the default options. All further options are customized implementations that can vary depending on the regarded module. The descriptions of the modules should also help with the configuration.

Browsing extraction results

The “Environment information”-tab provides the extracted file-independent information, whereas the extracted file-dependent information can be found at the “Monitored files”-tab by selecting one of the files in the list. By default an “information tree” is displayed that shows the extracted information sorted by extraction dates and extraction modules inserted into a tree structure. A double click on a result will open it in JSON format in a new window. An display mode intended for the visualisation of changes of environment information can be accessed by clicking the “Visualise information change”-button. Therefore an extraction module has to be selected in the combo box above. This mode will show the results of the selected module for all past extraction runs in a table, whereby the first row shows the corresponding date of extraction. The table can be opened in fullscreen mode and exported for further analysis. If no extraction module was selected, and the “Visualise information change”-button is clicked, the last extraction result is compared to the previous result with highlighted differences. The “Show information in JSON”-button displays the same information as the information change display, but uses the JSON format instead of a table.

It highly depends on the actual use case, which of the displaying modes are the appropriate ones.

Startup parameters

The following commands can either be specified in the configuration file .../PET_data/config/extractionPreferences in the format “option=value” with one option per line, or added as flags at tool start in the format “java -jar PET.jar --option1 --option2 …”.

• help: Prints out all possible start commands. The tool won’t be executed, if this command is entered.
• phelp: Prints out the description of this tool. The tool won’t be executed, if this command is entered.
• version: Prints the version of this tool. The tool won’t be executed, if this command is entered.
• headless: This option will disable the GUI and the system tray icon to start the tool without any graphics. The command line interface will be started.
• storage: This option defines the storage to be used for saving the extraction results. By default the results are saved to an elasticsearch database.
• destination: Defines the directory where the “PET_data” directory will be created.
• once: Starts a single extraction at start. This will prevent that the tool starts in the continuous extraction mode.