HTTP Breakout Proxy

Um proxy de interceptação HTTP/HTTPS leve e uma ferramenta de análise de tráfego escrita em Go, com uma interface web para inspecionar, filtrar, colorir e anotar o tráfego capturado em tempo real.

Visão Geral

HTTP Breakout Proxy funciona tanto como um proxy MITM HTTP e HTTPS quanto como uma ferramenta de visualização ao vivo.
Ele captura requisições e respostas entre dois componentes de software, permitindo que desenvolvedores:

• Inspecionem cabeçalhos, corpos e detalhes de temporização de cada requisição e resposta.
• Organizem, filtrem e persistam os dados capturados.
• Destaquem requisições com base em regras de cores definidas pelo usuário.
• Pausem ou retomem a captura dinamicamente.
• Visualizem a temporização das requisições como um gráfico de Gantt para analisar as fases de desempenho.

O proxy incorpora uma interface completa, acessível a partir de qualquer navegador web moderno, permitindo análise imediata em tempo real sem ferramentas externas.

Recursos

🔍 Captura e Inspeção

• Intercepta tráfego HTTP e HTTPS (com suporte a CA para MITM).
• Exibe todos os metadados, cabeçalhos e corpos de requisições e respostas.
• Suporta truncamento de corpos muito grandes.

💾 Persistência

• Capturas e regras de cores são armazenadas em captures.json (ou no arquivo especificado).
• Recarrega automaticamente o estado na inicialização e salva periodicamente em disco.
• Regras de cores padrão são geradas na primeira execução se nenhuma existir.

🖥️ Interface Web

• Interface web embutida e responsiva (servida pelo próprio proxy).
• Exibe as capturas em uma lista rolável com indicadores codificados por cores.
• O painel de detalhes mostra:
  • Cabeçalhos/corpos de requisição e resposta
  • Detalhamento de temporização
  • Notas editáveis
  • Gráfico de desempenho estilo Gantt para as fases de conexão

🎨 Regras de Cores

• Defina realces de cor condicionais para capturas usando uma sintaxe de filtro flexível:
  • Exemplo: status:4 status:5 → destaca erros HTTP
  • Exemplo: url:/api/ → destaca requisições de API
  • Exemplo: /\.css$/ → correspondência regex na URL
• Cada regra inclui:
  • Nome, cor, expressão de correspondência, prioridade e nota
• A correspondência com maior prioridade vence.
• Gerenciadas interativamente por uma interface modal com pré-visualizações em tempo real.
• Persistidas entre sessões.

⏸️ Controle de Captura

• O botão Pausar/Retomar permite interromper a coleta de novas capturas sem parar o proxy.
• Útil ao focar em um conjunto fixo de dados ou isolar um comportamento específico.

📈 Visualização de Desempenho

• Cada captura inclui temporização detalhada da conexão:
  • Consulta DNS
  • Conexão TCP
  • Handshake TLS
  • Processamento do servidor
  • Leitura da resposta
• Exibida como um gráfico de Gantt no painel de detalhes.
• A escala arredonda automaticamente para o segundo mais próximo para facilitar a leitura.

🧭 Filtragem e Pesquisa

• Caixa de filtro em tempo real com suporte a:
  • Filtros baseados em campos (method:GET, status:404, header:Content-Type=application/json)
  • Expressões regex (/login/)
  • Termos combinados com semântica AND/OR
• Suporta correspondência sem diferenciar maiúsculas/minúsculas e parcial.
• O filtro se aplica tanto à lista de capturas quanto ao realce de cores.
• Histórico de pesquisa armazenado localmente no navegador.

🧹 Gerenciamento

• Exclua capturas individuais ou limpe todas as capturas pela interface.
• Regras e notas são persistidas junto com as capturas.

🧩 Utilitários de Exportação

• Copie uma captura como:
  • Comando curl (formatado para o terminal)
  • Trecho de código python requests (representação JSON limpa)
• Baixe corpos de resposta diretamente da interface.

Uso pela Linha de Comando

httpbreakout  -l 127.0.0.1:8080

Início Rápido

Compilar (a partir do código-fonte)

git clone https://github.com/jbsouthe/http-breakout-proxy.git
cd http-breakout-proxy
go build -o http-breakout-proxy

Isso produz um único executável contendo o proxy compilado e os recursos da interface web embutidos.

Executar (padrão)

# run with defaults (proxy + UI)
./http-breakout-proxy

