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

🔐 GEMMA-by-GOOGLE — HALO

Ein vollständig lokaler, autonomer KI-Penetrationstest-Agent – Gemma 4-12B treibt ein Arsenal aus 42 Tools durch Reconnaissance, Angriffe und Reporting an, bereitgestellt als Standard-Model-Context-Protocol-Server (MCP). Keine Cloud, keine API-Schlüssel.

Funktionsweise · Tool-Arsenal · Architektur · Stack · Schnellstart · Changelog · Mitmachen

HALO ist ein autonomer Sicherheitsagent, der in einer Linux-Umgebung läuft und von einem lokalen LLM angetrieben wird – Gemma 4-12B (uncensored / abliterated), bereitgestellt über LM Studio. Es plant, führt Aufklärung durch, verkettet Angriffe basierend auf seinen Erkenntnissen und schreibt eigenständig einen professionellen Pentest-Bericht. Alles läuft lokal: keine Cloud, keine API-Schlüssel, nichts verlässt deine Maschine.

Ein einziges Wort startet einen Einsatz: engage.

Funktionsweise

• 🔍 Autonome Aufklärung – masscover + nmap zur Ermittlung offener Ports und Dienste

• ⚔️ Autonome Angriffsschleife – wählt Tools basierend auf den Erkenntnissen aus und verkettet sie

• 🌐 Web-Recon → Angriffs-Pipeline – Apex-zu-URL-Enumeration (Subdomains, Hosts, historische URLs), Content-Kenntnis, Template-Scanning und XSS, mit automatischem Flag-Capture bei CTF-artigen Web-Zielen

• ✅ Verifizierte Einbrüche, keine Vermutungen – jeder Versuch enthält eine einmalige Challenge beim Nonce, dein Exploit von innerhalb der geknackten Shell zurückgeben muss; ein bloßes uid=0-Banner oder eine Tarpit kann sie nicht fälschen. Ein bestätigter Einbruch ist also belegt (ausführungsbasierter Nachweis, einmaliger Gebrauch am Gate)

• 🎯 Kuratierte PoC-Bibliothek – deterministische, selbstbelegende EWegen (vsftpd 2.3.4, Arecase, UnrealIRCd), ausgeführt durch eine Sandbox-Primitive, das eine echte Shell zurückliefert, keine Vermutung

• me gradă Persistenter Negativerlebnis-Cache – lernt aus allen Sitzungen, was fehlschlägt, und vermeidet nachweislich unbrauchbare Enden Opponent

• 🧩 Adaptive Skill-Injektion – lädt passende Angriffs-Playbooks in den Prompt, basierend auf dem aktuellen Ziel

• 📝 Automatische HTML-Berichte – fasst Ergebnisse beim Verlassen in einem gebrandeten Bericht zusammen

• 🔒 100 % lokal – Gemma 4-12B in LM Studio; nichts verlässt ihre Maschinen

Related MCP server: Debugg AI MCP

Tool-Arsenal

42 Tools stehen hinter der Entscheidungsschleife des Agentenwenns, alle über die gleiche Fehler-Cache-Ebene geroutet. Sie werden einmalig im TOOLS-Schema-Registry in der Datei halo_tools.py definiert und über beide Transportwege (MCP und HTTP) bereitgestellt.

Recon & OSINT

• run_recon_ng | recon-ng-OSINT-Framework (nicht interaktiv) |

Scanning

Web & And Fuzzing

Exploitation

Credentials

Enumerationen & System

Architektur

Eine gemeinsame Tool-Engine (halo_tools.py) verwaltet das Arsenal und seine Schemas; zwei dünne Transportschichten stehen darüber, sodass die Toolsit genau einmal definiert werden:

   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 – ein spezifikationskonformer Model Context Protocol-Server (stdio, JSON-RPC 2.0). Jeder MCP-Client (Claude Desktop, IDE-Agenten, Inspektoren) oder ein MCP-Registry kann sich daran anbinden, um das HALO-Arsenal als Style-Tools zu nutzen.

• tool_server.py – der lokale Flask-HTTP-Tool-Server (Port 8000), den die autonome Agentenschleife betreibt.

HALO als MCP-Server nutzen

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

Ein fertig überreichbares Registry-Manifest liegt in server.json.

Multi-Agenten-Ebene

Einsätze werden durch eine Gruppe spezialisierter Agenten koordiniert, alle verbunden durch ein gemeinsames Nachrichten-Schema (agent_schema.py):

Souveräne Agenten-Ebene

Der Negativerferfahrungsbild-Cache stellt jedem possess Tool-Aufruf jedem eine Finger-Note. Ein Aufruf [,] ist fehlgeschlagen, er bekommt ein Retry-[.]; schlägt er zum zweiten Mal fehl, wird er geblockt, sodass sich der Agent besser nach geeigneter Tools umstattet. Im Laufe eines Einsatzes strukturiert der Agent sein eigenes Learning through trial and error – Erfahrung, Vermeidung bekannter Sackgassen, intelligentes Hochstufen – und führt nicht erneut aus, was schon bewiesen, unnötig ist.

