GEMMA-by-GOOGLE

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

HALO is an autonomous security agent that runs inside a Linux environment driven

by a local LLM — Gemma 4-12B (uncensored / abliterated) served through

LM Studio. It plans, runs reconnaissance, chains attacks based on what it finds,

and writes a professional pentest report on its own. Everything 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

• ✅ Verified 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-derived evidence, consume-once at the gate)

• 🎯 Curated PoC library — deterministic, self-evident exploits

(vsftpd 2.3.4, ingreslock, UnrealIRCd) fired through a sandboxed delivery

primitive that returns a real shell, not a guess

• 🧠 Persistent negative-experience cache — learns what fails across *all*

sessions and stops wasting cycles on proven dead ends

• 🧩 Adaptive skill 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

Scanning

Web & Fuzzing

Exploitation

Credentials

Enumeration & System

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:

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` — 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

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

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`):

Sovereign Agent Layer

The negative-experience 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, avoiding repeated dead ends, and

escalating intelligently — rather than re-running what it has already proven

doesn't work.

Verified 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-EVIDENCE 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 never-minted 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-evident bugs

(vsftpd 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

developer and security researcher. The multi-agent core came together one

specialist at a time, each verified 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, verified against live LM Studio
• Orchestrator: routes each task to the right specialist
• Vuln Discovery: surfaces candidate vulnerabilities, tested against a live Metasploitable target
• Attacker: branches into SQLi / brute-force / IDOR / SSRF / XSS / auth specialists
• Debugger: diagnoses failed tool runs and adjusts
• Validator + reporting: findings are confirmed against real evidence 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

negative-experience cache turned trial-and-error into persistent learning across

sessions. Active development 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:

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

> Note: endpoints and paths default to a standard local setup (LM Studio on

> `localhost:1234`, HTTP tool server on `localhost:8000`). Override any of them

> with the `HALO_*` environment variables — see the

> environment overrides table. A few

> author-specific log/cache path defaults remain in `agent_cache.py` and

> `tool_server.py`; the env vars cover those 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:

python3 -m unittest

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 developed by an independent, self-taught developer and security

researcher. New capabilities are pushed regularly.

Disclaimer & Legal

This is a community project by an independent developer. 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 sensitive requests without the usual guardrails. Use responsibly,

> in appropriate environments 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.