Por padrão, o binário vincula a 127.0.0.1:8080 para o proxy (e opcionalmente para a interface — veja as flags da CLI). Abra a interface em um navegador para inspecionar as capturas.

Exemplo: testando o proxy com o curl

# send an HTTPS request via the proxy (proxy listens on 127.0.0.1:8080)
curl -x http://127.0.0.1:8080 https://example.com

O tráfego capturado aparecerá na interface web.

Argumentos de Linha de Comando

Use ./http-breakout-proxy -h para listar as flags disponíveis e as descrições de uso.

Visão Geral da Interface Web

A interface é otimizada para fluxos de trabalho investigativos.

• Barra superior: campo de filtro global (com suporte a regex e prefixos de campo), Pausar/Retomar captura, Limpar e Ajuda sobre filtros (abre em uma nova aba).
• Painel esquerdo: listagem cronológica das capturas (mais recentes primeiro). Cada item mostra o nome da captura; por padrão, é METHOD URL [STATUS], mas um nome personalizado pode ser atribuído.
• Painel direito: detalhes da captura selecionada:
  • Visão geral: metadados, cabeçalhos e corpos (JSON formatado quando aplicável).
  • Abas Requisição/Resposta: corpos brutos formatados.
  • Aba Bruto: JSON completo da captura.
• Ações da linha: copiar como curl, copiar como requests do Python, baixar corpo da resposta, renomear, excluir.

Linguagem de Filtro (Referência Rápida)

• Token simples: corresponde em qualquer lugar (método, URL, status, host, cabeçalhos, corpos).
• Prefixos: method:, status:, host:, url:, body:, req.body:, resp.body:, header:, req.header:, resp.header:.
• Sintaxe de regex: /pattern/flags (por exemplo, /bearer\\s+\\S+/i).
• Especificação de cabeçalho: header:name=value, em que name ou value podem ser regex.

Exemplos:

• method:POST status:2 host:api.example.com
• /token\\s*[:=]\\s*\\S+/i
• req.header:authorization=/bearer/i
• body:/\\"success\\"\\s*:\\s*true/i

Interceptação HTTPS (MITM)

Quando o modo Man-in-the-Middle está ativado:

1. O proxy gera um par de chaves RSA de CA e um certificado raiz, armazenando-os em -ca (padrão ./ca).
2. Para inspecionar tráfego HTTPS, você deve adicionar o certificado da CA gerada (ca.pem ou similar) ao armazenamento de confiança do cliente (ou do sistema) que faz as requisições. Em muitas plataformas, isso exige privilégios administrativos.
3. O proxy realiza a interceptação TLS emitindo certificados folha assinados pela CA local para cada nome de host solicitado pelo cliente.

Nota de segurança: Instale a CA apenas em ambientes controlados. Não confie nesta CA em sistemas nos quais você lê tráfego sensível não relacionado.

Persistência

Se a persistência estiver ativada (por meio de -f ou de um caminho configurado):

• As capturas são gravadas periodicamente em disco (ex.: captures.json).
• Na inicialização, o aplicativo tentará carregar capturas anteriores do arquivo de persistência para o buffer em memória (preservando a ordem).
• Renomeações e exclusões são sincronizadas com o armazenamento persistido nas operações de salvamento; considere acionar um flush imediato para operações críticas.

Formato de Armazenamento

Os itens capturados são serializados em JSON e contêm os seguintes campos (lista não exaustiva):

• id — identificador de sequência único
• time — carimbo de data/hora (ISO 8601)
• method, url
• request_headers, response_headers
• request_body, response_body — truncados para -max-body se necessário
• response_status, duration_ms
• name — rótulo de usuário opcional
• notes, deleted — metadados de controle para eventos SSE e estado da interface

Auxiliares de Exportação e Replay

• Copiar como cURL: cria um comando curl seguro para shell, incluindo cabeçalhos e corpo (omite cabeçalhos hop-by-hop).
• Copiar como Python: gera um pequeno trecho de requests com url, headers e data opcional.
• Baixar: salva o corpo da resposta em um arquivo; a extensão é inferida a partir de Content-Type quando possível.

Considerações de design:

• Cabeçalhos hop-by-hop (ex.: Host, Content-Length, Connection) são omitidos dos comandos de replay gerados.
• Corpos de resposta binários (imagens, PDFs) podem ser baixados como blobs binários. Se as respostas forem armazenadas codificadas em Base64, o cliente as decodificará antes do download.

API: Endpoints REST (para automação)

