GEMMA-by-GOOGLE - A fully local, autonomous AI penetration-testing a

项目说明

<img width="1021" height="720" alt="HALO banner" src=" />

<di="center">

🔐 GEMMA-by-GOOGLE — HALO

A fully local, autonomous AI penetration-testing agent — Gemma 4-12B driving a 42-tool arsenal through recon, attack, and reporting, exposed as a standard Model Context Protocol (MCP) server. No cloud, no API keys.

What It Does · Tools · Architecture · Stack · Quickstart · Changelog · Contributing

!License
!Python
!Tools
!LM Studio
!Platform
!PRs Welcome
![GEMMA-by-GOOGLE MCP server]()

</div>

---

HALO is an autonomous security agent that runs inside a Linux en driven
by a local LLM — Gemma 4-12B (uncensored / abliterated) ser
LM Studio. It plans, runs reconnaissance, chains attacks based on what it finds,
and writes a professional pentest report on its own. E runs locally:
no cloud, no API keys, nothing leaves your machine.

One word starts an engagement: engage.

---

What It Does

🔍 Autonomous recon — masscan + nmap to discover open ports and services

⚔️ Autonomous attack loop — selects and chains tools based on what it finds

🌐 Web recon → attack pipeline — apex-to-URL enumeration (subdomains,

hosts, historical URLs), content discovery, template scanning and XSS, with
automatic flag capture on CTF-style web targets

✅ breaches, not banners — every attempt carries a single-use

challenge/nonce the exploit must echo *from inside the popped shell*; a bare
uid=0 banner or a tarpit can't forge it, so a confirmed breach is a real one
(execution-deri, consume-once at the gate)

🎯 Curated PoC library — deterministic, self-e exploits

( 2.3.4, ingreslock, UnrealIRCd) fired through a sandboxed delivery
primitive that returns a real shell, not a guess

🧠 Persistent negati cache — learns what fails across *all*

sessions and stops wasting cycles on proven dead ends

🧩 Adapti injection — loads relevant attack playbooks into the

prompt based on the current goal

📝 Automatic HTML reports — compiles findings into a branded report on exit

🔒 100% local — Gemma 4-12B in LM Studio; nothing leaves your machine

---

Tool Arsenal

42 tools sit behind the agent's decision loop, all routed through the same
failure-caching layer. They are defined once in the TOOLS schema registry in
halo_tools.py and served over both transports (MCP and HTTP).

Recon & OSINT
| Tool | Purpose |
|------|---------|
| run_subfinder | Subdomain enumeration |
| run_thehar | Passi — emails, subdomains, hosts |
| run_httpx | HTTP probing and fingerprinting |
| run_katana | Web crawling |
| run_sherlock | Username OSINT across 90+ platforms |
| run_shodan | Internet-exposure intelligence lookups |
| run_phoneinfoga | Phone-number OSINT |
| run_phonextract | Phone-number OSINT / extraction |
| run_ghosttrack | OSINT for username / IP / phone |
| run_cloudfox | Cloud-infrastructure enumeration |
| run_wafw00f | WAF / security-solution fingerprinting |
| run_amass | Subdomain enumeration (passive by default) |
| run_dnsx | DNS resolution and probing |
| run_gau | Known URLs from OTX / Wayback / Common Crawl |
| run_waybackurls | Historical URLs from the Wayback Machine |
| run_gowitness | Web screenshotting for recon |
| run_spiderfoot | Headless multi-module OSINT scanning |
| run_recon_ng | recon-ng OSINT framework (non-interactive) |

Scanning
| Tool | Purpose |
|------|---------|
| run_masscan | Fast port discovery |
| run_nmap | Deep service/ scanning |
| run_nikto | Web scanning |
| run_nuclei | Template-based scanning |
| run_netstat | Network connection analysis |

Web & Fuzzing
| Tool | Purpose |
|------|---------|
| run_gobuster | Web directory brute forcing |
| run_ffuf | Web fuzzing |
| run_feroxbuster | Recursi discovery |
| run_dalfox | XSS scanning (reflected / stored / DOM) |
| run_curl | HTTP request testing |
| run_wget | File retrieval |

Exploitation
| Tool | Purpose |
|------|---------|
| run_sqlmap | SQL injection testing |
| run_searchsploit | Exploit lookup |
| run_metasploit | Fire a chosen Metasploit module at a target (human-approved) |
| run_exploit | Sandboxed execution of custom PoC scripts |
| run_setoolkit | Social-engineering toolkit |

Credentials
| Tool | Purpose |
|------|---------|
| run_hydra | Credential brute forcing |
| run_ncrack | Network authentication cracking |
| run_medusa | Fast parallel brute forcing |
| run_john | Hash cracking |

Enumeration & System
| Tool | Purpose |
|------|---------|
| run_enum4linux | SMB / Samba enumeration |
| run_command | Arbitrary command execution |
| read_file | Read file contents |
| write_file | Write output to files |

---

Architecture

A single tool engine (halo_tools.py) owns the arsenal and its schemas; two
thin transports sit on top of it, so the tools are defined exactly once:

mcp_server.py — a spec-compliant Model Context Protocol server

