Smokescreen v0.1.0

This release includes changes merged since v0.0.4 in May 2022.

We'll publish versions more often from here and keep dependencies current. Each release will carry upgrade notes where behavior changes.

Breaking changes and upgrade notes

• Custom ACL implementations must accept acl.DecideArgs. The struct carries the service and destination, along with the requested proxy host. During MITM checks, the request fields expose the current HTTP request (Req) and its original CONNECT request (ConnectReq). (#286, #298)
• The metrics API has changed. Helpers moved to pkg/smokescreen/metrics, where NewStatsdMetricsClient replaces NewMetricsClient. Tags use map[string]string. Update timing calls to TimingWithTags(name, duration, tags, rate) and use StatsdClient() to access the underlying StatsD client. Config.MetricsClient accepts MetricsClientInterface. (#169, #174, #179)

Go 1.25.0 or later is required. CI tests Go 1.25 through 1.27. (#306, #305)

Timeout defaults have changed. These values apply through the CLI and NewConfig():

Setting	Default	Details
Outbound connection timeout	10 seconds	Applies when connect_timeout or --timeout is omitted. An explicit 0 disables this deadline. #297
HTTP header, request-read, and response-write timeouts	300 seconds each	YAML values of 0 retain the defaults. Check the configured durations for long uploads and streaming responses. #276
Idle HTTP keep-alive timeout	300 seconds with the default read timeout	When idle_timeout is 0, Go uses ReadTimeout for idle keep-alive connections. An explicit nonzero idle_timeout overrides that fallback.
DNS lookup deadline	5 seconds	Set dns_timeout or --dns-timeout to adjust it. Zero selects the default. #280

The HTTP settings govern the server created by StartWithConfig. Established CONNECT tunnels follow the configured tunnel idle timeout. Applications supplying their own HTTP server control its deadlines.

Rate limiting and MITM require explicit configuration. When enabled, Prometheus starts a listener at 0.0.0.0:9810/metrics using its defaults.

Added

• Prometheus metrics, with a configurable listen address and endpoint. (#179, #203)
• MITM support with per-domain rules. Configuration controls request headers and which HTTP details appear in logs. (#225)
• Upstream HTTP/HTTPS proxies accept configuration, including URLs with credentials, with ACLs governing client-requested CONNECT proxies. Applications can customize connections through hooks that select a proxy and adjust its TLS settings or CONNECT request. (#208, #213, #222, #275)
• Request-rate and concurrency limits. A separate limit caps active CONNECT tunnels. (#280, #284)
• YAML accepts allow_addresses and deny_addresses. (#237)
• Hooks for inspecting allowed requests and changing proxy responses. SmokescreenContext and its decision fields are exported for use by integrations. (#180, #189, #196, #199, #200, #232, #234)
• Connection-success tracking and DNS lookup timing, with more metrics for connection errors. (#168, #169, #170, #181)
• The proxy_duration_ms metric measures time spent handling a request before dialing the destination. (#175)
• Exported hostname helpers in pkg/smokescreen/hostport and acl.HostMatchesGlob for applications that need the same parsing and matching rules. (#172, #185)
• An option to include the destination IP in the CONNECT response's X-Server-Ip header. (#263)

Changed

• Connection tracking accepts TrackerInterface. Update calls to NewTracker to pass the metrics interface and an optional success-rate tracker. Instrumented-connection constructors take a project argument, while the wait group is available through Wg(). (#171, #173, #268)
• Config.Resolver accepts custom resolvers implementing LookupPort and LookupIP. Existing *net.Resolver values satisfy that interface. (#187)
• Startup preserves a supplied connection tracker. (#168)
• DNS address selection checks each returned address against IP policy. It chooses the first allowed address outside the configured deferred list, falling back to a deferred address when needed. Selection happens before dialing. (#260)
• Hostname parsing handles bracketed addresses more consistently and accepts underscores in requested domains. CONNECT requests must contain a valid host and port. (#163, #164, #166, #177)
• CLI version output comes from Go build metadata. (#165)
• Connection-close metrics carry a project tag. The domain label was removed from connection timing to reduce cardinality. (#259, #268)
• Updated vendored dependencies, including golang.org/x/net v0.56.0, golang.org/x/text v0.39.0, Logrus v1.9.0, gopkg.in/yaml.v2 v2.4.0, and google.golang.org/protobuf v1.33.0. (#186, #216, #306)

Deprecated

• Config.RejectResponseHandler is deprecated in favor of RejectResponseHandlerWithCtx. Configurations that set both handlers fail validation. (#232)

Removed

• smokescreen.Version() and smokescreen.VersionID. Applications can read version information through runtime/debug.ReadBuildInfo. (#165)
• PrivateRuleRanges. Private-address checks use net.IP.IsPrivate(), and callers can set address exceptions through Config. (#160)
• ACL.ValidateDomainGlobs. Use ValidateDomainGlob for one glob or ValidateRule for a rule. (#178, #225)

Fixed

• Applied the 10-second connection timeout consistently when configuration omits it. (#297)
• YAML transport settings now control idle connection limits. Existing values for transport_max_idle_conns and transport_max_idle_conns_per_host take effect on upgrade. (#278)
• Fixed a race in Prometheus metrics. (#256)
• CONNECT requests return HTTP 502 for DNS lookup failures and HTTP 504 when the lookup times out. (#194)
• Close the upstream proxy connection when writing its CONNECT request fails. (#291)
• Persistent tags work on the connection metrics for duration and byte counts, as well as connection-close and shutdown metrics. (#247)
• Corrected the available-metric names shown in errors from MockMetricsClient. (#233)
• Restored missing role information in HTTP proxy logs and improved error logs with status codes. Address fields are recorded as connections are established and closed. (#159, #201, #252, #253, #255, #291)
• Validate client-supplied upstream HTTPS proxy addresses before use. (#224)
• Repaired the vulnerability workflow's govulncheck installation. (#306)
• Integration tests use local fixtures and run with the integration build tag. CI runs them separately from unit tests and checks the vendor tree for drift. (#305)

Security

• ACL validation now covers default rules and global lists, including domain globs for external proxies. Revalidate existing ACL files before upgrading because invalid entries fail to load. Host matching uses ASCII/Punycode normalization. (#178, #248, #264)
• CGNAT and recognized IPv4-embedding IPv6 ranges are denied by default. This covers 100.64.0.0/10, the well-known NAT64 prefix, 6to4, and Teredo. Explicit allow rules take precedence for these ranges. (#265, #277)
• Startup discovers local interface addresses so the proxy can reject connections back to itself on its configured listening port. That check runs before allow-range evaluation. (#282)
• MITM inner requests pass through ACL checks, using the role from the original CONNECT request. (#279)
• Configured CRLs are enforced during TLS verification. Clients presenting a revoked certificate are rejected. (#293)
• The goproxy update generates MITM leaf certificates with cryptographic randomness. A bounded cache keeps certificate generation costs down. (#303)
• Sanitize role and project values before writing metric tags. (#266)
• Vulnerability checks run on relevant pull requests and every push to master, as well as the weekly schedule. GitHub Actions are pinned to commit SHAs. (#307, #299)

Full changelog: v0.0.4...609eb89