• GET /api/captures — lista as capturas (array JSON).
• DELETE /api/captures — limpa todas as capturas.
• GET /api/captures/{id} — recupera uma única captura.
• DELETE /api/captures/{id} — exclui uma captura específica.
• PATCH /api/captures/{id} — atualiza metadados da captura; exemplo de corpo: { "name": "My label" }.
• GET /api/pause — retorna { "paused": true|false }.
• POST /api/pause — define o estado de pausa; exemplo de corpo: { "paused": true }.
• GET /events — stream de Eventos Enviados pelo Servidor (SSE) para notificações de captura em tempo real e eventos de controle.

Notas de Implementação (para desenvolvedores)

• Incorporação da interface: use //go:embed ui/* e fs.Sub para servir arquivos estáticos. Isso produz um único artefato implantável.
• Descompressão: o código de captura verifica Content-Encoding e tenta descomprimir corpos gzip e deflate antes de exibi-los. Os bytes originais são mantidos para a transparência do proxy.
• Concorrência: o armazenamento de capturas usa bloqueio interno para fornecer operações thread-safe de adicionar/listar/obter/atualizar. Sempre que possível, booleanos atômicos são usados para flags de alternância (ex.: pausar/retomar).
• SSE: um broker leve transmite adições, exclusões, renomeações e eventos de controle de captura para os clientes de interface conectados.
• Bufferização: os corpos das capturas são lidos com io.LimitReader para detectar truncamento e proteger o uso de memória.

Empacotamento e Distribuição

Modelo de distribuição recomendado:

1. Compile binários estáticos e reduzidos para as plataformas alvo (CGO_ENABLED=0, -trimpath, -ldflags "-s -w").
2. Produza arquivos compactados (.tar.gz para Unix, .zip para Windows) e inclua README.md e LICENSE.
3. Forneça somas de verificação SHA-256 e anexe os artefatos aos lançamentos (Releases) do GitHub.
4. Opcionalmente, use goreleaser para automatizar compilações multiplataforma e artefatos de lançamento.

Exemplos de comandos de compilação:

# Linux x86_64
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-linux-amd64 .

# macOS (arm64)
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-darwin-arm64 .

Executando como Serviço

Unidade systemd (exemplo para Linux)

[Unit]
Description=HTTP Breakout Proxy
After=network.target

[Service]
ExecStart=/opt/http-breakout-proxy/http-breakout-proxy -l 0.0.0.0:8080
Restart=on-failure
User=proxy
Group=proxy

[Install]
WantedBy=multi-user.target

launchd (agente de usuário do macOS)

Crie um plist em ~/Library/LaunchAgents e carregue com launchctl.

Solução de Problemas

• O corpo capturado aparece como lixo binário
  O corpo está comprimido (ex.: gzip). Certifique-se de estar executando uma compilação que inclua a descompressão automática; a interface mostra JSON/texto descomprimido quando disponível.

• Tráfego HTTPS não exibido / erros de conexão
  O cliente não confia na CA gerada. Instale ca/ca.pem no armazenamento de confiança do cliente/sistema e marque como confiável para interceptação TLS.

• A interface mostra seleção desatualizada após limpar capturas
  Atualize para um cliente que limpe selectedId em eventos SSE cleared ou invoque o endpoint GET /api/captures para atualizar o estado.

• 405 ao usar DELETE /api/captures
  Certifique-se de que o handler do servidor aceita DELETE para /api/captures e de que você não está encontrando uma incompatibilidade de barra final.

Segurança e Privacidade

Esta ferramenta realiza interceptação TLS quando o MITM está ativado. Use-a apenas em ambientes controlados nos quais você tenha autorização explícita para inspecionar tráfego. A CA gerada é poderosa: trate sua chave privada com a mesma confidencialidade que qualquer outra chave privada de CA raiz. Não instale a CA em armazenamentos de confiança compartilhados ou de produção.

Contribuindo

Contribuições são bem-vindas. Por favor, abra issues para bugs ou solicitações de recursos. Para contribuições de código:

1. Faça um fork do repositório.
2. Crie um branch de recurso.
3. Execute testes unitários e linters quando aplicável.
4. Envie um pull request descrevendo a mudança, a justificativa e quaisquer preocupações de compatibilidade reversa.

Licença

Este projeto é distribuído sob a Licença MIT. Consulte LICENSE para obter detalhes.

Atribuição e Contato

Autor: John Southerland (GitHub: jbsouthe)
Projeto: http-breakout-proxy — destinado à depuração, desenvolvimento e aprendizado sobre o comportamento do HTTP.