Mahoraga 웹앱 디펜더

AI 기반의 반응형 웹앱 방어 시스템으로, AI 기반 해킹을 실시간으로 견딜 수 있도록 설계되었습니다.

소개

Mahoraga 디펜더는 반응형, 공격자 유형에 구애받지 않는 실시간 방어 시스템의 PoC(개념 증명)입니다. 핵심 메커니즘은 적이 무해한 가짜 환경("섀도우" 환경)에서 탐색 및 공격을 수행하도록 속이고 이러한 공격을 기록하는 것입니다. 그런 다음 LLM 에이전트가 로그를 분석하고 감지된 익스플로잇 세부 정보를 더 많은 LLM 에이전트에 전달하여 취약점을 수정하고 패치를 배포합니다.

이 시스템은 API 비용 최적화를 염두에 두고 완전 자동화되도록 설계되었습니다. 트래픽 로그, 에이전트 활동 및 패치 파이프라인을 쉽게 모니터링하고 배포할 에이전트 수를 제어할 수 있는 GUI가 만들어졌습니다.

대상 웹사이트

대상(희생) 웹사이트는 OWASP에서 API 보안 테스트 교육용으로 만든 의도적으로 취약한 웹 애플리케이션인 crAPI(Completely Ridiculous API)의 포크입니다. crAPI는 OWASP Top 10 API 취약점을 다루는 마이크로서비스가 포함된 차량 소유자 플랫폼을 시뮬레이션합니다. 디펜더는 일반 사용자 세션과 적대적 사용자 세션을 명확히 구분하여, 디펜더가 웹사이트를 공격자로부터 보호하는 동안 일반 사용자가 사용자 경험 품질 저하를 겪지 않도록 설계되었습니다.

저희 포크(crapi-fork/)는 다음을 추가합니다:

공격자 탐지를 위한 심어진 허니팟(가짜 자격 증명, 엔드포인트, 토큰)
공격 표면 전반에 걸쳐 총 12개의 CTF 스타일 플래그 내장
안전한 공격자 관찰을 위한 동일한 서비스와 별도 데이터베이스를 갖춘 병렬 "섀도우" 스택
의심스러운 세션을 프로덕션에서 섀도우로 투명하게 리디렉션하는 nginx Lua 기반 세션 라우팅

실험 간 환경을 재설정할 수 있도록 원본 복사본이 crapi-original/에 보관됩니다.

Mahoraga 디펜더 아키텍처

이중 환경

프로드(Prod): nginx 리버스 프록시(포트 8888)를 통해 실제 사용자에게 서비스 제공
섀도우(Shadow): 동일한 가짜 스택과 별도 데이터베이스로, 공격자 트래픽을 투명하게 수신하여 리디렉션

에이전트 파이프라인

오케스트레이터(Orchestrator): 전체 파이프라인을 조정합니다. 에이전트 수명 주기, 패치/검토 대기열, 티켓 상태, 배포 및 충돌 복구를 관리합니다. 런타임에 수정자/검토자 에이전트를 확장 및 축소합니다.
감시자(Watcher) (규칙 기반): 프로드 트래픽 로그를 모니터링하고 패턴 매칭(무차별 대입, 인젝션, 열거, 허니팟 접근 등)을 사용하여 위협 수준에 따라 세션을 점수화합니다. 위협 점수가 임계값을 초과하면 리디렉션 작업을 트리거합니다.
섀도우 분석기(Shadow Analyzer) (LLM 에이전트): 구성 가능한 간격으로 섀도우 환경 트래픽 로그를 읽어 성공적인 익스플로잇을 감지합니다. 로그 항목 중복을 제거하고, 공격 패턴을 감지하며, 확인된 익스플로잇을 수정 대기열에 푸시합니다.
수정자(Fixer) (LLM 에이전트): 익스플로잇 보고서를 받고, 관련 소스 코드를 읽은 후 crapi-fork/에서 직접 패치를 적용합니다. crapi-fork/로만 제한된 샌드박스 bash 환경에서 작동합니다.
검토자(Reviewer) (LLM 에이전트): 패치의 정확성, 범위 및 보안을 확인합니다. 승인된 패치는 배포 작업을 트리거하고, 거부된 패치는 피드백과 함께 수정자에게 다시 보내집니다.

배포 시 Python 서비스는 gunicorn을 통해 즉시 핫-리로드되고, Java/Go 서비스는 docker compose up -d --build로 재빌드됩니다.

테스터 에이전트는 왜 없나요? 전용 사용자 테스트 에이전트와 별도의 테스트 환경을 추가하는 것을 고려했지만, 시스템을 가볍게 유지하기 위해 둘 다 제거했습니다.

