fix: harden socks5 connections

Author: zengyufei

CHANGELOG.en.md

@@ -2,6 +2,16 @@
 
 All notable changes to `ii` are documented here. The default Chinese version is [CHANGELOG.md](CHANGELOG.md).
 
+## 0.3.10 - 2026-08-11
+
+### Added
+
+- Added `ii socks5` options `--max`, `--handshake-timeout`, and `--idle-timeout`. Defaults cap active connections at 100, require SOCKS5 handshakes within 10 seconds, and close CONNECT tunnels after 5 minutes without traffic, preventing public half-open and permanently idle connections from exhausting service resources.
+
+### Changed
+
+- `ii test` now reports target access as successful only after it reads target response body data through the proxy; header-only empty responses now fail explicitly.
+
 ## 0.3.9 - 2026-08-11
 
 ### Added

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 本文件记录 `ii` 的重要变更。默认中文版本在这里，英文版本见 [CHANGELOG.en.md](CHANGELOG.en.md)。
 
+## 0.3.10 - 2026-08-11
+
+### 新增
+
+- `ii socks5` 新增 `--max`、`--handshake-timeout`、`--idle-timeout`，默认限制 100 个活动连接、10 秒 SOCKS5 握手和 5 分钟无流量的 CONNECT 隧道，防止公网半开和永久空闲连接耗尽服务资源。
+
+### 变更
+
+- `ii test` 仅在经代理读取到目标响应体数据后才将目标访问判为通过；仅有响应头的空响应现在会明确失败。
+
 ## 0.3.9 - 2026-08-11
 
 ### 新增

Cargo.lock

@@ -24,7 +24,7 @@ unused-async = "warn"
 
 [package]
 name = "ii"
-version = "0.3.9"
+version = "0.3.10"
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true

Cargo.toml

@@ -303,7 +303,7 @@ ii socks5
 ii socks5 --port 1080 --username alice --password secret
 ```
 
-`ii socks5` is a standalone ordinary network proxy. It listens on a random `0.0.0.0` port by default and prints the actual address. It supports SOCKS5 `CONNECT`, `UDP ASSOCIATE`, `BIND`, IPv4, IPv6, and domain targets. It does not use Iroh, tickets, or relays. Supplying `--username` and `--password` enables SOCKS5 username/password authentication; both options are required together.
+`ii socks5` is a standalone ordinary network proxy. It listens on a random `0.0.0.0` port by default and prints the actual address. It supports SOCKS5 `CONNECT`, `UDP ASSOCIATE`, `BIND`, IPv4, IPv6, and domain targets. It does not use Iroh, tickets, or relays. Supplying `--username` and `--password` enables SOCKS5 username/password authentication; both options are required together. To prevent public half-open connections from exhausting resources, it defaults to 100 active connections, a 10-second handshake deadline, and a 5-minute idle `CONNECT` tunnel timeout; use `--max`, `--handshake-timeout`, and `--idle-timeout` to adjust them.
 
 ### Self-hosted Relay
 

README.en.md

@@ -303,7 +303,7 @@ ii socks5
 ii socks5 --port 1080 --username alice --password secret
 ```
 
-`ii socks5` 是独立的普通网络代理，默认监听 `0.0.0.0` 的随机端口并打印实际地址。支持 SOCKS5 `CONNECT`、`UDP ASSOCIATE`、`BIND`、IPv4、IPv6 和域名目标；不经过 Iroh、ticket 或 relay。提供 `--username` 与 `--password` 时启用 SOCKS5 用户名密码认证，两个参数必须成对出现。
+`ii socks5` 是独立的普通网络代理，默认监听 `0.0.0.0` 的随机端口并打印实际地址。支持 SOCKS5 `CONNECT`、`UDP ASSOCIATE`、`BIND`、IPv4、IPv6 和域名目标；不经过 Iroh、ticket 或 relay。提供 `--username` 与 `--password` 时启用 SOCKS5 用户名密码认证，两个参数必须成对出现。为避免公网半开连接耗尽资源，默认最多 100 个活动连接，10 秒内必须完成握手，`CONNECT` 隧道连续 5 分钟无数据会关闭；可用 `--max`、`--handshake-timeout`、`--idle-timeout` 调整。
 
 ### 自建 Relay
 

README.md

