# 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: <mark style="color:$danger;">`<Laufzeitumgebung>`</mark>`_`<mark style="color:blue;">`<Schweregrad>`</mark>`_`<mark style="color:green;">`<Skriptname>`</mark>`.`<mark style="color:orange;">`<Dateiendung>`</mark>

Ersetze die Werte in `<>` wie folgt:

<table><thead><tr><th width="191.03125">Parameter</th><th>Beschreibung</th></tr></thead><tbody><tr><td><mark style="color:red;">&#x3C;Laufzeitumgebung></mark></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><mark style="color:blue;">&#x3C;Schweregrad></mark></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><mark style="color:green;">&#x3C;Skriptname></mark></td><td>Lege einen benutzerdefinierten Skriptnamen für dein Skript fest.</td></tr><tr><td><mark style="color:orange;">&#x3C;Dateiendung></mark></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: <mark style="color:red;">`python2`</mark>`_`<mark style="color:blue;">`critical`</mark>`_`<mark style="color:green;">`meineigenesskript`</mark>`.`<mark style="color:orange;">`py`</mark>
{% endstep %}

{% step %}

### Skript einfügen und speichern

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.

Speichere und schließe die Datei.
{% 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

Logge dich auf dem Linux-Server ein, auf dem du das oder die benutzerdefinierten Skripte hinterlegt hast.

Öffne mit folgendem Befehl die Datei **description.json**:

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

{% endstep %}

{% step %}

### Titel und Empfehlung hinzufügen

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

```
{
    <DateinameA>":{
        "title":"<Eigener Titel des Checks>",
        "recommendation":"<Empfehlung zur Behebung>"
    },
    "<DateinameB>":{
        "title":"<Eigener Titel des Checks>",
        "recommendation":"<Empfehlung zur Behebung>"
    }
```

Ersetze die Parameter in Klammern <> wie folgt:

<table><thead><tr><th width="250.22265625">Parameter</th><th>Beschreibung</th></tr></thead><tbody><tr><td>&#x3C;DateinameA></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>&#x3C;Eigener Titel des Checks></td><td>Lege einen benutzerdefinierten Titel für den Check fest, der in der Plattform angezeigt werden soll.</td></tr><tr><td>&#x3C;Empfehlung zur Behebung></td><td>Gib eine Empfehlung an, wie die durch den Check überprüfte Schwachstelle behoben werden kann.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Den Hacktor neu starten

Speichere und schließe die Datei.

Starte dann mit folgendem Befehl den Hacktor neu:

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

{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enginsight.com/docs/knowledge-base/penetrationstests/wie-kann-ich-bei-penetrationstests-mit-enginsight-benutzerdefinierte-skripte-einsetzen.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.