h3-cli

Für den Zugriff auf die H3-API ist ein API-Schlüssel erforderlich. Sie können einen im Portal unter dem Menü Benutzer -> Kontoeinstellungen erstellen.

Beim Erstellen eines API-Schlüssels müssen Sie ihm eine Rolle zuweisen, die seine Berechtigungen steuert. Die verfügbaren Rollen sind:

• User: Grundlegende Lese-/Schreibrechte. Der API-Schlüssel kann Pentests ausführen und Ergebnisse lesen.
• Read-only: Der API-Schlüssel kann Pentest-Ergebnisse lesen, aber keine Pentests ausführen.
• NodeZero Runner: Eine spezialisierte, stark eingeschränkte Rolle, die speziell für NodeZero Runner entwickelt wurde.

Wir empfehlen die Rolle User, wenn Sie h3-cli testen und alle Funktionen ausprobieren möchten. Danach möchten Sie je nach Anwendungsfall möglicherweise restriktivere Berechtigungen verwenden. Wenn Sie h3-cli beispielsweise nur zum Einrichten eines NodeZero Runners verwenden möchten, empfehlen wir die Rolle NodeZero Runner.

Sie können mehrere API-Schlüssel innerhalb derselben h3-cli-Installation problemlos verwalten. Erfahren Sie mehr hier.

❗ Bewahren Sie Ihren API-Schlüssel sicher auf, denn jeder, der Ihren API-Schlüssel besitzt, kann auf Ihr H3-Konto zugreifen. Betrachten Sie einen API-Schlüssel als Benutzername + Passwort in einem. Jeder mit dem API-Schlüssel kann von überall auf Ihr Konto zugreifen. h3-cli speichert Ihren API-Schlüssel im Verzeichnis $HOME/.h3. Dieses Verzeichnis wird während der Installation erstellt und mit Berechtigungen konfiguriert, sodass nur Sie es lesen oder beschreiben können.

2. h3-cli installieren

Installieren Sie das h3-cli-Git-Repository auf Ihrem Rechner, indem Sie den folgenden Git-Befehl in einer Shell-/Terminal-Sitzung ausführen.

Dadurch wird ein neues Verzeichnis h3-cli erstellt und der Inhalt des Repositorys dorthin heruntergeladen. Das Verzeichnis h3-cli wird in dem Verzeichnis erstellt, in dem Sie den Git-Befehl ausführen. Sie können h3-cli überall im Dateisystem installieren.

Wenn Sie kein Git haben, können Sie das Repository über das obige Menü als ZIP-Archiv herunterladen und es überall im Dateisystem entpacken.

3. Das h3-cli-Installationsskript ausführen

Führen Sie die folgenden Befehle aus, um h3-cli zu installieren und zu konfigurieren. Ersetzen Sie your-api-key-here durch Ihren tatsächlichen API-Schlüssel.

Das Installationsskript installiert Abhängigkeiten (jq) und erstellt Ihr Standard-h3-cli-Profil im Verzeichnis $HOME/.h3. Ihr API-Schlüssel wird in Ihrem h3-cli-Profil gespeichert. Die Berechtigungen für Verzeichnis und Profil sind so eingeschränkt, dass keine anderen Benutzer (außer Ihnen selbst) sie lesen oder beschreiben können.

Das Installationsskript fordert Sie auf, Ihr Shell-Profil ($HOME/.bash_profile oder $HOME/.bash_login oder $HOME/.profile, je nach Betriebssystem) zu bearbeiten, um die folgenden Umgebungsvariablen festzulegen:

• H3_CLI_HOME: Diese Umgebungsvariable wird von h3-cli verwendet, um sich selbst und seine unterstützenden Dateien zu finden.
• PATH: Diese Umgebungsvariable gibt die Verzeichnisse an, die durchsucht werden, um einen Shell-Befehl zu finden.

Melden Sie sich nach der Aktualisierung Ihres Shell-Profils neu an oder starten Sie Ihre Shell-Sitzung neu, um die Profiländerungen zu übernehmen. Überprüfen Sie dann, ob Sie h3 aufrufen können, indem Sie es an der Eingabeaufforderung ausführen:

