h3-cli

Uma chave de API é necessária para acessar a API H3. Você pode criar uma no Portal no menu Usuário -> Configurações da conta.

Ao criar uma chave de API, você deve atribuir a ela uma função que controla suas permissões. As funções disponíveis são:

• Usuário: Permissões básicas de leitura/escrita. A chave de API pode executar pentests e ler resultados.
• Somente leitura: A chave de API pode ler resultados de pentests, mas não pode executar pentests.
• NodeZero Runner: Uma função especializada e fortemente restrita, projetada especificamente para NodeZero Runners.

Recomendamos a função Usuário se você estiver testando o h3-cli e quiser experimentar todos os seus recursos. Depois disso, talvez você queira usar permissões mais restritivas, com base no seu caso de uso. Por exemplo, se você quiser usar o h3-cli apenas para configurar um NodeZero Runner, recomendamos usar a função NodeZero Runner.

Você pode gerenciar facilmente várias chaves de API na mesma instalação do h3-cli. Saiba mais aqui.

❗ Mantenha sua chave de API segura, pois qualquer pessoa com sua chave de API pode acessar sua conta H3. Pense em uma chave de API como um nome de usuário + senha em um só. Qualquer pessoa com a chave de API pode acessar sua conta de qualquer lugar. O h3-cli armazenará sua chave de API no diretório $HOME/.h3. Este diretório é criado durante a instalação e configurado com permissões para que apenas você possa ler ou gravar nele.

2. Instale o h3-cli

Instale o repositório git do h3-cli em sua máquina executando o seguinte comando git em uma sessão de shell/terminal.

Isso criará um novo diretório, h3-cli, e baixará o conteúdo do repositório para ele. O diretório h3-cli será criado no diretório onde você executa o comando git. Você pode instalar o h3-cli em qualquer lugar no sistema de arquivos.

Se você não tiver o git, pode baixar o repositório como um arquivo zip no menu acima e descompactá-lo em qualquer lugar no sistema de arquivos.

3. Execute o script de instalação do h3-cli

Execute os seguintes comandos para instalar e configurar o h3-cli. Substitua your-api-key-here pela sua chave de API real.

O script de instalação instalará as dependências (jq) e criará seu perfil padrão do h3-cli no diretório $HOME/.h3. Sua chave de API é armazenada no perfil do h3-cli. As permissões do diretório e do perfil são restritas para que nenhum outro usuário (além de você) possa ler ou gravar neles.

O script de instalação pedirá que você edite seu perfil de shell ($HOME/.bash_profile ou $HOME/.bash_login ou $HOME/.profile, dependendo do seu sistema operacional) para definir as seguintes variáveis de ambiente:

• H3_CLI_HOME: esta variável de ambiente é usada pelo h3-cli para localizar a si mesmo e seus arquivos de suporte.
• PATH: esta variável de ambiente especifica os diretórios que devem ser pesquisados para encontrar um comando de shell.

Após atualizar seu perfil de shell, faça login novamente ou reinicie sua sessão de shell para aplicar as alterações do perfil, e verifique se você pode invocar o h3 executando-o no prompt de comando:

Se tudo estiver instalado corretamente, você verá o texto de ajuda do h3-cli.

Atualizando o h3-cli

Lançamos novos recursos, correções de bugs e outras atualizações para o h3-cli todos os meses. Atualize sua instalação usando um dos métodos abaixo.

Opção 1: Por meio do comando h3 upgrade (recomendado)

A partir de junho de 2023, você pode usar o comando h3 upgrade para atualizar para a versão mais recente do h3-cli.

Se você receber um ERROR: unrecognized command: "upgrade", então você está em uma versão anterior do h3-cli que não suporta o comando de atualização. Use um dos métodos abaixo para atualizar o h3-cli.

Opção 2: Por meio do easy_install.sh (recomendado se o h3 upgrade não estiver disponível)

Execute este comando a partir do diretório pai do h3-cli (ou seja, o diretório que contém o diretório h3-cli/):

Opção 3: Por meio do git

Se você usou git clone para instalar o repositório, basta executar git pull para instalar a versão mais recente.

Opção 4: Por meio do download do zip

Se você baixou o repositório como um arquivo zip, baixe novamente o arquivo zip e descompacte-o no mesmo local (em outras palavras, substitua sua instalação existente do h3-cli pelo novo zip).

Verificando a versão atual

A partir de junho de 2023, você pode visualizar sua versão atual do h3-cli por meio de:

Você pode visualizar o histórico completo de versões e notas de versão por meio de:

Primeiros passos

1. Verifique a conectividade com a API

Execute o seguinte comando para verificar a conectividade com a API.

Você deve ver a resposta:

❗️ Se você estiver recebendo uma resposta de erro, entre em contato com a H3 pelo ícone de chat no Portal Horizon3.ai.

2. Consulte a lista de pentests na sua conta

O comando abaixo retornará a lista de pentests da sua conta, do mais recente para o mais antigo.

