h3-cli

Al crear una clave de API, debes asignarle un rol que controle sus permisos. Los roles disponibles son:

• Usuario: permisos básicos de lectura/escritura. La clave de API puede ejecutar pentests y leer resultados.
• Solo lectura: la clave de API puede leer resultados de pentests, pero no puede ejecutar pentests.
• NodeZero Runner: un rol especializado y muy restringido diseñado específicamente para NodeZero Runners.

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.

2. Instalar h3-cli

Instala el repositorio git de h3-cli en tu máquina ejecutando el siguiente comando git dentro de una sesión de shell/terminal.

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.

3. Ejecutar el script de instalación de h3-cli

Ejecuta los siguientes comandos para instalar y configurar h3-cli. Sustituye your-api-key-here por tu clave de API real.

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:

Si todo está instalado correctamente, deberías ver el texto de ayuda de h3-cli.

Actualizar 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.

Opción 1: Mediante el comando 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.

Opción 2: Mediante 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/):

Opción 3: Mediante git

Si usaste git clone para instalar el repositorio, simplemente ejecuta git pull para instalar la última versión.

Opción 4: Mediante descarga zip

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).

Comprobar la versión actual

A partir de junio de 2023, puedes ver tu versión actual de h3-cli mediante:

Puedes ver el historial completo de versiones y notas de la versión mediante:

Primeros pasos

1. Verificar la conectividad con la API

Ejecuta el siguiente comando para verificar la conectividad con la API.

Deberías ver la respuesta:

❗️ Si estás recibiendo una respuesta de error, contacta con H3 a través del icono de chat en el Portal de Horizon3.ai.

2. Consultar la lista de pentests en tu cuenta

El siguiente comando devolverá la lista de pentests en tu cuenta, del más reciente al más antiguo.

Para filtrar los pentests que coinciden con un término de búsqueda determinado, pasa el término de búsqueda como parámetro:

3. Consultar un pentest específico de tu cuenta

Para consultar el pentest más reciente de tu cuenta:

Para consultar cualquier pentest de tu cuenta, pasa el op_id del pentest como parámetro:

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.

4. Ejecutar un pentest

Ejecutar un pentest requiere especificar una plantilla de op. Una plantilla de op especifica una configuración completa del pentest, que incluye alcance, parámetros de ataque y otra configuración (opcional).

Horizon3.ai proporciona a los nuevos usuarios una plantilla de op predeterminada llamada Default 1 - Recommended. Esta plantilla está siempre actualizada con nuestros últimos parámetros de ataque y configuración recomendada. La plantilla predeterminada no define un alcance, en cuyo caso NodeZero usará Intelligent Scope - la subred del host de NodeZero proporcionará el alcance inicial y se expandirá orgánicamente durante el pentest a medida que se descubran más hosts y subredes. Para obtener más información sobre Intelligent Scope y otras opciones de implementación, visita nuestra documentación del producto.

Para usuarios experimentados, se pueden crear plantillas de op personalizadas a través del Portal de Horizon3.ai. Para crear una plantilla de op personalizada, recorre el modal Run a Pentest hasta que veas la opción de personalizar la configuración del pentest. La plantilla de op se puede crear sin ejecutar realmente el pentest.

Para aprovisionar un pentest usando la plantilla de op predeterminada e Intelligent Scope:

La respuesta JSON contiene los detalles del pentest recién creado. Puedes verificar que el pentest se está aprovisionando consultando tu Portal de Horizon3.ai, o ejecutando h3 pentest.

Hay varias formas de especificar parámetros adicionales al crear pentests. Para obtener más información, consulta ejemplos adicionales aquí.

❗ ¡ESPERA! ¡AÚN NO HAS TERMINADO!

Para pentests internos (que son los predeterminados), se requieren pasos adicionales antes de que el pentest comience a ejecutarse. Consulta la siguiente sección sobre descargar y ejecutar NodeZero para completar el inicio de tu pentest.

