https://github.com/user-attachments/assets/ba467fae-a4c9-4f63-b2e6-3fc30fb023f3

🔐 GEMMA-by-GOOGLE — HALO

Полностью локальный автономный ИИ-агент для тестирования на проникновение — Gemma 4-12B управляет арсеналом из 42 инструментов через разведку, атаку и отчёты, предоставляемый как стандартный сервер Model Context Protocol (MCP). Без облака, без API-ключей.

Что делает · Инструменты · Архитектура · Стек · Быстрый старт · Журнал изменений · Вклад

HALO — это автономный агент безопасности, работающий в среде Linux под управлением локальной LLM — Gemma 4-12B (uncensored / abliterated), развёрнутой через LM Studio. Он планирует, проводит разведку, выстраивает цепочки атак на основе того, что находит, и самостоятельно пишет профессиональный отчёт о пентесте. Всё работает локально: без облака, без API-ключей, ничего не покидает вашу машину.

Одно слово запускает задание: engage.

Что делает

• 🔍 Автономная разведка — masscan + nmap для обнаружения открытых портов и сервисов

• ⚔️ Автономный цикл атак — выбирает и связывает инструменты на основе найденного

• 🌐 Конвейер «веб-разведка → атака» — перечисление от apex до URL (поддомены, хосты, исторические URL), поиск контента, сканирование по шаблонам и XSS, с автоматическим захватом флагов на веб-целях в стиле CTF

• ✅ Проверенные взломы, а не баннеры — каждая попытка содержит одноразовый вызов/nonce, который эксплойт должен вернуть из-внутри полученной оболочки; голый баннер uid=0 или тарпит не могут его подделать, поэтому подтверждённый взлом — настоящий (доказательства, полученные из выполнения, одноразовое использование на шлюзе)

• 🎯 Подобранная библиотека PoC — детерминированные, самоочевидные эксплойты (vsftpd 2.3.4, ingreslock, UnrealIRCd), запускаемые через изолированный примитив доставки, который возвращает настоящую оболочку, а не догадку

• 🧠 Постоянный кэш негативного опыта — учится на том, что не срабатывает, во всех сессиях и перестаёт тратить циклы на проверенные тупики

• 🧩 Адаптивное внедрение навыков — загружает релевантные сценарии атак в промпт в зависимости от текущей цели

• 📝 Автоматические HTML-отчёты — собирает результаты в фирменный отчёт при выходе

• 🔒 100% локально — Gemma 4-12B в LM Studio; ничего не покидает вашу машину

Related MCP server: Debugg AI MCP

Арсенал инструментов

42 инструмента работают в цикле принятия решений агента, все проходят через один и тот же слой кэширования ошибок. Они определены один раз в реестре схем TOOLS в halo_tools.py и доступны через оба транспорта (MCP и HTTP).

Разведка и OSINT

Сканирование

Веб и фаззинг

Эксплуатация

Учётные данные

Перечисление и система

Архитектура

Единый инструментальный движок (halo_tools.py) владеет арсеналом и его схемами; поверх него расположены два тонких транспорта, поэтому инструменты определяются ровно один раз:

   agent_loop.py ──HTTP─►  tool_server.py ─┐
                                            ├─►  halo_tools.py  ──►  security tools
   MCP clients  ──stdio►  mcp_server.py  ──┘   (42-tool engine +
                                                 schema registry)
     │
     ├─►  agent_cache.py         (persistent negative-experience cache)
     ├─►  skills.py              (adaptive playbook injection)
     └─►  report_generator.py    (auto HTML pentest report on exit)

• mcp_server.py — сервер Model Context Protocol, соответствующий спецификации (stdio, JSON-RPC 2.0). Подключите к нему любой MCP-клиент (Claude Desktop, IDE-агенты, инспекторы) или MCP-реестр, чтобы использовать арсенал HALO как стандартные инструменты.

• tool_server.py — локальный HTTP-сервер инструментов на Flask (порт 8000), которым управляет автономный цикл агента.

Используйте HALO как MCP-сервер

// e.g. an MCP client config
{
  "mcpServers": {
    "halo": { "command": "python3", "args": ["/abs/path/to/mcp_server.py"] }
  }
}

Готовый к отправке манифест реестра находится в server.json.

Многоагентный слой

Задания координируются набором специализированных агентов, которые обмениваются общей схемой сообщений (agent_schema.py):

Автономный слой агента

Кэш негативного опыта фиксирует сигнатуру каждого вызова инструмента. Неудачный вызов получает одну попытку повтора; при второй неудаче он попадает в чёрный список, и агент переходит к более практичному инструменту для этой задачи. В ходе задания агент выстраивает собственное обучение методом проб и ошибок — накапливает контекст, избегает повторных тупиков и разумно эскалирует — вместо того чтобы повторять то, что уже доказано не работает.

Подтверждённые взломы, а не догадки

