15 Das Greenbone Management Protocol nutzen¶
Die Schwachstellenverwaltung der Greenbone Enterprise Appliance ist auch über das Greenbone Management Protocol (GMP) verfügbar. GMP ist ein XML-basiertes, menschenlesbares, zustandsloses Anfrage-Antwort-Protokoll.
Greenbone stellt Greenbone Vulnerability Management Tools (gvm-tools) bereit, um diese Funktion mit GMP verfügbar zu machen (siehe Kapitel 15.3). Dieses Anwenderhandbuch deckt gvm-tools bis zu Version 2.0.0 beta ab.
Die neueste GMP-Version ist unter https://docs.greenbone.net/API/GMP/gmp-22.5.html dokumentiert.
15.1 Änderungen am GMP¶
GMP wird regelmäßig aktualisiert, um Änderungen in der Funktionalität, die durch den zugrunde liegenden Dienst bereitgestellt werden, anzuwenden und eine einheitliche und umfassende Oberfläche zur Verfügung zu stellen.
Updates führen zu einer neuen Version von GMP. Jede neue Version enthält eine Liste hinzugefügter, veränderter oder entfernter Protokollelementen (Befehle oder Attribute). Die neueste Version der Liste ist unter https://docs.greenbone.net/API/GMP/gmp-22.4.html#changes verfügbar.
Abhängig von den Änderungen ist die veraltete Version noch für einige Zeit verfügbar. Während dieser Übergangsphase sind sowohl die veraltete als auch die neue Version erhältlich.
Die Liste kann bei der frühstmöglichen Vorbereitung auf kommende Veränderungen helfen. Sie stellt nicht die komplette Liste an bevorstehenden Veränderungen dar.
15.2 GMP aktivieren¶
Bevor GMP genutzt werden kann, muss es auf der Appliance aktiviert werden.
Während die Web-Oberfläche GMP lokal auf der Appliance nutzt, kann standardmäßig nicht remote über das Netzwerk auf GMP zugegriffen werden.
Der Remote-GMP-Dienst kann mithilfe des GOS-Administrationsmenüs aktiviert werden (siehe Kapitel 7.2.4.2).
Allgemein wird der Zugriff auf GMP mit SSL/TLS authentifiziert und verschlüsselt. Dieselben Benutzer wie für die Web-Oberfläche werden genutzt. Die Benutzer unterliegen denselben Beschränkungen und haben dieselben Berechtigungen.
15.3 Die gvm-tools nutzen¶
Die Greenbone Vulnerability Management Tools (gvm-tools) sind eine Sammlung von Werkzeugen, die Zugang zu den Funktionen des Greenbone Management Protocols (GMP) bereitstellen. GMP-Skripte, die mit gvm-script ausgeführt werden, benutzen die API, die von der Bibliothek python-gvm zur Verfügung gestellt wird.
Bemerkung
python-gvm wird bei der Installation von gvm-tools automatisch installiert.
Die gvm-tools sind als Befehlszeilenschnittstelle (CLI) und als Python-Shell für Microsoft Windows und jedes andere Betriebssystem, das Python unterstützt (einschließlich Linux), verfügbar.
Bemerkung
Sowohl gvm-tools als auch python-gvm verwenden ein anderes Versionsschema als GOS, sodass die Versionen von gvm-tools, python-gvm und GOS nicht unbedingt identisch sind.
Es wird empfohlen, die neuesten Versionen von gvm-tools und python-gvm zu verwenden.
Die gvm-tools können vom offiziellen GitHub-Repository des Projekts heruntergeladen werden. Python 3.9 oder höher wird benötigt. Um gvm-tools zu installieren, müssen die Anweisungen unter https://greenbone.github.io/gvm-tools/ befolgt werden.
Zusätzlich sind die gvm-tools als statisch verknüpfte EXE-Dateien für alle unterstützten Versionen von Microsoft Windows verfügbar.
Die EXE-Versionen der gvm-tools benötigen Python nicht und können direkt von Greenbone heruntergeladen werden:
CLI: gvm-cli.exe
Python-Shell: gvm-pyshell.exe
Wichtig
Externe Links zur Greenbone-Downloadseite unterscheiden Groß- und Kleinbuchstaben.
Großbuchstaben, Kleinbuchstaben und Sonderzeichen müssen exakt so, wie sie in den Fußnoten stehen, eingegeben werden.
Bemerkung
Die gvm-tools sind unter der GNU General Public License v3.0 lizensiert und können möglicherweise für andere Anwendungsfälle, basierend auf dem Quellcode, angepasst und gebaut werden.
15.3.1 Mit gvm-cli.exe zugreifen¶
GMP ist XML-basiert. Jeder Befehl und jede Antwort ist ein GMP-Objekt.
Das Kommandozeilenprogramm gvm-cli.exe, das von Greenbone angeboten wird, bietet direktes Senden und Empfangen von XML-Befehlen und -Antworten.
gvm-cli.exe unterstützt die folgenden Verbindungen:
SSH
TLS
Unix Domain Socket
gvm-cli.exe unterstützt zahlreiche Befehlszeilenoptionen, die wie folgt angezeigt werden können:
$ gvm-cli -h
usage: gvm-cli [-h] [-c [CONFIG]]
[--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]]
[--timeout TIMEOUT] [--gmp-username GMP_USERNAME]
[--gmp-password GMP_PASSWORD] [-V] [--protocol {GMP,OSP}]
CONNECTION_TYPE ...
optional arguments:
-h, --help show this help message and exit
-c [CONFIG], --config [CONFIG]
Configuration file path (default: ~/.config/gvm-
tools.conf)
--log [{DEBUG,INFO,WARNING,ERROR,CRITICAL}]
Activate logging (default level: None)
--timeout TIMEOUT Response timeout in seconds, or -1 to wait
indefinitely (default: 60)
--gmp-username GMP_USERNAME
Username for GMP service (default: '')
--gmp-password GMP_PASSWORD
Password for GMP service (default: '')
-V, --version Show version information and exit
--protocol {GMP,OSP} Service protocol to use (default: GMP)
connections:
valid connection types
CONNECTION_TYPE Connection type to use
ssh Use SSH to connect to service
tls Use TLS secured connection to connect to service
socket Use UNIX Domain socket to connect to service
Obwohl gvm-cli.exe noch mehr Befehlszeilenoptionen unterstützt, werden die zusätzlichen Optionen nur angezeigt, wenn der Verbindungstyp angegeben wird:
$ gvm-cli ssh -h
usage: gvm-cli ssh [-h] --hostname HOSTNAME [--port PORT]
[--ssh-username SSH_USERNAME]
[--ssh-password SSH_PASSWORD] [-X XML] [-r] [--pretty]
[--duration]
[infile]
positional arguments:
infile File to read XML commands from.
optional arguments:
-h, --help show this help message and exit
--hostname HOSTNAME Hostname or IP address
--port PORT SSH port (default: 22)
--ssh-username SSH_USERNAME
SSH username (default: 'gmp')
--ssh-password SSH_PASSWORD
SSH password (default: 'gmp')
-X XML, --xml XML XML request to send
-r, --raw Return raw XML
--pretty Pretty format the returned xml
--duration Measure command execution time
Alle aktuellen Appliances nutzen SSH zum Verschlüsseln von GMP. Die Nutzung von TLS ist veraltet, wird nicht offiziell unterstützt und könnte in zukünftigen Versionen entfernt werden.
Die gvm-tools sind hauptsächlich für den Batch-Modus (batch processing, scripting) hilfreich.
Mit gvm-cli.exe kann GMP einfach genutzt werden:
gvm-cli --xml "<get_version/>"
gvm-cli --xml "<get_tasks/>"
gvm-cli < file
15.3.1.1 Den Client konfigurieren¶
Für die Nutzung des Befehls gvm-cli ist das Einloggen in die Appliance nötig.
Die benötigten Informationen werden entweder mithilfe von Befehlszeilenoptionen oder einer Konfigurationsdatei (~/.config/gvm-tools.conf) geliefert.
Um dem GMP-Benutzer Befehlszeilenoptionen zur Verfügung zu stellen, können die folgenden Befehle genutzt werden:
--gmp-username--gmp-password
Alternativ kann eine Konfigurationsdatei ~/.config/gvm-tools.conf, die die Informationen enthält, erstellt werden:
[Auth]
gmp_username=webadmin
gmp_password=kennwort
Diese Konfigurationsdatei wird nicht standardmäßig gelesen. Die Befehlszeilenoption --config oder -c muss hinzugefügt werden, um die Konfigurationsdatei zu lesen.
15.3.1.2 Einen Scan mithilfe des Befehls gvm-cli starten¶
Ein typisches Beispiel für die Nutzung von GMP ist der automatische Scan eines neuen Systems.
In diesem Beispiel wird angenommen, dass ein Intrusion Detection System (IDS) genutzt wird, das die Systeme in der Demilitarisierten Zone (DMZ) überwacht und unmittelbar neue Systeme und unübliche TCP-Ports, die noch nicht genutzt wurden, entdeckt. Falls solch ein Fall beobachtet wird, sollte das IDS mithilfe eines Skripts automatisch einen Scan des neuen Systems einleiten.
Dafür kann der Befehl gvm-cli genutzt werden, obwohl der Befehl gvm-pyshell oder die Nutzung selbst geschriebener Python-Skripte geeigneter sein könnte (siehe Kapitel 15.3.2.1). Die Verarbeitung der XML-Ausgabe wird durch Python besser unterstützt, als durch die Nutzung der Shell.
Startpunkt ist die IP-Adresse des neuen, verdächtigen Systems. Auf der Appliance muss ein Ziel für diese IP-Adresse erstellt werden.
Der Befehl create_target ist hier beschrieben:
https://docs.greenbone.net/API/GMP/gmp-22.5.html#command_create_target.
Falls die IP-Adresse in der Variable
IPADDRESSgespeichert ist, entsprechendes Ziel wie folgt erstellen:
$ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 \
--xml "<create_target><name>Suspect Host</name>\
<hosts>$IPADDRESS</hosts></create_target>"
<create_target_response status="201" status_text="OK, resource
created" id="4574473f-a5d0-494c-be6f-3205be487793"/>
Aufgabe wie folgt erstellen:
$ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 \
--xml "<create_task><name>Scan Suspect Host</name> \
<target id=\"4574473f-a5d0-494c-be6f-3205be487793\"></target> \
<config id=\"daba56c8-73ec-11df-a475-002264764cea\"></config></create_task>"
<create_task_response status="201" status_text="OK, resource
created" id="ce225181-c836-4ec1-b83f-a6fcba70e17d"/>
→ Die Ausgabe ist die ID der Aufgabe. Diese wird für das Starten und Überwachen der Aufgabe benötigt.
Die anderen vom Befehl genutzten IDs können durch Nutzung der folgenden Befehle, die die verfügbaren Ziele und Scan-Konfigurationen anzeigen, erhalten werden:
$ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 --xml "<get_targets/>"
$ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 --xml "<get_configs/>"
Bemerkung
Die Ausgabe der Befehle ist XML.
Aufgabe wie folgt starten:
$ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 \
--xml '<start_task task_id="ce225181-c836-4ec1-b83f-a6fcba70e17d"/>'
→ Die Verbindung wird von der Appliance getrennt. Die Aufgabe läuft.
Status der Aufgabe wie folgt anzeigen:
$ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 \
--xml '<get_tasks task_id="ce225181-c836-4ec1-b83f-a6fcba70e17d"/>'
<get_tasks_response status="200" status_text="OK"><apply_overrides>
...<status>Running</status><progress>98<host_progress>
<host>192.168.255.254</host>98</host_progress></progress>.../>
→ Sobald der Scan abgeschlossen ist, kann der Bericht heruntergeladen werden.
Dafür wird die ID benötigt, die beim Erstellen der Aufgabe ausgegeben wurde. Außerdem muss ein sinnvolles Berichtformat eingegeben werden.
IDs für die Berichtformate wie folgt anzeigen:
$ $ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 --xml '<get_report_formats/>'
Bericht wie folgt laden:
$ gvm-cli --gmp-username webadmin --gmp-password kennwort ssh \
--hostname 192.168.222.115 \
--xml '<get_reports report_id="23a335d6-65bd-4be2-a83e-be330289eef7" \
format_id="35ba7077-dc85-42ef-87c9-b0eda7e903b6"/>'
Tipp
Um die Daten vollständig und automatisch zu verarbeiten, kann die Aufgabe mit einer Benachrichtigung kombiniert werden, die den Bericht, basierend auf den gegebenen Bedingungen, weiterleitet.
15.3.2 Mit gvm-pyshell.exe zugreifen¶
Das Kommandozeilenprogramm gvm-pyshell.exe, das von Greenbone angeboten wird, bietet direktes Senden und Empfangen von XML-Befehlen und -Antworten mithilfe von Python-Befehlen. Die Befehle sorgen für das Erzeugen und Parsen der XML-Daten.
Das Werkzeug unterstützt die folgenden Transportkanäle:
TLS
SSH
Socket
Während die aktuellen Appliances SSH nutzen, um GMP zu schützen, haben ältere Appliances TLS und Port 9390 für den Transport von GMP genutzt. Die gvm-tools können sowohl mit dem älteren als auch mit dem aktuellen GOS genutzt werden.
Die gvm-tools sind hauptsächlich für den Batch-Modus (batch processing, scripting) hilfreich.
Die Konfiguration der Authentifizierung des Befehls gvm-pyshell kann in einer Datei im Home-Verzeichnis des Benutzers gespeichert werden. Die Syntax ist in Kapitel 15.3.1.1 erklärt.
Die Python-Implementierung folgt der GMP-API (https://docs.greenbone.net/API/GMP/gmp-22.5.html). Optionale Argumente in der API sind durch ein ? gekennzeichnet. Das folgende Beispiel erklärt die Nutzung der Python-Funktion:
gmp.create_task("Name","Config","Scanner","Target",comment="comment")
Tipp
Während zwingend notwendige Parameter in der korrekten Reihenfolge eingegeben werden können und automatisch identifiziert werden, können sie auch mithilfe ihres Bezeichners angegeben werden:
gmp.create_task(name="Name",config_id="Config",scanner_id="Scanner",
target_id="Target",comment="comment")
15.3.2.1 Einen Scan mithilfe des Befehls gvm-pyshell starten¶
Ein typisches Beispiel für die Nutzung von GMP ist der automatische Scan eines neuen Systems.
In diesem Beispiel wird angenommen, dass ein Intrusion Detection System (IDS) genutzt wird, das die Systeme in der Demilitarisierten Zone (DMZ) überwacht und unmittelbar neue Systeme und unübliche TCP-Ports, die noch nicht genutzt wurden, entdeckt. Falls solch ein Fall beobachtet wird, sollte das IDS mithilfe eines Skripts automatisch einen Scan des neuen Systems einleiten.
Der Befehl gvm-pyshell ist dafür sehr geeignet. Die Verarbeitung der XML-Ausgabe wird durch Python besser unterstützt als durch Nutzung der Shell.
Startpunkt ist die IP-Adresse des neuen, verdächtigen Systems. Auf der Appliance muss ein Ziel für diese IP-Adresse erstellt werden.
Der Befehl create_target ist hier beschrieben:
https://docs.greenbone.net/API/GMP/gmp-22.5.html#command_create_target.
Die folgenden Zeilen zeigen die Befehle, die benötigt werden, wenn
gvm-pyshellgenutzt wird:
$ gvm-pyshell \
--gmp-username webadmin --gmp-password kennwort \
ssh --hostname 192.168.222.115
GVM Interactive Console 2.0.0 API 1.1.0. Type "help" to get information about
functionality.
>>> res=gmp.create_target("Suspect Host", make_unique=True, \
hosts=['192.168.255.254'])
>>> target_id = res.xpath('@id')[0]
Die Variable target_id enthält die ID des erstellten Ziels. Diese ID kann genutzt werden, um die zugehörige Aufgabe zu erstellen.
Bemerkung
Die Erzeugung der Aufgabe erfordert den folgenden Angaben:
target_id
config_id
scanner_id
task_name
task_comment
Alle verfügbaren Scan-Konfigurationen können wie folgt angezeigt werden:
>>> res = gmp.get_configs()
>>> for i, conf in enumerate(res.xpath('config')):
... id = conf.xpath('@id')[0]
... name = conf.xpath('name/text()')[0]
... print('\n({0}) {1}: ({2})'.format(i, name, id))
Alle verfügbaren Scanner können mithilfe der gleichen Methode angezeigt werden. Falls nur die integrierten Scanner genutzt werden, sind die folgenden IDs fest codiert:
OpenVAS-Scanner: 08b69003-5fc2-4037-a479-93b440211c73
CVE-Scanner: 6acd0832-df90-11e4-b9d5-28d24461215b
Aufgabe wie folgt erstellen:
>>> res=gmp.create_task(name="Scan Suspect Host",
... config_id="daba56c8-73ec-11df-a475-002264764cea",
... scanner_id="08b69003-5fc2-4037-a479-93b440211c73",
... target_id=target_id)
>>> task_id = res.xpath('@id')[0]
Aufgabe wie folgt starten:
>>> gmp.start_task(task_id)
→ Die aktuelle Verbindung wird unmittelbar geschlossen. Zusätzliche Befehle sind nicht erforderlich.
Alle Befehle können in ein Python-Skript eingefügt werden, das von der Python-Shell aufgerufen werden kann:
len_args = len(args.script) - 1
if len_args is not 2:
message = """
This script creates a new task with specific host and vt!
It needs two parameters after the script name.
First one is name of the target and the second one is the
chosen host. The task is called target-task
Example:
$ gvm-pyshell ssh newtask target host
"""
print(message)
quit()
target = args.script[1]
host = args.script[2]
task = target + " Task"
# Full and Fast
myconfig_id = "daba56c8-73ec-11df-a475-002264764cea"
# OpenVAS Scanner
myscanner_id = "08b69003-5fc2-4037-a479-93b440211c73"
res=gmp.create_target(target, True, hosts=host)
mytarget_id = res.xpath('@id')[0]
res=gmp.create_task(name=task,
config_id=myconfig_id,
scanner_id=myscanner_id,
target_id=mytarget_id)
mytask_id = res.xpath('@id')[0]
gmp.start_task(mytask_id)
15.3.3 Beispielskripte¶
Die gvm-tools bringen eine Sammlung von Beispielskripten mit sich, welche vom Befehl gvm-script genutzt werden können.
Aktuell sind die folgenden Skripte für die gvm-tools Version 2.0.0 verfügbar (https://github.com/greenbone/gvm-tools/tree/main/scripts):
application-detection.gmp.py: Dieses Skript zeigt alle Hosts mit der gesuchten Anwendung.
cfg-gen-for-certs.gmp.py: Dieses Skript erstellt eine neue Scan-Konfiguration mit VTs basierend auf einem gegebenen CERT-Bund-Advisory.
clean-sensor.gmp.py: Dieses Skript entfernt alle Ressourcen, abgesehen von aktiven Aufgaben, von einem Sensor.
create-dummy-data.gmp.py: Dieses Skript erstellt Dummy-Daten.
DeleteOverridesByFilter.gmp.py: Dieses Skript entfernt Übersteuerungen von einem Filter.
monthly-report2.gmp.py: Dieses Skript zeigt alle Schwachstellen, die auf dem Bericht eines vorgegebenen Monats basieren. Geeignet für GOS 4.x.
monthly-report.gmp.py: Dieses Skript zeigt alle Schwachstellen, die auf dem Bericht eines vorgegebenen Monats basieren. Geeignet für GOS 3.1.
nvt-scan.gmp.py: Dieses Skript erstellt eine neue Aufgabe mit einem bestimmten Host und einem bestimmten VT, die eine fest codierte Basis-Konfiguration nutzt.
startNVTScan.gmp.py: Dieses Skript erstellt interaktiv eine neue Aufgabe mit einem bestimmten Host und einem bestimmten VT.
SyncAssets.gmp.py: Dieses Skript lädt Assets in die Asset-Datenbank hoch.
SyncReports.gmp.py: Dieses Skript lädt Berichte von einer Appliance herunter und lädt sie mithilfe von Container-Aufgaben in eine zweite Appliance hoch.
Tipp
Diese Skripte können als Startpunkt für die Entwicklung benutzerdefinierter Skripte dienen.
15.4 Statuscodes¶
GMP nutzt Statuscodes, die HTTP-Statuscodes ähnlich sind. Die folgenden Codes werden genutzt:
- 2xx:
Das Kommando wurde erfolgreich übertragen, verstanden und akzeptiert.
- 200: OK
- 201: Resource created
- 202: Request submitted
- 4xx:
Es liegt ein Benutzerfehler vor.
- 400: Syntax-Fehler
Dies beinhaltet verschiedene Syntaxfehler. Oft fehlen Elemente oder Attribute im GMP-Befehl. Der Statustext zeigt zusätzliche Informationen.
Aktuell wird dieser Statuscode auch für fehlende oder falsche Authentifizierungen genutzt.
- 401: Authenticate First
Dieser Fehlercode wird für eine fehlende oder falsche Authentifizierung genutzt. Aktuell wird noch der Wert 400 genutzt.
- 403: Access to resource forbidden
Dieser Fehlercode wird genutzt, wenn nicht genug Berechtigungen vorhanden sind. Oft wird stattdessen 400: Permission denied angezeigt.
- 404: Resource missing
Die Ressource konnte nicht gefunden werden. Die Ressourcen-ID ist leer oder falsch.
- 409: Resource busy
Dieser Fehlercode tritt beispielsweise dann auf, wenn die Synchronisierung des Feeds gestartet wird, während sie bereits läuft.
- 5xx:
Es liegt ein Serverfehler vor.
- 500: Internal Error
Dies kann durch Einträge, die die interne Puffergröße übersteigen, ausgelöst werden.
- 503: Scanner loading NVTs
Der Scanner lädt gerade VTs aus seinem Speicher. Die Anfrage sollte zu einem späteren Zeitpunkt noch einmal gestellt werden.
- 503: Service temporarily down
Möglicherweise läuft der Scanner-Daemon nicht. Oft wird dieses Problem durch abgelaufene Zertifikate hervorgerufen.
- 503: Service unavailable
Der GMP-Befehl ist auf der Appliance gesperrt.