NodeZero MCP Server

Теперь доступен NodeZero MCP Server, позволяющий запускать и управлять локально размещённым MCP-сервером, который привносит возможности Find, Fix, Verify (FFV) от NodeZero непосредственно в ваши рабочие процессы разработки и безопасности.

MCP Readme

h3-cli: CLI-инструмент для Horizon3.ai API

h3-cli — это удобный CLI (интерфейс командной строки) для доступа к API Horizon3.ai. API Horizon3.ai предоставляет программный доступ к подмножеству функций, доступных через портал Horizon3.ai. В целом API позволяет вам:

планировать автономный пентест
загружать и запускать NodeZero™
отслеживать статус пентеста во время его выполнения
получать отчёт о пентесте после его завершения

API можно использовать для различных сценариев, например для планирования периодических оценок вашей среды или запуска пентеста в рамках конвейера непрерывной интеграции.

Установка и первоначальная настройка

Шаги, описанные ниже, помогут вам быстро начать работу с h3-cli. Эти инструкции были проверены на машинах с macOS и Linux и, как правило, должны работать в любой POSIX-совместимой системе с поддержкой bash.

Если вы планируете запускать внутренние пентесты с помощью h3-cli, установите h3-cli на тот же Docker-хост, где вы запускаете NodeZero.

Предполагается, что у вас уже есть учётная запись Horizon3.ai. Если нет, зарегистрируйтесь на https://portal.horizon3ai.com/.

1. Создание API-ключа

Для доступа к H3 API требуется API-ключ. Вы можете создать его на портале в меню Пользователь -> Настройки учётной записи.

При создании API-ключа вы должны назначить ему роль, определяющую его разрешения. Доступны следующие роли:

User (Пользователь): базовые разрешения на чтение и запись. API-ключ может запускать пентесты и читать результаты.
Read-only (Только чтение): API-ключ может читать результаты пентестов, но не может запускать пентесты.
NodeZero Runner: специализированная, строго ограниченная роль, предназначенная специально для NodeZero Runners.

Мы рекомендуем роль User, если вы тестируете h3-cli и хотите поэкспериментировать со всеми его функциями. После этого вы, возможно, захотите использовать более строгие разрешения в зависимости от вашего сценария. Например, если вы хотите использовать h3-cli только для настройки NodeZero Runner, мы рекомендуем роль NodeZero Runner.

Вы можете легко управлять несколькими API-ключами в одной установке h3-cli. Подробнее здесь.

❗ Храните свой API-ключ в безопасности: любой, у кого есть ваш API-ключ, может получить доступ к вашей учётной записи H3. Относитесь к API-ключу как к комбинации «имя пользователя + пароль». Любой, у кого есть API-ключ, может получить доступ к вашей учётной записи откуда угодно. h3-cli будет хранить ваш API-ключ в каталоге $HOME/.h3. Этот каталог создаётся во время установки и настраивается с такими правами доступа, что только вы можете читать или записывать в него.

2. Установка h3-cli

Установите git-репозиторий h3-cli на свою машину, выполнив следующую команду git в сеансе оболочки/терминала.

git clone https://github.com/horizon3ai/h3-cli

Эта команда создаст новый каталог h3-cli и загрузит в него содержимое репозитория. Каталог h3-cli будет создан в том каталоге, где вы выполняете команду git. Вы можете установить h3-cli в любом месте файловой системы.

Если у вас нет git, вы можете скачать репозиторий в виде zip-архива из меню выше и распаковать его в любом месте файловой системы.

3. Запуск сценария установки h3-cli

Выполните следующие команды, чтобы установить и настроить 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-cli. Обновите вашу установку, используя один из способов ниже.

Вариант 1: с помощью команды `h3 upgrade` (рекомендуется)

Начиная с июня 2023 года вы можете использовать команду h3 upgrade для обновления до последней версии h3-cli.

Если вы получаете сообщение ERROR: unrecognized command: "upgrade", значит, вы используете предыдущую версию h3-cli, которая не поддерживает команду upgrade. Используйте один из способов ниже для обновления h3-cli.

Вариант 2: с помощью `easy_install.sh` (рекомендуется, если `h3 upgrade` недоступен)

Выполните эту команду из родительского каталога h3-cli (т.е. каталога, который содержит каталог h3-cli/):

curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash

Вариант 3: через git

