horizon3ai/h3-cliStrumento CLI per l'API Horizon3.ai
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