How to Configure Rate Limiting on the MasterDnsVPN SOCKS5 Proxy

MasterDnsVPN implements automatic IP-based rate limiting for SOCKS5 connections via hardcoded constants in internal/client/socks_ratelimit.go that you tune by editing the source and recompiling.

The MasterDnsVPN repository provides a DNS-over-HTTPS and SOCKS5 proxy solution written in Go. Its built-in rate limiter protects the SOCKS5 authentication endpoint from brute-force attacks by tracking failures per IP address within a sliding time window. Unlike external middleware, this protection is embedded directly in the client package and operates automatically for every incoming connection.

How the Rate Limiter Works

The implementation uses a sliding-window counter with escalating penalties to distinguish between accidental mistakes and malicious automation.

Sliding Window: Failed authentication attempts are accumulated inside a 2‑minute window (socksRateLimitWindow).

Failure Threshold: When an IP records 10 or more failures (socksRateLimitMaxFailures), it is immediately banned.

Escalating Bans: The first ban lasts 1 minute (socksRateLimitBaseBan). Each subsequent violation doubles the ban duration (exponential back‑off) until it reaches the ceiling of 15 minutes (socksRateLimitMaxBanDuration).

Decay Mechanism: If an IP remains clean for 10 minutes after a ban expires (socksRateLimitBanDecayAfter), its escalation counter resets to the base duration.

Maintenance Tasks: Stale entries are purged every 60 seconds (socksRateLimitPurgeInterval) to prevent memory bloat. Loopback addresses (127.0.0.1 and ::1) are unconditionally exempt from blocking. All state mutations are guarded by a sync.Mutex to ensure thread‑safety under concurrent load.

Locating the Configuration Constants

The rate limiter is not controlled via external configuration files. Instead, behavior is hardcoded in the source file internal/client/socks_ratelimit.go at lines 19‑44.

Key tunables include:

• socksRateLimitWindow – Duration of the observation window
• socksRateLimitMaxFailures – Failure count that triggers a ban
• socksRateLimitBaseBan – Initial ban duration
• socksRateLimitMaxBanDuration – Maximum allowable ban time
• socksRateLimitBanDecayAfter – Clean‑slate period for resetting escalation
• socksRateLimitPurgeInterval – Garbage collection frequency for old entries

Modifying Rate Limit Parameters

To configure custom limits, you must edit the constants and rebuild the binary.

1. Open internal/client/socks_ratelimit.go.

2. Adjust the constant block (lines 19‑44):

const (
    // Sliding window duration (default 2 min)
    socksRateLimitWindow = 2 * time.Minute

    // Max failures before a ban (default 10)
    socksRateLimitMaxFailures = 10

    // Base ban duration (default 1 min)
    socksRateLimitBaseBan = 1 * time.Minute

    // Maximum ban (default 15 min)
    socksRateLimitMaxBanDuration = 15 * time.Minute

    // Time after which escalation counter resets (default 10 min)
    socksRateLimitBanDecayAfter = 10 * time.Minute

    // How often stale entries are cleaned up (default 60 s)
    socksRateLimitPurgeInterval = 60 * time.Second
)

3. Rebuild the client binary:

go build ./cmd/client

The new limits take effect immediately when the updated binary starts. If you require runtime‑adjustable limits without recompilation, you would need to expose these constants through a wrapper in internal/client/client.go and wire them to the existing TOML configuration parser or command‑line flags.

Runtime Integration Examples

According to the MasterDnsVPN source code, the limiter exposes four primary methods. These are typically invoked inside the SOCKS5 handshake logic found in internal/client/client.go.

Checking ban status before processing authentication:

ip := extractIP(conn) // helper logic from socks_ratelimit.go
if client.socksRateLimiter.IsBlocked(ip) {
    log.Warnf("SOCKS5 request from %s blocked by rate limiter", ip)
    // Send AUTH_FAILURE and close connection
    return
}

Recording failures and detecting new bans:

if authFailed {
    if client.socksRateLimiter.RecordFailure(ip) {
        log.Infof("IP %s banned due to repeated failures", ip)
        // Trigger alert or metrics increment
    }
}

Clearing state after successful authentication:

if authSucceeded {
    client.socksRateLimiter.RecordSuccess(ip)
}

Administrative reset of all rate‑limit data:

client.socksRateLimiter.Reset()
log.Info("All SOCKS5 rate-limit data cleared")

Summary

• MasterDnsVPN SOCKS5 proxy rate limiting is compile‑time configurable via constants in internal/client/socks_ratelimit.go.
• The default policy blocks IPs for 1 minute after 10 failures within a 2‑minute window, with exponential escalation up to 15 minutes.
• Loopback traffic is automatically exempt, and thread‑safe operations are enforced by a sync.Mutex.
• To apply changes, edit lines 19‑44, rebuild with go build ./cmd/client, and restart the service.
• Runtime integration relies on four methods: IsBlocked(), RecordFailure(), RecordSuccess(), and Reset().

Frequently Asked Questions

Can I configure SOCKS5 rate limiting without rebuilding the binary?

No. As implemented in the MasterDnsVPN repository, the rate limits are hardcoded constants. To adjust thresholds or windows, you must modify internal/client/socks_ratelimit.go and recompile. For runtime changes, you would need to fork the repository and add TOML or flag‑based configuration parsing in internal/client/client.go.

How long does an IP remain banned after repeated failures?

The first ban lasts 1 minute (socksRateLimitBaseBan). Each subsequent ban doubles in duration until it hits the 15‑minute ceiling (socksRateLimitMaxBanDuration). If the IP avoids authentication failures for 10 minutes after a ban expires, the escalation counter resets to the base 1‑minute duration.

Does the rate limiter affect local development on localhost?

No. Loopback addresses—specifically IPv4 127.0.0.1 and IPv6 ::1—are explicitly whitelisted and will never be blocked, regardless of failure count. This exemption is hardcoded in the IsBlocked() logic within internal/client/socks_ratelimit.go.

What happens if the rate limiter state grows too large?

The implementation automatically purges stale entries every 60 seconds (socksRateLimitPurgeInterval). This cleanup removes IPs that have not seen activity within the relevant time windows, preventing unbounded memory growth in long‑running deployments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}