Если вы использовали git clone для установки репозитория, просто выполните git pull, чтобы установить последнюю версию.

Вариант 4: через загрузку zip-архива

Если вы скачали репозиторий в виде zip-файла, скачайте zip-файл заново и распакуйте его в то же место (другими словами, замените существующую установку h3-cli новым zip-архивом).

Проверка текущей версии

Начиная с июня 2023 года вы можете просмотреть текущую версию h3-cli с помощью:

h3 version

Полную историю версий и примечания к выпускам можно просмотреть с помощью:

h3 version -v

Начало работы

1. Проверка подключения к API

Выполните следующую команду, чтобы проверить подключение к API.

h3 hello-world

Вы должны увидеть ответ:

{
  "data": {
    "hello": "world!"
  }
}

❗️ Если вы получаете ответ с ошибкой, свяжитесь с H3 через значок чата на портале Horizon3.ai.

2. Запрос списка пентестов в вашей учётной записи

Приведённая ниже команда вернёт список пентестов в вашей учётной записи, начиная с самого последнего.

h3 pentests

Чтобы отфильтровать пентесты по заданному поисковому запросу, передайте поисковый запрос в качестве параметра:

h3 pentests sample

3. Запрос конкретного пентеста из вашей учётной записи

Чтобы запросить самый последний пентест в вашей учётной записи:

h3 pentest

Чтобы запросить любой пентест в вашей учётной записи, передайте op_id пентеста в качестве параметра:

h3 pentest your-op-id-here

Некоторые команды h3-cli будут использовать самый последний пентест по умолчанию, если не передан параметр op_id.

Термины «op» и «pentest» часто используются как взаимозаменяемые.

4. Запуск пентеста

Для запуска пентеста необходимо указать шаблон операции (op template). Шаблон операции задаёт полную конфигурацию пентеста, которая включает область действия, параметры атаки и другие (необязательные) настройки.

Horizon3.ai предоставляет новым пользователям шаблон операции по умолчанию с именем Default 1 - Recommended. Этот шаблон всегда актуален и содержит наши последние параметры атаки и рекомендуемую конфигурацию. Шаблон по умолчанию не определяет область действия, и в этом случае NodeZero будет использовать Intelligent Scope — подсеть хоста NodeZero обеспечит начальную область действия, и она будет органически расширяться во время пентеста по мере обнаружения новых хостов и подсетей. Дополнительную информацию об Intelligent Scope и других вариантах развёртывания см. в нашей документации по продукту.

Для опытных пользователей пользовательские шаблоны операций могут быть созданы через портал Horizon3.ai. Чтобы создать пользовательский шаблон операции, пройдите по модальному окну Run a Pentest, пока не увидите возможность настроить конфигурацию пентеста. Шаблон операции можно создать, фактически не запуская пентест.

Чтобы создать пентест с использованием шаблона операции по умолчанию и Intelligent Scope:

h3 run-pentest

JSON-ответ содержит сведения о только что созданном пентесте. Вы можете убедиться, что пентест создаётся, проверив портал Horizon3.ai, или выполнив h3 pentest.

Существует несколько способов указать дополнительные параметры при создании пентестов. Дополнительную информацию см. в дополнительных примерах здесь.

❗ ПОДОЖДИТЕ! ВЫ ЕЩЁ НЕ ЗАКОНЧИЛИ!

Для внутренних пентестов (которые используются по умолчанию) перед началом выполнения пентеста требуются дополнительные шаги. См. следующий раздел о загрузке и запуске NodeZero, чтобы завершить инициализацию вашего пентеста.

Если вы выполняете внешний пентест, NodeZero запускается за вас автоматически в облаке H3 в рамках h3 run-pentest, в этом случае с вашей стороны не требуется дополнительных шагов для запуска пентеста.

5. Запуск NodeZero

❗ ️Следующий шаг применим только к внутренним пентестам; для внешних пентестов NodeZero запускается за вас автоматически в облаке H3.

После создания внутреннего пентеста вам необходимо запустить наш контейнер NodeZero на Docker-хосте внутри вашей сети. Это делается путём запуска сценария запуска NodeZero (NodeZero Launch Script) на вашем Docker-хосте.

Чтобы запустить сценарий запуска NodeZero для вашего самого последнего созданного пентеста:

h3 run-nodezero

