horizon3ai/h3-cliCLI tool for the Horizon3.ai API
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 :
h3 pentest
Pour interroger n'importe quel pentest de votre compte, passez l'op_id du pentest en paramètre :
h3 pentest your-op-id-here
Plusieurs commandes h3-cli utiliseront le pentest le plus récent comme valeur par défaut,
sauf si un op_id est passé en paramètre.
Les termes « op » et « pentest » sont souvent utilisés de manière interchangeable.
Lancer un pentest nécessite de spécifier un modèle d'op. Un modèle d'op spécifie une configuration complète de pentest, qui inclut le périmètre, les paramètres d'attaque et d'autres configurations (optionnelles).
Horizon3.ai fournit aux nouveaux utilisateurs un modèle d'op par défaut nommé Default 1 - Recommended. Ce modèle est toujours
à jour avec nos derniers paramètres d'attaque et la configuration recommandée. Le modèle par défaut ne définit pas de périmètre,
auquel cas NodeZero utilisera Intelligent Scope - le sous-réseau hôte de NodeZero fournira le périmètre initial, et il s'étendra
naturellement pendant le pentest à mesure que d'autres hôtes et sous-réseaux seront découverts. Pour plus d'informations sur Intelligent Scope et les autres
options de déploiement, consultez notre documentation produit.
Pour les utilisateurs expérimentés, des modèles d'op personnalisés peuvent être créés via le portail Horizon3.ai. Pour créer un modèle d'op personnalisé, parcourez la fenêtre modale Run a Pentest jusqu'à voir l'option de personnalisation de la configuration du pentest. Le modèle d'op peut être créé sans réellement exécuter le pentest.
Pour provisionner un pentest à l'aide du modèle d'op par défaut et d'Intelligent Scope :
h3 run-pentest
La réponse JSON contient les détails du pentest nouvellement créé.
Vous pouvez vérifier que le pentest est en cours de provisionnement en consultant votre portail Horizon3.ai,
ou en exécutant h3 pentest.
Il existe plusieurs façons de spécifier des paramètres supplémentaires lors de la création de pentests. Pour plus d'informations, voir des exemples supplémentaires ici.
❗ ATTENDEZ ! VOUS N'AVEZ PAS TERMINÉ !
Pour les pentests internes (qui sont le comportement par défaut), des étapes supplémentaires sont nécessaires avant que le pentest ne commence à s'exécuter. Consultez la section suivante sur le téléchargement et l'exécution de NodeZero afin de terminer le lancement de votre pentest.
Si vous exécutez un pentest externe, NodeZero est lancé automatiquement pour vous dans le cloud H3 dans le cadre de
h3 run-pentest, auquel cas aucune étape supplémentaire n'est requise de votre côté pour lancer le pentest.
❗ ️L'étape suivante s'applique uniquement aux pentests internes ; pour les pentests externes, NodeZero est lancé automatiquement pour vous dans le cloud H3.
Après avoir créé un pentest interne, vous devez ensuite exécuter notre conteneur NodeZero sur un hôte Docker à l'intérieur de votre réseau. Cela se fait en exécutant le script de lancement NodeZero sur votre hôte Docker.
Pour exécuter le script de lancement NodeZero pour votre pentest le plus récemment créé :
h3 run-nodezero
VOTRE PENTEST A ÉTÉ LANCÉ ! En supposant que toutes les commandes se sont exécutées sans erreur, vous avez créé et lancé votre pentest avec succès. Vous devriez voir la sortie du script de lancement NodeZero être journalisée dans la console. Le script vérifiera d'abord que votre système est compatible avec NodeZero avant de le télécharger et de l'exécuter. Lorsque le pentest est terminé, NodeZero s'arrêtera automatiquement.
NodeZero est un conteneur Docker. Vous pouvez le visualiser avec docker ps. Le nom du conteneur sera de la forme n0-xxxx.
Après la fin de votre pentest, utilisez la commande suivante pour télécharger un fichier zip contenant tous les rapports PDF et CSV du pentest le plus récemment créé :
h3 pentest-reports
La commande ci-dessus téléchargera le fichier zip vers pentest-reports-{op_id}.zip dans le répertoire courant.
jq. Apprenez à tirer parti de la puissance de jq pour analyser les réponses JSON
de h3-cli. jq peut analyser des champs spécifiques, afficher la structure d'une réponse, et même transformer une réponse JSON en CSV.L'authentification se produit de manière transparente et automatique lorsque vous invoquez la commande h3.
Vous n'avez rien à faire explicitement pour vous authentifier. Cette section documente les
mécanismes sous-jacents.
h3-cli lit votre H3_API_KEY depuis votre profil h3-cli (sous $HOME/.h3) pour s'authentifier
auprès de l'API Horizon3.ai et établir une session (temporaire). Le jeton de session (un JWT) est
mis en cache sous $HOME/.h3. Le jeton de session expire après 1 heure ; à ce moment, h3-cli se
réauthentifiera automatiquement et rétablira une session.
Vous pouvez vous authentifier explicitement à l'aide de la commande suivante :
h3 auth
La commande ci-dessus affichera le jeton de session (et le mettra également en cache sous $HOME/.h3).
Si vous disposez déjà d'un jeton de session établi (non expiré), h3 auth continuera à utiliser
ce jeton de session plutôt que de se réauthentifier.
Si vous souhaitez forcer h3-cli à se réauthentifier, utilisez l'option force :
h3 auth force
Vous pouvez gérer plusieurs profils d'authentification h3-cli dans le même répertoire $HOME/.h3.
Chaque profil h3-cli possède sa propre clé API.
Lors de la première installation de h3-cli, il créera automatiquement un profil initial nommé default
avec la clé API que vous avez fournie à install.sh.
Si vous souhaitez créer un autre profil avec une clé API différente, utilisez la commande suivante :
h3 save-profile my-profile {api-key}
Cela créera un profil nommé my-profile sous $HOME/.h3 pour la {api_key} donnée.
Pour activer le profil dans votre session shell actuelle, utilisez la commande suivante (notez le point . au début) :
. h3 profile my-profile
Vous pouvez vérifier le profil actuellement actif avec h3 profile, et afficher les détails de sa clé API avec h3 whoami :
h3 profile
h3 whoami
Vous pouvez enregistrer plusieurs clés API sous différents profils h3-cli et basculer entre eux selon vos besoins à l'aide de la commande ci-dessus.
Par exemple, pour revenir au profil default :
. h3 profile default
Pour afficher la liste des profils h3-cli dans votre répertoire $HOME/.h3 :
h3 profiles
Vous pouvez supprimer un profil de votre répertoire $HOME/.h3 en utilisant :
h3 delete-profile {name}
Cela supprimera le profil nommé {name} et sa clé API du répertoire $HOME/.h3 sur la machine locale.
Notez que cela ne révoquera PAS la clé API ; cela la supprime uniquement de la machine locale. Vous pouvez révoquer la clé API depuis le portail.
Cette section contient des exemples supplémentaires pour lancer des pentests avec h3-cli.
Le moyen le plus simple de provisionner un pentest est d'utiliser le modèle d'op par défaut et Intelligent Scope :
h3 run-pentest
Pour provisionner un pentest ET lancer NodeZero sur la machine locale (uniquement pour les pentests internes) :
h3 run-pentest-and-nodezero
Notez que cela ne s'applique qu'aux pentests internes. Pour les pentests externes, NodeZero est lancé automatiquement pour vous dans le cloud H3 dans le cadre de h3 run-pentest.
Si vous exécutez
h3 run-pentest-and-nodezeropour un pentest externe, il ignorera simplement la partie où il télécharge et exécute NodeZero, puisque cela est géré automatiquement dans le cloud H3.
Pour lancer un pentest à l'aide d'un modèle d'op personnalisé, spécifiez-le en paramètre de schedule_op_template.graphql :
h3 run-pentest '{"op_template_name":"your-op-template-here"}'
Pour lancer un pentest avec le modèle d'op par défaut mais lui attribuer un nom de votre choix, utilisez le paramètre optionnel op_name :
h3 run-pentest '{"op_name":"your-op-name-here"}'
Pour lancer un pentest avec le modèle d'op par défaut mais spécifier son nom et son périmètre, utilisez le paramètre optionnel schedule_op_form :
h3 run-pentest '{"schedule_op_form":{"op_name":"your-op-name-here", "op_param_max_scope": "192.168.0.0/24"}}'
Notez que
h3 run-pentesteth3 run-pentest-and-nodezeroacceptent tous les mêmes paramètres optionnels.
Pour lancer un pentest et l'attribuer à un NodeZero Runner nommé my-nodezero-runner :
h3 run-pentest '{"schedule_op_form":{"op_name":"Pentest created via h3-cli and launched via runner", "runner_name":"my-nodezero-runner"}}'
Si vous disposez d'un modèle d'op configuré pour votre pentest externe :
h3 run-pentest '{"op_template_name":"your-op-template-here"}'
Si vous n'avez PAS de modèle d'op, vous pouvez lancer un pentest externe en recherchant d'abord l'uuid de votre groupe d'actifs (Asset Group) via h3 asset-groups :
h3 asset-groups
Utilisez ensuite la commande ci-dessous pour lancer un pentest externe contre ce groupe d'actifs. Remplacez l'uuid de votre groupe d'actifs par {your-asset-group-uuid} :
h3 run-pentest '{"schedule_op_form": {"op_type": "ExternalAttack", "asset_group_uuid": "{your-asset-group-uuid}"}}'
L'API Horizon3.ai est propulsée par GraphQL. En plus de ce document CLI, la documentation pertinente comprend :
h3-cli fournit un mécanisme simple pour exécuter vos propres requêtes GraphQL. Commencez par définir la
requête GraphQL dans un fichier (généralement avec une extension .graphql, bien que cela ne soit pas obligatoire).
Passez ensuite le fichier à h3 gql :
h3 gql {your-query-file}
Par exemple, définissez ce qui suit dans un fichier nommé my_session.graphql :
query {
session_user_account {
email
name
company_name
}
}
Puis exécutez :
h3 gql ./my_session.graphql
Vous devriez voir la réponse JSON brute du serveur GraphQL. Vous pouvez afficher la réponse JSON de manière lisible avec jq :
h3 gql ./my_session.graphql | jq .
Important ! Vous devez spécifier le chemin vers le fichier graphql (complet ou relatif, par exemple ./my_session.graphql au lieu de simplement my_session.graphql),
sinon vous risquez d'entrer en collision avec les fichiers graphql que h3-cli utilise en interne.
Les requêtes GraphQL peuvent également définir des paramètres, qui sont passés à h3 gql sous forme d'objet JSON.
Par exemple, définissez ce qui suit dans un fichier nommé my_pentest.graphql :
query q($op_id: String!) {
pentest(op_id:$op_id) {
op_id
name
state
}
}
Dans cet exemple, $op_id est un paramètre qui doit être fourni pour exécuter la requête.
Le paramètre est passé à la requête dans un objet JSON :
h3 gql ./my_pentest.graphql '{"op_id":"your-op-id-here"}' | jq .
Remplacez
your-op-id-herepar unop_idréel.