Wenn alles korrekt installiert ist, sollten Sie den h3-cli-Hilfetext sehen.

h3-cli aktualisieren

Wir veröffentlichen jeden Monat neue Funktionen, Fehlerbehebungen und andere Aktualisierungen für h3-cli. Aktualisieren Sie Ihre Installation mit einer der folgenden Methoden.

Option 1: Über den Befehl h3 upgrade (empfohlen)

Seit Juni 2023 können Sie den Befehl h3 upgrade verwenden, um auf die neueste Version von h3-cli zu aktualisieren.

Wenn Sie eine Fehlermeldung ERROR: unrecognized command: "upgrade" erhalten, verwenden Sie eine ältere Version von h3-cli, die den Upgrade-Befehl nicht unterstützt. Verwenden Sie eine der folgenden Methoden, um h3-cli zu aktualisieren.

Option 2: Über easy_install.sh (empfohlen, wenn h3 upgrade nicht verfügbar ist)

Führen Sie diesen Befehl aus dem übergeordneten Verzeichnis von h3-cli aus (d. h. dem Verzeichnis, das das Verzeichnis h3-cli/ enthält):

Option 3: Über Git

Wenn Sie git clone zur Installation des Repositorys verwendet haben, führen Sie einfach git pull aus, um die neueste Version zu installieren.

Option 4: Über ZIP-Download

Wenn Sie das Repository als ZIP-Datei heruntergeladen haben, laden Sie die ZIP-Datei erneut herunter und entpacken Sie sie am selben Ort (mit anderen Worten: Ersetzen Sie Ihre vorhandene h3-cli-Installation durch die neue ZIP-Datei).

Aktuelle Version prüfen

Seit Juni 2023 können Sie Ihre aktuelle Version von h3-cli wie folgt anzeigen:

Die vollständige Versionshistorie und die Versionshinweise können Sie wie folgt anzeigen:

Erste Schritte

1. Die Konnektivität mit der API überprüfen

Führen Sie den folgenden Befehl aus, um die Konnektivität mit der API zu überprüfen.

Sie sollten die folgende Antwort sehen:

❗️ Wenn Sie eine Fehlerantwort erhalten, kontaktieren Sie H3 bitte über das Chat-Symbol im Horizon3.ai-Portal.

2. Die Liste der Pentests in Ihrem Konto abfragen

Der folgende Befehl gibt die Liste der Pentests in Ihrem Konto zurück, die neuesten zuerst.

Um nach Pentests zu filtern, die einem bestimmten Suchbegriff entsprechen, übergeben Sie den Suchbegriff als Parameter:

3. Einen bestimmten Pentest aus Ihrem Konto abfragen

Um den neuesten Pentest in Ihrem Konto abzufragen:

Um einen beliebigen Pentest in Ihrem Konto abzufragen, übergeben Sie die op_id des Pentests als Parameter:

Mehrere h3-cli-Befehle verwenden standardmäßig den neuesten Pentest, sofern nicht eine op_id als Parameter übergeben wird.

Die Begriffe „op“ und „Pentest“ werden häufig synonym verwendet.

4. Einen Pentest ausführen

Für die Ausführung eines Pentests muss eine Op-Vorlage angegeben werden. Eine Op-Vorlage legt eine vollständige Pentest-Konfiguration fest, die Scope, Angriffsparameter und andere (optionale) Konfiguration umfasst.

Horizon3.ai stellt neuen Benutzern eine Standard-Op-Vorlage namens Default 1 - Recommended zur Verfügung. Diese Vorlage ist stets auf dem neuesten Stand unserer Angriffsparameter und empfohlenen Konfiguration. Die Standardvorlage definiert keinen Scope; in diesem Fall verwendet NodeZero Intelligent Scope – das Host-Subnetz von NodeZero bildet den anfänglichen Scope und erweitert sich während des Pentests organisch, wenn weitere Hosts und Subnetze entdeckt werden. Weitere Informationen zu Intelligent Scope und anderen Bereitstellungsoptionen finden Sie in unserer Produktdokumentation.

