Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

feat(agent): --gateway-insecure-tls for self-signed gateway APIs (#88)

luolei127b1b2cac75
diff --git a/apps/agent/internal/agent/runner.go b/apps/agent/internal/agent/runner.go
index fcc59d7..42494cc 100644
--- a/apps/agent/internal/agent/runner.go
+++ b/apps/agent/internal/agent/runner.go
@@ -6,6 +6,7 @@ import (
"context"
"crypto/md5"
"crypto/rand"
+ "crypto/tls"
"encoding/hex"
"encoding/json"
"fmt"
@@ -99,6 +100,14 @@ const preexistingFlowGraceMs = 5_000
func NewRunner(cfg config.Config) *Runner {
httpClient := &http.Client{Timeout: cfg.RequestTimeout}
+ gatewayHTTPClient := &http.Client{Timeout: cfg.RequestTimeout}
+ if cfg.GatewayInsecureTLS {
+ transport := http.DefaultTransport.(*http.Transport).Clone()
+ // Explicit opt-in for self-signed gateway APIs on a trusted LAN only.
+ transport.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
+ gatewayHTTPClient.Transport = transport
+ log.Printf("[agent:%s] warning: gateway TLS certificate verification is disabled; use only on a trusted LAN", cfg.AgentID)
+ }
hostname, _ := os.Hostname()
if hostname == "" {
hostname = "unknown-host"
@@ -107,7 +116,7 @@ func NewRunner(cfg config.Config) *Runner {
return &Runner{
cfg: cfg,
httpClient: httpClient,
- gatewayClient: gateway.NewClient(httpClient, cfg.GatewayType, cfg.GatewayEndpoint, cfg.GatewayToken),
+ gatewayClient: gateway.NewClient(gatewayHTTPClient, cfg.GatewayType, cfg.GatewayEndpoint, cfg.GatewayToken),
hostname: hostname,
queue: make([]domain.TrafficUpdate, 0, cfg.ReportBatchSize*2),
flows: make(map[string]trackedFlow, 2048),
diff --git a/apps/agent/internal/agent/runner_test.go b/apps/agent/internal/agent/runner_test.go
index 72da24c..e0fa70f 100644
--- a/apps/agent/internal/agent/runner_test.go
+++ b/apps/agent/internal/agent/runner_test.go
@@ -1,6 +1,11 @@
package agent
import (
+ "context"
+ "crypto/tls"
+ "errors"
+ "net/http"
+ "net/http/httptest"
"testing"
"time"
@@ -8,6 +13,66 @@ import (
"github.com/foru17/neko-master/apps/agent/internal/domain"
)
+func TestGatewayInsecureTLS(t *testing.T) {
+ server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ switch r.URL.Path {
+ case "/connections":
+ _, _ = w.Write([]byte(`{"connections":[{"id":"tls-flow","upload":10,"download":20}]}`))
+ case "/v1/requests/recent":
+ _, _ = w.Write([]byte(`{"requests":[{"id":"tls-flow","outBytes":10,"inBytes":20}]}`))
+ case "/api/agent/report":
+ _, _ = w.Write([]byte(`{}`))
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer server.Close()
+
+ for _, gatewayType := range []string{"clash", "surge"} {
+ t.Run(gatewayType, func(t *testing.T) {
+ // Check the default after opting in to catch mutation of DefaultTransport.
+ for _, tc := range []struct {
+ name string
+ insecure bool
+ }{
+ {name: "enabled", insecure: true},
+ {name: "disabled", insecure: false},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ runner := NewRunner(config.Config{
+ ServerAPIBase: server.URL + "/api",
+ GatewayType: gatewayType,
+ GatewayEndpoint: server.URL,
+ GatewayInsecureTLS: tc.insecure,
+ RequestTimeout: time.Second,
+ })
+ snapshots, err := runner.gatewayClient.Collect(context.Background())
+ if tc.insecure {
+ if err != nil {
+ t.Fatalf("gateway should accept a self-signed certificate when enabled: %v", err)
+ }
+ if len(snapshots) != 1 || snapshots[0].ID != "tls-flow" || snapshots[0].Upload != 10 || snapshots[0].Download != 20 {
+ t.Fatalf("unexpected gateway response: %+v", snapshots)
+ }
+ } else {
+ var verificationErr *tls.CertificateVerificationError
+ if !errors.As(err, &verificationErr) {
+ t.Fatalf("gateway should reject a self-signed certificate when disabled, got: %v", err)
+ }
+ }
+
+ err = runner.postJSON(context.Background(), "/agent/report", reportPayload{})
+ var verificationErr *tls.CertificateVerificationError
+ if !errors.As(err, &verificationErr) {
+ t.Fatalf("reporting must always reject a self-signed certificate, got: %v", err)
+ }
+ })
+ }
+ })
+ }
+}
+
func TestIngestSnapshotsDeltaCalculation(t *testing.T) {
runner := NewRunner(config.Config{
ServerAPIBase: "http://localhost:3000/api",
diff --git a/apps/agent/internal/config/config.go b/apps/agent/internal/config/config.go
index 14d6da8..57aeb35 100644
--- a/apps/agent/internal/config/config.go
+++ b/apps/agent/internal/config/config.go
@@ -6,6 +6,8 @@ import (
"errors"
"flag"
"fmt"
+ "os"
+ "strconv"
"strings"
"time"
)
@@ -29,6 +31,7 @@ type Config struct {
GatewayType string
GatewayEndpoint string
GatewayToken string
+ GatewayInsecureTLS bool
ReportInterval time.Duration
HeartbeatInterval time.Duration
GatewayPollInterval time.Duration
@@ -49,6 +52,7 @@ func Parse(args []string) (Config, error) {
gatewayType := fs.String("gateway-type", "clash", "Gateway type: clash or surge")
gatewayURL := fs.String("gateway-url", "", "Gateway control endpoint URL")
gatewayToken := fs.String("gateway-token", "", "Gateway secret token (optional)")
+ gatewayInsecureTLS := fs.Bool("gateway-insecure-tls", false, "Skip gateway TLS certificate verification (trusted LAN only; env NEKO_GATEWAY_INSECURE_TLS)")
logEnabled := fs.Bool("log", true, "Enable runtime logs (set false to disable)")
reportInterval := fs.Duration("report-interval", 2*time.Second, "Report interval, e.g. 2s")
@@ -75,6 +79,20 @@ func Parse(args []string) (Config, error) {
return Config{}, ErrVersion
}
+ gatewayInsecureTLSSet := false
+ fs.Visit(func(f *flag.Flag) {
+ if f.Name == "gateway-insecure-tls" {
+ gatewayInsecureTLSSet = true
+ }
+ })
+ if value := strings.TrimSpace(os.Getenv("NEKO_GATEWAY_INSECURE_TLS")); value != "" && !gatewayInsecureTLSSet {
+ enabled, err := strconv.ParseBool(value)
+ if err != nil {
+ return Config{}, fmt.Errorf("invalid NEKO_GATEWAY_INSECURE_TLS: %w", err)
+ }
+ *gatewayInsecureTLS = enabled
+ }
+
if strings.TrimSpace(*serverURL) == "" || *backendID <= 0 || strings.TrimSpace(*backendToken) == "" || strings.TrimSpace(*gatewayURL) == "" {
return Config{}, errors.New("server-url, backend-id, backend-token, gateway-url are required")
}
@@ -115,6 +133,7 @@ func Parse(args []string) (Config, error) {
GatewayType: gt,
GatewayEndpoint: normalizeGatewayEndpoint(gt, *gatewayURL),
GatewayToken: strings.TrimSpace(*gatewayToken),
+ GatewayInsecureTLS: *gatewayInsecureTLS,
ReportInterval: *reportInterval,
HeartbeatInterval: *heartbeatInterval,
GatewayPollInterval: *gatewayPollInterval,
@@ -141,6 +160,7 @@ func Usage() string {
" --log enable runtime logs (default true, set --log=false to disable)",
" --gateway-type clash|surge (default clash)",
" --gateway-token Gateway secret",
+ " --gateway-insecure-tls Skip gateway TLS certificate verification (default false; env NEKO_GATEWAY_INSECURE_TLS; trusted LAN only)",
" --report-interval default 2s",
" --heartbeat-interval default 30s",
" --gateway-poll-interval default 2s",
diff --git a/apps/agent/internal/config/config_test.go b/apps/agent/internal/config/config_test.go
new file mode 100644
index 0000000..4163eb7
--- /dev/null
+++ b/apps/agent/internal/config/config_test.go
@@ -0,0 +1,48 @@
+package config
+
+import "testing"
+
+func TestParseGatewayInsecureTLS(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ env string
+ flag string
+ want bool
+ wantErr bool
+ }{
+ {name: "default"},
+ {name: "flag enabled", flag: "--gateway-insecure-tls", want: true},
+ {name: "env enabled", env: "true", want: true},
+ {name: "env disabled", env: "false"},
+ {name: "flag overrides env", env: "true", flag: "--gateway-insecure-tls=false"},
+ {name: "flag enables over env", env: "false", flag: "--gateway-insecure-tls=true", want: true},
+ {name: "invalid env", env: "invalid", wantErr: true},
+ {name: "flag overrides invalid env", env: "invalid", flag: "--gateway-insecure-tls=false"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Setenv("NEKO_GATEWAY_INSECURE_TLS", tc.env)
+ args := []string{
+ "--server-url", "https://collector.example.com",
+ "--backend-id", "1",
+ "--backend-token", "test-token",
+ "--gateway-url", "https://127.0.0.1:9090",
+ }
+ if tc.flag != "" {
+ args = append(args, tc.flag)
+ }
+ cfg, err := Parse(args)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatal("expected an error for invalid TLS configuration")
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("Parse returned error: %v", err)
+ }
+ if cfg.GatewayInsecureTLS != tc.want {
+ t.Fatalf("GatewayInsecureTLS = %t, want %t", cfg.GatewayInsecureTLS, tc.want)
+ }
+ })
+ }
+}
diff --git a/apps/agent/nekoagent b/apps/agent/nekoagent
index 0f6a022..e0265a2 100755
--- a/apps/agent/nekoagent
+++ b/apps/agent/nekoagent
@@ -240,6 +240,7 @@ set -- "\$AGENT_BIN" \
--gateway-url "\$NEKO_GATEWAY_URL"
[ -n "\${NEKO_GATEWAY_TOKEN:-}" ] && set -- "\$@" --gateway-token "\$NEKO_GATEWAY_TOKEN"
+set -- "\$@" --gateway-insecure-tls="\${NEKO_GATEWAY_INSECURE_TLS:-false}"
[ -n "\${NEKO_AGENT_ID:-}" ] && set -- "\$@" --agent-id "\$NEKO_AGENT_ID"
[ -n "\${NEKO_REPORT_INTERVAL:-}" ] && set -- "\$@" --report-interval "\$NEKO_REPORT_INTERVAL"
[ -n "\${NEKO_HEARTBEAT_INTERVAL:-}" ] && set -- "\$@" --heartbeat-interval "\$NEKO_HEARTBEAT_INTERVAL"
@@ -699,6 +700,7 @@ Quick add with flags (auto-starts by default):
--gateway-type <clash|surge> \
--gateway-url <url> \
[--gateway-token <token>] \
+ [--gateway-insecure-tls] \
[--no-start] # skip auto-start after add
Upgrade examples:
@@ -713,7 +715,7 @@ Config and runtime paths:
Required config keys:
NEKO_SERVER, NEKO_BACKEND_ID, NEKO_BACKEND_TOKEN, NEKO_GATEWAY_TYPE, NEKO_GATEWAY_URL
Optional keys:
- NEKO_GATEWAY_TOKEN, NEKO_LOG, NEKO_AGENT_ID, NEKO_REPORT_INTERVAL,
+ NEKO_GATEWAY_TOKEN, NEKO_GATEWAY_INSECURE_TLS, NEKO_LOG, NEKO_AGENT_ID, NEKO_REPORT_INTERVAL,
NEKO_HEARTBEAT_INTERVAL, NEKO_GATEWAY_POLL_INTERVAL, NEKO_REQUEST_TIMEOUT,
NEKO_REPORT_BATCH_SIZE, NEKO_MAX_PENDING_UPDATES, NEKO_STALE_FLOW_TIMEOUT
@@ -780,6 +782,7 @@ build_agent_args() {
if [ -n "${NEKO_GATEWAY_TOKEN:-}" ]; then
set -- "$@" --gateway-token "$NEKO_GATEWAY_TOKEN"
fi
+ set -- "$@" --gateway-insecure-tls="${NEKO_GATEWAY_INSECURE_TLS:-false}"
if [ -n "${NEKO_AGENT_ID:-}" ]; then
set -- "$@" --agent-id "$NEKO_AGENT_ID"
fi
@@ -835,7 +838,7 @@ cmd_add() {
if [ "$#" -lt 6 ]; then
err "add requires: <name> --server-url <url> --backend-id <id> --backend-token <token> --gateway-type <type> --gateway-url <url>"
echo ""
- echo "Usage: $PROG add <name> --server-url <url> --backend-id <id> --backend-token <token> --gateway-type <clash|surge> --gateway-url <url> [--gateway-token <token>] [--auto-start]"
+ echo "Usage: $PROG add <name> --server-url <url> --backend-id <id> --backend-token <token> --gateway-type <clash|surge> --gateway-url <url> [--gateway-token <token>] [--gateway-insecure-tls] [--auto-start]"
exit 1
fi
@@ -849,6 +852,7 @@ cmd_add() {
gateway_type=""
gateway_url=""
gateway_token=""
+ gateway_insecure_tls="${NEKO_GATEWAY_INSECURE_TLS:-false}"
auto_start="true" # default: start immediately after add
while [ "$#" -gt 0 ]; do
@@ -877,6 +881,14 @@ cmd_add() {
gateway_token="$2"
shift 2
;;
+ --gateway-insecure-tls)
+ gateway_insecure_tls="true"
+ shift
+ ;;
+ --gateway-insecure-tls=*)
+ gateway_insecure_tls="${1#*=}"
+ shift
+ ;;
--auto-start)
auto_start="true"
shift
@@ -906,6 +918,7 @@ cmd_add() {
config_vars="$config_vars NEKO_BACKEND_TOKEN=$backend_token"
config_vars="$config_vars NEKO_GATEWAY_TYPE=$gateway_type"
config_vars="$config_vars NEKO_GATEWAY_URL=$gateway_url"
+ config_vars="$config_vars NEKO_GATEWAY_INSECURE_TLS=$gateway_insecure_tls"
if [ -n "$gateway_token" ]; then
config_vars="$config_vars NEKO_GATEWAY_TOKEN=$gateway_token"
fi
diff --git a/docs/agent/install.en.md b/docs/agent/install.en.md
index 571e1f1..c53c523 100644
--- a/docs/agent/install.en.md
+++ b/docs/agent/install.en.md
@@ -66,6 +66,14 @@ nekoagent uninstall
3. Extract `neko-agent`
4. Run executable with backend parameters
+### Optional gateway flags
+
+| Flag | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `--gateway-insecure-tls` | `NEKO_GATEWAY_INSECURE_TLS` | `false` | Skip gateway API TLS certificate verification for self-signed Surge `http-api-tls` / mihomo `external-controller-tls` certificates. Use only on a trusted LAN. Server reporting still verifies certificates. |
+
+Append `--gateway-insecure-tls` to `nekoagent add` to persist the setting. For an existing instance, set `NEKO_GATEWAY_INSECURE_TLS=true` in `/etc/neko-agent/<name>.env` and restart it.
+
## OpenWrt note
Before build selection, check architecture:
diff --git a/docs/agent/install.md b/docs/agent/install.md
index 557406c..a9eb8e8 100644
--- a/docs/agent/install.md
+++ b/docs/agent/install.md
@@ -66,6 +66,14 @@ nekoagent uninstall
3. 解压 `neko-agent`
4. 携带后端参数直接运行可执行文件
+### 可选网关参数
+
+| Flag | 环境变量 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `--gateway-insecure-tls` | `NEKO_GATEWAY_INSECURE_TLS` | `false` | 跳过网关 API 的 TLS 证书校验,适用于 Surge `http-api-tls` / mihomo `external-controller-tls` 自签证书;仅在可信局域网内使用。上报服务端仍校验证书。 |
+
+使用 `nekoagent add` 时可追加 `--gateway-insecure-tls`,管理器会持久化该配置;已有实例可在 `/etc/neko-agent/<name>.env` 中设置 `NEKO_GATEWAY_INSECURE_TLS=true` 后重启。
+
## 安装了哪些文件
安装脚本在 `NEKO_INSTALL_DIR`(默认 `~/.local/bin`)中放置两个二进制文件: