HexStrike AI — Docker + Remote MCP

Docker-образ HexStrike AI на базе linuxserver.io Kali, с новым удалённым MCP-сервером на streamable-HTTP, чтобы весь набор инструментов HexStrike можно было использовать по сети (например, из Claude Code), а не только из локального stdio-клиента.

[!WARNING] Это открывает удалённое выполнение инструментов offensive security по сети. Клиент, подключённый к MCP-эндпоинту, может фактически выполнять удалённые команды через весь арсенал инструментов контейнера. Прочтите раздел Безопасность, прежде чем запускать это где-либо, кроме изолированной лаборатории. Всегда задавайте HEXSTRIKE_MCP_TOKEN, запускайте только в доверенной/изолированной сети или через VPN и тестируйте только те системы, на которые у вас есть явное разрешение.

[!NOTE] Готовый образ не публикуется. Поскольку полный набор инструментов Kali делает образ большим (>10 ГБ — примерно ~17 ГБ в собранном виде), он не публикуется в Docker Hub или любом другом реестре. Вы собираете его сами из этого репозитория (см. Быстрый старт); убедитесь, что на Docker-хосте достаточно свободного места.

Содержание

• Возможности

• Обзор

• Архитектура

• Порты

• Быстрый старт

• Подключение из Claude Code

• Переменные окружения

• Постоянное хранение

• Веб-доступ к рабочему столу

• Проверка здоровья

• Безопасность

• Покрытие инструментов

• Обновление закреплённой версии upstream

• Авторы и лицензия

Related MCP server: Pentest MCP

Возможности

• Полный набор инструментов HexStrike AI из upstream — более 150 инструментов безопасности, управляемых через его Flask API, — предустановлен на образе на базе Kali, без ручной настройки окружения.

• Новое: hexstrike_mcp_http.py — streamable-HTTP MCP-сервер, который предоставляет все определения @mcp.tool() из upstream по сети на порту 8889 (путь /mcp), так что им можно управлять удалённо, а не только через локальный stdio.

• Необязательная аутентификация по bearer-токену для защиты MCP-эндпоинта.

• Доступный через браузер рабочий стол KDE (Selkies/KasmVNC, унаследован от базового образа) для интерактивной работы наряду с автоматическим запуском инструментов.

• Супервизор процессов s6-overlay v3 с явным порядком запуска служб — служба MCP ожидает, пока API-сервер HexStrike будет определён как зависимость.

• Постоянный том /config: виртуальные окружения для каждого инструмента и состояние файлового менеджера сохраняются после перезапуска контейнера.

• Воспроизводимая сборка: uv управляет окружением Python, а исходники upstream загружаются по закреплённому коммиту git, а не включаются в репозиторий.

Обзор

HexStrike AI из upstream поставляет две точки входа на Python:

• hexstrike_server.py — Flask API-сервер, слушающий порт 8888, который выполняет более 150 внешних инструментов безопасности через subprocess и отдаёт их результаты по HTTP (включая эндпоинт /health, сообщающий о доступности инструментов).

• hexstrike_mcp.py — сервер FastMCP, который преобразует вызовы MCP-инструментов в HTTP-запросы к указанному выше API-серверу. Upstream запускает его только через транспорт stdio, поэтому им может управлять только MCP-клиент на той же машине, что и контейнер.

Этот репозиторий добавляет hexstrike_mcp_http.py, который импортирует модуль hexstrike_mcp.py из upstream и целиком переиспользует его функцию setup_mcp_server() — все определения инструментов без изменений — но обслуживает их через MCP-транспорт streamable-HTTP на порту 8889 по пути /mcp вместо stdio. Это единственное функциональное отличие: та же поверхность инструментов, доступная удалённо (например, из Claude Code, работающего на другой машине), а не только из процесса, запущенного рядом.

uv (Astral) управляет интерпретатором Python и окружением зависимостей и используется для запуска обоих процессов при старте контейнера.

Архитектура

• Базовый образ: lscr.io/linuxserver/kali-linux:latest, который предоставляет доступный через браузер рабочий стол KDE (Selkies/KasmVNC) на портах 3000 (HTTP) и 3001 (HTTPS), репозитории apt Kali-rolling и инициализацию s6-overlay v3.

