> For the complete documentation index, see [llms.txt](https://docs.enginsight.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enginsight.com/docs/knowledge-base/penetrationstests/wie-kann-ich-bei-penetrationstests-mit-enginsight-benutzerdefinierte-skripte-einsetzen.md).

# Wie kann ich bei Penetrationstests mit Enginsight benutzerdefinierte Skripte einsetzen?

Ein Penetrationstest ist ein geplanter und kontrolliert durchgeführter automatisierter Angriff auf die eigenen Systeme, um Schwachstellen gezielt aufzudecken. Penetrationstests werden mit der Enginsight Komponente Hacktor durchgeführt. 

Enginsight stellt dafür eine umfangreiche Bibliothek an Checks zur Verfügung, die du zusätzlich durch benutzerdefinierte Skripte erweitern kannst. Diese Skripte werden direkt auf dem Linux-Server hinterlegt, auf dem der Hacktor installiert ist. 

Im Folgenden zeigen wir dir, wie du benutzerdefinierte Skripte für Penetrationstests erstellst und für die Enginsight Plattform verfügbar machst.

***

## Custom Script hinzufügen

{% hint style="warning" %}
**Bitte beachte**: Um benutzerdefinierte Skripte zu erstellen und auf der Enginsight Plattform nutzen zu können, benötigst du Administrator-Rechte für den Server, auf dem der Hacktor installiert ist.
{% endhint %}

Gehe folgendermaßen vor, um ein eigenes Skript für Penetrationstests hinzuzufügen:

{% stepper %}
{% step %}

### Zum Skript-Ordner navigieren

Logge dich auf dem Linux-Server ein, auf dem der Hacktor, der das benutzerdefinierte Skript ausführen soll, installiert ist.

Navigiere mit folgendem Befehl in den Ordner **scripts**:

```
cd /opt/enginsight/hacktor/scripts
```

{% endstep %}

{% step %}

### Skript-Datei anlegen

Lege mit folgendem Befehl eine Datei für das benutzerdefinierte Skript an:

```
sudo nano <Laufzeitumgebung>_<Schweregrad>_<Skriptname>.<Dateiendung>
```

Der Dateiname muss dabei dem folgendem Schema entsprechen: `<Laufzeitumgebung>_<Schweregrad>_<Skriptname>.<Dateiendung>`

Ersetze die Platzhalter in `<>` wie folgt:

<table><thead><tr><th width="191.03125">Parameter</th><th>Beschreibung</th></tr></thead><tbody><tr><td><code>&#x3C;Laufzeitumgebung></code></td><td><p>Lege die Laufzeitumgebung (Runtime Environment) fest, die du für dein Skript verwenden möchtest.<br></p><p>Folgende Laufzeitumgebungen werden unterstützt:</p><ul><li>bash</li><li>python2</li><li>python3</li><li>ruby</li></ul></td></tr><tr><td><code>&#x3C;Schweregrad></code></td><td><p>Lege den Schweregrad bzw. die Kritikalität fest, die angezeigt wird, wenn der im Skript definierte Check nicht bestanden wird.</p><p><br>Folgende Schweregrade werden unterstützt:</p><ul><li>ok</li><li>low</li><li>medium</li><li>high</li><li>critical</li></ul></td></tr><tr><td><code>&#x3C;Skriptname></code></td><td>Lege einen benutzerdefinierten Skriptnamen für dein Skript fest.</td></tr><tr><td><code>&#x3C;Dateiendung></code></td><td>Gib die Dateiendung an, die der festgelegten Laufzeitumgebung entspricht, also <strong>.sh</strong> für Bash-Skripte, <strong>.py</strong> für Python-Skripte und <strong>.rb</strong> für Ruby-Skripte.</td></tr></tbody></table>

Beispiel: `python2_critical_meineigenesskript.py`
{% endstep %}

{% step %}

### Skript einfügen und speichern

1. Füge nun dein eigenes Skript ein. Dies muss den [Richtlinien für Custom Scripts](#richtlinien-fur-custom-scripts) gemäß erstellt sein. [Skript-Muster](#muster) für die verschiedenen Laufzeitumgebungen findest du weiter unten.
2. Speichere die Datei (**Strg** + **o**) und bestätige den Speicherprozess. Schließe die Datei (**Strg** + **x**).
   {% endstep %}

{% step %}

### Skript-Datei für den Hacktor verfügbar machen

Sorge nun mit folgendem Befehl dafür, dass der Hacktor auf die neu angelegte Skript-Datei zugreifen und sie ausführen kann:

```
chmod 755 <Dateiname>
```

Der `<Dateiname>` entspricht dabei dem Namen, den du in [Schritt 2](#skript-datei-anlegen) erstellt hast.
{% endstep %}

{% step %}

### Den Hacktor neu starten

Starte den Hacktor mit folgendem Befehl neu, um die vorgenommenen Konfigurationen wirksam zu machen:

```
sudo systemctl restart ngs-hacktor
```

{% endstep %}

{% step %}

### Erweiterte Einstellungen prüfen

Logge dich auf der Enginsight Plattform ein und navigiere zu **Penetrationstests** → **Audit-Definition**.&#x20;

<i class="fa-computer-mouse">:computer-mouse:</i> Klicke auf <i class="fa-plus">:plus:</i> **Audit-Definition hinzufügen** in der rechten oberen Ecke der Audit-Übersicht, um eine [neue Audit-Definition zu erstellen](https://docs.enginsight.com/docs/manual/bedienung-der-plattform/penetrationstests/management/audit-definitionen/audit-definition-hinzufugen), oder bearbeite eine existierende Audit-Definition.

<i class="fa-computer-mouse">:computer-mouse:</i> Klicke auf **Erweiterte Einstellungen** und stelle sicher, dass die Checkbox <i class="fa-square-check">:square-check:</i> neben der Option **Custom Scripts ausführen** aktiviert ist.

<figure><img src="/files/YlZk2hzt0mECsrJOWnMM" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

***

## Richtlinien für Custom Scripts

Für die Erstellung benutzerdefinierter Skripte gelten unabhängig von der Skriptsprache folgende Richtlinien:

### Argumente

Argument 1 muss immer der **Hostname** sein. Die Argumente 2-n müssen die **offenen Ports** sein, die für das Ausführen des Skripts benötigt werden.

### Exit-Code

Damit der Hacktor das Ergebnis des Checks auslesen kann, der mithilfe des Skripts durchgeführt wird, musst du die folgenden Konventionen für den Exit-Status-Code einhalten:

<table><thead><tr><th width="164.13411458333331">Status</th><th width="128.51953125">Exit Code</th><th>Beschreibung</th></tr></thead><tbody><tr><td>Passed</td><td>0</td><td>Der Check wurde bestanden.</td></tr><tr><td>Error</td><td>1</td><td>Der Check hat nicht funktioniert.</td></tr><tr><td>Skipped</td><td>5</td><td>Der Check ist für das Zielsystem irrelevant.</td></tr><tr><td>Failed</td><td>9</td><td>Der Check wurde nicht bestanden. Das Zielsystem ist verwundbar.</td></tr></tbody></table>

{% hint style="info" %}
**Bitte beachte**: Jeder andere Exit-Code wird wie der Status **Error** behandelt.
{% endhint %}

Unabhängig vom Ergebnis des Checks werden die Standardausgabe `stdout` und die Fehlerausgabe `stderr` im Audit angezeigt. Ab 1024 Zeichen wird der Output abgeschnitten.

***

## Muster für verschiedene Skriptsprachen

### Python2 und Python3

```
import sys

print("Host:",sys.argv[1])
print("Ports:",sys.argv[2:])

print("Use 'sys.exit(1)' with error codes (1=error, 5=skipped, 9=failed) to determine check status")

sys.exit(9)
```

#### Beispiel-Python-Skript für einen benutzerdefinierten Check&#x20;

```
import socket
import sys

# This is an example script
# It checks if a host uses an OpenSSH implementation

host = sys.argv[1]
ports = sys.argv[2:]

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

if '22' in ports:

    addr = (host, 22)

    try:
        sock.connect(addr)
    except:
       print >>sys.stderr, 'failed to connect'
       sys.exit(1) # check has 'error' status

    try:
        message = 'SSH-2.0-Hacktor'
        sock.sendall(message)
   
        data = sock.recv(256)
        print >>sys.stdout, "Banner: %s" % data

        if 'OpenSSH' in data:
            print >>sys.stdout, "Host uses OpenSSH implementation"
            sock.close()
            sys.exit(0)

        else:
            print >>sys.stdout, "Host does not use OpenSSH implementation."
            sock.close()
            sys.exit(9) # check is 'failed'

    finally:
        sock.close()

else:
    print >>sys.stdout, 'host %s does not use port 22' % host
    sys.exit(5) # check is 'skipped'
```

### Ruby

```
puts "Host: "+ARGV[0]
puts "Ports: "+ARGV.inspect[0..-1]

puts "Use 'exit(1)' with error codes (1=error, 5=skipped, 9=failed) to determine check status"
```

### Bash

```
#!/bin/bash

echo "Host: $1"

shift # remove the first argument
echo "Shift. Then Ports:" "$@"

exit 5 # Use 'exit 1' with error codes (1=error, 5=skipped, 9=failed) to determine check status
```

***

## Optional: Eigener Titel und Empfehlungstext für den Check

Optional kannst du für den Check, den du über das benutzerdefinierte Skript definiert hast, einen eigenen Titel hinterlegen. Dieser ersetzt im Audit den Titel, den du weiter oben in [Schritt 2](#skript-datei-anlegen) im Dateinamen hinterlegt hast. Zudem kannst du eine Empfehlung hinterlegen, wie mit einer erkannten Schwachstelle umzugehen ist.

Gehe dazu folgendermaßen vor:

{% stepper %}
{% step %}

### Die Description-Datei öffnen

1. Logge dich auf dem Linux-Server ein, auf dem du das oder die benutzerdefinierten Skripte hinterlegt hast.
2. Öffne mit folgendem Befehl die Datei **description.json**:

```
sudo nano /opt/enginsight/hacktor/scripts/descriptions.json
```

{% endstep %}

{% step %}

### Titel und Empfehlung hinzufügen

1. Füge nun Titel und Empfehlung nach folgendem Schema ein:

```
{
    <DateinameA>":{
        "title":"<EigenerTitelCheck>",
        "recommendation":"<EmpfehlungBehebung>"
    },
    "<DateinameB>":{
        "title":"<EigenerTitelCheck>",
        "recommendation":"<EmpfehlungBehebung>"
    }
```

Ersetze die Platzhalter in `<>` wie folgt:

<table><thead><tr><th width="250.22265625">Parameter</th><th>Beschreibung</th></tr></thead><tbody><tr><td><code>&#x3C;DateinameA></code></td><td>Gib den Dateinamen an, den du weiter oben in <a href="#skript-datei-anlegen">Schritt 2</a> definiert hast.</td></tr><tr><td><code>&#x3C;EigenerTitelCheck></code></td><td>Lege einen benutzerdefinierten Titel für den Check fest, der in der Plattform angezeigt werden soll.</td></tr><tr><td><code>&#x3C;EmpfehlungBehebung></code></td><td>Gib eine Empfehlung an, wie die durch den Check überprüfte Schwachstelle behoben werden kann.</td></tr></tbody></table>

2. Speichere die Datei (**Strg** + **o**) und bestätige den Speicherprozess. Schließe die Datei (**Strg** + **x**).
   {% endstep %}

{% step %}

### Hacktor neu starten

Starte mit folgendem Befehl den Hacktor neu, um die Änderungen zu übernehmen:

```
sudo systemctl restart ngs-hacktor
```

{% endstep %}
{% endstepper %}

***