Initial commit

00-html_header.md

@@ -0,0 +1,15 @@
+---
+title:  'Jungbusch-Auditorium: Benutzerhandbuch'
+
+subtitle: |
+  Dies ist das Benutzerhandbuch für das Jungbusch-Auditorium.
+  Das Jungbusch-Auditorium `(JBA)` ist ein Framework, welches das Durchführen eines Sicherheitsaudits auf einer Maschine erleichtern soll. 
+  
+  Es wurde spezifisch für die Auslieferung an einen Kunden designed. Das bedeutet, dass die Software vollständig konfiguriert ausgeliefert werden kann und daraufhin keinerlei Nutzereingaben, angeben von Commandline-Parametern oder sonstige Konfiguration mehr benötigt. 
+ 
+  Das JBA wird mit einer Vielzahl an Modulen für viele bekannte Betriebssysteme und Architekturen ausgeliefert, welche häufig verwendete Funktionalität zur leichten Verwendung verallgemeinern. Außerdem ist das Erstellen von nutzereigenen Modulen in Golang möglich, ohne dass Code des Frameworks selbst angepasst werden muss.
+  
+  Für das Definieren von Audit-Schritte wurde das JSON-ähnliche `.jba`-Dateiformat entwickelt, in welchem Auditschritte definiert, verschachtelt und mit Variablen oder Bedingungen untereinander verknüpft werden können. 
+  
+  Sobald alle Audit-Schritte abgeschlossen sind, wird eine detailreiche Output-Datei erstellt, welche nicht nur die Ergebnisse sammelt, sondern vor Allem auch mit dem Ziel entworfen wurde, die Ergebnisse nachvollziehbar zu machen. Um dies zu erreichen sammelt das Jungbusch-Auditorium jegliche Artefakte, die beim Ausführen der Schritte verwendet wurden. Dies beeinhaltet ausgelesene Dateien, ausgeführte Konsolen-Befehle und Systemcalls.
+---

00-pdf_header.md

@@ -0,0 +1,31 @@
+---
+title: "Jungbusch Auditorium Dokumentation"
+author: [Jungbusch-Softwareschmiede]
+date: "2021-06-30"
+
+subject: "Jungbusch Auditorium"
+subtitle: "Das Benutzerhandbuch für das Audit-Framework Jungbusch Auditorium"
+
+toc: true
+toc-own-page: true
+
+titlepage: true
+titlepage-color: "3C9F53"
+titlepage-text-color: "FFFFFF"
+titlepage-rule-color: "FFFFFF"
+titlepage-rule-height: 2
+...
+
+# Einleitung
+
+Dies ist das Benutzerhandbuch für das Jungbusch-Auditorium.
+Das Jungbusch-Auditorium `(JBA)` ist ein Framework, welches das Durchführen eines Sicherheitsaudits auf einer Maschine erleichtern soll. 
+
+Es wurde spezifisch für die Auslieferung an einen Kunden designed. Das bedeutet, dass die Software vollständig konfiguriert ausgeliefert werden kann und daraufhin keinerlei Nutzereingaben, angeben von Commandline-Parametern oder sonstige Konfiguration mehr benötigt. 
+
+Das JBA wird mit einer Vielzahl an Modulen für viele bekannte Betriebssysteme und Architekturen ausgeliefert, welche häufig verwendete Funktionalität zur leichten Verwendung verallgemeinern. Außerdem ist das Erstellen von nutzereigenen Modulen in Golang möglich, ohne dass Code des Frameworks selbst angepasst werden muss.
+
+Für das Definieren von Audit-Schritte wurde das JSON-ähnliche `.jba`-Dateiformat entwickelt, in welchem Auditschritte definiert, verschachtelt und mit Variablen oder Bedingungen untereinander verknüpft werden können. 
+
+Sobald alle Audit-Schritte abgeschlossen sind, wird eine detailreiche Output-Datei erstellt, welche nicht nur die Ergebnisse sammelt, sondern vor Allem auch mit dem Ziel entworfen wurde, die Ergebnisse nachvollziehbar zu machen. Um dies zu erreichen sammelt das Jungbusch-Auditorium jegliche Artefakte, die beim Ausführen der Schritte verwendet wurden. Dies beeinhaltet ausgelesene Dateien, ausgeführte Konsolen-Befehle und Systemcalls.
+

