🔍 Cattura e Ispezione

• Intercetta traffico sia HTTP che HTTPS (con supporto MITM CA).
• Mostra tutti i metadati, header e corpi delle richieste e risposte.
• Supporta il troncamento per corpi molto grandi.

💾 Persistenza

• Le catture e le regole di colore sono memorizzate in captures.json (o file specificato).
• Ricarica automaticamente lo stato all'avvio e salva periodicamente su disco.
• Le regole di colore predefinite vengono generate al primo avvio se non esistono.

🖥️ Interfaccia Web

• Interfaccia web integrata e reattiva (servita dal proxy stesso).
• Visualizza le catture in un elenco scorrevole con indicatori colorati.
• Pannello dei dettagli che mostra:
  • Header e corpi di richiesta/risposta
  • Suddivisioni temporali
  • Note modificabili
  • Grafico delle prestazioni in stile Gantt per le fasi di connessione

🎨 Regole di Colore

• Definisci evidenziazioni di colore condizionali per le catture utilizzando una sintassi di filtro flessibile:
  • Esempio: status:4 status:5 → evidenzia errori HTTP
  • Esempio: url:/api/ → evidenzia richieste API
  • Esempio: /\.css$/ → corrispondenza regex sull'URL
• Ogni regola include:
  • Nome, colore, espressione di corrispondenza, priorità e nota
• Vince la corrispondenza con priorità più alta.
• Gestito interattivamente tramite un'interfaccia modale con anteprime in tempo reale.
• Persistente tra sessioni.

⏸️ Controllo della Cattura

• Pulsante Pausa/Riprendi consente di interrompere la raccolta di nuove catture senza fermare il proxy.
• Utile quando ci si concentra su un set di dati fisso o si isola un comportamento specifico.

📈 Visualizzazione delle Prestazioni

• Ogni cattura include dettagli temporali della connessione:
  • Risoluzione DNS
  • Connessione TCP
  • Handshake TLS
  • Elaborazione server
  • Lettura risposta
• Visualizzato come diagramma di Gantt nel pannello dei dettagli.
• La scala arrotonda automaticamente al secondo più vicino per leggibilità.

🧭 Filtraggio e Ricerca

• Casella di filtro in tempo reale che supporta:
  • Filtri basati su campi (method:GET, status:404, header:Content-Type=application/json)
  • Espressioni regex (/login/)
  • Termini combinati con semantica AND/OR
• Supporto per corrispondenza parziale e case-insensitive.
• Il filtro si applica sia all'elenco delle catture che all'evidenziazione dei colori.
• Cronologia di ricerca memorizzata localmente nel browser.

🧹 Gestione

• Elimina singole catture o cancella tutte le catture tramite UI.
• Regole e note vengono conservate insieme alle catture.

🧩 Utilità di Esportazione

• Copia una cattura come:
  • Comando curl (formattato per terminale)
  • Frammento di codice python requests (rappresentazione JSON pulita)
• Scarica direttamente i corpi delle risposte dall'interfaccia utente.

Utilizzo da Riga di Comando

Avvio Rapido

Compilazione (da sorgente)

Questo produce un singolo eseguibile contenente il proxy compilato e le risorse dell'interfaccia utente incorporate.

Esecuzione (predefinito)

Di default il binario si collega a 127.0.0.1:8080 per il proxy (e opzionalmente UI — vedere i flag CLI). Apri l'interfaccia utente in un browser per ispezionare le catture.

Esempio: esercitare il proxy con curl

Il traffico catturato apparirà nell'interfaccia web.

Argomenti da Riga di Comando

Usa ./http-breakout-proxy -h per elencare i flag disponibili e le descrizioni di utilizzo.

Panoramica dell'Interfaccia Web

L'UI è ottimizzata per flussi di lavoro investigativi.