Si estás ejecutando un pentest externo, NodeZero se lanza automáticamente por ti en la nube de H3 como parte de h3 run-pentest, en cuyo caso no hay pasos adicionales de tu parte para iniciar el pentest.

5. Ejecutar NodeZero

❗ ️El siguiente paso se aplica únicamente a pentests internos; para pentests externos, NodeZero se lanza automáticamente por ti en la nube de H3.

Después de crear un pentest interno, tienes que ejecutar nuestro contenedor NodeZero en un Docker Host dentro de tu red. Esto se hace ejecutando el NodeZero Launch Script en tu Docker Host.

Para ejecutar el NodeZero Launch Script para tu pentest creado más recientemente:

¡TU PENTEST HA SIDO LANZADO! Suponiendo que todos los comandos se ejecutaron sin errores, has creado y lanzado tu pentest con éxito. Deberías ver en la consola el resultado del NodeZero Launch Script. El script primero verificará que tu sistema sea compatible con NodeZero antes de descargarlo y ejecutarlo. Cuando el pentest esté completo, NodeZero se apagará automáticamente.

NodeZero es un contenedor Docker. Puedes verlo usando docker ps. El nombre del contenedor tendrá la forma n0-xxxx.

6. Descargar informes de pentest

Después de que tu pentest haya finalizado, usa el siguiente comando para descargar un archivo zip que contiene todos los informes PDF y CSV del pentest creado más recientemente:

El comando anterior descargará el archivo zip como pentest-reports-{op_id}.zip en el directorio actual.

Casos de uso

• Implementación automatizada de NodeZero mediante un NodeZero Runner. Aprende a usar un NodeZero Runner para implementar NodeZero en tu Docker Host automáticamente, sin tener que copiar y pegar manualmente el NodeZero Launch Script.
• Programación automatizada. Aprende a ejecutar pentests automáticamente con una programación regular, por ejemplo una vez a la semana o una vez al mes.
• Credenciales de inyección automática. Aprende a inyectar automáticamente credenciales en un pentest programado regularmente usando un NodeZero Runner.
• Supervisión de pentests. Aprende a supervisar pentests usando h3-cli.
• Paginación de resultados. Aprende a paginar grandes conjuntos de resultados usando h3-cli.
• Análisis JSON con jq. Aprende a aprovechar el poder de jq para analizar respuestas JSON de h3-cli. jq puede analizar campos específicos, imprimir la estructura de una respuesta e incluso transformar una respuesta JSON a CSV.

Autenticación y perfiles de h3-cli

La autenticación se produce de forma fluida y automática cuando invocas el comando h3. No hay nada explícito que necesites hacer para autenticarte. Esta sección documenta los mecanismos subyacentes.

h3-cli lee tu H3_API_KEY de tu perfil de h3-cli (en $HOME/.h3) para autenticarse en la API de Horizon3.ai y establecer una sesión (temporal). El token de sesión (un JWT) se almacena en caché en $HOME/.h3. El token de sesión caduca después de 1 hora, momento en el que h3-cli se reautenticará automáticamente y restablecerá la sesión.

Puedes autenticarte explícitamente usando el siguiente comando:

El comando anterior mostrará el token de sesión (y también lo almacenará en caché en $HOME/.h3). Si ya tienes un token de sesión establecido (no caducado), h3 auth seguirá usando ese token de sesión en lugar de reautenticarse.

Si quieres forzar a h3-cli a reautenticarse, usa la opción force:

Perfiles de h3-cli

Puedes administrar múltiples perfiles de autenticación de h3-cli bajo el mismo directorio $HOME/.h3. Cada perfil de h3-cli tiene su propia clave de API.

Cuando instalas h3-cli por primera vez, crea automáticamente un perfil inicial llamado default con la clave de API que proporcionaste a install.sh.

Si deseas crear otro perfil con una clave de API diferente, usa el siguiente comando:

Esto creará un perfil llamado my-profile en $HOME/.h3 para la {api_key} proporcionada. Para activar el perfil en tu sesión de shell actual, usa el siguiente comando (observa el punto inicial .):