• Добавленные службы: две службы longrun из s6-overlay добавлены поверх системы инициализации базового образа и зарегистрированы в наборе служб user:

  • root/etc/s6-overlay/s6-rc.d/hexstrike-server — запускает uv run --no-sync python hexstrike_server.py --port 8888 от имени пользователя abc.

  • root/etc/s6-overlay/s6-rc.d/hexstrike-mcp — запускает uv run --no-sync python hexstrike_mcp_http.py --server http://127.0.0.1:8888 --host 0.0.0.0 --port 8889 от имени пользователя abc. Его запись dependencies.d/hexstrike-server задаёт запуск после API-сервера.

• Исходники upstream не включаются в репозиторий. Dockerfile выполняет git clone репозитория 0x4m4/hexstrike-ai во время сборки и переключается на закреплённый коммит (ARG HEXSTRIKE_REF, по умолчанию d689933ff579d839c676c82b231f8e98326c5f04), копируя только hexstrike_server.py, hexstrike_mcp.py и hexstrike-ai-mcp.json в /app. Это сохраняет репозиторий небольшим, а обновление upstream сводится к изменению одной строки.

• Окружение Python: управляемый uv CPython 3.12 (закреплён через .python-version), зависимости из pyproject.toml устанавливаются в /app/.venv через uv sync --no-dev во время сборки.

• Инициализация постоянного хранения: root/custom-cont-init.d/10-hexstrike-persist запускается от имени root до запуска служб longrun (см. Постоянное хранение).

Порты

Быстрый старт

Docker Compose (рекомендуется)

Вся конфигурация находится непосредственно в docker-compose.yml — файла .env нет. Перед первым запуском отредактируйте блок environment: и задайте:

• HEXSTRIKE_MCP_TOKEN — bearer-токен для MCP-эндпоинта. Сгенерируйте надёжное значение с помощью openssl rand -hex 32 и вставьте его (или оставьте пустым для открытого эндпоинта — только для лаборатории/CTF в изолированной сети).

• CUSTOM_USER / PASSWORD — логин и пароль для базовой аутентификации веб-рабочего стола.

Затем соберите и запустите:

# generate a token to paste into docker-compose.yml:
openssl rand -hex 32

docker compose up -d --build

Сборка большая и медленная, и готового образа для загрузки нет — результирующий образ >10 ГБ (~17 ГБ), поэтому он не публикуется ни в каком реестре и должен собираться локально. Он устанавливает метапакет kali-linux-headless плюс длинный список именованных инструментов, компилирует колёса angr / pwntools (отсюда build-essential и заголовочные файлы разработчика в образе), собирает три инструмента на Go из исходников и загружает пакет релиза rustscan. Ожидайте, что первая сборка займёт значительное время и потребует много свободного места (закладывайте ~20 ГБ+ запаса, больше при итерациях).

Обычный Docker

docker build -t hexstrike-ai:local .

docker run -d \
  --name hexstrike-ai \
  --cap-add=NET_RAW --cap-add=NET_ADMIN \
  --shm-size=1g \
  -p 3000:3000 -p 3001:3001 -p 8888:8888 -p 8889:8889 \
  -v "$(pwd)/config:/config" \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e CUSTOM_USER=kali \
  -e PASSWORD=changeme \
  -e HEXSTRIKE_MCP_TOKEN="$(openssl rand -hex 32)" \
  hexstrike-ai:local

--cap-add=NET_RAW --cap-add=NET_ADMIN и --shm-size=1g обязательны — см. Безопасность и комментарии в docker-compose.yml.

Подключение из Claude Code

Когда контейнер запущен, укажите Claude Code MCP-эндпоинт на порту 8889. Если задан HEXSTRIKE_MCP_TOKEN (настоятельно рекомендуется — см. Безопасность), каждый запрос должен включать соответствующий заголовок Authorization: Bearer <token>; эндпоинт принимает неаутентифицированные запросы только в том случае, если токен не задан.

Конфигурация MCP для проекта/пользователя (.mcp.json или настройки Claude Code):

