JPKCom DB
Auf GitHub ansehen

localproxy — Anleitung & Tipps

localproxy ist ein schlanker lokaler HTTP-Proxy für Browser-basierte Online-Tools — Download, Start, Konfiguration und Endpunkte, um externe URLs ohne CORS-Probleme abzurufen.

localproxy ist ein schlanker, sicherer lokaler HTTP-Proxy für Browser-basierte Online-Tools. Er bindet ausschließlich an 127.0.0.1 und erlaubt deinen Web-Anwendungen, externe URLs abzurufen — ohne an den CORS-Beschränkungen des Browsers zu scheitern.

Anleitung

Voraussetzungen

  • Eine vorgefertigte Binary für deine Plattform (Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD — jeweils gängige Architekturen)
  • Alternativ für den Build aus dem Quellcode: Go 1.26+

Binary herunterladen

Vorgefertigte Binaries für alle Plattformen liegen im Repository unter Releases (z. B. localproxy-linux-amd64, localproxy-macos-apple-silicon, localproxy-windows-amd64.exe).

Ausführbar machen (macOS / Linux)

chmod +x ./localproxy-macos-apple-silicon
# macOS: Gatekeeper-Warnung der unsignierten Binary aufheben:
xattr -dr com.apple.quarantine ./localproxy-macos-apple-silicon

Starten

Im einfachsten Fall ohne weitere Konfiguration:

./localproxy

Beim Start zeigt ein Banner die wichtigen Werte an: die Adresse (http://127.0.0.1:PORT — ohne --port ein zufälliger freier Port), das bei jedem Start neu erzeugte Token, die verwendeten DNS-Server und die zugelassenen Origins.

Konfiguration

--port      int     TCP-Port (0 = zufälliger freier Port)                  [Standard: 0]
--origin    string  Erlaubte Origins, kommagetrennt
--timeout   int     Timeout für Upstream-Anfragen in Sekunden              [Standard: 30]
--max-mb    int64   Maximale Antwortgröße in MB (0 = unbegrenzt)           [Standard: 50]
--dns       string  DNS-Server, kommagetrennt, oder "system" für OS-DNS    [Standard: "1.1.1.1,8.8.8.8"]
--version           Versionsinformation ausgeben und beenden

Beispiele:

# Produktion: nur ein bestimmtes Tool zulassen
./localproxy --origin https://deintool.example.com

# Eigene DNS-Server (Quad9 + Cloudflare)
./localproxy --dns "9.9.9.9,1.1.1.1"

# DNS-Resolver des Betriebssystems verwenden
./localproxy --dns system

Standardmäßig löst localproxy Namen über Cloudflare (1.1.1.1) und Google (8.8.8.8) auf — unabhängig von der DNS-Konfiguration des Hosts, was über Maschinen hinweg konsistente Ergebnisse liefert. Fehlt beim --dns-Wert der Port, wird :53 automatisch ergänzt.

Endpunkte

Endpunkt Auth Beschreibung
GET/POST/HEAD /proxy?url=... ja (X-Proxy-Token) Anfrage an die Ziel-URL weiterleiten (Body-Streaming, Metadaten-Header)
GET /inspect?url=... ja Verbindungs-Metadaten als JSON (SSL, Timing, IP, Header); &body=1 inkl. Body
GET /page?url=... ja Vollständige Seitenanalyse: Redirect-Kette + Body + SSL + Timing in einem JSON
`OPTIONS /proxy /inspect /page`
GET /ping nein Health-Check (gibt localproxy ok zurück)
GET /version nein Versionsinfo als JSON

Einbindung im Tool

  1. Nutzer gibt Adresse (http://127.0.0.1:PORT) und Token im Online-Tool ein.
  2. Das Tool prüft die Verbindung über /ping.
  3. Alle weiteren Anfragen laufen über /proxy?url=... mit dem Header X-Proxy-Token. Beispiel:
const response = await fetch(
  `${PROXY_BASE}/proxy?url=${encodeURIComponent(targetUrl)}`,
  { headers: { "X-Proxy-Token": PROXY_TOKEN } }
);

Jede /proxy-Antwort liefert zusätzlich Upstream-Metadaten als Header: X-Upstream-Protocol, X-Upstream-IP, X-Upstream-Timing (z. B. dns=12;tcp=45;ssl=23;ttfb=156;total=234), X-Upstream-Content-Encoding und X-Upstream-Content-Length. Alle Upstream-Header sind per JavaScript lesbar.

Tipps & Tricks

  • In Produktion Origins einschränken: Ohne --origin sind alle Origins erlaubt. Für den produktiven Einsatz immer das konkrete Tool per --origin https://deintool.example.com freigeben.
  • HTTPS-Seite ruft HTTP-localhost auf — kein Problem: Browser behandeln http://127.0.0.1 als „potentially trustworthy origin" (W3C Secure Contexts). Anfragen von einer HTTPS-Seite an den lokalen Proxy werden nicht als Mixed Content blockiert; Chromes Private-Network-Access-Preflight wird automatisch beantwortet.
  • /page spart Roundtrips: Der Endpunkt verfolgt die Redirect-Kette (bis zu 20 Hops), lädt den Body, inspiziert SSL und misst Timings in einem einzigen JSON — er ersetzt mehrere /proxy- und /inspect-Aufrufe.
  • SSL-Details, die der Browser nicht hergibt: /inspect liefert Zertifikatsinformationen (Version, Aussteller, Gültigkeit, SANs, Chain), die über die Fetch-API nicht zugänglich sind. Ohne body=1 wird upstream nur ein HEAD-Request gesendet (schneller, kein Body-Download).
  • Sicherheits-Defaults: 48-Zeichen-Session-Token bei jedem Start neu, SSRF-Schutz (Ziel-Hosts werden aufgelöst und gegen private/Loopback-CIDRs geprüft), TLS-Upstream-Verifikation immer aktiv, Redirects werden nicht automatisch gefolgt (der Client entscheidet), Antwortgröße per --max-mb gedeckelt.
  • Nebenläufigkeit & Kompression: Der Proxy bearbeitet Anfragen parallel (eine Goroutine pro Verbindung); jede Upstream-Anfrage nutzt eine frische Verbindung für genaues Timing. Brotli, gzip und deflate werden bei /proxy transparent durchgereicht — die Dekompression übernimmt der Browser.
  • Aus dem Quellcode bauen: Mit Go 1.26+ via go build -o localproxy .; Cross-Compiles über GOOS/GOARCH (z. B. GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -trimpath -o localproxy.exe .). Ein Git-Tag (git tag v1.0.5 && git push origin v1.0.5) stößt über GitHub Actions automatisch plattformübergreifende Release-Builds an.
  • Tests & Linting: go test -race ./... für den Race-Detector; das Projekt wird mit staticcheck gelintet (CI blockt den Release bei jedem Befund). staticcheck ist reines Dev-Tooling und landet nie in der Binary.

Weiterführende Informationen