Сложнейшая задача автономного атакующего — понять, действительно ли он проник в систему или просто повторил обнадёживающий баннер. HALO решает это с помощью шлюза запрос-ответ:

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

• Взлом засчитывается, только если вывод инструмента содержит структурированную строку HALO-EVIDENCE nonce=… level=…, повторяющую этот nonce, — которую примитив доставки (pocs/_delivery.py) может создать, только выполнив код внутри оболочки, к которой, как утверждается, получен доступ.

• Nonce является одноразовым: шлюз (exploitation_core.py:breach_confirmed) отклоняет повторно использованный или никогда не выпущенный nonce, поэтому тарпит, отражённая строка или статический баннер uid=0 не могут подделать подтверждение.

Подобранные PoC в pocs/ — это детерминированные, самоочевидные баги (vsftpd 2.3.4, ingreslock 1524, UnrealIRCd 3.2.8.1), которые честно проходят этот шлюз — либо они дают настоящую root-оболочку, либо не сообщают ничего.

Как это было создано

HALO был создан в одиночку, с нуля, менее чем за шесть месяцев самоучкой-разработчиком и исследователем безопасности. Многоагентное ядро собиралось по одному специалисту за раз, каждый проверялся на реальной цели перед переходом к следующему:

• Общий язык: общая схема сообщений (agent_schema.py), чтобы агенты могли общаться друг с другом

• Планировщик: превращает цель в упорядоченный план, проверен на живой LM Studio

• Оркестратор: направляет каждую задачу нужному специалисту

• Поиск уязвимостей: выявляет потенциальные уязвимости, протестирован на живой цели Metasploitable

• Атакующий: разветвляется на специалистов по SQLi / брутфорсу / IDOR / SSRF / XSS / auth

• Отладчик: диагностирует неудачные запуски инструментов и корректирует действия

• Валидатор + отчётность: находки подтверждаются реальными доказательствами, прежде чем засчитываться, затем собираются в отчёт, читаемый клиентом

После этого арсенал вырос до 42 инструментов, появились полный конвейер веб-разведки → атаки с захватом флагов и подтверждение взлома по принципу запрос-ответ, а кэш негативного опыта превратил метод проб и ошибок в постоянное обучение между сессиями. Активная разработка продолжается — новые возможности добавляются регулярно; см. журнал изменений о выпущенных этапах.

Стек

• Модель: Gemma 4-12B Instruct Abliterated (GGUF через LM Studio) — работает с любой локальной моделью на ваш выбор

• Агент: автономный цикл на Python с вызовами инструментов MCP

• Транспорты инструментов: сервер Model Context Protocol (stdio) для MCP-клиентов, плюс HTTP-сервер инструментов на Flask для цикла агента (порт 8000)

• ОС: Kali Linux (протестировано в UTM на Apple Silicon M1)

• Эталонное железо: MacBook Pro M1, 16 ГБ ОЗУ

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

Полную настройку см. в docs/QUICKSTART.md. Если кратко:

git clone https://github.com/XenoCoreGiger31/GEMMA-by-GOOGLE.git
cd GEMMA-by-GOOGLE
python3 -m pip install -r requirements.txt

cp engagement.example.yaml engagement.yaml   # then fill in authorization + scope_targets

python3 tool_server.py      # terminal 1 — HTTP tool server on port 8000
python3 agent_loop.py       # terminal 2 — the agent

>>> engage 203.0.113.3     # full autonomous recon + attack
>>> run nmap on 10.0.0.1    # single-goal query
>>> exit                    # triggers HTML report generation

Примечание: конечные точки и пути по умолчанию соответствуют стандартной локальной настройке (LM Studio на localhost:1234, HTTP-сервер инструментов на localhost:8000). Любую из них можно переопределить с помощью переменных окружения HALO_* — см. таблицу переопределения окружения. Несколько заданных автором путей по умолчанию для журналов/кэша остаются в agent_cache.py и tool_server.py; переменные окружения покрывают и их.

agent_loop.py не запустится без engagement.yaml — это шлюз авторизации и прав доступа, через который проходит каждый вызов инструмента, а не необязательная настройка. См. шаг 5 из «Быстрого старта».

Запуск тестов

Модульные тесты используют встроенный в Python unittest — никаких дополнительных зависимостей:

python3 -m unittest

Участие в разработке

Приветствуется вклад от сообществ специалистов по безопасности, ИИ и Python — см. CONTRIBUTING.md. Поставьте звезду репозиторию, если он вам полезен, или откройте PR — давайте создавать что-то вместе.

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

Отказ от ответственности и правовая информация

Это общественный проект независимого разработчика. Он не связан с Google LLC, не одобрен и не спонсируется ею. «Gemma» является товарным знаком Google LLC.

⚠️ Предупреждение о содержимом: Упомянутая модель сильно аблятирована и будет отвечать на деликатные запросы без обычных ограничений. Используйте ответственно, только в соответствующих средах.

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

Лицензия

Выпущено под лицензией MIT.