ВАШ ПЕНТЕСТ ЗАПУЩЕН! Если все команды были выполнены без ошибок, вы успешно создали и запустили свой пентест. Вы должны увидеть в консоли вывод, регистрируемый сценарием запуска NodeZero. Сначала сценарий проверит совместимость вашей системы с NodeZero, а затем загрузит и запустит его. Когда пентест завершится, NodeZero автоматически завершит свою работу.

NodeZero — это Docker-контейнер. Вы можете просмотреть его с помощью docker ps. Имя контейнера будет иметь вид n0-xxxx.

6. Загрузка отчётов о пентестах

После завершения пентеста используйте следующую команду, чтобы загрузить zip-файл, содержащий все отчёты в форматах PDF и CSV для самого последнего созданного пентеста:

h3 pentest-reports

Приведённая выше команда загрузит zip-файл в pentest-reports-{op_id}.zip в текущий каталог.

Варианты использования

Автоматическое развёртывание NodeZero с помощью NodeZero Runner. Узнайте, как использовать NodeZero Runner для автоматического развёртывания NodeZero на вашем Docker-хосте без необходимости вручную копировать и вставлять сценарий запуска NodeZero.
Автоматическое планирование. Узнайте, как автоматически запускать пентесты по регулярному расписанию, например раз в неделю или раз в месяц.
Автоматически внедряемые учётные данные. Узнайте, как автоматически внедрять учётные данные в регулярно планируемый пентест с помощью NodeZero Runner.
Мониторинг пентестов. Узнайте, как отслеживать пентесты с помощью h3-cli.
Постраничный вывод результатов. Узнайте, как выполнять постраничный просмотр больших наборов результатов с помощью h3-cli.
Разбор JSON с помощью jq. Узнайте, как использовать возможности jq для разбора JSON-ответов от h3-cli. jq может извлекать отдельные поля, выводить структуру ответа и даже преобразовывать JSON-ответ в CSV.

Аутентификация и профили h3-cli

Аутентификация происходит незаметно и автоматически при вызове команды h3. Вам не нужно предпринимать никаких явных действий для аутентификации. В этом разделе описаны лежащие в основе механизмы.

h3-cli считывает ваш H3_API_KEY из вашего профиля h3-cli (в $HOME/.h3) для аутентификации в API Horizon3.ai и установления (временного) сеанса. Маркер сеанса (JWT) кэшируется в $HOME/.h3. Маркер сеанса истекает через 1 час, после чего h3-cli автоматически выполнит повторную аутентификацию и восстановит сеанс.

Вы можете выполнить явную аутентификацию с помощью следующей команды:

h3 auth

Приведённая выше команда выведет маркер сеанса (а также закэширует его в $HOME/.h3). Если у вас уже есть установленный (не истёкший) маркер сеанса, h3 auth продолжит использовать этот маркер сеанса, а не выполнит повторную аутентификацию.

Если вы хотите принудительно заставить h3-cli выполнить повторную аутентификацию, используйте параметр force:

h3 auth force

Профили h3-cli

Вы можете управлять несколькими профилями аутентификации h3-cli в одном каталоге $HOME/.h3. Каждый профиль h3-cli имеет собственный API-ключ.

При первой установке h3-cli автоматически создаст исходный профиль с именем default, используя API-ключ, который вы указали в install.sh.

Если вы хотите создать другой профиль с другим API-ключом, используйте следующую команду:

h3 save-profile my-profile {api-key}

Это создаст профиль с именем my-profile в $HOME/.h3 для указанного {api_key}. Чтобы активировать профиль в текущем сеансе оболочки, используйте следующую команду (обратите внимание на ведущую точку .):

. h3 profile my-profile

Вы можете проверить текущий активный профиль с помощью h3 profile, а просмотреть сведения о его API-ключе с помощью h3 whoami:

h3 profile
h3 whoami

Вы можете сохранить несколько API-ключей в разных профилях h3-cli и переключаться между ними по мере необходимости с помощью указанной выше команды. Например, чтобы переключиться обратно на профиль default:

. h3 profile default

Чтобы просмотреть список профилей h3-cli в вашем каталоге $HOME/.h3:

h3 profiles

Вы можете удалить профиль из вашего каталога $HOME/.h3 с помощью:

h3 delete-profile {name}

Это удалит профиль с именем {name} и его API-ключ из вашего каталога $HOME/.h3 на локальной машине. Обратите внимание, что это НЕ отзывает API-ключ; он только удаляется с локальной машины. Вы можете отозвать API-ключ на портале.