Para filtrar os pentests que correspondem a um termo de pesquisa específico, passe o termo de pesquisa como parâmetro:

3. Consulte um pentest específico da sua conta

Para consultar o pentest mais recente da sua conta:

Para consultar qualquer pentest da sua conta, passe o op_id do pentest como parâmetro:

Vários comandos do h3-cli usarão o pentest mais recente como padrão, a menos que um op_id seja passado como parâmetro.

Os termos "op" e "pentest" são frequentemente usados de forma intercambiável.

4. Execute um pentest

Executar um pentest exige especificar um op template. Um op template especifica uma configuração completa de pentest, que inclui escopo, parâmetros de ataque e outra configuração (opcional).

A Horizon3.ai fornece a novos usuários um op template padrão chamado Default 1 - Recommended. Este template está sempre atualizado com nossos parâmetros de ataque mais recentes e configuração recomendada. O template padrão não define um escopo; nesse caso, o NodeZero usará o Intelligent Scope - a sub-rede do host do NodeZero fornecerá o escopo inicial, e ele se expandirá organicamente durante o pentest à medida que mais hosts e sub-redes forem descobertos. Para obter mais informações sobre o Intelligent Scope e outras opções de implantação, visite nossa documentação do produto.

Para usuários experientes, op templates personalizados podem ser criados por meio do Portal Horizon3.ai. Para criar um op template personalizado, percorra o modal Run a Pentest até ver a opção de personalizar a configuração do pentest. O op template pode ser criado sem realmente executar o pentest.

Para provisionar um pentest usando o op template padrão e o Intelligent Scope:

A resposta JSON contém os detalhes do pentest recém-criado. Você pode verificar se o pentest está sendo provisionado consultando seu Portal Horizon3.ai, ou executando h3 pentest.

Existem várias maneiras de especificar parâmetros adicionais ao criar pentests. Para obter mais informações, veja exemplos adicionais aqui.

❗ ESPERA! VOCÊ AINDA NÃO TERMINOU!

Para pentests internos (que são o padrão), etapas adicionais são necessárias antes que o pentest comece a ser executado. Consulte a próxima seção sobre como baixar e executar o NodeZero para concluir o início do seu pentest.

Se você estiver executando um pentest externo, o NodeZero é iniciado automaticamente para você na nuvem H3 como parte do h3 run-pentest, caso em que não há etapas adicionais de sua parte para iniciar o pentest.

5. Execute o NodeZero

❗ ️A etapa a seguir se aplica apenas a pentests internos; para pentests externos, o NodeZero é iniciado automaticamente para você na nuvem H3.

Depois de criar um pentest interno, você precisa executar nosso contêiner NodeZero em um Docker Host dentro da sua rede. Isso é feito executando o NodeZero Launch Script no seu Docker Host.

Para executar o NodeZero Launch Script para o pentest criado mais recentemente:

SEU PENTEST FOI INICIADO! Supondo que todos os comandos tenham sido executados sem erro, você criou e iniciou seu pentest com sucesso. Você deve ver a saída do NodeZero Launch Script sendo registrada no console. O script primeiro verificará se o seu sistema é compatível com o NodeZero antes de baixá-lo e executá-lo. Quando o pentest for concluído, o NodeZero será desligado automaticamente.

O NodeZero é um contêiner Docker. Você pode vê-lo usando docker ps. O nome do contêiner terá a forma n0-xxxx.

6. Baixe os relatórios de pentest

Depois que seu pentest for concluído, use o seguinte comando para baixar um arquivo zip contendo todos os relatórios PDF e CSV do pentest criado mais recentemente:

O comando acima baixará o arquivo zip para pentest-reports-{op_id}.zip no diretório atual.

Casos de uso

• Implantação automatizada do NodeZero usando um NodeZero Runner. Saiba como usar um NodeZero Runner para implantar o NodeZero no seu Docker Host automaticamente, sem precisar copiar+colar manualmente o NodeZero Launch Script.
• Agendamento automatizado. Saiba como executar pentests automaticamente em um agendamento regular, por exemplo, uma vez por semana ou uma vez por mês.
• Credenciais injetadas automaticamente. Saiba como injetar automaticamente credenciais em um pentest agendado regularmente usando um NodeZero Runner.
• Monitoramento de pentests. Saiba como monitorar pentests usando o h3-cli.
• Paginação de resultados. Saiba como paginar grandes conjuntos de resultados usando o h3-cli.
• Análise de JSON usando jq. Saiba como aproveitar o poder do jq para analisar respostas JSON do h3-cli. O jq pode analisar campos específicos, imprimir a estrutura de uma resposta e até transformar uma resposta JSON em CSV.

Autenticação e perfis do h3-cli

A autenticação ocorre de forma transparente e automática quando você invoca o comando h3. Não há nada explícito que você precise fazer para autenticar. Esta seção documenta a mecânica subjacente.