(stdio, JSON-RPC 2.0). Point any MCP client (Claude Desktop, IDE agents,
inspectors) or an MCP registry at it to use HALO's arsenal as standard tools.

tool_server.py — the local Flask HTTP tool server (port 8000) the

autonomous agent loop drives.

Use HALO as an MCP server

A ready-to-submit registry manifest lives in server.json.

Multi-agent layer

Engagements are coordinated by a set of specialist agents that pass a shared
message schema (agent_schema.py):

| Agent | Role |
|-------|------|
| planner_agent.py | Turns a goal into an ordered plan |
| orchestrator_agent.py | Routes tasks to the right specialist |
| .py | Surfaces candidate |
| attacker_agent.py | Branches into specialists (SQLi, brute force, IDOR, SSRF, XSS, auth) |
| .py | Confirms findings against real e before they count |
| debugger_agent.py | Diagnoses failed tool runs and adjusts |

So Agent Layer

The negati cache fingerprints every tool call. A call that fails
gets one retry; fail twice and it is blacklisted, so the agent moves on to a
more practical tool for the job. Over an engagement the agent structures its own
trial-and-error learning — building context, a repeated dead ends, and
escalating intelligently — rather than re-running what it has already proven
doesn't work.

breaches, not vibes

The hard problem with an autonomous attacker is knowing whether it *actually*
broke in or just parroted a hopeful banner. HALO answers this with a
challenge-response gate:

The orchestrator mints a per-attempt nonce, bound to that target and the

exact payload hash, before firing.

A breach only counts if the tool output carries a structured

HALO-E nonce=… level=… line echoing that nonce — which the
delivery primitive (pocs/_delivery.py) can only produce by running code
*inside* the shell it claims to have.

The nonce is consume-once: the gate (exploitation_core.py:breach_confirmed)

rejects a replayed or ne nonce, so a tarpit, a reflected string, or a
static uid=0 banner cannot forge a confirmation.

The curated PoCs in pocs/ are deterministic, self-e bugs
( 2.3.4, ingreslock 1524, UnrealIRCd 3.2.8.1) that pass this gate honestly —
they land a real root shell or they report nothing.

---

How It Was Built

HALO was built solo, from the ground up, in under six months by a self-taught
de and security researcher. The multi-agent core came together one
specialist at a time, each against a real target before moving on:

Shared language: a common message schema (agent_schema.py) so the agents can talk to each other

Planner: turns a goal into an ordered plan, against live LM Studio

Orchestrator: routes each task to the right specialist

Vuln Discovery: surfaces candidate , tested against a li target

Attacker: branches into SQLi / brute-force / IDOR / SSRF / XSS / auth specialists

Debugger: diagnoses failed tool runs and adjusts

+ reporting: findings are confirmed against real e before they count, then compiled into a client-readable report

From there the arsenal grew to 42 tools, a full web recon → attack pipeline with
flag capture, and challenge-response breach confirmation, while the
negati cache turned trial-and-error into persistent learning across
sessions. Acti continues — new capabilities are pushed regularly;
see the changelog for the shipped milestones.

---

Stack

Model: Gemma 4-12B Instruct Abliterated (GGUF via LM Studio) — works with

any local model of your choosing

Agent: Python autonomous loop with MCP tool calls

Tool transports: a Model Context Protocol server (stdio) for MCP clients,

plus a Flask HTTP tool server on port 8000 for the agent loop

OS: Kali Linux (tested under UTM on Apple Silicon M1)

Hardware reference: MacBook Pro M1, 16 GB RAM

---

Quickstart

See docs/QUICKSTART.md for full setup. In short:

> Note: endpoints and paths default to a standard local setup (LM Studio on
> localhost:1234, HTTP tool server on localhost:8000). O any of them
> with the HALO_* en — see the
> en o table. A few
> author-specific log/cache path defaults remain in agent_cache.py and
> tool_server.py; the env vars co too.
>
> agent_loop.py will not start without engagement.yaml — it's the
> authorization + scope gate every tool call passes through, not optional
> config. See step 5 of the Quickstart.

---

Running Tests

The unit tests use Python's built-in unittest — no extra dependencies:

---

Contributing

Contributions from the security, AI, and Python communities are welcome — see
CONTRIBUTING.md. Star the repo if it's useful to you, or open
a PR and let's build something together.

Actively de by an independent, self-taught de and security
researcher. New capabilities are pushed regularly.

---

Disclaimer & Legal

This is a community project by an independent de. It is **not affiliated
with, endorsed by, or sponsored by Google LLC.** "Gemma" is a trademark of
Google LLC.

> ⚠️ Content warning: The referenced model is heavily abliterated and will
> respond to sensiti without the usual guardrails. Use responsibly,
> in appropriate en only.

> 🔒 Legal warning: This tool is intended strictly for authorized
> penetration testing and security research on systems you own or have
> explicit written permission to test. Unauthorized use is illegal.

License

Released under the MIT License.

项目信息

开发语言：Python

Star 数：9

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A fully local, autonomous AI penetration-testing agent powered by Gemma 4-12B and a Flask MCP tool server. Runs recon, attack loops, and report generation on its own — no cloud, no API keys. For authorized security testing only.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。