horizon3ai/h3-cliFerramenta de linha de comando para a API do Horizon3.ai
O NodeZero MCP Server agora está disponível, permitindo que você execute e gerencie um MCP Server hospedado localmente que traz os recursos Find, Fix, Verify (FFV) da NodeZero diretamente para seus fluxos de trabalho de desenvolvimento e segurança.
O h3-cli é uma CLI conveniente (interface de linha de comando) para acessar a API da Horizon3.ai. A API da Horizon3.ai fornece acesso programático a um subconjunto da funcionalidade disponível por meio do Portal Horizon3.ai. Em um nível alto, a API permite que você:
A API pode ser usada para vários casos de uso, como agendar avaliações periódicas do seu ambiente ou iniciar um pentest como parte de um pipeline de integração contínua.
As etapas abaixo farão você começar rapidamente com o h3-cli. Estas instruções foram testadas em máquinas macOS e Linux e, em geral, devem funcionar em qualquer sistema compatível com POSIX com suporte ao bash.
Se você planeja executar pentests internos usando o h3-cli, instale o h3-cli no mesmo Docker Host em que você inicia o NodeZero.
Presume-se que você já tenha uma conta na Horizon3.ai. Caso contrário, cadastre-se em https://portal.horizon3ai.com/.
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:
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.
Instale o repositório git do h3-cli em sua máquina executando o seguinte comando git em uma sessão de shell/terminal.
git clone https://github.com/horizon3ai/h3-cli
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.
Execute os seguintes comandos para instalar e configurar o h3-cli. Substitua your-api-key-here pela sua chave de API real.
cd h3-cli
bash install.sh your-api-key-here
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:
h3
Se tudo estiver instalado corretamente, você verá o texto de ajuda do 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.
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.
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/):
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
Se você usou git clone para instalar o repositório, basta executar git pull para instalar a versão mais recente.
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).
A partir de junho de 2023, você pode visualizar sua versão atual do h3-cli por meio de:
h3 version
Você pode visualizar o histórico completo de versões e notas de versão por meio de:
h3 version -v
Execute o seguinte comando para verificar a conectividade com a API.
h3 hello-world
Você deve ver a resposta:
{
"data": {
"hello": "world!"
}
}
❗️ Se você estiver recebendo uma resposta de erro, entre em contato com a H3 pelo ícone de chat no Portal Horizon3.ai.
O comando abaixo retornará a lista de pentests da sua conta, do mais recente para o mais antigo.
h3 pentests
Para filtrar os pentests que correspondem a um termo de pesquisa específico, passe o termo de pesquisa como parâmetro:
h3 pentests sample
Para consultar o pentest mais recente da sua conta:
h3 pentest
Para consultar qualquer pentest da sua conta, passe o op_id do pentest como parâmetro:
h3 pentest your-op-id-here
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.