{
  "mcpServers": {
    "hexstrike-ai": {
      "type": "http",
      "url": "http://<HOST>:8889/mcp",
      "headers": { "Authorization": "Bearer <HEXSTRIKE_MCP_TOKEN>" }
    }
  }
}

Или через CLI:

claude mcp add --transport http hexstrike-ai http://<HOST>:8889/mcp \
  --header "Authorization: Bearer <TOKEN>"

Замените <HOST> на адрес/имя хоста контейнера, а <HEXSTRIKE_MCP_TOKEN> / <TOKEN> — на значение, которое вы сгенерировали выше. Если вы намеренно оставили HEXSTRIKE_MCP_TOKEN пустым, опустите аргумент headers / --header — в этом случае эндпоинт открыт.

Invalid Host header / HTTP 421? Транспорт MCP streamable-HTTP имеет встроенную защиту от DNS-rebinding, которая по умолчанию доверяет только заголовку Host со значением localhost. Этот образ отключает эту проверку по умолчанию, чтобы вы могли обращаться к эндпоинту по LAN через IP или имя хоста. Если вы всё же видите эту ошибку, либо обновитесь до этого образа (по умолчанию он уже обрабатывает это), либо задайте HEXSTRIKE_MCP_ALLOWED_HOSTS с точным значением(ями) host:port, которые отправляют ваши клиенты.

Переменные окружения

hexstrike_mcp_http.py также принимает переопределения --server / HEXSTRIKE_SERVER_URL, --path / HEXSTRIKE_MCP_PATH, --timeout / HEXSTRIKE_TIMEOUT и --allowed-hosts / HEXSTRIKE_MCP_ALLOWED_HOSTS. Поставляемый s6 run-скрипт передаёт только --server, --host и --port; остальные читаются из своих env-фолбэков (поэтому HEXSTRIKE_MCP_ALLOWED_HOSTS работает при задании на контейнере) или сохраняют встроенные значения по умолчанию (/mcp, стандартный таймаут запроса вышестоящего проекта и отключённая проверка Host).

Постоянное хранение (Persistence)

Том /config — это домашний каталог по соглашению linuxserver и единственный путь, который переживает пересоздание контейнера. Cont-init-скрипт root/custom-cont-init.d/10-hexstrike-persist выполняется от root перед запуском longrun-сервисов и:

1. Создаёт /config/hexstrike/envs, /config/hexstrike/files и /config/hexstrike/output.

2. Заменяет жёстко заданные вышестоящим проектом пути /tmp/hexstrike_envs и /tmp/hexstrike_files символическими ссылками на /config/hexstrike/envs и /config/hexstrike/files соответственно, чтобы создаваемые по требованию Python-виртуальные окружения для каждого инструмента HexStrike и область чтения/записи файлового менеджера переживали перезапуски контейнера.

3. Выполняет chown постоянного дерева на abc:abc (с учётом PUID/PGID) через lsiown.

Динамические каталоги /tmp/<tool>_output, создаваемые отдельными запусками инструментов, не связываются символическими ссылками и остаются эфемерными — явно укажите конкретному инструменту путь /config/hexstrike/output, если нужно, чтобы его вывод пережил перезапуск.

Доступ к веб-рабочему столу

Откройте https://<HOST>:3001/ в браузере и войдите с учётными данными CUSTOM_USER / PASSWORD, настроенными выше (HTTP-рабочий стол также доступен на порту 3000 без TLS).

Проверка работоспособности (Health Check)

curl http://<HOST>:8888/health

Возвращает JSON от API-сервера HexStrike со списком инструментов, которые были обнаружены как доступные на PATH внутри контейнера.

Безопасность

[!WARNING] Конечная точка MCP на 8889 позволяет подключённому клиенту автономно управлять выполнением инструментов атакующего тестирования внутри контейнера — по сути это удалённое выполнение команд by design, ограниченное только тем bearer-токеном, который вы настроите.

• Всегда задавайте HEXSTRIKE_MCP_TOKEN. Сгенерируйте его с помощью openssl rand -hex 32 и храните в секрете. Пустое значение делает конечную точку MCP неаутентифицированной.

• Открывайте доступ только через доверенную/изолированную сеть или VPN. Не публикуйте порт 8889 (или 8888) в открытый интернет.

