Proxy

Hugin’s proxy is a full MITM (man-in-the-middle) HTTP and WebSocket proxy. It sits between your browser and the target application, decrypting TLS traffic, capturing every request and response, and feeding them to all other tools in real time.

🔗Getting Started

  1. Start Hugin. The proxy listens on 127.0.0.1:8080 by default.
  2. Install the CA certificate (see below).
  3. Configure your browser to use 127.0.0.1:8080 as its HTTP/HTTPS proxy.
  4. Browse the target application. All traffic appears in the History view.

🔗How It Works

For plain HTTP, the proxy captures requests and responses directly.

For HTTPS, the flow is:

  1. Your browser sends a CONNECT tunnel request for the target host.
  2. Hugin completes the TLS handshake with the browser using a dynamically generated certificate for that host.
  3. Hugin establishes a separate TLS connection to the upstream server.
  4. Every request and response is captured as an HTTP flow and stored in the database.
  5. The flow is broadcast to the UI, scanner, and any loaded plugins immediately.

🔗HTTP/2 Support

HTTP/2 is enabled by default. The proxy negotiates the protocol via ALPN during the upstream TLS handshake. When the server speaks HTTP/2, Hugin uses a persistent connection pool keyed by host. Pseudo-headers (:method, :path, :authority, :scheme) are captured alongside regular headers so HTTP/2 flows are fully inspectable.

HTTP/2 can be disabled in configuration if a target misbehaves with it.

🔗CA Certificate

On first launch, Hugin generates an RSA CA key pair and writes it to disk. You install the CA certificate once so your browser trusts the proxy’s per-host certificates.

Installation:

  • macOS – double-click the certificate, add to Keychain, mark as “Always Trust”
  • Firefox – Settings > Privacy & Security > Certificates > View Certificates > Import
  • Chrome/Chromium – follows the OS trust store on macOS and Linux

The CA cert PEM is served at http://127.0.0.1:8081/api/ca.pem for easy download. You can also export it via the CLI:

hugin ca export --print
hugin ca export --output ~/ca.crt

Or install/remove the CA in the system trust store automatically:

hugin ca trust
hugin ca untrust

🔗Scope Filtering

Scope controls what gets captured and stored. Four modes are available:

  • CaptureAll (default) – every flow is stored regardless of host
  • InScopeOnly – only flows matching at least one include pattern are stored
  • OutOfScopeOnly – flows matching exclude patterns are dropped before storage
  • CaptureAllTagOOS – all flows are stored, but out-of-scope flows are tagged

Scope patterns can match on host, URL prefix, or regular expression. Scope is updated at runtime without restarting the proxy; changes take effect on the next request.

Out-of-scope traffic is always forwarded transparently – the browser still gets its responses, they just are not stored.

🔗Upstream Proxy Chaining

Hugin can route traffic through an upstream proxy. Supported types:

  • HTTP and HTTPS proxies
  • SOCKS4 and SOCKS5 proxies
  • Per-host routing rules with wildcard patterns and priority ordering
  • Basic authentication for proxies that require credentials
  • A built-in tor preset routing through socks5://127.0.0.1:9050

Per-host rules are evaluated in priority order (higher numbers first). If no rule matches, Hugin falls back to the global proxy or connects directly.

🔗DNS Configuration

Hugin provides full control over DNS resolution at the proxy level. Three mechanisms are evaluated in order:

🔗Rewrite Rules

Static hostname-to-IP mappings. When a request matches a rewrite pattern, the proxy connects directly to the specified IP, bypassing DNS entirely. Useful for testing staging servers behind CDNs or routing to specific backends.

[[dns.rewrite_rules]]
pattern = "api.example.com"
target = "10.0.1.50"
enabled = true
rank = 0

[[dns.rewrite_rules]]
pattern = "*.staging.example.com"
target = "10.0.1.100"
enabled = true
rank = 1

Patterns support exact match, wildcard (*.example.com), and regex (~pattern).

🔗Upstream Resolvers

Route DNS queries through specific nameservers instead of the system resolver. Each resolver can be scoped to specific domains via allowlist/denylist patterns. When multiple resolvers match, the lowest-rank resolver wins.

[[dns.upstream_resolvers]]
address = "1.1.1.1"
label = "Cloudflare"
enabled = true
rank = 0
# allowlist = ["*.example.com"]  # empty = all domains
# denylist = ["internal.example.com"]

[[dns.upstream_resolvers]]
address = "8.8.8.8:53"
label = "Google"
enabled = true
rank = 1

Upstream resolvers use hickory-dns with UDP + TCP fallback, 5-second timeout, and 2 retry attempts. Resolver instances are cached per address for the lifetime of the proxy.

🔗System Fallback

When no rewrite rule or upstream resolver matches, Hugin uses the operating system’s default DNS resolution (equivalent to getaddrinfo).

🔗DNS Cache

DNS cache TTL can be configured to reduce repeated lookups:

[dns]
cache_ttl_secs = 300  # 5 minutes (default)
# cache_ttl_secs = 0  # disable caching

All DNS settings can be changed at runtime via the Settings UI or MCP tools. Changes take effect on the next connection.

🔗WebSocket Detection

When the proxy sees an Upgrade: websocket request, it hands the connection to the WebSocket manager. The HTTP 101 handshake is recorded as a normal flow, and all subsequent frames are captured separately. See WebSocket for details.

🔗Hosted Files

Hugin can serve static files directly through the proxy port for payload injection during testing. Place files in ~/.hugin/hosted/ and reference them as:

http://127.0.0.1:8080/hosted/payload.js

The proxy intercepts requests to /hosted/* when the Host header targets localhost (127.0.0.1, localhost, or [::1]). Requests to external hosts with /hosted/ paths pass through normally.

Hosted files are managed via the Files view in the UI, which supports uploading, deleting, and copying the URL to clipboard.

🔗Plugin and Extension Hooks

Every proxied flow passes through the plugin bus before being stored. Registered plugins can modify, flag, or drop requests and responses. Lua extensions can hook OnRequest and OnResponse to modify traffic in-flight.

🔗Flow Recording

Flow recording can be paused and resumed without stopping the proxy. When paused, the proxy still forwards traffic but does not write flows to the database. This is useful when you want to reduce noise while performing a specific test.

🔗Configuration

Proxy settings are stored in ~/.hugin/config.toml:

[proxy]
listen_addr = "127.0.0.1:8080"

[ca]
cert_path = "~/.hugin/Hugin-Proxy-CA.pem"
key_path  = "~/.hugin/Hugin-Proxy-CA-key.pem"

[http2]
enabled        = true
alpn_protocols = ["h2", "http/1.1"]

🔗CLI

hugin start                        # Start proxy on default port
hugin start --port 9090            # Start on custom port
hugin start --bind 0.0.0.0         # Bind to all interfaces
hugin status                       # Show proxy status
hugin ca export --print            # Print CA certificate to stdout

🔗MCP Tools

infra – proxy infrastructure info and tunnel management.

Actions: health, status, ca_cert, tunnel_list, tunnel_add, tunnel_remove

scope – manage proxy scope.

Actions: get, set_mode, add_pattern, remove_pattern, update, export, import, save_preset, load_preset, list_presets, delete_preset, from_sitemap