horizon3ai/h3-cliOutil CLI pour l'API Horizon3.ai
Le serveur MCP NodeZero est désormais disponible, vous permettant d'exécuter et de gérer un serveur MCP hébergé localement qui apporte les capacités Find, Fix, Verify (FFV) de NodeZero directement à vos flux de travail de développement et de sécurité.
h3-cli est un CLI (interface en ligne de commande) pratique pour accéder à l'API Horizon3.ai. L'API Horizon3.ai fournit un accès programmatique à un sous-ensemble des fonctionnalités disponibles via le portail Horizon3.ai. De manière générale, l'API vous permet de :
L'API peut être utilisée pour divers cas d'usage, tels que la planification d'évaluations périodiques de votre environnement ou le lancement d'un pentest dans le cadre d'un pipeline d'intégration continue.
Les étapes ci-dessous vous permettront de démarrer rapidement avec h3-cli. Ces instructions ont été testées sur des machines macOS et Linux et devraient généralement fonctionner sur tout système compatible POSIX avec le support de bash.
Si vous prévoyez d'exécuter des pentests internes avec h3-cli, vous devriez installer h3-cli sur le même hôte Docker où vous lancez NodeZero.
Nous supposons que vous avez déjà un compte chez Horizon3.ai. Si ce n'est pas le cas, inscrivez-vous sur https://portal.horizon3ai.com/.
Une clé API est requise pour accéder à l'API H3. Vous pouvez en créer une dans le portail, sous le menu Utilisateur -> Paramètres du compte.
Lors de la création d'une clé API, vous devez lui assigner un rôle qui contrôle ses permissions. Les rôles disponibles sont :
Nous recommandons le rôle User si vous testez h3-cli et souhaitez expérimenter toutes ses fonctionnalités. Ensuite, vous pouvez utiliser des permissions plus restrictives, selon votre cas d'usage. Par exemple, si vous souhaitez uniquement utiliser h3-cli pour configurer un NodeZero Runner, nous recommandons d'utiliser le rôle NodeZero Runner.
Vous pouvez facilement gérer plusieurs clés API dans une même installation de h3-cli. En savoir plus ici.
❗ Gardez votre clé API en sécurité, car toute personne disposant de votre clé API peut accéder à votre compte H3. Considérez une clé API comme
un nom d'utilisateur + un mot de passe combinés. Toute personne disposant de la clé API peut accéder à votre compte depuis n'importe où. h3-cli
stockera votre clé API dans le répertoire $HOME/.h3. Ce répertoire est créé lors de l'installation et
configuré avec des permissions telles que vous seul pouvez y lire ou y écrire.
Installez le dépôt git h3-cli sur votre machine en exécutant la commande git suivante dans une session shell/terminal.
git clone https://github.com/horizon3ai/h3-cli
Cela créera un nouveau répertoire, h3-cli, et téléchargera le contenu du dépôt dans celui-ci. Le répertoire h3-cli
sera créé dans le répertoire où vous exécutez la commande git. Vous pouvez installer h3-cli n'importe où sur le système de fichiers.
Si vous n'avez pas git, vous pouvez télécharger le dépôt sous forme d'archive zip depuis le menu ci-dessus, et la décompresser n'importe où sur le système de fichiers.
Exécutez les commandes suivantes pour installer et configurer h3-cli. Remplacez your-api-key-here par votre véritable clé API.
cd h3-cli
bash install.sh your-api-key-here
Le script d'installation installera les dépendances (jq) et créera votre profil h3-cli par défaut dans le répertoire $HOME/.h3.
Votre clé API est stockée dans votre profil h3-cli. Les permissions du répertoire et du profil sont restreintes afin qu'aucun autre
utilisateur (en dehors de vous) ne puisse y lire ou y écrire.
Le script d'installation vous demandera de modifier votre profil shell ($HOME/.bash_profile ou $HOME/.bash_login ou $HOME/.profile, selon
votre système d'exploitation) pour définir les variables d'environnement suivantes :
H3_CLI_HOME : cette variable d'environnement est utilisée par h3-cli pour se localiser lui-même ainsi que ses fichiers de support.PATH : cette variable d'environnement spécifie les répertoires à rechercher pour trouver une commande shell.Après avoir mis à jour votre profil shell, reconnectez-vous ou redémarrez votre session shell pour prendre en compte les modifications du profil, puis vérifiez que vous pouvez invoquer h3 en l'exécutant depuis l'invite de commande :
h3
Si tout est installé correctement, vous devriez voir le texte d'aide de h3-cli.
Nous publions de nouvelles fonctionnalités, des corrections de bugs et d'autres mises à jour pour h3-cli chaque mois. Mettez à niveau votre installation en utilisant l'une des méthodes ci-dessous.
h3 upgrade (recommandé)À partir de juin 2023, vous pouvez utiliser la commande h3 upgrade pour passer à la dernière version de h3-cli.
Si vous obtenez ERROR: unrecognized command: "upgrade", vous êtes sur une version antérieure de h3-cli qui ne prend pas en charge
la commande upgrade. Utilisez l'une des méthodes ci-dessous pour mettre à niveau h3-cli.
easy_install.sh (recommandé si h3 upgrade n'est pas disponible)Exécutez cette commande depuis le répertoire parent de h3-cli (c'est-à-dire le répertoire qui contient le répertoire h3-cli/) :
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
Si vous avez utilisé git clone pour installer le dépôt, exécutez simplement git pull pour installer la dernière version.
Si vous avez téléchargé le dépôt sous forme de fichier zip, téléchargez à nouveau le fichier zip et décompressez-le au même emplacement (en d'autres termes, remplacez votre installation h3-cli existante par le nouveau zip).
À partir de juin 2023, vous pouvez consulter votre version actuelle de h3-cli via :
h3 version
Vous pouvez consulter l'historique complet des versions et les notes de version via :
h3 version -v
Exécutez la commande suivante pour vérifier la connectivité avec l'API.
h3 hello-world
Vous devriez voir la réponse :
{
"data": {
"hello": "world!"
}
}
❗️ Si vous obtenez une réponse d'erreur, veuillez contacter H3 via l'icône de chat dans le portail Horizon3.ai.
La commande ci-dessous renverra la liste des pentests de votre compte, du plus récent au plus ancien.
h3 pentests
Pour filtrer les pentests correspondant à un terme de recherche donné, passez le terme de recherche en paramètre :
h3 pentests sample
Pour interroger le pentest le plus récent de votre compte :