@@ -15,7 +15,7 @@ ii watch <目录> [--interval <duration>] [--stabilize <duration>] [发送选项
 ii queue <path...> [--after <duration>|--every <duration>] [发送选项]
 ii web [<目录>] [--port <port>] [--bind <ip>] [--token [<value>]] [--upload] [--path <目录>] [--once]
 ii dav [<目录>] [--port <port>] [--bind <ip>] [--token [<value>]] [--read-only] [--username <username> --password <password>] [--tls [--domain <name>] [--cert <path> --key <path>]]
-ii socks5 [--port <port>] [--bind <ip>] [--username <user> --password <pass>]
+ii socks5 [--port <port>] [--bind <ip>] [--username <user> --password <pass>] [--max <n>] [--handshake-timeout <duration>] [--idle-timeout <duration>]
 ii http [<目录>] [--port <port>] [--bind <ip>] [--token [<value>]]
 ii paste [<text>] [--port <port>] [--bind <ip>] [--token [<value>]] [--ttl <duration>]
 ii drop [<目录>] [--port <port>] [--bind <ip>] [--token [<value>]]
@@ -374,6 +374,8 @@ ii socks5 --bind 192.168.1.20 --username alice --password secret
 
 支持 SOCKS5 `CONNECT`、`UDP ASSOCIATE`、`BIND`，以及 IPv4、IPv6 和域名目标。域名由代理端解析。没有认证参数时使用 SOCKS5 无认证方式；`--username <user>` 和 `--password <pass>` 必须成对提供，提供后只接受 RFC 1929 用户名密码认证。
 
+默认最多保留 100 个活动连接，客户端必须在 10 秒内完成 SOCKS5 握手，`CONNECT` 隧道连续 5 分钟没有任意方向的数据即关闭。`--max <n>`、`--handshake-timeout <duration>` 和 `--idle-timeout <duration>` 可覆盖这些默认值；时长接受 `500ms`、`2s`、`5m`、`1h`。
+
 ## 代理、转发与网络工具
 
 ```powershell

ii.md

@@ -8,7 +8,7 @@ Usage:
   ii queue <path...> [--after <duration>|--every <duration>] [options]
   ii web [directory] [--port <port>] [--bind <ip>] [--token [value]] [--upload] [--path <dir>] [--once]
   ii dav [directory] [--port <port>] [--bind <ip>] [--token [value]] [--read-only] [--username <username> --password <password>] [--tls [--domain <name>] [--cert <path> --key <path>]]
-  ii socks5 [--port <port>] [--bind <ip>] [--username <user> --password <pass>]
+  ii socks5 [--port <port>] [--bind <ip>] [--username <user> --password <pass>] [--max <n>] [--handshake-timeout <duration>] [--idle-timeout <duration>]
   ii http [directory] [--port <port>] [--bind <ip>] [--token [value]]
   ii paste [text] [--port <port>] [--bind <ip>] [--token [value]] [--ttl <duration>]
   ii drop [directory] [--port <port>] [--bind <ip>] [--token [value]]
@@ -190,13 +190,16 @@ Options:
 
 pub(crate) const SOCKS5_HELP: &str = "\
 Usage:
-  ii socks5 [--port <port>] [--bind <ip>] [--username <user> --password <pass>]
+  ii socks5 [--port <port>] [--bind <ip>] [--username <user> --password <pass>] [--max <n>] [--handshake-timeout <duration>] [--idle-timeout <duration>]
 
 Options:
   --port <port>              Listener port; defaults to a random free port
   --bind <ip>                Listener IPv4 or IPv6 address; defaults to 0.0.0.0
   --username <user>          Enable SOCKS5 username/password authentication
   --password <pass>          SOCKS5 password; requires --username
+  --max <n>                  Maximum active connections; defaults to 100
+  --handshake-timeout <d>    SOCKS5 handshake deadline; defaults to 10s
+  --idle-timeout <d>         Close a CONNECT tunnel with no traffic; defaults to 5m
 ";
 
 pub(crate) const HTTP_HELP: &str = "\

src/cli/help.rs

@@ -1,14 +1,31 @@
 use super::*;
+use std::time::Duration;
+
+const DEFAULT_MAX_CONNECTIONS: usize = 100;
+const DEFAULT_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(10);
+const DEFAULT_IDLE_TIMEOUT: Duration = Duration::from_secs(5 * 60);
 
 pub(super) fn parse(args: Vec<String>) -> Result<Socks5Args, ParseAction> {
-    let mut out = Socks5Args::default();
+    let mut out = Socks5Args {
+        max_connections: DEFAULT_MAX_CONNECTIONS,
+        handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT,
+        idle_timeout: DEFAULT_IDLE_TIMEOUT,
+        ..Default::default()
+    };
     let mut iter = ArgsIter::new(args);
     while let Some(arg) = iter.next() {
         match split_long_value(&arg) {
             Some(("port", value)) => out.port = Some(parse_port("--port", value)?),
             Some(("bind", value)) => out.bind = Some(parse_bind("--bind", value)?),
             Some(("username", value)) => out.username = Some(value.to_string()),
             Some(("password", value)) => out.password = Some(value.to_string()),
+            Some(("max", value)) => out.max_connections = parse_max("--max", value)?,
+            Some(("handshake-timeout", value)) => {
+                out.handshake_timeout = parse_duration("--handshake-timeout", value)?
+            }
+            Some(("idle-timeout", value)) => {
+                out.idle_timeout = parse_duration("--idle-timeout", value)?
+            }
             Some((flag, _)) => {
                 return Err(ParseAction::error(format!("unknown option `--{flag}`")));
             }
@@ -18,6 +35,15 @@ pub(super) fn parse(args: Vec<String>) -> Result<Socks5Args, ParseAction> {
                 "--bind" => out.bind = Some(parse_bind("--bind", &iter.value("--bind")?)?),
                 "--username" => out.username = Some(iter.value("--username")?),
                 "--password" => out.password = Some(iter.value("--password")?),
+                "--max" => out.max_connections = parse_max("--max", &iter.value("--max")?)?,
+                "--handshake-timeout" => {
+                    out.handshake_timeout =
+                        parse_duration("--handshake-timeout", &iter.value("--handshake-timeout")?)?
+                }
+                "--idle-timeout" => {
+                    out.idle_timeout =
+                        parse_duration("--idle-timeout", &iter.value("--idle-timeout")?)?
+                }
                 _ if arg.starts_with('-') => {
                     return Err(ParseAction::error(format!("unknown option `{arg}`")));
                 }
@@ -48,3 +74,49 @@ pub(super) fn parse(args: Vec<String>) -> Result<Socks5Args, ParseAction> {
     }
     Ok(out)
 }
+
+fn parse_max(flag: &str, value: &str) -> Result<usize, ParseAction> {
+    value
+        .parse()
+        .ok()
+        .filter(|value| *value > 0)
+        .ok_or_else(|| ParseAction::error(format!("{flag} expects a positive integer")))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn defaults_connection_governance() {
+        let args = parse(vec![]).unwrap();
+        assert_eq!(args.max_connections, DEFAULT_MAX_CONNECTIONS);
+        assert_eq!(args.handshake_timeout, DEFAULT_HANDSHAKE_TIMEOUT);
+        assert_eq!(args.idle_timeout, DEFAULT_IDLE_TIMEOUT);
+    }
+
+    #[test]
+    fn accepts_connection_governance_options() {
+        let args = parse(
+            ["--max=4", "--handshake-timeout=2s", "--idle-timeout=30s"]
+                .into_iter()
+                .map(str::to_string)
+                .collect(),
+        )
+        .unwrap();
+        assert_eq!(args.max_connections, 4);
+        assert_eq!(args.handshake_timeout, Duration::from_secs(2));
+        assert_eq!(args.idle_timeout, Duration::from_secs(30));
+    }
+
+    #[test]
+    fn rejects_invalid_connection_governance_options() {
+        for args in [
+            vec!["--max=0"],
+            vec!["--handshake-timeout=0s"],
+            vec!["--idle-timeout=invalid"],
+        ] {
+            assert!(parse(args.into_iter().map(str::to_string).collect()).is_err());
+        }
+    }
+}

src/cli/socks5.rs

@@ -177,6 +177,9 @@ pub struct Socks5Args {
     pub bind: Option<IpAddr>,
     pub username: Option<String>,
     pub password: Option<String>,
+    pub max_connections: usize,
+    pub handshake_timeout: std::time::Duration,
+    pub idle_timeout: std::time::Duration,
 }
 
 #[derive(Debug, Clone, Default)]