Verifizierte Einbrüche, nur Vibe-Forschung

The difficult challenge with autonomous attackers is to ascertain whether they successfullybreak in or are merely "repeating" a desirable banner. HALO answers this with a Challenge-Response-Gate:

• The orchestrator creates a pro-attempt nonce that is linked to the target and the precise payload hash, before the attack is sent.

• A breach only counts if the tool output contains a structure line of HALO-EVIDENCE nonce=… level=… that backechoes specifically the nonce – something that the delivery primitive (../pocs/_delivery.py) can only generate by running code inside the shell it claims to possess. *Das Nonce is consumed once: the gate (exploitation_core.py:breach_confirmed) rejects a replayed or non-externalized nonce, so a tarpit, a reflected sum, or a static uid=0 banner cannot fake a App.

The curated PoCs in pocs/ are deterministic, self-explanatory vulnerabilities (vsftpd 2.3.4, older Metasploitable 1524, UnrealIRCd 3.2.8), which honestly go through this gate – they land a real root shell or output nothing.

How It Was Built

HALO was built solo from scratch in under six months by a self-taught developer and security researcher. The multi-agent core grew one expert another, each against a real target before the next:

• Common language: a shared message schema (agent_schema.py) so that the agents can talk to each other

• Planner: translates a target into an ordered plan, checked against live LM Studio

• Ochestrator: routes each task to the right specialist

• Vulnerability Discovery: finds candidates for vulnerabilities, tested against a live Metasploitable target

• Attacker: branches into SQLi / brute-force / IDOR () / SSRF / XSS / Auth specialists

• Debugger: diagnoses failed tool operations and compensates accordingly

• Validator + reporting: results are counterchecked against real evidence before they count, then compiled into client-readableYMXYJ report

From there, the arsenal grew to 42 tools plus a single combined web-recon → attack pipeline with flag capturing and Challenge-Response certification, while the negative-emergency cache transformed trial/error into continuously progressive learning across sessions. Active development continues – new incisors are regularly pushed out; see you in the changelog for the release delivered so far.

Stack

• Model: Gemma 4-12B Instruct Abliterated (GGUF via Hotspot) – works with any local model of your choix

• Agent: Python autonomous loop with MCPco-calls

• Tool transports: A Model Context Protocol server (stdio) for MCP client, plus a Flask HTTP-Tool-Server on port 8000 for the agent loop

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

• Hardware referent: MacBook Pro M1, 16 GB RAM

Quickstart

See docs/QUICKSTART.md for the 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

Hinweis: Endpunkte und Pfade nutzen standardmäßig ein lokales Standard-Setup (LM Studio auf localhost:1234, HTTP-Tool-Server auf localhost:8000). Jeder von ihnen lässt sich mit den HALO_*-Umgebungsvariablen überschreiben — siehe die Tabelle environment overrides. Einige autorspezifische Standardwerte für Log-/Cache-Pfade bleiben in agent_cache.py und tool_server.py; die Umgebungsvariablen decken auch diese ab.

agent_loop.py startet nicht ohne engagement.yaml — es ist das Autorisierungs- und Scope-Gate, das jeder Tool-Aufruf durchläuft, keine optionale Konfiguration. Siehe Schritt 5 des Quickstarts.

Tests ausführen

Die Unit-Tests verwenden Pythons eingebautes unittest — keine zusätzlichen Abhängigkeiten:

python3 -m unittest

Mitwirken

Beiträge aus der Security-, KI- und Python-Community sind willkommen — siehe CONTRIBUTING.md. Star das Repository, wenn es dir nützlich ist, oder öffne einen PR und lass uns gemeinsam etwas aufbauen.

Das Projekt wird aktiv von einem unabhängigen, autodidaktischen Entwickler und Sicherheitsforscher entwickelt. Neue Funktionen werden regelmäßig veröffentlicht.

Haftungsausschluss & Rechtliches

Dies ist ein Community-Projekt von einem unabhängigen Entwickler. Es ist weder mit Google LLC verbunden, noch von Google LLC unterstützt oder von Google LLC gesponsert. „Gemma“ ist eine Marke von Google LLC.

⚠️ Inhaltswarnung: Das referenzierte Modell ist stark abliteriert und antwortet auf heikle Anfragen ohne die üblichen Schutzvorkehrungen. Verwende es verantwortungsvoll und nur in geeigneten Umgebungen.

🔒 Rechtlicher Hinweis: Dieses Tool ist ausschließlich für autorisierte Penetrationstests und Sicherheitsforschung an Systemen vorgesehen, die du besitzt oder für die du eine ausdrückliche schriftliche Genehmigung zum Testen hast. Unbefugte Nutzung ist rechtswidrig.

Lizenz

Unter der MIT-Lizenz veröffentlicht.