major refractor

* removed option to run one proxy per port
* added -subnet-size option to select one IP per network if provided (fixes #3)
* use permute package to reduce memory overhead
* use goreleaser to build packages automatically
* major code refractor and modernizations
* added -test flag to ensure routing is setup corectly
* added fail-safe checks to pervent IP leaks
* modernized the code

Author: lanrat

Makefile

@@ -3,9 +3,12 @@ default: stargate
 RELEASE_DEPS = fmt lint
 include release.mk
 
+SOURCES := $(shell find . -type f -name "*.go")
+
+
 .PHONY: all fmt clean docker lint
 
-stargate: *.go go.mod
+stargate: ${SOURCES} go.mod go.sum
 	CGO_ENABLED=0 go build -ldflags "-w -s -X main.version=${VERSION}" -trimpath -o $@
 
 clean:

README.md

@@ -1,6 +1,7 @@
 # Stargate
 
-Stargate runs TCP SOCKS proxies on different ports egressing on sequential IPs in the same subnet.
+Stargate is a TCP SOCKS5 proxy server that can egress traffic from multiple IP addresses within a subnet. It randomly distributes connections across different IP addresses to help avoid rate-limiting and provide load balancing across your available IP range.
+
 This requires the host running stargate to have the subnet routed directly to it.
 
 If you have an IPv6 subnet, stargate can allow you to make full use of it by any program that can speak SOCKS.
@@ -9,62 +10,117 @@ If you have an IPv6 subnet, stargate can allow you to make full use of it by any
 
 ```console
 Usage of ./stargate: [OPTION]... CIDR
-        CIDR example: "192.0.2.0/24"
+ CIDR example: "192.0.2.0/24"
 OPTIONS:
   -listen string
-        IP to listen on (default "localhost")
-  -port uint
-        first port to start listening on
-  -random uint
-        port to use for random proxy server
+     listen on specified [IP:]port (e.g., '1337', '127.0.0.1:8080', '[::1]:1080') (default "localhost:1080")
   -subnet-size uint
-        CIDR prefix length for random subnet proxy (e.g., 24 for /24 subnets)
+     CIDR prefix length for random subnet proxy (e.g., 64 for /64 IPv6 subnets)
+  -test
+     run test request on all IPs and exit
   -verbose
-        enable verbose logging
+     enable verbose logging
   -version
-        print version and exit
+     print version and exit
 ```
 
-## Random
+Stargate now operates as a single SOCKS5 proxy server that randomly selects egress IP addresses from your specified CIDR range. This approach is much more memory-efficient and suitable for large IPv6 ranges.
 
-The `-random` flag starts a SOCKS5 proxy that egresses traffic on a random IP in the subnet.
-This is useful to avoid rate-limiting or in situations where there are too many IPs in the subnet to listen on each port which is common with IPv6.
+## Test Flag - Preventing IP Address Leakage
 
-When used with `-subnet-size`, the proxy will randomly distribute connections across different subnets within the main CIDR range. For example, with a /48 IPv6 block and `-subnet-size 64`, connections will be distributed across random /64 subnets.
+**IMPORTANT**: Before using Stargate in production, always run the test mode first to ensure there are no unintended IP address leaks.
 
-## Example
+The `-test` flag performs comprehensive validation by:
 
-The following will start 254 SOCKS proxies listening on 127.0.0.7 ports 10001-100254 sending traffic egressing on 192.0.2.1 through 192.0.2.254.
+- Testing HTTP requests from every available IP address in your CIDR range
+- Verifying that each egress IP matches the intended source address
+- Detecting binding errors or network misconfigurations
+- Ensuring no connections leak through unintended IP addresses
 
-```console
-./stargate -listen 127.0.0.7 -port 10001 192.0.2.0/24
+**Note:** When using `-subnet-size`, the test will validate one randomly selected IP address from each subnet rather than testing every possible IP. For example, with `-subnet-size 64` on a /48, it tests one IP per /64 subnet, not every IP in the entire /48. In order to test every possible IP address, do not pass a `-subnet-size` option when using `-test`.
+
+**Always run this test before production use:**
+
+```bash
+# Test your configuration first - THIS IS CRITICAL!
+./stargate -test 192.0.2.0/24
+
+# Only proceed to normal operation after tests pass
+./stargate 192.0.2.0/24
 ```
 
-The following will start a single socks proxy listening on 127.0.0.1:1337 egressing each connection from a random IP in 2001:DB8:1337::1/64 This offers you 2<sup>64</sup> possible IPs to egress on.
+The test will fail immediately if any IP address binding issues are detected, preventing potential IP leakage that could compromise your setup.
 
-```console
-./stargate -random 1337 2001:DB8:1337::1/64
+## Subnet Distribution
+
+When used with `-subnet-size`, the proxy will randomly distribute connections across different subnets within the main CIDR range. For example, with a /48 IPv6 block and `-subnet-size 64`, connections will be distributed across random /64 subnets, giving you access to multiple /64 networks within your larger allocation.
+
+## Examples
+
+### Basic Usage
+
+Start a SOCKS5 proxy on the default port (1080) that randomly egresses from IPs in the 192.0.2.0/24 range:
+
+```bash
+# Always test first!
+./stargate -test 192.0.2.0/24
+
+# Run the proxy after tests pass
+./stargate 192.0.2.0/24
 ```
 
-The following will start a single socks proxy listening on 127.0.0.1:8080 that distributes connections across random /64 subnets within a /48 IPv6 block:
+### Custom Listen Address
 
-```console
-./stargate -random 8080 -subnet-size 64 2001:DB8:1337::/48
+Start a SOCKS5 proxy listening on a specific IP and port:
+
+```bash
+./stargate -listen 127.0.0.7:8080 192.0.2.0/24
 ```
 
+### IPv6 with Large Address Space
+
+Use an IPv6 /64 subnet - this gives you 2^64 possible egress IPs:
+
+```bash
+./stargate -test 2001:DB8:1337::/64
+./stargate 2001:DB8:1337::/64
+```
+
+### Subnet-Level Distribution
+
+Distribute connections across multiple /64 subnets within a /48 IPv6 allocation:
+
+```bash
+./stargate -test -subnet-size 64 2001:DB8:1337::/48
+./stargate -subnet-size 64 2001:DB8:1337::/48
+```
+
+This will randomly select from different /64 networks within your /48, providing both IP and subnet-level distribution.
+
 ## Download
 
 ### [Precompiled Binaries](https://github.com/lanrat/stargate/releases)
 
+The easiest way to get started is with [precompiled binaries](https://github.com/lanrat/stargate/releases) available for multiple platforms including Linux and FreeBSD. These are statically linked and ready to run without additional dependencies.
 
 ### [Docker](https://github.com/lanrat/stargate/pkgs/container/stargate)
 
-Stargate can be run inside Docker as well, but it will require fancy routing rules or `--net=host`.
+Docker is particularly useful for deployment in containerized environments, though network configuration requires special attention to ensure proper subnet routing.
+
+Running in docker will require `--net=host`, or the subnet must be routed directly to the container.
 
 ```shell
 docker pull ghcr.io/lanrat/stargate:latest
 ```
 
 ## Building
 
-Just run `make`!
+Building from source is straightforward - just run `make`!
+
+```bash
+git clone https://github.com/lanrat/stargate.git
+cd stargate
+make
+```
+
+This will produce a statically linked binary that's ready to use.

addresses.go

@@ -2,71 +2,80 @@ package main
 
 import (
 	"fmt"
-	"math"
-	"math/big"
-	"math/rand"
 	"net"
 	"net/netip"
 )
 
-// TODO possible enhancement
-// dial from iface: https://gist.github.com/creack/43ee6542ddc6fe0da8c02bd723d5cc53
+// broadcastAddrs is a global map that tracks IP addresses identified as broadcast addresses.
+// It is populated by checkHostConflicts and used to prevent binding to these addresses.
+var broadcastAddrs = make(map[string]bool)
 
-// hosts returns a slice of all usable host IP addresses within the given CIDR range.
-// It excludes the network address and broadcast address for IPv4 networks.
-// Uses the modern netip package for cleaner iteration.
-// Updated based on: https://gist.github.com/kotakanbe/d3059af990252ba89a82?permalink_comment_id=4105265#gistcomment-4105265
-func hosts(cidr *net.IPNet) ([]net.IP, error) {
-	// Convert to netip.Prefix for cleaner iteration
-	ip, ok := netip.AddrFromSlice(cidr.IP)
-	if !ok {
-		return nil, fmt.Errorf("invalid IP address")
-	}
-	ones, _ := cidr.Mask.Size()
-	prefix := netip.PrefixFrom(ip.Unmap(), ones)
-
-	var ips []net.IP
-	for addr := prefix.Addr(); prefix.Contains(addr); addr = addr.Next() {
-		// Convert netip.Addr back to net.IP
-		ips = append(ips, net.IP(addr.AsSlice()))
+// checkHostConflicts detects if any of the addresses we are going to use are broadcast addresses.
+// It populates the global broadcastAddrs map by examining all system network interfaces.
+func checkHostConflicts(prefix *netip.Prefix) error {
+	interfaces, err := net.Interfaces()
+	if err != nil {
+		return err
 	}
 
-	// For single host or empty range, return as-is
-	if len(ips) < 2 {
-		return ips, nil
+	for _, i := range interfaces {
+		addrs, err := i.Addrs()
+		if err != nil {
+			return err
+		}
+		for _, a := range addrs {
+			ipnet, ok := a.(*net.IPNet)
+			if !ok {
+				continue
+			}
+			// We are only interested in IPv4 addresses for broadcast.
+			if ipnet.IP.To4() == nil {
+				continue
+			}
+			brdIP, err := getBroadcastAddressFromAddr(ipnet)
+			if err != nil {
+				return err
+			}
+			brdAddr, ok := netip.AddrFromSlice(brdIP)
+			if !ok {
+				return fmt.Errorf("unable to parse IP to addr: %+v", brdAddr)
+			}
+			if prefix.Contains(brdAddr) {
+				broadcastAddrs[brdAddr.String()] = true
+				l.Printf("WARNING: interface %s broadcast address is within provided prefix %s", i.Name, brdIP)
+			}
+		}
 	}
 
-	// Remove network and broadcast addresses (first and last)
-	// This handles both IPv4 and IPv6 appropriately
-	return ips[1 : len(ips)-1], nil
+	return nil
 }
 
-// maskSize returns the number of addresses in the network mask as a big.Int,
-// which can handle arbitrarily large address spaces (e.g., IPv6).
-func maskSize(m *net.IPMask) big.Int {
-	var size big.Int
-	maskBits, totalBits := m.Size()
-	addrBits := totalBits - maskBits
-	size.Lsh(big.NewInt(1), uint(addrBits))
-	return size
-}
+// getBroadcastAddressFromAddr calculates the broadcast address from a net.IPNet.
+// It only supports IPv4 addresses and returns an error for IPv6 or invalid inputs.
+func getBroadcastAddressFromAddr(addr net.Addr) (net.IP, error) {
+	// Type assertion to check if the net.Addr is a *net.IPNet.
+	ipnet, ok := addr.(*net.IPNet)
+	if !ok {
+		return nil, fmt.Errorf("address is not a net.IPNet type: %T", addr)
+	}
 
-// randomIP generates a random IP address within the given CIDR range.
-// It preserves the network portion and randomizes the host portion.
-func randomIP(cidr *net.IPNet) net.IP {
-	ip := cidr.IP
-	for i := range ip {
-		rb := byte(rand.Intn(math.MaxUint8))
-		ip[i] = (cidr.Mask[i] & ip[i]) + (^cidr.Mask[i] & rb)
+	// Check if the IP is an IPv4 address.
+	if ipnet.IP.To4() == nil {
+		return nil, fmt.Errorf("only IPv4 addresses are supported for broadcast calculation")
 	}
-	return ip
-}
 
-// getIPNetwork returns "ip4" for IPv4 addresses or "ip6" for IPv6 addresses.
-// This is used for DNS resolution context.
-func getIPNetwork(ip *net.IP) string {
-	if ip.To4() != nil {
-		return "ip4"
+	// Perform the bitwise OR calculation.
+	// Use IPv4 representation to avoid length mismatches
+	ip4 := ipnet.IP.To4()
+	mask4 := ipnet.Mask
+	if len(mask4) != 4 {
+		return nil, fmt.Errorf("invalid IPv4 mask length: %d", len(mask4))
 	}
-	return "ip6"
+
+	broadcast := make(net.IP, 4)
+	for i := 0; i < 4; i++ {
+		broadcast[i] = ip4[i] | ^mask4[i]
+	}
+
+	return broadcast, nil
 }