Запуск пентестов с помощью h3-cli

В этом разделе приведены дополнительные примеры запуска пентестов с помощью h3-cli.

Самый простой способ создать пентест — использовать шаблон операции по умолчанию и Intelligent Scope:

h3 run-pentest

Чтобы создать пентест И запустить NodeZero на локальной машине (только для внутренних пентестов):

h3 run-pentest-and-nodezero

Обратите внимание, что это применимо только к внутренним пентестам. Для внешних пентестов NodeZero запускается за вас автоматически в облаке H3 в рамках h3 run-pentest.

Если вы случайно выполните h3 run-pentest-and-nodezero для внешнего пентеста, он просто пропустит часть, где загружается и запускается NodeZero, поскольку это обрабатывается автоматически в облаке H3.

Чтобы запустить пентест с использованием пользовательского шаблона операции, укажите его в качестве параметра в schedule_op_template.graphql:

h3 run-pentest '{"op_template_name":"your-op-template-here"}'

Чтобы запустить пентест с использованием шаблона операции по умолчанию, но присвоить ему имя на ваш выбор, используйте необязательный параметр op_name:

h3 run-pentest '{"op_name":"your-op-name-here"}'

Чтобы запустить пентест с использованием шаблона операции по умолчанию, но указать его имя и область действия, используйте необязательный параметр schedule_op_form:

h3 run-pentest '{"schedule_op_form":{"op_name":"your-op-name-here", "op_param_max_scope": "192.168.0.0/24"}}'

Обратите внимание, что h3 run-pentest и h3 run-pentest-and-nodezero принимают все те же необязательные параметры.

Чтобы запустить пентест и назначить его NodeZero Runner с именем my-nodezero-runner:

h3 run-pentest '{"schedule_op_form":{"op_name":"Pentest created via h3-cli and launched via runner", "runner_name":"my-nodezero-runner"}}'

Запуск внешних пентестов

Если у вас есть шаблон операции, настроенный для вашего внешнего пентеста:

h3 run-pentest '{"op_template_name":"your-op-template-here"}'

Если у вас НЕТ шаблона операции, вы можете запустить внешний пентест, предварительно найдя uuid вашей группы ресурсов (Asset Group) с помощью h3 asset-groups:

h3 asset-groups

Затем используйте приведённую ниже команду, чтобы запустить внешний пентест против этой группы ресурсов. Замените uuid вашей группы ресурсов на {your-asset-group-uuid}:

h3 run-pentest '{"schedule_op_form": {"op_type": "ExternalAttack", "asset_group_uuid": "{your-asset-group-uuid}"}}'

На базе GraphQL

API Horizon3.ai работает на базе GraphQL. В дополнение к этому документу CLI соответствующая документация включает:

Дополнительно: написание собственных GraphQL-запросов

h3-cli предоставляет простой механизм для выполнения собственных GraphQL-запросов. Сначала вы определяете GraphQL-запрос в файле (обычно с расширением .graphql, хотя это необязательно). Затем передайте файл команде h3 gql:

h3 gql {your-query-file}

Например, определите следующее в файле с именем my_session.graphql:

query {
    session_user_account {
        email
        name
        company_name
    }
}

Затем выполните:

h3 gql ./my_session.graphql

Вы должны увидеть исходный JSON-ответ от GraphQL-сервера. Вы можете красиво отформатировать JSON-ответ с помощью jq:

h3 gql ./my_session.graphql | jq .

Важно! Необходимо указать путь к graphql-файлу (полный или относительный, например ./my_session.graphql, а не просто my_session.graphql), в противном случае вы рискуете создать конфликт с graphql-файлами, которые h3-cli использует внутри себя.

Дополнительно: параметризованные GraphQL-запросы

GraphQL-запросы также могут определять параметры, которые передаются в h3 gql в виде JSON-объекта.

Например, определите следующее в файле с именем my_pentest.graphql:

query q($op_id: String!) {
    pentest(op_id:$op_id) {
        op_id
        name
        state
    }
}

В этом примере $op_id — это параметр, который необходимо указать для выполнения запроса. Параметр передаётся в запрос в составе JSON-объекта:

h3 gql ./my_pentest.graphql '{"op_id":"your-op-id-here"}' | jq .

Замените your-op-id-here на фактический op_id.

h3-cli

Популярное