horizon3ai/h3-cliHerramienta CLI para la API de Horizon3.ai
El NodeZero MCP Server ya está disponible; te permite ejecutar y administrar un MCP Server alojado localmente que lleva las capacidades Find, Fix, Verify (FFV) de NodeZero directamente a tus flujos de trabajo de desarrollo y seguridad.
h3-cli es una práctica CLI (interfaz de línea de comandos) para acceder a la API de Horizon3.ai. La API de Horizon3.ai proporciona acceso programático a un subconjunto de la funcionalidad disponible a través del Portal de Horizon3.ai. A alto nivel, la API te permite:
La API se puede utilizar en diversos casos de uso, como programar evaluaciones periódicas de tu entorno o iniciar un pentest como parte de un pipeline de integración continua.
Los siguientes pasos te permitirán poner en marcha h3-cli rápidamente. Estas instrucciones se probaron en máquinas macOS y Linux y, en general, deberían funcionar en cualquier sistema compatible con POSIX con soporte de bash.
Si planeas ejecutar pentests internos con h3-cli, debes instalar h3-cli en el mismo Docker Host donde lances NodeZero.
Se asume que ya tienes una cuenta con Horizon3.ai. Si no es así, regístrate en https://portal.horizon3ai.com/.
Se requiere una clave de API para acceder a la API de H3. Puedes crear una en el Portal, en el menú Usuario -> Configuración de la cuenta.
Al crear una clave de API, debes asignarle un rol que controle sus permisos. Los roles disponibles son:
Recomendamos el rol Usuario si estás probando h3-cli y quieres experimentar con todas sus funciones. Después, puede que quieras usar permisos más restrictivos según tu caso de uso. Por ejemplo, si solo quieres usar h3-cli para configurar un NodeZero Runner, te recomendamos usar el rol NodeZero Runner.
Puedes administrar fácilmente varias claves de API dentro de la misma instalación de h3-cli. Obtén más información aquí.
❗ Mantén tu clave de API segura, ya que cualquiera que tenga tu clave de API puede acceder a tu cuenta de H3. Piensa en una clave de API como
un nombre de usuario + contraseña combinados en uno solo. Cualquier persona con la clave de API puede acceder a tu cuenta desde cualquier lugar. h3-cli
almacenará tu clave de API en el directorio $HOME/.h3. Este directorio se crea durante la instalación y
se configura con permisos para que solo tú puedas leerlo o escribirlo.
Instala el repositorio git de h3-cli en tu máquina ejecutando el siguiente comando git dentro de una sesión de shell/terminal.
git clone https://github.com/horizon3ai/h3-cli
Esto creará un nuevo directorio, h3-cli, y descargará el contenido del repositorio en él. El directorio h3-cli
se creará en el directorio donde ejecutes el comando git. Puedes instalar h3-cli en cualquier lugar del sistema de archivos.
Si no tienes git, puedes descargar el repositorio como archivo zip desde el menú superior y descomprimirlo en cualquier lugar del sistema de archivos.
Ejecuta los siguientes comandos para instalar y configurar h3-cli. Sustituye your-api-key-here por tu clave de API real.
cd h3-cli
bash install.sh your-api-key-here
El script de instalación instalará las dependencias (jq) y creará tu perfil h3-cli predeterminado en el directorio $HOME/.h3.
Tu clave de API se almacena en tu perfil de h3-cli. Los permisos del directorio y del perfil están restringidos para que ningún otro
usuario (aparte de ti) pueda leerlos o escribirlos.
El script de instalación te pedirá que edites tu perfil de shell ($HOME/.bash_profile o $HOME/.bash_login o $HOME/.profile, según
tu sistema operativo) para configurar las siguientes variables de entorno:
H3_CLI_HOME: esta variable de entorno es utilizada por h3-cli para localizarse a sí mismo y a sus archivos de soporte.PATH: esta variable de entorno especifica los directorios que se buscarán para encontrar un comando de shell.Después de actualizar tu perfil de shell, vuelve a iniciar sesión o reinicia tu sesión de shell para aplicar los cambios del perfil y, a continuación, verifica que puedes invocar h3 ejecutándolo desde el símbolo del sistema:
h3
Si todo está instalado correctamente, deberías ver el texto de ayuda de h3-cli.
Publicamos nuevas funciones, correcciones de errores y otras actualizaciones para h3-cli cada mes. Actualiza tu instalación usando uno de los siguientes métodos.
h3 upgrade (recomendado)A partir de junio de 2023, puedes usar el comando h3 upgrade para actualizar a la última versión de h3-cli.
Si recibes ERROR: unrecognized command: "upgrade", estás en una versión anterior de h3-cli que no admite
el comando upgrade. Usa uno de los siguientes métodos para actualizar h3-cli.
easy_install.sh (recomendado si h3 upgrade no está disponible)Ejecuta este comando desde el directorio principal de h3-cli (es decir, el directorio que contiene el directorio h3-cli/):
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
Si usaste git clone para instalar el repositorio, simplemente ejecuta git pull para instalar la última versión.
Si descargaste el repositorio como archivo zip, vuelve a descargar el archivo zip y descomprímelo en la misma ubicación (en otras palabras, reemplaza tu instalación existente de h3-cli con el nuevo zip).
A partir de junio de 2023, puedes ver tu versión actual de h3-cli mediante:
h3 version
Puedes ver el historial completo de versiones y notas de la versión mediante:
h3 version -v
Ejecuta el siguiente comando para verificar la conectividad con la API.
h3 hello-world
Deberías ver la respuesta:
{
"data": {
"hello": "world!"
}
}
❗️ Si estás recibiendo una respuesta de error, contacta con H3 a través del icono de chat en el Portal de Horizon3.ai.
El siguiente comando devolverá la lista de pentests en tu cuenta, del más reciente al más antiguo.
h3 pentests
Para filtrar los pentests que coinciden con un término de búsqueda determinado, pasa el término de búsqueda como parámetro:
h3 pentests sample
Para consultar el pentest más reciente de tu cuenta:
h3 pentest
Para consultar cualquier pentest de tu cuenta, pasa el op_id del pentest como parámetro:
h3 pentest your-op-id-here
Varios comandos de h3-cli usarán el pentest más reciente como predeterminado,
a menos que se pase un op_id como parámetro.
Los términos «op» y «pentest» se usan a menudo indistintamente.