• Атакуйте только те системы, на тестирование которых у вас есть явное разрешение. В контейнере поставляются реальные инструменты атакующего тестирования, способные на активное сканирование, эксплуатацию, атаки на учётные данные и многое другое.

• Контейнеру выданы capabilities NET_RAW и NET_ADMIN (см. docker-compose.yml / пример docker run), поскольку нескольким инструментам — SYN-сканам nmap, masscan, responder и т. д. — нужны raw-сокеты. Это уже, чем --privileged, но всё же существенно повышенные привилегии; выдавайте их только если вам нужны такие типы сканирования.

• Аутентификация реализована как минимальное ASGI-промежуточное ПО (BearerTokenASGIMiddleware в hexstrike_mcp_http.py), которое проверяет заголовок Authorization сравнением за константное время и отклоняет неаутентифицированные запросы к пути MCP с кодом 401 до того, как они достигнут MCP-приложения — оно не буферизует и иным образом не вмешивается в поток ответов streamable-HTTP/SSE.

Покрытие инструментами

Набор инструментов курируемый, а не исчерпывающий:

• Метапакет kali-linux-headless, плюс список инструментов, названных явно в Dockerfile (те, что проверяет конечная точка /health HexStrike, и распространённые утилиты разведки/веб/эксплуатации) — например, nmap, masscan, gobuster, feroxbuster, ffuf, dirb, dirsearch, nikto, sqlmap, wpscan, whatweb, wafw00f, hydra, john, hashcat, medusa, evil-winrm, amass, dnsenum, dnsrecon, fierce, theharvester, responder, nuclei, subfinder, httpx-toolkit, arjun, paramspider, hakrawler, getallurls (gau), netexec, enum4linux-ng, smbclient, seclists, wordlists, binwalk, foremost, steghide, exiftool, radare2 и gdb.

• Три инструмента на Go, собранные из исходников на этапе сборки, после чего из образа удаляется Go-тулчейн: katana, dalfox, waybackurls.

• rustscan, установленный из последнего GitHub-релиза (.deb поставляется внутри ассета rustscan.deb.zip, который сборка распаковывает перед установкой; best-effort — сборка продолжается без него, если ассет не удаётся разрешить).

Некоторые тяжёлые или лицензируемые инструменты, на которые ссылается вышестоящий проект HexStrike, — Ghidra, IDA, Burp Suite Pro, Maltego, Nessus и различные облачные/криминалистические утилиты — не установлены в этом образе, чтобы сборка оставалась выполнимой.

Фильтрация MCP-инструментов (меньше инструментов для модели)

Вышестоящий проект регистрирует ~150 MCP-инструментов. Это превышает лимит функций-инструментов некоторых провайдеров моделей (OpenAI ограничивает ~128) и выводит на поверхность инструменты, которые могут только завершиться ошибкой, поскольку их CLI-бинарник не установлен. Чтобы избежать этого, MCP-сервер скрывает любой инструмент, чей базовый бинарник отсутствует (проверяется через which при запуске, так как MCP-процесс работает в том же контейнере, что и инструменты). Типичная сборка открывает ~115 инструментов вместо 150. В логе запуска выводится количество и скрытый список.

Управление через переменные окружения на контейнере:

Обновление закреплённой версии вышестоящего проекта

Исходные репозитории клонируются во время сборки на коммите, указанном в ARG HEXSTRIKE_REF (Dockerfile). Чтобы подхватить новые изменения из апстрима, обновите этот пин и пересоберите:

docker build -t hexstrike-ai:local --build-arg HEXSTRIKE_REF=<new-sha> .

или, при использовании Compose, раскомментируйте и задайте запись args: HEXSTRIKE_REF: в ключе build: в docker-compose.yml и выполните docker compose up -d --build.

Авторство и лицензия

• HexStrike AI от 0x4m4 — платформа автоматизации безопасности, которую упаковывает этот образ, выпущена под лицензией MIT. Полные условия см. в файле LICENSE из апстрима.

• Образ kali-linux от linuxserver.io — базовый образ, предоставляющий окружение Kali и веб-рабочий стол.