O h3-cli lê sua H3_API_KEY do seu perfil do h3-cli (em $HOME/.h3) para autenticar na API da Horizon3.ai e estabelecer uma sessão (temporária). O token de sessão (um JWT) é armazenado em cache em $HOME/.h3. O token de sessão expira após 1 hora; nesse momento, o h3-cli reautenticará e restabelecerá automaticamente uma sessão.

Você pode autenticar explicitamente usando o seguinte comando:

O comando acima exibirá o token de sessão (e também o armazenará em cache em $HOME/.h3). Se você já tiver um token de sessão estabelecido (não expirado), h3 auth continuará usando esse token de sessão em vez de reautenticar.

Se você quiser forçar o h3-cli a reautenticar, use a opção force:

Perfis do h3-cli

Você pode gerenciar vários perfis de autenticação do h3-cli no mesmo diretório $HOME/.h3. Cada perfil do h3-cli tem sua própria chave de API.

Quando você instalou o h3-cli pela primeira vez, ele criou automaticamente um perfil inicial chamado default com a chave de API que você forneceu ao install.sh.

Se desejar criar outro perfil com uma chave de API diferente, use o seguinte comando:

Isso criará um perfil chamado my-profile em $HOME/.h3 para o {api_key} fornecido. Para ativar o perfil na sua sessão de shell atual, use o seguinte comando (observe o ponto . inicial):

Você pode verificar o perfil atualmente ativo usando h3 profile e visualizar detalhes sobre sua chave de API usando h3 whoami:

Você pode salvar várias chaves de API em diferentes perfis do h3-cli e alternar entre eles conforme necessário usando o comando acima. Por exemplo, para voltar ao perfil default:

Para visualizar a lista de perfis do h3-cli no diretório $HOME/.h3:

Você pode excluir um perfil do diretório $HOME/.h3 usando:

Isso removerá o perfil chamado {name} e sua chave de API do diretório $HOME/.h3 na máquina local. Observe que isso NÃO revoga a chave de API; apenas a exclui da máquina local. Você pode revogar a chave de API pelo Portal.

Executando pentests com o h3-cli

Esta seção contém exemplos adicionais para executar pentests usando o h3-cli.

A maneira mais simples de provisionar um pentest é usar o op template padrão e o Intelligent Scope:

Para provisionar um pentest E iniciar o NodeZero na máquina local (apenas para pentests internos):

Observe que isso se aplica apenas a pentests internos. Para pentests externos, o NodeZero é iniciado automaticamente para você na nuvem H3 como parte do h3 run-pentest.

Se você executar h3 run-pentest-and-nodezero para um pentest externo, ele simplesmente pulará a parte em que baixa e executa o NodeZero, pois isso é tratado automaticamente na nuvem H3.

Para executar um pentest usando um op template personalizado, especifique-o como um parâmetro para schedule_op_template.graphql:

Para executar um pentest usando o op template padrão, mas atribuir a ele um nome de sua escolha, use o parâmetro opcional op_name:

Para executar um pentest usando o op template padrão, mas especificar seu nome e escopo, use o parâmetro opcional schedule_op_form:

Observe que h3 run-pentest e h3 run-pentest-and-nodezero aceitam todos os mesmos parâmetros opcionais.

Para executar um pentest e atribuí-lo a um NodeZero Runner chamado my-nodezero-runner:

Executando pentests externos

Se você tiver um op template configurado para seu pentest externo:

Se você NÃO tiver um op template, poderá executar um pentest externo primeiro consultando o uuid do seu Asset Group por meio de h3 asset-groups:

Em seguida, use o comando abaixo para executar um pentest externo contra esse Asset Group. Substitua o uuid do seu Asset Group por {your-asset-group-uuid}:

Desenvolvido com GraphQL

A API da Horizon3.ai é desenvolvida com GraphQL. Além deste documento da CLI, a documentação relevante inclui:

• Documentação da Horizon3.ai
• GraphQL.org

Avançado: Escrevendo suas próprias consultas GraphQL

O h3-cli fornece um mecanismo simples para executar suas próprias consultas GraphQL. Primeiro, defina a consulta GraphQL em um arquivo (normalmente com extensão .graphql, embora isso não seja obrigatório). Em seguida, passe o arquivo para h3 gql:

Por exemplo, defina o seguinte em um arquivo chamado my_session.graphql:

Em seguida, execute:

Você deve ver a resposta JSON bruta do servidor GraphQL. Você pode imprimir a resposta JSON de forma formatada usando o jq:

Importante! Você deve especificar o caminho para o arquivo graphql (completo ou relativo, por exemplo, ./my_session.graphql em vez de apenas my_session.graphql), caso contrário, você corre o risco de colidir com arquivos graphql que o h3-cli usa internamente.

Avançado: Consultas GraphQL parametrizadas

As consultas GraphQL também podem definir parâmetros, que são passados para h3 gql como um objeto JSON.

Por exemplo, defina o seguinte em um arquivo chamado my_pentest.graphql:

Neste exemplo, $op_id é um parâmetro que deve ser fornecido para executar a consulta. O parâmetro é passado para a consulta dentro de um objeto JSON:

Substitua your-op-id-here por um op_id real.