• Barra degli strumenti superiore: input filtro globale (supporta espressioni regolari e prefissi chiave), Pausa/Riprendi cattura, Cancella e Aiuto filtro (si apre in una nuova scheda).
• Pannello sinistro: elenco cronologico delle catture (più recenti in alto). Ogni elemento mostra il nome della cattura; per impostazione predefinita è METHOD URL [STATUS] ma è possibile assegnare un nome personalizzato.
• Pannello destro: dettagli per la cattura selezionata:
  • Panoramica: metadati, header e corpi (JSON formattato ove applicabile).
  • Richiesta / Risposta schede: corpi formattati grezzi.
  • Raw scheda: JSON completo della cattura.
• Azioni riga: copia come curl, copia come Python requests, scarica corpo risposta, rinomina, elimina.

Linguaggio di Filtro (Riferimento Rapido)

• Token semplice: corrisponde ovunque (metodo, URL, stato, host, header, corpi).
• Prefissi: method:, status:, host:, url:, body:, req.body:, resp.body:, header:, req.header:, resp.header:.
• Sintassi regex: /pattern/flags (ad esempio /bearer\\s+\\S+/i).
• Specifica header: header:name=value dove name o value possono essere regex.
• I termini sono combinati con AND logico per default (separati da spazio). Passa a OR se desiderato modificando la logica client.

Esempi:

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

Intercettazione HTTPS (MITM)

Quando la modalità Man In The Middle è abilitata:

1. Il proxy genera una coppia di chiavi CA RSA e un certificato radice e li memorizza in -ca (default ./ca).
2. Per ispezionare il traffico HTTPS è necessario aggiungere il certificato CA generato (ca.pem o simile) al trust store del client (o del sistema) che effettua le richieste. Su molte piattaforme ciò richiede privilegi amministrativi.
3. Il proxy esegue l'intercettazione TLS emettendo certificati foglia firmati dalla CA locale per ogni hostname richiesto dal client.

Nota di sicurezza: Installare la CA solo in ambienti controllati. Non fidarsi di questa CA in sistemi in cui si legge traffico sensibile non correlato.

Persistenza

Se la persistenza è abilitata (tramite -f o percorso configurato):