Für erfahrene Benutzer können über das Horizon3.ai-Portal benutzerdefinierte Op-Vorlagen erstellt werden. Um eine benutzerdefinierte Op-Vorlage zu erstellen, gehen Sie durch das Modal Run a Pentest, bis Sie die Option zur Anpassung der Pentest-Konfiguration sehen. Die Op-Vorlage kann erstellt werden, ohne den Pentest tatsächlich auszuführen.

Um einen Pentest mit der Standard-Op-Vorlage und Intelligent Scope bereitzustellen:

Die JSON-Antwort enthält die Details des neu erstellten Pentests. Sie können überprüfen, ob der Pentest bereitgestellt wird, indem Sie Ihr Horizon3.ai-Portal prüfen oder h3 pentest ausführen.

Es gibt mehrere Möglichkeiten, beim Erstellen von Pentests zusätzliche Parameter anzugeben. Weitere Informationen finden Sie hier in den zusätzlichen Beispielen.

❗ MOMENT! SIE SIND NOCH NICHT FERTIG!

Für interne Pentests (die Standardeinstellung) sind zusätzliche Schritte erforderlich, bevor der Pentest zu laufen beginnt. Lesen Sie den nächsten Abschnitt über das Herunterladen und Ausführen von NodeZero, um die Initiierung Ihres Pentests abzuschließen.

Wenn Sie einen externen Pentest ausführen, wird NodeZero für Sie automatisch in der H3-Cloud als Teil von h3 run-pentest gestartet. In diesem Fall sind auf Ihrer Seite keine weiteren Schritte erforderlich, um den Pentest zu initiieren.

5. NodeZero ausführen

❗ ️Der folgende Schritt gilt nur für interne Pentests; bei externen Pentests wird NodeZero für Sie automatisch in der H3-Cloud gestartet.

Nach der Erstellung eines internen Pentests müssen Sie unseren NodeZero-Container auf einem Docker-Host in Ihrem Netzwerk ausführen. Dies geschieht durch Ausführen des NodeZero-Launch-Skripts auf Ihrem Docker-Host.

Um das NodeZero-Launch-Skript für Ihren zuletzt erstellten Pentest auszuführen:

IHR PENTEST WURDE GESTARTET! Unter der Annahme, dass alle Befehle fehlerfrei ausgeführt wurden, haben Sie Ihren Pentest erfolgreich erstellt und gestartet. Sie sollten sehen, wie die Ausgabe des NodeZero-Launch-Skripts in der Konsole protokolliert wird. Das Skript überprüft zunächst, ob Ihr System mit NodeZero kompatibel ist, bevor NodeZero heruntergeladen und ausgeführt wird. Wenn der Pentest abgeschlossen ist, fährt sich NodeZero automatisch herunter.

NodeZero ist ein Docker-Container. Sie können ihn mit docker ps anzeigen. Der Containername hat die Form n0-xxxx.

6. Pentest-Berichte herunterladen

Nach Abschluss Ihres Pentests verwenden Sie den folgenden Befehl, um eine ZIP-Datei mit allen PDF- und CSV-Berichten für den zuletzt erstellten Pentest herunterzuladen:

Der obige Befehl lädt die ZIP-Datei als pentest-reports-{op_id}.zip in das aktuelle Verzeichnis herunter.

Anwendungsfälle

