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

🔐 GEMMA-by-GOOGLE — HALO

一个完全本地的自主AI渗透测试代理——Gemma 4-12B驱动42种工具，覆盖侦察、攻击和报告，以标准Model Context Protocol (MCP)服务器形式提供。无需云服务，无需API密钥。

功能 · 工具库 · 架构 · 技术栈 · 快速入门 · 变更日志 · 贡献指南

HALO是一个自主安全代理，运行在由本地LLM——Gemma 4-12B（未审查/去审查版）——通过LM Studio提供的Linux环境中。它会规划、执行侦察、根据发现链式攻击，并自行撰写专业渗透测试报告。一切都在本地运行：无云服务、无API密钥，不会泄露任何信息到机器之外。

一个词即可启动一次渗透：engage。

功能

• 🔍 自主侦察 — 使用masscan和nmap发现开放端口和服务

• ⚔️ 自主攻击循环 — 根据发现选择并组合工具

• 🌐 Web侦察→攻击流程 — 从顶级域名到URL枚举（子域名、 主机、历史URL）、内容发现、模板扫描和XSS，并在CTF式Web目标上自动捕获标志

• ✅ 验证过的入侵，而非横幅 — 每次攻击尝试都带有一次性挑战/随机数， 漏洞利用必须从已入侵的shell内部回应；仅靠uid=0横幅或诱捕无法伪造， 因此确认的入侵是真实的（基于执行证据，在关卡处一次性消费）

• 🎯 精选PoC库 — 确定性、自证性的漏洞利用 （vsftpd 2.3.4、ingreslock、UnrealIRCd）通过沙箱化交付原语触发， 返回真实shell而非猜测

• 🧠 持久化负面经验缓存 — 跨所有会话学习失败的攻击， 避免在已验证的死路上浪费循环

• 🧩 自适应技能注入 — 基于当前目标加载相关攻击手册到提示中

• 📝 自动HTML报告 — 退出时将发现编译为品牌化报告

• 🔒 100%本地 — Gemma 4-12B在LM Studio中；不对外泄露任何信息

Related MCP server: Debugg AI MCP

工具库

42个工具位于代理决策循环之后，所有工具都通过相同的失败缓存层路由。它们在halo_tools.py中的TOOLS模式注册表中定义一次，并通过两种传输（MCP和HTTP）提供。

侦察与OSINT

扫描

Web与模糊测试

漏洞利用

凭据

枚举与系统

架构

一个统一的工具引擎（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代理、 inspector）或MCP注册表指向它，即可将HALO的工具库作为标准工具使用。

• tool_server.py — 本地Flask HTTP工具服务器（端口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通过挑战-响应关卡解决这个问题：

• 编排器在触发前铸造每次尝试的随机数，绑定到目标及确切payload哈希。

• 只有当工具输出包含结构化的HALO-EVIDENCE nonce=… level=…行， 且回显那个随机数时，入侵才计入——而交付原语（pocs/_delivery.py） 只能通过在实际声称的shell内部运行代码来产生。

• 随机数是一次性消费的：关卡（exploitation_core.py:breach_confirmed） 会拒绝重放或从未铸造的随机数，因此诱捕、反射字符串或静态uid=0横幅无法伪造确认。

pocs/中的精选PoC是确定性、自证性的漏洞 （vsftpd 2.3.4、ingreslock 1524、UnrealIRCd 3.2.8.1），它们诚实地通过此关卡—— 要么获得真实root shell，要么报告无结果。

构建历程

HALO由一位自学成才的开发者和安全研究员独立开发，在不到六个月内从零开始构建。 多代理核心逐个专家构建，每个专家都先在真实目标上验证后才继续：

• 共享语言： 通用消息模式（agent_schema.py），使代理能够互相通信

• Planner： 将目标转换为有序计划，并通过实时LM Studio验证

• 编排器： 将每个任务路由到正确的专家

• 漏洞发现： 发现候选漏洞，针对实时Metasploitable目标测试

• 攻击者： 分支到SQLi/暴力破解/IDOR/SSRF/XSS/auth专家

• 调试器： 诊断失败的工具运行并调整

• 验证器+报告： 发现经过真实证据确认后才计入，然后编译为客户可读的报告

此后，工具库扩展到42个工具，包括完整的Web侦察→攻击流程（含标志捕获）， 以及挑战-响应式入侵确认，而负面经验缓存将试错转化为跨会话的持久学习。 持续开发中——新功能定期推送；已发布里程碑参见变更日志。

技术栈

• 模型： Gemma 4-12B Instruct Abliterated（通过LM Studio提供GGUF）—— 可搭配您选择的任何本地模型

• 代理： 使用MCP工具调用的Python自主循环

• 工具传输： 一个Model Context Protocol服务器（stdio）用于MCP客户端， 以及一个Flask HTTP工具服务器（端口8000）用于代理循环

• 操作系统： Kali Linux（在Apple Silicon M1上的UTM中测试）

• 硬件参考： MacBook Pro M1，16 GB RAM

快速入门

完整设置请参阅 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 中；这些环境变量同样涵盖它们。

没有 engagement.yaml，agent_loop.py 将无法启动——它是每次工具调用 都必须经过的授权与作用域门禁，而不是可选的配置。 请参阅 快速入门第 5 步。

运行测试

单元测试使用 Python 内置的 unittest，无需额外依赖：

python3 -m unittest

贡献指南

欢迎来自安全、AI 和 Python 社区的贡献——请参阅 CONTRIBUTING.md。如果你觉得这个仓库有用，请给它点个 Star， 或者提交一个 PR，让我们一起构建更多内容。

本项目由一位独立、自学的开发者和安全研究员积极推进。 新功能会定期推送。

免责声明与法律说明

本文由独立开发者发起的社区项目。它与 Google LLC 没有任何关联， 未获得其认可，也未受其赞助。 “Gemma” 是 Google LLC 的商标。

⚠️ 内容警告： 所引用的模型经过了深度去约束处理（abliterated）， 将在缺少常规防护措施的情况下响应敏感请求。请负责任地使用，并仅在合适环境中使用。

🔒 法律警告： 本工具仅限于已授权的渗透测试和安全研究，且测试对象 只能是你拥有或经明确书面许可授权的系统。未经授权的使用是不合法的。

License

使用 MIT License 发布。