horizon3ai/h3-cliCLI-инструмент для Horizon3.ai API
Теперь доступен NodeZero MCP Server, позволяющий запускать и управлять локально размещённым MCP-сервером, который привносит возможности Find, Fix, Verify (FFV) от NodeZero непосредственно в ваши рабочие процессы разработки и безопасности.
h3-cli — это удобный CLI (интерфейс командной строки) для доступа к API Horizon3.ai. API Horizon3.ai предоставляет программный доступ к подмножеству функций, доступных через портал Horizon3.ai. В целом API позволяет вам:
API можно использовать для различных сценариев, например для планирования периодических оценок вашей среды или запуска пентеста в рамках конвейера непрерывной интеграции.
Шаги, описанные ниже, помогут вам быстро начать работу с h3-cli. Эти инструкции были проверены на машинах с macOS и Linux и, как правило, должны работать в любой POSIX-совместимой системе с поддержкой bash.
Если вы планируете запускать внутренние пентесты с помощью h3-cli, установите h3-cli на тот же Docker-хост, где вы запускаете NodeZero.
Предполагается, что у вас уже есть учётная запись Horizon3.ai. Если нет, зарегистрируйтесь на https://portal.horizon3ai.com/.
Для доступа к H3 API требуется API-ключ. Вы можете создать его на портале в меню Пользователь -> Настройки учётной записи.
При создании API-ключа вы должны назначить ему роль, определяющую его разрешения. Доступны следующие роли:
Мы рекомендуем роль User, если вы тестируете h3-cli и хотите поэкспериментировать со всеми его функциями. После этого вы, возможно, захотите использовать более строгие разрешения в зависимости от вашего сценария. Например, если вы хотите использовать h3-cli только для настройки NodeZero Runner, мы рекомендуем роль NodeZero Runner.
Вы можете легко управлять несколькими API-ключами в одной установке h3-cli. Подробнее здесь.
❗ Храните свой API-ключ в безопасности: любой, у кого есть ваш API-ключ, может получить доступ к вашей учётной записи H3. Относитесь к API-ключу
как к комбинации «имя пользователя + пароль». Любой, у кого есть API-ключ, может получить доступ к вашей учётной записи откуда угодно. h3-cli
будет хранить ваш API-ключ в каталоге $HOME/.h3. Этот каталог создаётся во время установки и
настраивается с такими правами доступа, что только вы можете читать или записывать в него.
Установите git-репозиторий h3-cli на свою машину, выполнив следующую команду git в сеансе оболочки/терминала.
git clone https://github.com/horizon3ai/h3-cli
Эта команда создаст новый каталог h3-cli и загрузит в него содержимое репозитория. Каталог h3-cli
будет создан в том каталоге, где вы выполняете команду git. Вы можете установить h3-cli в любом месте файловой системы.
Если у вас нет git, вы можете скачать репозиторий в виде zip-архива из меню выше и распаковать его в любом месте файловой системы.
Выполните следующие команды, чтобы установить и настроить h3-cli. Замените your-api-key-here на ваш фактический API-ключ.
cd h3-cli
bash install.sh your-api-key-here
Сценарий установки установит зависимости (jq) и создаст ваш профиль h3-cli по умолчанию в каталоге $HOME/.h3.
Ваш API-ключ хранится в вашем профиле h3-cli. Права доступа к каталогу и профилю ограничены так, чтобы никакие другие
пользователи (кроме вас) не могли читать или записывать в них.
Сценарий установки попросит вас отредактировать ваш профиль оболочки ($HOME/.bash_profile или $HOME/.bash_login или $HOME/.profile, в зависимости
от вашей операционной системы), чтобы задать следующие переменные окружения:
H3_CLI_HOME: эта переменная окружения используется h3-cli для определения своего местоположения и вспомогательных файлов.PATH: эта переменная окружения задаёт каталоги, в которых выполняется поиск команд оболочки.После обновления профиля оболочки выполните повторный вход в систему или перезапустите сеанс оболочки, чтобы применить изменения профиля, затем проверьте, что вы можете вызвать h3, запустив его из командной строки:
h3
Если всё установлено правильно, вы увидите справочный текст h3-cli.
Мы каждый месяц выпускаем новые функции, исправления ошибок и другие обновления для h3-cli. Обновите вашу установку, используя один из способов ниже.
h3 upgrade (рекомендуется)Начиная с июня 2023 года вы можете использовать команду h3 upgrade для обновления до последней версии h3-cli.
Если вы получаете сообщение ERROR: unrecognized command: "upgrade", значит, вы используете предыдущую версию h3-cli, которая не поддерживает
команду upgrade. Используйте один из способов ниже для обновления h3-cli.
easy_install.sh (рекомендуется, если h3 upgrade недоступен)Выполните эту команду из родительского каталога h3-cli (т.е. каталога, который содержит каталог h3-cli/):
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
Если вы использовали git clone для установки репозитория, просто выполните git pull, чтобы установить последнюю версию.
Если вы скачали репозиторий в виде zip-файла, скачайте zip-файл заново и распакуйте его в то же место (другими словами, замените существующую установку h3-cli новым zip-архивом).
Начиная с июня 2023 года вы можете просмотреть текущую версию h3-cli с помощью:
h3 version
Полную историю версий и примечания к выпускам можно просмотреть с помощью:
h3 version -v
Выполните следующую команду, чтобы проверить подключение к API.
h3 hello-world
Вы должны увидеть ответ:
{
"data": {
"hello": "world!"
}
}
❗️ Если вы получаете ответ с ошибкой, свяжитесь с H3 через значок чата на портале Horizon3.ai.
Приведённая ниже команда вернёт список пентестов в вашей учётной записи, начиная с самого последнего.
h3 pentests
Чтобы отфильтровать пентесты по заданному поисковому запросу, передайте поисковый запрос в качестве параметра:
h3 pentests sample
Чтобы запросить самый последний пентест в вашей учётной записи:
h3 pentest
Чтобы запросить любой пентест в вашей учётной записи, передайте op_id пентеста в качестве параметра:
h3 pentest your-op-id-here
Некоторые команды h3-cli будут использовать самый последний пентест по умолчанию,
если не передан параметр op_id.
Термины «op» и «pentest» часто используются как взаимозаменяемые.