• Automatisierte NodeZero-Bereitstellung mit einem NodeZero Runner. Erfahren Sie, wie Sie mit einem NodeZero Runner NodeZero automatisch auf Ihrem Docker-Host bereitstellen, ohne das NodeZero-Launch-Skript manuell kopieren und einfügen zu müssen.
• Automatische Planung. Erfahren Sie, wie Sie Pentests automatisch nach einem regelmäßigen Zeitplan ausführen, z. B. einmal pro Woche oder einmal pro Monat.
• Automatisch injizierte Anmeldedaten. Erfahren Sie, wie Sie einem regelmäßig geplanten Pentest mithilfe eines NodeZero Runners automatisch Anmeldedaten injizieren.
• Überwachung von Pentests. Erfahren Sie, wie Sie Pentests mit h3-cli überwachen.
• Ergebnisse paginieren. Erfahren Sie, wie Sie mit h3-cli durch große Ergebnislisten blättern.
• JSON-Parsing mit jq. Erfahren Sie, wie Sie die Leistungsfähigkeit von jq nutzen, um JSON-Antworten von h3-cli zu parsen. jq kann bestimmte Felder parsen, die Struktur einer Antwort ausgeben und sogar eine JSON-Antwort in CSV umwandeln.

Authentifizierung und h3-cli-Profile

Die Authentifizierung erfolgt nahtlos und automatisch, wenn Sie den Befehl h3 aufrufen. Sie müssen nichts explizit tun, um sich zu authentifizieren. Dieser Abschnitt dokumentiert die zugrunde liegende Mechanik.

h3-cli liest Ihren H3_API_KEY aus Ihrem h3-cli-Profil (unter $HOME/.h3), um sich bei der Horizon3.ai-API zu authentifizieren und eine (temporäre) Sitzung aufzubauen. Das Sitzungstoken (ein JWT) wird unter $HOME/.h3 zwischengespeichert. Das Sitzungstoken läuft nach 1 Stunde ab; zu diesem Zeitpunkt authentifiziert sich h3-cli automatisch neu und stellt eine neue Sitzung her.

Sie können sich mit dem folgenden Befehl explizit authentifizieren:

Der obige Befehl gibt das Sitzungstoken aus (und speichert es auch unter $HOME/.h3 zwischen). Wenn Sie bereits über ein aktives (nicht abgelaufenes) Sitzungstoken verfügen, verwendet h3 auth weiterhin dieses Sitzungstoken, anstatt sich erneut zu authentifizieren.

Wenn Sie h3-cli zwingen möchten, sich erneut zu authentifizieren, verwenden Sie die Option force:

h3-cli-Profile

Sie können mehrere h3-cli-Authentifizierungsprofile unter demselben Verzeichnis $HOME/.h3 verwalten. Jedes h3-cli-Profil hat seinen eigenen API-Schlüssel.

Wenn Sie h3-cli zum ersten Mal installieren, wird automatisch ein anfängliches Profil namens default mit dem API-Schlüssel erstellt, den Sie install.sh bereitgestellt haben.

Wenn Sie ein weiteres Profil mit einem anderen API-Schlüssel erstellen möchten, verwenden Sie den folgenden Befehl:

Dadurch wird ein Profil namens my-profile unter $HOME/.h3 für den angegebenen {api_key} erstellt. Um das Profil in Ihrer aktuellen Shell-Sitzung zu aktivieren, verwenden Sie den folgenden Befehl (beachten Sie den führenden Punkt .):

Sie können das aktuell aktive Profil mit h3 profile überprüfen und Details zu seinem API-Schlüssel mit h3 whoami anzeigen:

Sie können mehrere API-Schlüssel unter verschiedenen h3-cli-Profilen speichern und mit dem obigen Befehl bei Bedarf zwischen ihnen wechseln. Um beispielsweise zum Profil default zurückzukehren:

Um die Liste der h3-cli-Profile unter Ihrem Verzeichnis $HOME/.h3 anzuzeigen:

Sie können ein Profil mit dem folgenden Befehl aus Ihrem Verzeichnis $HOME/.h3 löschen:

Dadurch werden das Profil namens {name} und sein API-Schlüssel aus dem Verzeichnis $HOME/.h3 auf dem lokalen Rechner entfernt. Beachten Sie, dass der API-Schlüssel dadurch NICHT widerrufen wird; er wird nur vom lokalen Rechner gelöscht. Sie können den API-Schlüssel über das Portal widerrufen.