00-readme-header.md

@@ -0,0 +1,19 @@
+# Jungbusch-Auditorium: Handbuch
+
+Dieses Repository enthält das Handbuch für das Jungbusch-Auditorium. Für eine HTML/PDF-Version, siehe [Releases](https://github.com/Jungbusch-Softwareschmiede/jungbusch-manual/releases). Für zugehörige Repositories, siehe [Jungbusch-Overview](https://github.com/Jungbusch-Softwareschmiede/jungbusch-overview).
+
+----
+
+# Einleitung
+
+Dies ist das Benutzerhandbuch für das Jungbusch-Auditorium.
+Das Jungbusch-Auditorium `(JBA)` ist ein Framework, welches das Durchführen eines Sicherheitsaudits auf einer Maschine erleichtern soll. 
+
+Es wurde spezifisch für die Auslieferung an einen Kunden designed. Das bedeutet, dass die Software vollständig konfiguriert ausgeliefert werden kann und daraufhin keinerlei Nutzereingaben, angeben von Commandline-Parametern oder sonstige Konfiguration mehr benötigt. 
+
+Das JBA wird mit einer Vielzahl an Modulen für viele bekannte Betriebssysteme und Architekturen ausgeliefert, welche häufig verwendete Funktionalität zur leichten Verwendung verallgemeinern. Außerdem ist das Erstellen von nutzereigenen Modulen in Golang möglich, ohne dass Code des Frameworks selbst angepasst werden muss.
+
+Für das Definieren von Audit-Schritte wurde das JSON-ähnliche `.jba`-Dateiformat entwickelt, in welchem Auditschritte definiert, verschachtelt und mit Variablen oder Bedingungen untereinander verknüpft werden können. 
+
+Sobald alle Audit-Schritte abgeschlossen sind, wird eine detailreiche Output-Datei erstellt, welche nicht nur die Ergebnisse sammelt, sondern vor Allem auch mit dem Ziel entworfen wurde, die Ergebnisse nachvollziehbar zu machen. Um dies zu erreichen sammelt das Jungbusch-Auditorium jegliche Artefakte, die beim Ausführen der Schritte verwendet wurden. Dies beeinhaltet ausgelesene Dateien, ausgeführte Konsolen-Befehle und Systemcalls.
+

01-glossar.md

@@ -0,0 +1,20 @@
+# Glossar
+
+## Konfiguration
+Die **Konfiguration** (Config, Config.ini, Programmkonfiguration) ist die `.ini`-Datei in welcher die Programm-Konfiguration gespeichert werden kann. Die Config-Datei ist die Alternative zum [CLI](#commandline-interface). Diese Datei ist nicht zwingend anzugeben.
+
+## Commandline-Interface
+Das **Commandline-Interface** (CLI) ist die Programmkonfiguration per Konsole durch das angeben von Parametern.
+
+## Audit-Konfiguration
+Die **Audit-Konfiguration** (Audit-Config, DotJBA) enthält den gesamte Ablauf des durchzuführenden Audits. Sie besteht jeweils aus einem oder mehreren [Audit-Schritt](#audit-schritt)en. 
+
+## Audit-Schritt
+Ein **Audit-Schritt**, oder auch **Audit-Modul**, ist ein einzelner in der [Audit-Konfiguration](#audit-konfiguration) definierter Schritt. 
+
+## Modul
+Ein Modul ist ein austauschbarer Programmteil im Jungbusch-Auditorium. "Austauschbar" bedeutet, dass Module unabhängig vom [Framework](#framework) entfernt und hinzugefügt werden können. Module werden aus der [Audit-Konfiguration](#audit-konfiguration) aufgerufen, erwarten Eingabeparameter und führen dann Kommandos oder System-Calls aus, oder lesen Dateien ein. Auf ihr Ergebnis kann in der Audit-Konfiguration per Variable zugegriffen werden und es wird automatisch in die Ergebnis-Datei geschrieben. Des Weiteren merkt sich jedes Modul selbst, welche Artefakte es verwendet hat. Später werden diese von allen Modulen gesammelt, sortiert und abgespeichert.
+
+## Framework
+Das Framework ist im Falle des `Jungbusch-Auditoriums` alles außer den Modulen. Unter anderem das Commandline-Interface, der OS-Detector sowie der Parser und Interpreter der Audit-Konfiguration.
+

02-programmkonfiguration.md

@@ -0,0 +1,165 @@
+# Konfiguration des Jungbusch-Auditoriums
+
+Es gibt zwei Möglichkeiten um Einfluss auf die Programmkonfiguration des JBA zu nehmen: Entweder durch Commandline-Parameter und/oder durch eine Konfigurations-Datei `(ini)`.
+
+Priorität der Konfigurations-Werten (von bedeutsam zu unbedeutsam):
+
+1. Commandline-Parameter
+2. Konfigurations-Datei
+3. Default-Werte
+
+Das bedeutet, dass bei Werten, die sowohl in der Konfigurations-Datei, als auch per Commandline-Parameter angegeben werden, immer **der Wert des Commandline-Parameters** verwendet wird.
+
+Es ist keinerlei Konfiguration zwingend notwendig um das Programm zu starten und erfolgreich ein Audit durchzuführen. Werden Werte nicht explizit vom Nutzer angegeben, fällt das Programm auf [Default-Werte](#default-werte) zurück.
+
+## Pfade
+Pfade können entweder `absolut` oder `relativ zum Pfad der Executable` angeben werden.
+
+> Es wird **nicht** von der Working-Directory ausgegangen!
+
+## Default-Werte
+
+- Konfigurations-Datei --- Siehe Flowchart: [Auswahl der Konfigurations-Datei](#auswahl-der-konfigurations-datei-config.ini)
+- Audit-Datei --- Siehe Flowchart: [Auswahl der Audit-Datei](#auswahl-der-audit-konfigurations-datei-.jba)
+- Output-Pfad: `./` - Das bedeutet, dass wenn nicht anders angegeben, im Pfad der Executable ein Ordner mit dem Namen `jba-result` und einem Zeitstempel erstellt wird.
+- Log-Verbosity: 3, Information (siehe [Log](#log))
+- Konsolen-Verbosity: 2, Warning (siehe [Log](#log))
+
+## Konfiguration per Commandline
+
+Das Commandline-Interface `(CLI)` ist eine der Möglichkeiten des Jungbusch-Auditoriums `(JBA)` um die Software vor ihrem Start zu konfigurieren. 
+
+### Erlaubter Syntax
+- parameter=wert  
+- parameter="wert"
+- parameter wert (Nur bei Non-Booleans)
+- parameter (Nur bei Booleans)
+
+Alle Schreibweisen sind sowohl mit dem Prefix `-` als auch mit `--` erlaubt.
+
+Die Commandline-Parameter selbst sind Case-Sensitive.
+
+### Programmparameter
+Folgende Parameter legen die Programm-Konfiguration fest:
+
+#### -auditConfig, -a
+Der Pfad zur Audit-Konfigurations-Datei. Die angegebene Datei muss vom Format `.jba` sein.
+Wird dieser Parameter nicht angegeben, sucht das Jungbusch-Auditorium nach der Datei `audit.jba` oder verwendet eine `.jba` Datei mit beliebigem Name, solange diese Datei die einzige jba-Datei im Pfad der Executable ist. Siehe Flowchart: [Auswahl der Audit-Datei](#auswahl-der-audit-konfigurations-datei-.jba).
+
+#### -config, -c
+Der Pfad zur Konfigurations-Datei. Die angegebene Datei muss vom Format `.jba` sein. 
+Wird dieser Parameter nicht angegeben, sucht das Jungbusch-Auditorium nach der Datei `config.ini` im Pfad der Executable. Siehe Flowchart: [Auswahl der Konfigurations-Datei](#auswahl-der-konfigurations-datei-config.ini).
+
+#### -outputPath, -o
+Der Pfad zur Output-Directory. Am angegebenen Pfad erstellt das Jungbusch-Auditorium einen Ordner mit dem Namen `jba-result` inklusive Zeitstempel, welcher Ergebnisse, Logs und Artefakte enthält.
+
+#### -verbosityLog, -vl
+Legt fest, wie viele Informationen in die Log-Datei geschrieben werden. Das Level wird als Zahl angegeben.
+
+Siehe auch: [Log](#log)
+
+#### -verbosityCommandline, -vc
+Legt fest, wie viele Informationen auf der Konsole ausgegeben werden. Das Level wird als Zahl angegeben.
+
+Siehe auch: [Log](#log)
+
+#### -keepConsoleOpen
+Mit diesem Parameter kann erreicht werden, dass die Konsole nach eigentlichem Beenden des Programms offen bleibt, bis `Enter` gedrückt wird. Dies ermöglicht es dem Nutzer, die Executable per Doppelklick auszuführen, da sich ohne diesen Parameter das Fenster sofort schließt und man so einen möglicherweise aufgetretenen Fehler nicht rechtzeitig erfassen könnte. Dieser Parameter macht nur in der [Konfigurations-Datei](#konfiguration-per-konfigurations-datei) Sinn.
+
+#### -skipModuleCompatibilityCheck
+Mit diesem Parameter kann die interne Modul-Kompatibilitätsüberprüfung übersprungen werden. Die einzelnen Module legen für sich selbst fest, mit welcher Art von Betriebssystemen oder spezifisch mit welcher Version eines OS sie kompatibel sind. Befindet sich das Betriebssystem des ausführenden Rechners nicht in dieser Liste, wird das Modul nicht geladen. Wird ein nicht geladenes Modul in der Audit-Konfigurations-Datei verwendet, bricht das Programm beim Parsen der Konfiguration mit einem entsprechenden Fehler ab.
+
+#### -forceOS
+Mit diesem Parameter kann das Ergebnis des OS-Detectors überschrieben werden. Dieses wird verwendet um die Kompatibilität der Module zu überprüfen. Der Parameter kann beispielsweise verwendet werden, wenn man den Syntax einer Audit-Konfigurationsdatei auf einem anderen System als dem Zielrechner testen will. Im Gegensatz zu `skipModuleCompatibilityCheck` wird allerdings die Kompatibilitätsüberprüfung mit dem hier gesetzten Betriebssystem wie gewohnt durchgeführt. 
+
+#### -ignoreMissingPrivileges
+Mit diesem Parameter kann festgelegt werden, dass fehlende Privilegien ignoriert werden und das JBA alle Module soweit möglich ausführt. Siehe [Privilegien](#privilegien).
+
+#### -alwaysPrintProgress
+Gibt den Fortschritt des Auditoriums beim Ausführen der Audit-Schritte auf der Konsole unabhängig vom angegebenen Log-Level aus.
+
+#### -zip
+Wird dieser Parameter angegeben, dann wird vom Output-Ordner ein zip-Archiv erzeugt.
+
+#### -zipOnly
+Wird dieser Parameter angegeben, dann wird vom Output-Ordner ein zip-Archiv erzeugt. Der Output-Ordner wird daraufhin entfernt, sodass als Ergebnis nur die zip bleibt.
+
+### Parameter ohne Programmstart
+Folgende Parameter geben Informationen auf der Konsole aus, führen den Rest des Programms aber nicht vollständig aus. Es gilt zu beachten, dass die Ausgaben dieser Parameter sowohl auf die Konsole, als auch in den Log geschrieben werden, unabhängig von dem angegebenen Log-Level.
+
+#### -help
+Dieser Parameter zeigt die Hilfe-Seite an.
+
+#### -version
+Wird dieser Parameter angegeben, wird die interne Version und das Datum der letzten Änderung des Jungbusch-Auditoriums ausgegeben.
+
+#### -createDefault
+Mit diesem Parameter kann eine `config.ini`-Datei im Pfad der Executable erzeugt werden, welche die Default-Werte des Jungbusch-Auditoriums beinhaltet. Die Werte der Datei können nach Belieben angepasst werden und werden beim Starten der Software automatisch eingelesen.
+
+#### -showModules
+Dieser Parameter gibt eine Liste mit allen Modulen aus, die sich in der ausgeführten Executable befinden. Es gilt zu beachten, dass Module die ausschließlich mit beispielsweise Linux kompatibel sind sich aufgrund der Funktionsweise von GO nicht in der Executable von Windows befinden. Wird dieser Parameter an einer .exe angegeben, werden alle Module aufgeführt, die mit der Windows-Architektur kompatibel sind.
+
+#### -showModuleInfo
+Dieser Parameter gibt alle verfügbaren Informationen zu dem angegeben Modul-Name aus. Es gilt dieselbe Einschränkung wie bei `-showModules`. Beispiel: `-showModuleInfo=grep`
+
+#### -checkSyntax, -syntax
+Mit diesem Parameter kann der Syntax der Audit-Konfigurationsdatei überprüft werden, ohne dass die Audit-Schritte ausgeführt werden. Es wird allein der Syntax der Datei überprüft. Angegebene Werte oder Variablen werden nicht validiert. Das heißt, es wird beispielsweise nicht überprüft, ob die IDs der Audit-Schritte einzigartig ist. Es ist also möglich, dass der Syntax valide ist, die Audit-Konfigurationsdatei aber nicht. Es gilt zu beachten, dass die Programm-Konfiguration (.ini, Commandline-Parameter) ebenfalls überprüft werden und gültig sein müssen um bei der Überprüfung des Syntaxes der Audit-Konfiguration überhaupt anzukommen.
+
+#### -checkConfiguration
+Mit diesem Parameter können der Syntax und die Werte der Audit-Konfigurationsdatei überprüft werden, ohne dass die Audit-Schritte ausgeführt werden. Es gilt zu beachten, dass das Ausführen dieses Checks für eine Windows-Konfiguration auf einem Linuxbasierten System keinen Sinn ergibt, weil in der Konfiguration ggf. `"Windows-Only-Module"` verwendet werden, die sich nicht in der Linux-Executable befinden und die Konfiguration damit möglicherweise nicht erfolgreich validiert werden kann. Es kann also sein, dass eine gültige Linux-Konfiguration auf einem Windows-System als nicht valide markiert wird. Es gilt zu beachten, dass die Programm-Konfiguration (.ini, Commandline-Parameter) ebenfalls überprüft werden und gültig sein müssen um bei der Überprüfung der Audit-Konfiguration überhaupt anzukommen.
+
+#### -saveConfiguration, -s
+Mit diesem Befehl wird die `config.ini` dauerhaft mit den zum aktuellen Start angegebenen Commandline-Parametern überschrieben.
+
+Beispiel: `-outputPath /var/jba/ -save`
+
+Das Programm startet, die `config.ini` wird eingelesen, der OutputPath wird auf `/var/jba/` gesetzt und die Änderung wird in die `config.ini` Datei geschrieben. Anschließend beginnt der Audit Prozess.
+
+## Konfiguration per Konfigurations-Datei
+
+Wenn man die Konfiguration des Programms festhalten will, sodass nicht bei jedem Programmstart Commandline-Parameter angegeben werden müssen, bietet es sich an, eine `config.ini` Datei zu erstellen. 
+
+Die Konfigurationsdatei verwendet dieselbe Liste an Parametern wie die Commandline. Allerdings gibt es einige kleine Unterschiede im Syntax:
+
+- In der Konfigurationsdatei sind Parameter ohne `-` oder `--` anzugeben
+- Alle Parameter müssen im Format `name=wert` angegeben werden, auch Booleans
+- In der Konfigurationsdatei können keine Aliase (Kurzversionen) der Parameter angegeben werden
+- Bei Parameternamen wird die Groß- und Kleinschreibung nicht berücksichtigt
+
+Davon abgesehen können alle Parameter der Commandline in der Konfigurations-Datei angegeben werden.
+
+Mit dem Commandline-Flag `-createDefault` kann eine Beispiel-Konfigurationsdatei generiert werden, die daraufhin einfach editiert werden kann.
+
+### Auswahl der Konfigurations-Datei (config.ini)
+
+Theoretisch können auch mehrere Konfigurations-Dateien mit unterschiedlichen Werten angelegt werden. Welche Datei verwendet werden soll, muss dann allerdings über den Commandline-Parameter `-configPath` definiert werden.
+
+Wird kein Parameter angegeben, dann wird im Pfad der Executable nach einer Datei mit dem Namen `config.ini` gesucht (Name der Datei in diesem Fall nicht Case-Sensitive). 
+
+![config.ini-Auswahl](./img/config.ini.png)
+
+### config.ini Beispiel
+
+```ini
+[ENVIRONMENT]
+AuditConfig=./audit.jba
+OutputPath=.
+VerbosityLog=3
+VerbosityConsole=4
+SkipModuleCompatibilityCheck=false
+KeepConsoleOpen=false
+IgnoreMissingPrivileges=false
+AlwaysPrintProgress=false
+Zip=false
+ZipOnly=false
+Version=false
+CheckConfiguration=false
+CheckSyntax=false
+```
+
+## Auswahl der Audit-Konfigurations-Datei (.jba)
+
+Der Pfad zu einer Audit-Konfigurationsdatei kann sowohl über einen Commandline- als auch per Configparameter angegeben werden. Wird keine Datei explizit angegeben, überprüft das Jungbusch-Auditorium, welche JBA-Dateien im Pfad der Executable liegen. Liegt dort nur eine einzelne Datei, wird diese verwendet. Liegen dort mehrere Dateien, wird die Datei verwendet, welche den Default-Namen hat (`audit.jba`). Existiert diese nicht, wird das Jungbusch-Auditorium beendet.
+
+![Audit-Datei-Auswahl](./img/audit.jba.png)
+

03-betriebssysteme.md

@@ -0,0 +1,49 @@
+# Betriebssysteme
+
+## Der OS-Detector
+
+Das Jungbusch-Auditorium erkennt das Betriebssystem des auszuführenden Systems automatisch. Das Ergebnis des Detectors kann mit einem Parameter überschrieben werden.
+
+## OS-Kompatibilität in Modulen
+
+Die einzelnen Module geben in ihrer `Initialize`-Methode eine Liste an kompatiblen Betriebssystemen an. Ein Modul ist zum Aufruf aus der Audit-Konfiguration nur verfügbar, wenn sich das aktuelle Betriebssystem in der Liste der Betriebssysteme des Moduls befindet. 
+
+Module können folgende Betriebssysteme angeben:
+```
+ubuntu
+debian
+centos
+rhel               // RedHat
+sles               // Suse
+sles_sap           // Suse SAP
+
+windows10          // beinhaltet alle Versionen von Windows10
+windowsserver2012
+windowsserver2016
+windowsserver2020
+windows8
+windows7
+windowsxp
+
+macos11.0
+macos10.15
+macos10.14
+```
+
+### Wildcards
+
+Des Weiteren können folgende Wildcards angegeben werden:
+```
+all
+windows
+linux
+darwin
+```
+Damit kann ein Modul als kompatibel mit allen Systemen einer Gruppe markiert werden.
+
+## Beeinflussen der Kompatibilitäts-Überprüfung 
+
+Mit dem Flag `skipModuleCompatibilityCheck` kann der gesamte Modul-Kompatibilitätscheck übersprungen werden. Somit werden alle Module geladen, die mit der Architektur des Systems kompatibel sind. 
+
+Mit dem Flag `forceOS` kann das Ergebnis des OS-Detectors überschrieben werden. 
+