# Socks5-One

**Repository Path**: TheMoYu/socks5-one

## Basic Information

- **Project Name**: Socks5-One
- **Description**: No description available
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Socks5-One

一个轻量、安全、企业级可观测的 SOCKS5 代理服务器，使用 C# / .NET 10 实现。支持 RFC 1928（CONNECT / BIND / UDP ASSOCIATE）与 RFC 1961（GSSAPI 认证，含保护级别 1/2/3），内置 ACL、限流与暴力破解防护、指标导出与结构化审计日志。

## 特性

- **完整 SOCKS5 命令**：CONNECT、BIND（双向）、UDP ASSOCIATE（含分片重组）。
- **三种认证方式**：无认证、用户名/密码（`USERNAME/PASSWORD`，RFC 1929）、GSSAPI（Kerberos/NTLM，SSPI）。
- **GSSAPI 保护级别**：level 1（仅认证/明文）、level 2（完整性 MIC）、level 3（机密性加密），线缆格式严格遵循 RFC 1961。
- **访问控制（ACL）**：基于域名后缀、CIDR（IPv4/IPv6，含 IPv4 映射 IPv6 归一化）、端口的 allow/deny 规则；fail-closed 保守拒绝；国际化域名（Punycode）归一化。
- **限流与暴力破解防护**：单 IP 并发上限、单 IP 每秒新建连接速率（滑动窗口）、认证失败封禁；全部使用单调时钟，规避系统校时影响。
- **UDP 反射防护**：仅回送已转发目标的应答，源端点（IP+端口）严格匹配，防 SSRF/反射放大。
- **可观测性**：Prometheus 文本格式 `/metrics` + 存活探针 `/healthz`（仅本机回环可访问），后台周期指标日志。
- **结构化审计日志**：可选 JSON 格式，有界通道 + 异常隔离，避免日志写入阻塞主流程。
- **部署就绪**：提供 systemd service 单元与 Dockerfile（curl 探活）。

## 构建与运行

```bash
# 还原并构建
dotnet build -c Release

# 直接运行（默认监听 0.0.0.0:1080，无认证）
dotnet run --project Socks5-One

# 发布为独立可执行文件
dotnet publish Socks5-One -c Release -o ./publish
```

要求 **.NET 10 SDK**。

## 快速开始

```bash
# 无认证，监听回环（安全默认）
dotnet run --project Socks5-One -- -b 127.0.0.1 -p 1080

# 用户名/密码认证
dotnet run --project Socks5-One -- -u admin --pass "S3cret!" -b 0.0.0.0 -p 1080

# 从文件读取密码（避免密码出现在进程参数/历史中）
dotnet run --project Socks5-One -- -u admin --pass-file /run/secrets/socks5.pass

# 启用 GSSAPI（Kerberos/NTLM，Windows 需域环境）
dotnet run --project Socks5-One -- -g -b 0.0.0.0 -p 1080
```

> ⚠️ 当未启用任何强认证（`-u/--pass`、`--pass-file` 或 `-g`）且绑定到非回环地址时，程序会向 stderr 输出 `[Security] WARNING` 提示这是一个可被网络访问的开放代理。

## 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-p`, `--port <n>` | 监听端口（1–65535） | 1080 |
| `-b`, `--bind <addr>` | 绑定地址（IP 字面量） | `0.0.0.0` |
| `-u`, `--user <name>` | 用户名（需配合 `--pass`/`--pass-file`） | 无 |
| `--pass <pwd>` | 密码 | 无 |
| `--pass-file <path>` | 从文件读取密码（去除首尾空白） | 无 |
| `--pass-env <VAR>` | 从环境变量读取密码 | 无 |
| `-g`, `--gssapi` | 启用 GSSAPI 认证 | 关闭 |
| `-m`, `--max-conn <n>` | 全局最大并发连接（≥1） | 1024 |
| `-a`, `--allow <rule>` | ACL 允许规则（可多次） | 无 |
| `--deny <rule>` | ACL 拒绝规则（可多次） | 无 |
| `-l`, `--log <path>` | 审计日志文件路径 | 无（仅控制台） |
| `--json-log` | 审计日志使用 JSON 格式 | 关闭 |
| `--dns-ttl <sec>` | DNS 缓存 TTL（秒，>0） | 60 |
| `--metrics-port <n>` | 指标端口（0=禁用） | 9090 |
| `--metrics-bind <addr>` | 指标绑定地址 | `127.0.0.1` |
| `--max-conns-per-ip <n>` | 单 IP 并发上限（0=不限制） | 64 |
| `--connect-rate-per-ip <n>` | 单 IP 每秒新建连接上限（0=不限制） | 30 |
| `--max-auth-fail <n>` | 单 IP 认证失败封禁阈值（0=不限制） | 5 |
| `--auth-ban-min <n>` | 封禁时长（分钟） | 10 |
| `-h`, `--help` | 显示帮助 | |

