Mahoraga-Webapp-Defender

Sistema de defesa reativa para websites alimentado por IA que detecta ataques, os analisa e corrige autonomamente o código-fonte em tempo real usando agentes LLM.

Introdução

O Mahoraga Defender é uma Prova de Conceito (PoC) de um sistema de defesa reativo, agnóstico ao tipo de atacante, operando em tempo real. O mecanismo central envolve enganar um adversário para realizar descobertas e ataques em um ambiente benigno e falso (ambiente "sombra") e registrar esses ataques. Em seguida, um agente LLM analisa os logs e repassa os detalhes de quaisquer explorações detectadas para mais agentes LLM corrigirem as vulnerabilidades e implantarem os patches.

O sistema foi projetado para ser totalmente automatizado, com otimização de custos de API em mente. Uma interface gráfica foi criada para monitorar facilmente os logs de tráfego, a atividade dos agentes e o pipeline de patches, além de controlar o número de agentes a serem implantados.

Site Alvo

O site alvo (vítima) é um fork do crAPI (Completely Ridiculous API), uma aplicação web intencionalmente vulnerável criada pela OWASP para ensinar testes de segurança de API. O crAPI simula uma plataforma de proprietários de veículos com microsserviços que cobrem as vulnerabilidades de API do OWASP Top 10. O defensor foi projetado para distinguir claramente entre sessões de usuário normais e adversárias, de modo que os usuários comuns não experimentem qualquer queda na qualidade da experiência enquanto o defensor protege o site dos atacantes.

Nosso fork (crapi-fork/) adiciona:

• Honeypots plantados (credenciais falsas, endpoints, tokens) para detecção de atacantes
• Total de 12 flags estilo CTF embutidas na superfície de ataque
• Uma stack "sombra" paralela com serviços idênticos e bancos de dados separados para observação segura do atacante
• Roteamento de sessão baseado em nginx Lua que redireciona transparentemente sessões suspeitas da produção para a sombra

Uma cópia original é mantida em crapi-original/ para que o ambiente possa ser redefinido entre os experimentos.

Arquitetura do Defensor Mahoraga

Ambientes Duais

• Prod: atende usuários reais via proxy reverso nginx (porta 8888)
• Shadow: stack falsa idêntica com bancos de dados separados, recebe tráfego de atacantes redirecionado de forma transparente

Pipeline de Agentes

• Orquestrador: coordena todo o pipeline. Gerencia ciclos de vida dos agentes, filas de patches/revisão, estado dos tickets, implantação e recuperação de falhas. Escala agentes corrigidores/revisores para cima e para baixo em tempo de execução.
• Vigia (baseado em regras): monitora os logs de tráfego da produção e pontua as sessões quanto ao nível de ameaça usando correspondência de padrões (força bruta, injeção, enumeração, acesso a honeypot, etc.). Quando a pontuação de ameaça excede um limite, dispara a ação de redirecionamento.
• Analisador de Sombra (agente LLM): lê os logs de tráfego do ambiente sombra em um intervalo configurável para detectar explorações bem-sucedidas. Remove duplicatas de entradas de log, detecta padrões de ataque e envia explorações confirmadas para a fila de correção.
• Corrigidor (agente LLM): recebe relatórios de exploração, lê o código-fonte relevante e aplica patches diretamente em crapi-fork/. Opera em um ambiente bash isolado com acesso restrito apenas a crapi-fork/.
• Revisor (agente LLM): verifica os patches quanto à correção, escopo e segurança. Patches aprovados acionam a ação de implantação; patches rejeitados são enviados de volta ao corrigidor com feedback.

Na implantação, os serviços Python são recarregados a quente via gunicorn (instantâneo), enquanto os serviços Java/Go são reconstruídos via docker compose up -d --build.

Por que não há um agente Testador? Consideramos adicionar um agente dedicado de teste de usuário e um ambiente de teste separado, mas removemos ambos para manter o sistema leve.

Como Iniciar

Preparação

• Recomenda-se usar um ambiente virtual conda ou python (ex.: conda create -n XYZ python=3.13, depois conda activate XYZ).
• Instale as dependências: pip install -r requirements.txt

Experimento Completo: Defensor vs. Atacante

1. Execute ./start.sh a partir do diretório raiz do projeto — redefine o código fonte de crapi-fork/ a partir de crapi-original/, reconstrói todos os serviços, planta flags e honeypots.
2. Execute o defensor: python3 -m harness.main --app-url http://localhost:8888 -v.
3. Comece a testar a penetração do site em localhost:8888 (a descrição do desafio está em localhost:8888/challenge). Se estiver testando com um agente de IA, o agente não deve ter acesso a processos docker internos, pois isso seria considerado trapaça.
4. Durante o teste de penetração, monitore o painel do defensor em localhost:3000 para ver logs em tempo real, ações dos agentes, patches, flags capturadas, etc.
5. Após o término da sessão, execute docker compose down -v para remover os containers docker e bancos de dados que foram iniciados para este projeto.

Painel de Controle

Painel: http://localhost:3000

Uma barra de status global de agentes é visível em todas as abas, mostrando a saúde do agente (ativo/travado/ocioso/erro) com controles de escala.

Logs

Visualizador de logs de requisições de produção/sombra em tela dividida em tempo real, com entradas coloridas por severidade e agrupamento de tráfego

Agentes

Feed de atividade por agente com prompts do sistema, chamadas de ferramentas e rótulos do modelo LLM

Pipeline

Quadro Kanban: Detectado → Corrigindo → Revisando → Implantado, com painel de detalhes redimensionável

Patches

Diffs de código, arquivos modificados, comandos de reversão e linha do tempo por patch

Configuração do LLM

O sistema usa qualquer API compatível com OpenAI. Configure os modelos em config/llm.yaml:

Para trocar de provedor, altere provider e model, depois defina a chave de API correspondente em harness/.env:

Provedores suportados: OpenAI, Gemini, Anthropic, Groq, Together, Ollama, Mistral, DeepSeek, Fireworks, xAI, Perplexity, OpenRouter, Zhipu. Adicione provedores personalizados incluindo sua URL base na seção providers do YAML.

Nota: Apenas alguns provedores de API têm limite de taxa alto o suficiente para suportar 3+ agentes trabalhando simultaneamente. O Google Gemini é um deles.

Stack Tecnológica

• LLMs: Qualquer API compatível com OpenAI (padrão: Gemini 3 Flash Preview para agentes, Gemini 2.5 Flash para analisador)
• Aplicação Alvo: crAPI modificado (Python/Django, Java/Spring Boot, Go, MongoDB, PostgreSQL)
• Roteamento: nginx com script Lua para redirecionamento transparente de sessão
• Pontuação: Pontuação de ameaça baseada em Redis via plano de controle FastAPI
• Painel: React + Tailwind CSS, servido por FastAPI com WebSocket para atualizações ao vivo
• Orquestração: Python asyncio com coordenação de agentes baseada em filas

Agradecimentos Especiais

Agradecimentos especiais a d3lta05 (LinkedIn) e aleemladha pela ajuda com os testes de penetração.