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 — LM Studio를 통해 제공되는 Gemma 4-12B(검열 해제 / abliterated)로 구동되는 Linux 환경 내에서 실행되는 자율 보안 에이전트입니다. HALO는 계획을 세우고, 정찰을 수행하며, 발견한 내용을 기반으로 공격을 연쇄적으로 실행하고, 전문적인 침투 테스트 보고서를 스스로 작성합니다. 모든 것이 로컬에서 실행됩니다: 클라우드 없음, API 키 없음, 어떤 것도 머신 밖으로 나가지 않습니다.

한 단어로 작전이 시작됩니다: engage.

기능

• 🔍 자율 정찰 — masscan + nmap으로 열린 포트와 서비스 탐지

• ⚔️ 자율 공격 루프 — 발견한 내용에 따라 도구를 선택하고 연쇄 실행

• 🌐 웹 정찰 → 공격 파이프라인 — apex-to-URL 열거(하위 도메인, 호스트, 과거 URL), 콘텐츠 발견, 템플릿 스캔 및 XSS, CTF 스타일 웹 타깃에 대한 자동 플래그 캡처 포함

• ✅ 배너가 아닌 검증된 침해 — 모든 시도는 익스플로잇이 뚫린 셸 내부에서 반향해야 하는 일회용 챌린지/nonce를 수반합니다. 단순한 uid=0 배너나 tarpit은 이를 위조할 수 없으므로, 확인된 침해는 실제 침해입니다(실행 기반 증거, 게이트에서 일회 소비).

• 🎯 엄선된 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

스캐닝

웹 및 퍼징

익스플로잇

자격 증명

열거 및 시스템

아키텍처

단일 도구 엔진(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 에이전트, 인스펙터) 또는 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는 챌린지-응답 게이트로 이 문제를 해결합니다:

• 오케스트레이터는 발사 전에 해당 타깃과 정확한 페이로드 해시에 바인딩된 시도별 nonce를 발행합니다.

• 도구 출력에 그 nonce를 반향하는 구조화된 HALO-EVIDENCE nonce=… level=… 줄이 포함된 경우에만 침해로 간주됩니다. 이 줄은 전달 프리미티브(pocs/_delivery.py)가 자신이 획득했다고 주장하는 셸 내부에서 코드를 실행해야만 생성할 수 있습니다.

• nonce는 일회 소비입니다. 게이트(exploitation_core.py:breach_confirmed)는 재생되거나 발행된 적 없는 nonce를 거부하므로, tarpit, 반사된 문자열, 정적 uid=0 배너는 확인을 위조할 수 없습니다.

pocs/에 있는 엄선된 PoC는 결정적이고 자명한 버그(vsftpd 2.3.4, ingreslock 1524, UnrealIRCd 3.2.8.1)로, 이 게이트를 정직하게 통과합니다 — 실제 루트 셸을 획득하거나 아무것도 보고하지 않습니다.

어떻게 만들어졌나

HALO는 독학으로 배운 개발자이자 보안 연구원이 6개월도 안 되는 기간에 혼자서 처음부터 끝까지 만들었습니다. 멀티 에이전트 코어는 한 번에 한 명의 전문가씩 구성되었으며, 각 전문가는 다음 단계로 넘어가기 전에 실제 타깃에 대해 검증되었습니다:

• 공유 언어: 에이전트들이 서로 대화할 수 있도록 하는 공통 메시지 스키마(agent_schema.py)

• 플래너: 목표를 순서가 있는 계획으로 전환, 실제 LM Studio에 대해 검증됨

• 오케스트레이터: 각 작업을 올바른 전문가에게 라우팅

• 취약점 발견: 후보 취약점을 표면화, 실제 Metasploitable 타깃에서 테스트됨

• 공격자: SQLi / 무차별 대입 / IDOR / SSRF / XSS / 인증 전문가로 분기

• 디버거: 실패한 도구 실행을 진단하고 조정

• 검증자 + 보고: 발견 사항은 인정되기 전에 실제 증거와 대조하여 확인된 후, 클라이언트가 읽을 수 있는 보고서로 정리됩니다

그 후 무기고는 42개 도구, 플래그 캡처가 포함된 완전한 웹 정찰 → 공격 파이프라인, 챌린지-응답 침해 확인으로 성장했으며, 부정 경험 캐시는 시행착오를 세션 전반에 걸친 지속적 학습으로 전환했습니다. 활발한 개발이 계속되고 있습니다 — 새로운 기능이 정기적으로 추가됩니다. 출시된 이정표는 변경 로그를 참조하세요.

스택

• 모델: 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, 16GB 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에 남아 있으며, 환경 변수가 이들도 다룹니다.

agent_loop.py는 engagement.yaml 없이는 시작되지 않습니다 — 모든 도구 호출이 통과하는 권한 부여 및 범위 게이트이지, 선택적 구성이 아닙니다. Quickstart의 5단계를 참조하세요.

테스트 실행

단위 테스트는 Python에 내장된 unittest를 사용합니다 — 추가 종속성이 없습니다:

python3 -m unittest

기여

보안, AI, Python 커뮤니티의 기여를 환영합니다 — CONTRIBUTING.md를 참조하세요. 유용하다면 저장소에 Star를 눌러 주시거나, PR을 열어 함께 만들어 가요.

독립적인 독학 개발자이자 보안 연구자가 활발히 개발하고 있습니다. 새로운 기능이 정기적으로 제공됩니다.

면책 조항 및 법적 고지

이것은 독립 개발자의 커뮤니티 프로젝트입니다. Google LLC와 제휴, 보증, 후원 관계가 아닙니다. "Gemma"는 Google LLC의 상표입니다.

⚠️ 콘텐츠 경고: 참조된 모델은 안전장치가 크게 제거(heavily abliterated)되어 일반적인 보호 장치 없이 민감한 요청에 응답합니다. 책임감 있게, 적절한 환경에서만 사용하세요.

🔒 법적 경고: 이 도구는 본인이 소유했거나 테스트에 대한 명시적 서면 허가를 받은 시스템에 대해 인가된 침투 테스트 및 보안 연구 목적으로만 엄격히 사용됩니다. 승인되지 않은 사용은 불법입니다.

라이선스

MIT License에 따라 배포됩니다.