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偵察 → 攻撃パイプライン — apexドメインからURLまでの列挙（サブドメイン、ホスト、履歴URL）、コンテンツ発見、テンプレートスキャン、XSSを実行し、CTF形式のWebターゲットでは自動のフラグキャプチャを実施

• ✅ バナーではなく検証済みの侵害 — すべての試行には使い捨てのチャレンジ/ノンスが付与され、エクスプロイトは取得したシェルの内部からそのノンスをエコーバックする必要があります。素の uid=0 バナーやターピットでは偽造できないため、確認された侵害は本物です（実行由来の証拠、ゲートでの消費1回限り）

• 🎯 厳選されたPoCライブラリ — 決定論的で自明なエクスプロイト（vsftpd 2.3.4、ingreslock、UnrealIRCd）を、推測ではなく実際のシェルを返すサンドボックス化されたデリバリプリミティブを通じて実行

• 🧠 永続的な失敗体験キャッシュ — すべてのセッションでの失敗を学習し、実証済みの行き止まりにサイクルを浪費しない

• 🧩 適応型スキル注入 — 現在の目標に基づいて関連する攻撃プレイブックをプロンプトに読み込む

• 📝 自動HTMLレポート — 終了時に発見結果をブランド入りレポートにまとめる

• 🔒 100%ローカル — LM Studio 上の Gemma 4-12B。マシンの外に出るデータはありません

Related MCP server: Debugg AI MCP

ツール群

エージェントの意思決定ループの背後には42のツールがあり、すべて同じ失敗キャッシュ層を経由します。ツールは halo_tools.py 内の TOOLS スキーマレジストリに一度だけ定義され、両方のトランスポート（MCP と HTTP）で提供されます。

偵察 & OSINT

スキャン

Web & ファジング

エクスプロイテーション

認証情報

列挙 & システム

アーキテクチャ

単一のツールエンジン（halo_tools.py）がツール群とそのスキーマを保持し、その上に2つの軽量トランスポートが載るため、ツールは一度だけ定義されます：

   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 — 自律エージェントループが駆動するローカルな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）をやり取りする専門エージェント群によって調整されます：

Sovereign Agent レイヤー

失敗体験キャッシュはすべてのツール呼び出しのフィンガープリントを記録します。失敗した呼び出しには1回のリトライが与えられ、2回失敗するとブラックリスト入りするため、エージェントはその作業に適した別のツールへと進みます。エンゲージメントを通じて、エージェントは自らの試行錯誤学習を構造化します — コンテキストを構築し、実証済みの行き止まりを回避し、知的にエスカレーションする — すでに機能しないと証明されたものを再実行するのではなく。

検証済みの侵害、雰囲気ではない

自律型攻撃者にとって難しい問題は、実際に侵入に成功したのか、それとも希望的なバナーを繰り返しただけなのかを判断することです。HALOはこれをチャレンジレスポンスゲートで解決します：

• オーケストレーターは発射前に、そのターゲットと正確なペイロードハッシュに紐づく試行ごとのノンスを発行します。

• 侵害が認定されるのは、ツール出力が構造化された HALO-EVIDENCE nonce=… level=… 行でそのノンスをエコーバックした場合のみです — デリバリプリミティブ（pocs/_delivery.py）は、取得したと主張するシェルの内部でコードを実行することでしかこれを生成できません。

• ノンスは消費1回限りです：ゲート（exploitation_core.py:breach_confirmed）はリプレイされた、または発行されていないノンスを拒否するため、ターピット、反射された文字列、静的な uid=0 バナーでは確認を偽造できません。

pocs/ 内の厳選されたPoCは、決定論的で自明なバグ（vsftpd 2.3.4、ingreslock 1524、UnrealIRCd 3.2.8.1）であり、このゲートを正直に通過します — 実際のrootシェルを獲得するか、何も報告しないかのどちらかです。

開発の経緯

HALOは、独学の開発者兼セキュリティリサーチャーによって、ゼロから6ヶ月足らずで単独で構築されました。マルチエージェントコアは専門エージェントを1つずつ追加しながら組み上げられ、それぞれが実際のターゲットに対して検証されてから次の段階に進みました：

• 共通言語： エージェント同士が会話できる共通メッセージスキーマ（agent_schema.py）

• プランナー： 目標を順序立てた計画に変換し、稼働中のLM Studioに対して検証

• オーケストレーター： 各タスクを適切な専門エージェントにルーティング

• 脆弱性発見： 候補となる脆弱性を提示し、稼働中のMetasploitableターゲットに対してテスト

• 攻撃者： SQLi / ブルートフォース / IDOR / SSRF / XSS / 認証の専門エージェントに分岐

• デバッガー： 失敗したツール実行を診断して調整

• バリデーター + レポート： 発見は確定前に実際の証拠と照合して確認され、その後クライアントが読めるレポートにまとめられる

そこからツール群は42ツールへと成長し、フラグキャプチャを備えた完全なWeb偵察 → 攻撃パイプライン、チャレンジレスポンス方式の侵害確認が追加されました。一方、失敗体験キャッシュは試行錯誤をセッションをまたいだ永続的な学習へと変えました。現在も活発に開発が続いており、新機能は定期的に追加されています。リリース済みのマイルストーンは変更履歴を参照してください。

技術スタック

• モデル： Gemma 4-12B Instruct Abliterated（LM Studio経由のGGUF）— 任意のローカルモデルで動作します

• エージェント： MCPツール呼び出しを使用するPython自律ループ

• ツールトランスポート： MCPクライアント向けのModel Context Protocolサーバー（stdio）、およびエージェントループ向けのFlask HTTPツールサーバー（ポート8000）

• OS： 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

注: エンドポイントとパスは、デフォルトで標準的なローカル設定（localhost:1234 上の LM Studio、 localhost:8000 上の HTTP ツールサーバー）になっています。それらのいずれも HALO_* 環境変数で 上書きできます — 環境オーバーライド テーブルを 参照してください。いくつかの作者固有のログ/キャッシュパスのデフォルトは agent_cache.py と tool_server.py に残っていますが、環境変数はそれらもカバーします。

agent_loop.py は engagement.yaml なしでは起動しません — これはすべてのツール呼び出しが通過する 認可 + スコープゲートであり、オプション設定ではありません。 クイックスタートのステップ5 を参照してください。

テストの実行

ユニットテストは Python 組み込みの unittest を使用します — 追加の依存関係はありません：

python3 -m unittest

コントリビューション

セキュリティ、AI、Python コミュニティからのコントリビューションを歓迎します — CONTRIBUTING.md を参照してください。役に立った場合はリポジトリにスターを付けてください。または PR を開いて、一緒に何かを作りましょう。

独立した独学の開発者兼セキュリティリサーチャーによって積極的に開発されています。新しい機能が定期的にプッシュされています。

免責事項と法的情報

これは独立した開発者によるコミュニティプロジェクトです。Google LLC とは提携しておらず、承認も受けておらず、スポンサーでもありません。 "Gemma" は Google LLC の商標です。

⚠️ コンテンツ警告: 参照されているモデルは大幅にアブリテーションされており、通常のガードレールなしでセンシティブなリクエストに応答します。責任を持って、適切な環境でのみ使用してください。

🔒 法的警告: このツールは、所有しているシステム、またはテストするための明示的な書面による許可を得ているシステムに対する、許可されたペネトレーションテストとセキュリティリサーチ専用です。無許可での使用は違法です。

ライセンス

MIT License の下で公開されています。