• Le catture vengono scritte periodicamente su disco (ad es., captures.json).
• All'avvio, l'applicazione tenterà di caricare le catture precedenti dal file di persistenza nel buffer in memoria (preservando l'ordine).
• Rinomine ed eliminazioni vengono sincronizzate con l'archivio persistente durante le operazioni di salvataggio; considerare di invocare un flush immediato per operazioni critiche.

Formato di Archiviazione

Gli elementi catturati vengono serializzati in JSON e contengono i seguenti campi (non esaustivi):

• id — identificatore univoco di sequenza
• time — timestamp (ISO 8601)
• method, url
• request_headers, response_headers
• request_body, response_body — troncato a -max-body se necessario
• response_status, duration_ms
• name — etichetta utente opzionale
• notes, deleted — metadati di controllo per eventi SSE e stato UI

Esportazione e Aiuti per il Replay

• Copia come cURL: costruisce un comando curl sicuro per la shell includendo header e corpo (omette header hop-by-hop).
• Copia come Python: produce un piccolo frammento requests con url, headers e data opzionale.
• Scarica: salva il corpo della risposta in un file; estensione dedotta da Content-Type quando possibile.

Considerazioni di progettazione:

• Gli header hop-by-hop (ad es., Host, Content-Length, Connection) vengono omessi dai comandi di replay generati.
• I corpi di risposta binari (immagini, PDF) sono scaricabili utilizzando blob binari. Se le risposte sono memorizzate codificate in Base64, il client decodificherà prima del download.

API: Endpoint REST (per automazione)

• GET /api/captures — elenca catture (array JSON).
• DELETE /api/captures — cancella tutte le catture.
• GET /api/captures/{id} — recupera una singola cattura.
• DELETE /api/captures/{id} — elimina una cattura specifica.
• PATCH /api/captures/{id} — aggiorna metadati della cattura; esempio corpo: { "name": "My label" }.
• GET /api/pause — restituisce { "paused": true|false }.
• POST /api/pause — imposta stato pausa; esempio corpo: { "paused": true }.
• GET /events — Stream di eventi inviati dal server (SSE) per notifiche di cattura in tempo reale ed eventi di controllo.

Note di Implementazione (per sviluppatori)

• Incorporare UI: utilizzare //go:embed ui/* e fs.Sub per servire file statici. Questo produce un singolo artefatto distribuibile.
• Decompressione: il codice di cattura controlla Content-Encoding e tenta di decomprimere i corpi gzip e deflate prima della visualizzazione. I byte originali vengono mantenuti per la trasparenza del proxy.
• Concorrenza: l'archivio delle catture utilizza blocco interno per fornire operazioni thread-safe di append/list/get/update. Ove possibile vengono utilizzati booleani atomici per i flag di attivazione (ad es., pausa/ripresa).
• SSE: un broker leggero trasmette aggiunte, eliminazioni, rinomine ed eventi di controllo ai client UI connessi.
• Buffering: i corpi delle catture vengono letti utilizzando io.LimitReader per rilevare il troncamento e proteggere l'utilizzo della memoria.

Packaging e Distribuzione

Modello di distribuzione consigliato:

1. Compilare binari statici, ottimizzati per le piattaforme target (CGO_ENABLED=0, -trimpath, -ldflags "-s -w").
2. Produrre archivi (.tar.gz per Unix, .zip per Windows) e includere README.md e LICENSE.
3. Fornire checksum SHA-256 e allegare artefatti alle release di GitHub.
4. Opzionalmente utilizzare goreleaser per automatizzare build multipiattaforma e artefatti di release.

Esempi di comandi di build:

Esecuzione come Servizio

unità systemd (esempio Linux)

launchd (agente utente macOS)

Creare un plist in ~/Library/LaunchAgents e caricarlo con launchctl.

Risoluzione dei Problemi

• Il corpo catturato appare come rabbia binaria
  Il corpo è compresso (ad es., gzip). Assicurarsi di eseguire una build che includa la decompressione automatica; l'UI mostra JSON/testo decompresso quando disponibile.

• Il traffico HTTPS non viene visualizzato / errori di connessione
  Il client non si fida della CA generata. Installare ca/ca.pem nel trust store del client/sistema e contrassegnarlo come attendibile per l'intercettazione TLS.

• L'UI mostra una selezione obsoleta dopo aver cancellato le catture
  Aggiornare a un client che cancelli selectedId sugli eventi SSE cleared o invocare l'endpoint GET /api/captures per aggiornare lo stato.

• 405 su DELETE /api/captures
  Assicurarsi che il gestore del server accetti DELETE per /api/captures e che non si stia colpendo una mancata corrispondenza di slash finale.

Sicurezza e Privacy

Questo strumento esegue l'intercettazione TLS quando MITM è abilitato. Utilizzarlo solo in ambienti controllati in cui si ha esplicita autorizzazione a ispezionare il traffico. La CA generata è potente: trattare la sua chiave privata con la stessa riservatezza di qualsiasi altra chiave privata di CA radice. Non installare la CA in trust store condivisi o di produzione.

Contribuire

I contributi sono benvenuti. Si prega di aprire issue per bug o richieste di funzionalità. Per contributi di codice:

1. Forkare il repository.
2. Creare un ramo di funzionalità.
3. Eseguire test unitari e linter ove applicabile.
4. Inviare una pull request descrivendo la modifica, la motivazione e eventuali preoccupazioni di retrocompatibilità.

Licenza

Questo progetto è distribuito sotto la Licenza MIT. Vedi LICENSE per i dettagli.

Attribuzione e Contatti

Autore: John Southerland (GitHub: jbsouthe)
Progetto: http-breakout-proxy — destinato a debug, sviluppo e apprendimento del comportamento HTTP.