Puedes verificar el perfil actualmente activo usando h3 profile y ver detalles sobre su clave de API usando h3 whoami:

Puedes guardar múltiples claves de API en diferentes perfiles de h3-cli y cambiar entre ellos según sea necesario usando el comando anterior. Por ejemplo, para volver al perfil default:

Para ver la lista de perfiles de h3-cli en tu directorio $HOME/.h3:

Puedes eliminar un perfil de tu directorio $HOME/.h3 usando:

Esto eliminará el perfil llamado {name} y su clave de API del directorio $HOME/.h3 en la máquina local. Ten en cuenta que NO revocará la clave de API; solo la elimina de la máquina local. Puedes revocar la clave de API desde el Portal.

Ejecutar pentests con h3-cli

Esta sección contiene ejemplos adicionales para ejecutar pentests usando h3-cli.

La forma más sencilla de aprovisionar un pentest es usar la plantilla de op predeterminada e Intelligent Scope:

Para aprovisionar un pentest Y lanzar NodeZero en la máquina local (solo para pentests internos):

Ten en cuenta que esto solo se aplica a pentests internos. Para pentests externos, NodeZero se lanza automáticamente por ti en la nube de H3 como parte de h3 run-pentest.

Si llegas a ejecutar h3 run-pentest-and-nodezero para un pentest externo, simplemente omitirá la parte en la que descarga y ejecuta NodeZero, ya que eso se maneja automáticamente en la nube de H3.

Para ejecutar un pentest usando una plantilla de op personalizada, especifícala como parámetro de schedule_op_template.graphql:

Para ejecutar un pentest con la plantilla de op predeterminada pero asignarle un nombre de tu elección, usa el parámetro opcional op_name:

Para ejecutar un pentest con la plantilla de op predeterminada pero especificando su nombre y alcance, usa el parámetro opcional schedule_op_form:

Ten en cuenta que h3 run-pentest y h3 run-pentest-and-nodezero aceptan todos los mismos parámetros opcionales.

Para ejecutar un pentest y asignarlo a un NodeZero Runner llamado my-nodezero-runner:

Ejecutar pentests externos

Si tienes una plantilla de op configurada para tu pentest externo:

Si NO tienes una plantilla de op, puedes ejecutar un pentest externo consultando primero el uuid de tu Asset Group mediante h3 asset-groups:

Luego usa el siguiente comando para ejecutar un pentest externo contra ese Asset Group. Sustituye el uuid de tu Asset Group por {your-asset-group-uuid}:

Con tecnología de GraphQL

La API de Horizon3.ai está desarrollada con GraphQL. Además de este documento de CLI, la documentación relevante incluye:

• Horizon3.ai Docs
• GraphQL.org

Avanzado: Escribir tus propias consultas GraphQL

h3-cli proporciona un mecanismo simple para ejecutar tus propias consultas GraphQL. Primero defines la consulta GraphQL en un archivo (normalmente con extensión .graphql, aunque no es obligatorio). Luego pasa el archivo a h3 gql:

Por ejemplo, define lo siguiente en un archivo llamado my_session.graphql:

Luego ejecuta:

Deberías ver la respuesta JSON cruda del servidor GraphQL. Puedes formatear la respuesta JSON de forma legible usando jq:

¡Importante! Debes especificar la ruta al archivo graphql (completa o relativa, por ejemplo ./my_session.graphql en lugar de solo my_session.graphql), de lo contrario corres el riesgo de colisionar con los archivos graphql que h3-cli usa internamente.

Avanzado: Consultas GraphQL parametrizadas

Las consultas GraphQL también pueden definir parámetros, que se pasan a h3 gql como un objeto JSON.

Por ejemplo, define lo siguiente en un archivo llamado my_pentest.graphql:

En este ejemplo, $op_id es un parámetro que debe proporcionarse para poder ejecutar la consulta. El parámetro se pasa a la consulta dentro de un objeto JSON:

Sustituye your-op-id-here por un op_id real.