시작 방법

준비하기

conda나 python 가상 환경 사용을 권장합니다 (예: conda create -n XYZ python=3.13, 그 다음 conda activate XYZ).
필수 패키지 설치: pip install -r requirements.txt

전체 디펜더 vs 공격자 실험

프로젝트 루트 디렉토리에서 ./start.sh 실행 — crapi-original/에서 crapi-fork/ 소스 코드를 재설정하고, 모든 서비스를 재빌드하며, 플래그와 허니팟을 심습니다.
디펜더 실행: python3 -m harness.main --app-url http://localhost:8888 -v.
localhost:8888에서 웹사이트 펜테스트 시작 (도전 과제 설명은 localhost:8888/challenge에 있음). AI 에이전트를 사용하여 펜테스트하는 경우, 에이전트가 내부 도커 프로세스에 접근해서는 안 됩니다. 이는 부정행위로 간주됩니다.
펜테스트 중에는 localhost:3000의 디펜더 대시보드에서 실시간 로그, 에이전트 작업, 패치, 캡처된 플래그 등을 모니터링합니다.
세션이 끝난 후, docker compose down -v를 실행하여 이 프로젝트를 위해 생성된 도커 컨테이너와 데이터베이스를 제거합니다.

대시보드

대시보드: http://localhost:3000

모든 탭에 글로벌 에이전트 상태 표시줄이 표시되어 에이전트 상태(활성/중단/유휴/오류)와 확장/축소 컨트롤을 보여줍니다.

로그

프로드/섀도우 요청 로그를 실시간 분할 화면으로 보여주며, 심각도에 따라 색상이 구분되고 트래픽이 그룹화됩니다.

에이전트

각 에이전트별 활동 피드로 시스템 프롬프트, 도구 호출, LLM 모델 레이블을 표시합니다.

파이프라인

칸반 보드: 감지됨 → 수정 중 → 검토 중 → 배포됨, 크기 조정 가능한 세부 정보 패널 포함.

패치

코드 diff, 수정된 파일, 롤백 명령어, 각 패치별 타임라인을 표시합니다.

LLM 설정

시스템은 OpenAI 호환 API를 사용합니다. 모델은 config/llm.yaml에서 구성하세요:

# Shadow Analyzer — reads shadow logs to detect exploits (no tool calling)
shadow_analyzer:
  provider: gemini
  model: gemini-2.5-flash
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.30
    output_per_million: 2.50

# Fixer — patches source code (tool-calling agent)
fixer:
  provider: gemini
  model: gemini-3-flash-preview
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.50
    output_per_million: 3.00

# Reviewer — verifies patches (tool-calling agent)
reviewer:
  provider: gemini
  model: gemini-3-flash-preview
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.50
    output_per_million: 3.00

프로바이더를 변경하려면 provider와 model을 수정하고, harness/.env에 해당 API 키를 설정하세요:

지원되는 프로바이더: OpenAI, Gemini, Anthropic, Groq, Together, Ollama, Mistral, DeepSeek, Fireworks, xAI, Perplexity, OpenRouter, Zhipu. YAML의 providers 섹션에 기본 URL을 추가하여 사용자 정의 프로바이더를 추가할 수 있습니다.

providers:
  openai: https://api.openai.com/v1
  gemini: https://generativelanguage.googleapis.com/v1beta/openai/
  anthropic: https://api.anthropic.com/v1/
  groq: https://api.groq.com/openai/v1
  ... # add more if needed

참고: 동시에 3개 이상의 에이전트를 지원할 수 있는 충분한 속도 제한을 가진 API 제공업체는 소수에 불과합니다. Google의 Gemini가 그 중 하나입니다.

기술 스택

LLM: 모든 OpenAI 호환 API (기본값: 에이전트용 Gemini 3 Flash Preview, 분석기용 Gemini 2.5 Flash)
대상 앱: 수정된 crAPI (Python/Django, Java/Spring Boot, Go, MongoDB, PostgreSQL)
라우팅: 투명한 세션 리디렉션을 위한 Lua 스크립팅이 포함된 nginx
점수화: FastAPI 제어 평면을 통한 Redis 기반 위협 점수화
대시보드: React + Tailwind CSS, 실시간 업데이트를 위해 FastAPI + WebSocket으로 제공
오케스트레이션: 큐 기반 에이전트 조정을 위한 Python asyncio

특별 감사

특별히 d3lta05 (LinkedIn)와 aleemladha님께 침투 테스트에 도움을 주셔서 감사드립니다.

인기

Mahoraga-Webapp-Defender

인기