## 配置文件（appsettings.json）

支持三层覆盖，优先级：**命令行 > 环境变量 > appsettings.json > 内置默认值**。

```json
{
  "Port": 1080,
  "BindAddress": "0.0.0.0",
  "Username": null,
  "Password": null,
  "MaxConnections": 1024,
  "LogPath": null,
  "GssApi": false,
  "DnsTtlSeconds": 60,
  "JsonLog": false,
  "Allow": [],
  "Deny": [],
  "MetricsPort": 9090,
  "MetricsBind": "127.0.0.1",
  "MaxConnsPerIp": 64,
  "ConnectRatePerIp": 30,
  "MaxAuthFailuresPerIp": 5,
  "AuthBanMinutes": 10
}
```

环境变量使用 `SOCKS5_` 前缀，例如 `SOCKS5_PORT=1080`、`SOCKS5_USER=admin`、`SOCKS5_PASS=xxx`、`SOCKS5_MAXCONN=2048`。

### ACL 规则语法

- 域名后缀：`example.com`（匹配 `example.com` 及其子域 `*.example.com`）
- CIDR：`192.168.0.0/16`、`10.0.0.0/8`、`2001:db8::/32`
- 单 IP：`203.0.113.5`
- 带端口：`1.2.3.4:443`（仅该端口放行/拒绝）
- 全部放行/拒绝：`*`（用于白名单模式下兜底）
- 国际化域名：可用 Punycode（`xn--mnchen-3ya.de`）或 Unicode（`münchen.de`）书写，内部归一化

deny 规则优先于 allow；存在 allow 规则时采用白名单模式（未匹配 allow 即拒绝）。

## 可观测性

启用指标端点后（`--metrics-port` 非 0，默认 9090）：

- `GET /metrics`：Prometheus 文本格式，导出活跃连接、CONNECT 成败、BIND/UDP 计数、认证失败、限流拒绝、ACL 拒绝、转发字节数、UDP 包量等。
- `GET /healthz`：存活探针，返回 `200 OK`。

指标端点**仅接受本机回环来源**，即使 `MetricsBind` 被误配为通配地址也不会泄露给网络。

## 部署

### systemd

示例单元见 `deploy/socks5-one.service`：

```bash
cp deploy/socks5-one.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now socks5-one
```

服务以 `--pass-file` 读取凭据，避免明文出现在单元文件中。

### Docker

提供 `deploy/Dockerfile`（多阶段构建，curl 探活）。构建并运行：

```bash
docker build -f deploy/Dockerfile -t socks5-one .
docker run -p 1080:1080 -p 9090:9090 socks5-one
```

## 测试

```bash
# 单元/集成测试（无需特殊环境）
dotnet test Socks5-One/Socks5-One.Tests/Socks5-One.Tests.csproj

# GSSAPI 端到端冒烟（需 Windows + 可用 NTLM/Kerberos；非 Windows 自动 SKIP）
dotnet run --project GssApiSmoke
```

测试覆盖：协议编解码、ACL（CIDR/域名/Punycode/端口）、限流与封禁、UDP 分片重组与反射防护、BIND 双向、GSSAPI 帧封装与保护级别协商、配置三层覆盖，以及进程级安全自检（开放代理告警、非法配置拒绝启动）。

## 安全说明

- 生产环境**务必启用认证**（`-u/--pass`、`--pass-file` 或 `-g`）并绑定到受信任网络或回环地址。
- ACL 采用 fail-closed：域名解析失败/超时、未知目标一律保守拒绝。
- UDP 关联严格校验源端点，防止被用于反射放大攻击。
- 所有外部输入（地址类型、Punycode、帧长度）均做了边界与异常隔离处理。

## 免责声明

1. 本软件按"现状"提供，作者与贡献者不对软件的正确性、可靠性、适用性作任何明示或暗示担保，包括但不限于对特定用途的适用性与不侵权的担保。
2. 使用本软件所产生的任何直接或间接后果（包括但不限于数据泄露、服务中断、被滥用为开放代理、违反所在地法律法规等）均由使用者自行承担，作者与贡献者不承担任何法律责任。
3. 使用者须确保对部署环境拥有合法授权，并遵守所在国家/地区关于代理、加密与网络访问的相关法律法规；未经授权对他人网络进行代理转发、扫描或探测属违法行为。
4. 本软件仅供合法授权范围内的网络调试、内部访问与学习研究之用，禁止用于绕过访问控制、侵犯他人权益或任何非法目的。
5. 因使用、无法使用或依赖本软件而导致的任何损失、损害或第三方索赔，作者与贡献者概不负责，即使已被告知发生此类损害的可能性。
6. 本声明构成软件使用许可的一部分；继续下载、安装或使用即表示你已阅读、理解并同意上述全部条款。