Ausführen von Pentests mit h3-cli

Dieser Abschnitt enthält zusätzliche Beispiele für die Ausführung von Pentests mit h3-cli.

Der einfachste Weg, einen Pentest bereitzustellen, ist die Verwendung der Standard-Op-Vorlage und von Intelligent Scope:

Um einen Pentest bereitzustellen UND NodeZero auf dem lokalen Rechner zu starten (nur für interne Pentests):

Beachten Sie, dass dies nur für interne Pentests gilt. Bei externen Pentests wird NodeZero für Sie automatisch in der H3-Cloud als Teil von h3 run-pentest gestartet.

Wenn Sie h3 run-pentest-and-nodezero versehentlich für einen externen Pentest ausführen, wird einfach der Teil übersprungen, in dem NodeZero heruntergeladen und ausgeführt wird, da dies automatisch in der H3-Cloud übernommen wird.

Um einen Pentest mit einer benutzerdefinierten Op-Vorlage auszuführen, geben Sie sie als Parameter an schedule_op_template.graphql an:

Um einen Pentest mit der Standard-Op-Vorlage auszuführen, ihm aber einen Namen Ihrer Wahl zuzuweisen, verwenden Sie den optionalen Parameter op_name:

Um einen Pentest mit der Standard-Op-Vorlage auszuführen, aber seinen Namen und Scope festzulegen, verwenden Sie den optionalen Parameter schedule_op_form:

Beachten Sie, dass h3 run-pentest und h3 run-pentest-and-nodezero alle dieselben optionalen Parameter akzeptieren.

Um einen Pentest auszuführen und ihn einem NodeZero Runner namens my-nodezero-runner zuzuweisen:

Externe Pentests ausführen

Wenn Sie eine Op-Vorlage für Ihren externen Pentest konfiguriert haben:

Wenn Sie KEINE Op-Vorlage haben, können Sie einen externen Pentest ausführen, indem Sie zunächst die UUID Ihrer Asset-Gruppe über h3 asset-groups nachschlagen:

Verwenden Sie dann den folgenden Befehl, um einen externen Pentest gegen diese Asset-Gruppe auszuführen. Ersetzen Sie die UUID Ihrer Asset-Gruppe durch {your-asset-group-uuid}:

Angetrieben von GraphQL

Die Horizon3.ai-API wird von GraphQL angetrieben. Zusätzlich zu diesem CLI-Dokument umfasst die relevante Dokumentation:

• Horizon3.ai Docs
• GraphQL.org

Fortgeschritten: Eigene GraphQL-Abfragen schreiben

h3-cli bietet einen einfachen Mechanismus zum Ausführen eigener GraphQL-Abfragen. Zuerst definieren Sie die GraphQL-Abfrage in einer Datei (normalerweise mit der Erweiterung .graphql, auch wenn dies nicht erforderlich ist). Dann übergeben Sie die Datei an h3 gql:

Definieren Sie beispielsweise Folgendes in einer Datei namens my_session.graphql:

Führen Sie dann aus:

Sie sollten die rohe JSON-Antwort des GraphQL-Servers sehen. Sie können die JSON-Antwort mit jq hübsch formatieren:

Wichtig! Sie müssen den Pfad zur GraphQL-Datei angeben (vollständig oder relativ, z. B. ./my_session.graphql statt nur my_session.graphql), andernfalls besteht die Gefahr einer Kollision mit GraphQL-Dateien, die h3-cli intern verwendet.

Fortgeschritten: Parametrisierte GraphQL-Abfragen

GraphQL-Abfragen können auch Parameter definieren, die als JSON-Objekt an h3 gql übergeben werden.

Definieren Sie beispielsweise Folgendes in einer Datei namens my_pentest.graphql:

In diesem Beispiel ist $op_id ein Parameter, der angegeben werden muss, um die Abfrage auszuführen. Der Parameter wird innerhalb eines JSON-Objekts an die Abfrage übergeben:

Ersetzen Sie your-op-id-here durch eine tatsächliche op_id.