horizon3ai/h3-cliCLI tool for the Horizon3.ai API
Il NodeZero MCP Server è ora disponibile e consente di eseguire e gestire un MCP Server ospitato localmente che porta le funzionalità Find, Fix, Verify (FFV) di NodeZero direttamente nei tuoi flussi di lavoro di sviluppo e sicurezza.
h3-cli è una pratica CLI (interfaccia a riga di comando) per accedere all'API Horizon3.ai. L'API Horizon3.ai fornisce accesso programmatico a un sottoinsieme delle funzionalità disponibili tramite il Portale Horizon3.ai. A livello generale, l'API consente di:
L'API può essere utilizzata per una varietà di casi d'uso, come la pianificazione di valutazioni periodiche del tuo ambiente o l'avvio di un penetration test come parte di una pipeline di integrazione continua.
I passaggi seguenti ti permetteranno di iniziare rapidamente con h3-cli. Queste istruzioni sono state testate su macchine macOS e Linux e, in generale, dovrebbero funzionare su qualsiasi sistema conforme a POSIX con supporto bash.
Se prevedi di eseguire penetration test interni usando h3-cli, dovresti installare h3-cli sullo stesso Docker Host in cui avvii NodeZero.
Si presuppone che tu abbia già un account con Horizon3.ai. In caso contrario, registrati su https://portal.horizon3ai.com/.
Per accedere all'API H3 è richiesta una chiave API. Puoi crearne una nel Portale tramite il menu Utente -> Impostazioni account.
Quando crei una chiave API, devi assegnarle un ruolo che ne controlli i permessi. I ruoli disponibili sono:
Ti consigliamo il ruolo Utente se stai provando h3-cli e vuoi sperimentare con tutte le sue funzionalità. Successivamente, potresti voler usare permessi più restrittivi, in base al tuo caso d'uso. Ad esempio, se vuoi solo usare h3-cli per configurare un NodeZero Runner, ti consigliamo di usare il ruolo NodeZero Runner.
Puoi gestire facilmente più chiavi API all'interno della stessa installazione di h3-cli. Scopri di più qui.
❗ Mantieni al sicuro la tua chiave API, poiché chiunque abbia la tua chiave API può accedere al tuo account H3. Considera una chiave API come
un nome utente + password in un'unica soluzione. Chiunque abbia la chiave API può accedere al tuo account da qualsiasi luogo. h3-cli
memorizzerà la tua chiave API nella directory $HOME/.h3. Questa directory viene creata durante l'installazione e
configurata con permessi tali per cui solo tu puoi leggerla o scriverci.
Installa il repository git di h3-cli sulla tua macchina eseguendo il seguente comando git in una sessione shell/terminale.
git clone https://github.com/horizon3ai/h3-cli
Questo creerà una nuova directory, h3-cli, e scaricherà al suo interno il contenuto del repository. La directory h3-cli
verrà creata nella directory in cui esegui il comando git. Puoi installare h3-cli in qualsiasi punto del filesystem.
Se non hai git, puoi scaricare il repository come archivio zip dal menu qui sopra e decomprimerlo in qualsiasi punto del filesystem.
Esegui i seguenti comandi per installare e configurare h3-cli. Sostituisci your-api-key-here con la tua chiave API effettiva.
cd h3-cli
bash install.sh your-api-key-here
Lo script di installazione installerà le dipendenze (jq) e creerà il tuo profilo h3-cli predefinito nella directory $HOME/.h3.
La tua chiave API viene memorizzata nel tuo profilo h3-cli. I permessi della directory e del profilo sono limitati in modo che nessun altro utente
(oltre a te) possa leggerli o scriverci.
Lo script di installazione ti chiederà di modificare il tuo profilo di shell ($HOME/.bash_profile o $HOME/.bash_login o $HOME/.profile, a seconda
del tuo sistema operativo) per impostare le seguenti variabili d'ambiente:
H3_CLI_HOME: questa variabile d'ambiente viene utilizzata da h3-cli per individuare sé stesso e i suoi file di supporto.PATH: questa variabile d'ambiente specifica le directory da cercare per trovare un comando di shell.Dopo aver aggiornato il profilo di shell, effettua nuovamente il login o riavvia la sessione di shell per applicare le modifiche al profilo, quindi verifica di poter invocare h3 eseguendolo dal prompt dei comandi:
h3
Se tutto è stato installato correttamente, dovresti vedere il testo di aiuto di h3-cli.
Pubbliciamo nuove funzionalità, correzioni di bug e altri aggiornamenti per h3-cli ogni mese. Aggiorna la tua installazione utilizzando uno dei metodi seguenti.
h3 upgrade (consigliata)A partire da giugno 2023, puoi usare il comando h3 upgrade per passare all'ultima versione di h3-cli.
Se ricevi ERROR: unrecognized command: "upgrade", significa che stai utilizzando una versione precedente di h3-cli che non
supporta il comando upgrade. Usa uno dei metodi seguenti per aggiornare h3-cli.
easy_install.sh (consigliata se h3 upgrade non è disponibile)Esegui questo comando dalla directory padre di h3-cli (cioè la directory che contiene la cartella h3-cli/):
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
Se hai usato git clone per installare il repository, esegui semplicemente git pull per installare l'ultima versione.
Se hai scaricato il repository come file zip, riscarica il file zip e decomprimilo nella stessa posizione (in altre parole, sostituisci la tua installazione esistente di h3-cli con il nuovo zip).
A partire da giugno 2023, puoi visualizzare la tua versione corrente di h3-cli tramite:
h3 version
Puoi visualizzare la cronologia completa delle versioni e le note di rilascio tramite:
h3 version -v
Esegui il seguente comando per verificare la connettività con l'API.
h3 hello-world
Dovresti vedere la risposta:
{
"data": {
"hello": "world!"
}
}
❗️ Se ricevi una risposta di errore, contatta H3 tramite l'icona della chat nel Portale Horizon3.ai.
Il comando seguente restituirà l'elenco dei penetration test nel tuo account, partendo dai più recenti.
h3 pentests
Per filtrare i penetration test che corrispondono a un determinato termine di ricerca, passa il termine di ricerca come parametro:
h3 pentests sample
Per interrogare il penetration test più recente nel tuo account:
h3 pentest
Per interrogare qualsiasi penetration test nel tuo account, passa l'op_id del penetration test come parametro:
h3 pentest your-op-id-here
Diversi comandi di h3-cli utilizzeranno il penetration test più recente come predefinito,
a meno che non venga passato un op_id come parametro.
I termini "op" e "pentest" sono spesso usati in modo intercambiabile.
Eseguire un penetration test richiede di specificare un op template. Un op template specifica una configurazione completa del penetration test, che include scope, parametri di attacco e altra configurazione (opzionale).
Horizon3.ai fornisce ai nuovi utenti un op template predefinito chiamato Default 1 - Recommended. Questo template è sempre
aggiornato con i nostri ultimi parametri di attacco e la configurazione consigliata. Il template predefinito non definisce uno scope,
nel qual caso NodeZero utilizzerà Intelligent Scope: la subnet host di NodeZero fornirà lo scope iniziale e si espanderà
organicamente durante il penetration test man mano che vengono scoperti altri host e subnet. Per maggiori informazioni su Intelligent Scope e altre
opzioni di distribuzione, visita la nostra documentazione di prodotto.
Per gli utenti esperti, è possibile creare op template personalizzati tramite il Portale Horizon3.ai. Per creare un op template personalizzato, scorri la finestra modale Run a Pentest finché non vedi l'opzione per personalizzare la configurazione del penetration test. L'op template può essere creato senza eseguire effettivamente il penetration test.
Per eseguire il provisioning di un penetration test usando l'op template predefinito e Intelligent Scope:
h3 run-pentest
La risposta JSON contiene i dettagli del penetration test appena creato.
Puoi verificare che il penetration test sia in fase di provisioning controllando il tuo Portale Horizon3.ai,
oppure eseguendo h3 pentest.
Esistono diversi modi per specificare parametri aggiuntivi durante la creazione dei penetration test. Per maggiori informazioni vedi ulteriori esempi qui.
❗ ASPETTA! NON HAI FINITO!
Per i penetration test interni (che sono l'impostazione predefinita), sono necessari passaggi aggiuntivi prima che il penetration test inizi a essere eseguito. Vedi la sezione successiva sul download e l'esecuzione di NodeZero per completare l'avvio del tuo penetration test.
Se stai eseguendo un penetration test esterno, NodeZero viene avviato automaticamente per te nel cloud H3 come parte di
h3 run-pentest, in tal caso non ci sono passaggi aggiuntivi da parte tua per avviare il penetration test.
❗ ️Il passaggio seguente si applica solo ai penetration test interni; per i penetration test esterni, NodeZero viene avviato automaticamente per te nel cloud H3.
Dopo aver creato un penetration test interno, devi eseguire il container NodeZero su un Docker Host all'interno della tua rete. Per farlo, esegui lo Script di Avvio di NodeZero sul tuo Docker Host.
Per eseguire lo Script di Avvio di NodeZero per il penetration test creato più di recente:
h3 run-nodezero
IL TUO PENETRATION TEST È STATO AVVIATO! Supponendo che tutti i comandi siano stati eseguiti senza errori, hai creato e avviato correttamente il tuo penetration test. Dovresti vedere l'output dello Script di Avvio di NodeZero registrato nella console. Lo script verificherà prima che il tuo sistema sia compatibile con NodeZero prima di scaricarlo ed eseguirlo. Quando il penetration test è completo, NodeZero si spegnerà automaticamente.
NodeZero è un container Docker. Puoi visualizzarlo usando docker ps. Il nome del container sarà della forma n0-xxxx.
Dopo che il tuo penetration test è terminato, usa il seguente comando per scaricare un file zip contenente tutti i report PDF e CSV del penetration test creato più di recente:
h3 pentest-reports
Il comando precedente scaricherà il file zip come pentest-reports-{op_id}.zip nella directory corrente.
jq. Scopri come sfruttare la potenza di jq per analizzare le risposte JSON
di h3-cli. jq può analizzare campi specifici, stampare la struttura di una risposta e persino trasformare una risposta JSON in CSV.L'autenticazione avviene in modo trasparente e automatico quando invochi il comando h3.
Non c'è nulla di esplicito che devi fare per autenticarti. Questa sezione documenta i
meccanismi sottostanti.
h3-cli legge la tua H3_API_KEY dal tuo profilo h3-cli (in $HOME/.h3) per autenticarsi
all'API Horizon3.ai e stabilire una sessione (temporanea). Il token di sessione (un JWT) viene
memorizzato nella cache in $HOME/.h3. Il token di sessione scade dopo 1 ora, a quel punto h3-cli
si riautenticherà automaticamente e stabilirà una nuova sessione.
Puoi autenticarti esplicitamente usando il seguente comando:
h3 auth
Il comando precedente restituirà il token di sessione (e lo memorizzerà anche nella cache in $HOME/.h3).
Se hai già un token di sessione attivo (non scaduto), h3 auth continuerà a usare
quel token di sessione invece di riautenticarsi.
Se vuoi forzare h3-cli a riautenticarsi, usa l'opzione force:
h3 auth force
Puoi gestire più profili di autenticazione h3-cli nella stessa directory $HOME/.h3.
Ogni profilo h3-cli ha la propria chiave API.
Quando installi h3-cli per la prima volta, creerà automaticamente un profilo iniziale chiamato default
con la chiave API che hai fornito a install.sh.
Se desideri creare un altro profilo con una chiave API diversa, usa il seguente comando:
h3 save-profile my-profile {api-key}
Questo creerà un profilo chiamato my-profile in $HOME/.h3 per la {api_key} fornita.
Per attivare il profilo nella sessione di shell corrente, usa il seguente comando (nota il punto iniziale .):
. h3 profile my-profile
Puoi verificare il profilo attualmente attivo usando h3 profile e visualizzare i dettagli della sua chiave API usando h3 whoami:
h3 profile
h3 whoami
Puoi salvare più chiavi API in diversi profili h3-cli e passare da uno all'altro secondo necessità usando il comando precedente.
Ad esempio, per tornare al profilo default:
. h3 profile default
Per visualizzare l'elenco dei profili h3-cli nella tua directory $HOME/.h3:
h3 profiles
Puoi eliminare un profilo dalla tua directory $HOME/.h3 usando:
h3 delete-profile {name}
Questo rimuoverà il profilo chiamato {name} e la sua chiave API dalla directory $HOME/.h3 sulla macchina locale.
Nota che NON revocherà la chiave API; la elimina solo dalla macchina locale. Puoi revocare la chiave API dal Portale.
Questa sezione contiene esempi aggiuntivi per eseguire penetration test usando h3-cli.
Il modo più semplice per eseguire il provisioning di un penetration test è usare l'op template predefinito e Intelligent Scope:
h3 run-pentest
Per eseguire il provisioning di un penetration test E avviare NodeZero sulla macchina locale (solo per penetration test interni):
h3 run-pentest-and-nodezero
Nota che questo si applica solo ai penetration test interni. Per i penetration test esterni, NodeZero viene avviato automaticamente per te nel cloud H3 come parte di h3 run-pentest.
Se ti capita di eseguire
h3 run-pentest-and-nodezeroper un penetration test esterno, verrà semplicemente saltata la parte in cui NodeZero viene scaricato ed eseguito, poiché è gestita automaticamente nel cloud H3.
Per eseguire un penetration test usando un op template personalizzato, specificalo come parametro di schedule_op_template.graphql:
h3 run-pentest '{"op_template_name":"your-op-template-here"}'
Per eseguire un penetration test usando l'op template predefinito ma assegnandogli un nome a tua scelta, usa il parametro opzionale op_name:
h3 run-pentest '{"op_name":"your-op-name-here"}'
Per eseguire un penetration test usando l'op template predefinito ma specificandone nome e scope, usa il parametro opzionale schedule_op_form:
h3 run-pentest '{"schedule_op_form":{"op_name":"your-op-name-here", "op_param_max_scope": "192.168.0.0/24"}}'
Nota che
h3 run-pentesteh3 run-pentest-and-nodezeroaccettano tutti gli stessi parametri opzionali.
Per eseguire un penetration test e assegnarlo a un NodeZero Runner chiamato 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"}}'
Se hai un op template configurato per il tuo penetration test esterno:
h3 run-pentest '{"op_template_name":"your-op-template-here"}'
Se NON hai un op template, puoi eseguire un penetration test esterno cercando prima l'uuid del tuo Asset Group tramite h3 asset-groups:
h3 asset-groups
Quindi usa il comando seguente per eseguire un penetration test esterno su quel Asset Group. Sostituisci l'uuid del tuo Asset Group con {your-asset-group-uuid}:
h3 run-pentest '{"schedule_op_form": {"op_type": "ExternalAttack", "asset_group_uuid": "{your-asset-group-uuid}"}}'
L'API Horizon3.ai è basata su GraphQL. Oltre a questo documento CLI, la documentazione pertinente include:
h3-cli fornisce un semplice meccanismo per eseguire le proprie query GraphQL. Per prima cosa definisci la
query GraphQL in un file (tipicamente con estensione .graphql, anche se non è obbligatorio).
Poi passa il file a h3 gql:
h3 gql {your-query-file}
Ad esempio, definisci quanto segue in un file chiamato my_session.graphql:
query {
session_user_account {
email
name
company_name
}
}
Quindi esegui:
h3 gql ./my_session.graphql
Dovresti vedere la risposta JSON grezza dal server GraphQL. Puoi stampare la risposta JSON in modo leggibile usando jq:
h3 gql ./my_session.graphql | jq .
Importante! Devi specificare il percorso del file graphql (completo o relativo, ad esempio ./my_session.graphql invece di solo my_session.graphql),
altrimenti rischi di entrare in conflitto con i file graphql che h3-cli utilizza internamente.
Le query GraphQL possono anche definire parametri, che vengono passati a h3 gql come oggetto JSON.
Ad esempio, definisci quanto segue in un file chiamato my_pentest.graphql:
query q($op_id: String!) {
pentest(op_id:$op_id) {
op_id
name
state
}
}
In questo esempio, $op_id è un parametro che deve essere fornito per poter eseguire la query.
Il parametro viene passato alla query all'interno di un oggetto JSON:
h3 gql ./my_pentest.graphql '{"op_id":"your-op-id-here"}' | jq .
Sostituisci
your-op-id-herecon unop_ideffettivo.