diff --git a/CHANGELOG.md b/CHANGELOG.md index 353cebf8..1a00a208 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,7 +39,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - CI gates: unit tests with the race detector and coverage, golangci-lint (`make lint`), govulncheck (`make vuln`), and a `go mod tidy` check. - Release workflow: pushing a `v*` tag publishes a GitHub Release with `linux/amd64` and `linux/arm64` archives, checksums, and the matching `CHANGELOG.md` section. `scripts/dist.sh` builds the same archives locally. - `goclusterfs-fsck -version` prints the release version, commit, and commit date. -- HTTP API in `goclusterfs-mount` (`-api`, on by default): `/health`, `/metrics`, `/api/v1/status` and `/api/v1/stats/...`. It listens on `127.0.0.1:8080` (`-api-addr`). Mount refuses a non-loopback `-api-addr` without `-api-token`. +- HTTP API in `goclusterfs-mount` (`-api`, on by default): `/health`, `/metrics`, `/api/v1/status` and `/api/v1/stats/...`. It listens on `127.0.0.1:8080` (`-api-addr`). Mount refuses a non-loopback `-api-addr` or `-api-cors '*'` without `-api-token`, and checks the API flags before it opens the device. - `goclusterfs-mount -version`, which prints the same version string as `goclusterfs-fsck -version`. `/api/v1/status` reports it too. - Mount logs a `WARNING` line at startup when `-broadcast` is on without `-broadcast-secret`. - Design, deployment, operations, and troubleshooting docs in `docs/`. diff --git a/cmd/mount/main.go b/cmd/mount/main.go index 9e4d6003..db9a6849 100644 --- a/cmd/mount/main.go +++ b/cmd/mount/main.go @@ -3,6 +3,7 @@ package main import ( "context" + "errors" "flag" "fmt" "log" @@ -55,7 +56,7 @@ func (p *fsStatusProvider) Capacity() *api.CapacityInfo { freeBlocks := p.bitmapMgr.FreeCount() usedBlocks := totalBlocks - freeBlocks - const blockSize uint64 = 1024 * 1024 // 1MB blocks + const blockSize uint64 = goclusterfs.BlockSize totalBytes := totalBlocks * blockSize usedBytes := usedBlocks * blockSize freeBytes := freeBlocks * blockSize @@ -148,8 +149,15 @@ func main() { apiCfg := apiConfig(*apiAddr, *apiToken, *apiCORS) if *apiEnabled { + if err := apiCfg.Validate(); err != nil { + log.Fatalf("Invalid API settings: %v", err) + } if err := apiCfg.CheckExposure(); err != nil { - log.Fatalf("Refusing to start the API: %v. Set -api-token, set -api-addr to a loopback address such as 127.0.0.1:8080, or pass -api=false", err) + hint := "set -api-addr to a loopback address such as 127.0.0.1:8080" + if errors.Is(err, api.ErrWildcardCORSWithoutToken) { + hint = "list the allowed origins in -api-cors" + } + log.Fatalf("Refusing to start the API: %v. Set -api-token, %s, or pass -api=false", err, hint) } } if *broadcastEnabled && *broadcastSecret == "" { diff --git a/docs/API-CONFIG.md b/docs/API-CONFIG.md index afa026d2..370f1c83 100644 --- a/docs/API-CONFIG.md +++ b/docs/API-CONFIG.md @@ -93,6 +93,8 @@ The kernel caches file attributes and directory entries for `-attr-timeout`. For The API serves `GET /health`, `GET /metrics`, `GET /api/v1/status` and `GET /api/v1/stats/...`. Mount does not feed statistics to the API yet, so `/api/v1/stats/...` answers 503, `/health` only checks the API itself, and `/metrics` only reports `goclusterfs_up`. With `-api-token` set, `/api/v1/...` requests need `Authorization: Bearer `. `/health` and `/metrics` never need the token. +Without `-api-token`, the API answers only requests whose `Host` header is `localhost`, a `127.x` address or `[::1]`, so a web page cannot reach it through DNS rebinding, and mount refuses `-api-cors '*'`. List the dashboard's origin instead, for example `-api-cors http://localhost:5173`. + By default the API only accepts connections from this host. To serve other hosts, set `-api-addr` (for example `:8080` or `10.0.0.5:8080`) and `-api-token`. Mount exits before it opens the device when the address is not loopback (`127.0.0.0/8`, `::1` or `localhost`) and the token is empty. The token is a command-line flag, so local users can read it with `ps`. Each mount on a host needs its own `-api-addr`. When the port is taken, mount logs a warning and runs without the API. diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 2d04cfad..a50271a1 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -532,6 +532,7 @@ GoClusterFS assumes every node, and everything that can reach the shared device - To expose it, set `-api-addr` and `-api-token`. Mount refuses a non-loopback address without a token. - `/health` and `/metrics` never need the token, so anyone who can reach the port can read them. +- Without a token, the API rejects requests whose `Host` header is not a loopback name, and mount refuses `-api-cors '*'`. Both stop web pages that a local user opens from reading the API. - The API uses plain HTTP. Put a TLS proxy in front of it if the token crosses an untrusted network. - The token is a command-line flag, so local users can read it with `ps`. diff --git a/internal/api/config.go b/internal/api/config.go index ef4e4ca5..2b0b570f 100644 --- a/internal/api/config.go +++ b/internal/api/config.go @@ -4,6 +4,7 @@ import ( "fmt" "net" "net/url" + "slices" "strings" "time" ) @@ -133,11 +134,17 @@ func (c *Config) LoopbackOnly() bool { return ip != nil && ip.IsLoopback() } -// CheckExposure refuses a config that serves other hosts without an auth token. +// CheckExposure refuses a config that lets other hosts, or any web page, read the API without an auth token. func (c *Config) CheckExposure() error { - if c.AuthToken == "" && !c.LoopbackOnly() { + if c.AuthToken != "" { + return nil + } + if !c.LoopbackOnly() { return fmt.Errorf("%w: %s", ErrUnauthenticatedRemote, c.ListenAddr) } + if slices.Contains(c.CORSOrigins, "*") { + return ErrWildcardCORSWithoutToken + } return nil } diff --git a/internal/api/doc.go b/internal/api/doc.go index d73d2bd9..e0934b59 100644 --- a/internal/api/doc.go +++ b/internal/api/doc.go @@ -1,15 +1,13 @@ // Package api provides the HTTP JSON API server for GoClusterFS. // // The API server runs embedded within the mount process and exposes -// endpoints for health checks, status queries, statistics, and -// administrative operations. It is consumed by the gfsctl CLI tool -// and the web dashboard. +// read-only endpoints for health checks, status queries and statistics. // // # Endpoints // // The following endpoints are available: // -// - GET /health - Health check (always returns 200) +// - GET /health - Health check (503 when a checker reports unhealthy) // - GET /api/v1/status - Filesystem status overview // - GET /api/v1/stats/* - Detailed component statistics // - GET /metrics - Prometheus metrics export @@ -18,16 +16,19 @@ // // Authentication is via Bearer token when configured. Set the AuthToken // in Config to enable authentication. When enabled, all endpoints except -// /health require a valid Authorization header: +// /health and /metrics require a valid Authorization header: // // Authorization: Bearer // +// Without a token, Config.CheckExposure refuses non-loopback addresses and +// CORS "*", and the server rejects requests whose Host is not a loopback name. +// // # Configuration // // Use DefaultConfig() to get sensible defaults, then customize as needed: // // cfg := api.DefaultConfig() -// cfg.ListenAddr = ":9090" +// cfg.ListenAddr = "127.0.0.1:9090" // cfg.AuthToken = "secret-token" // server, err := api.NewServer(cfg) // diff --git a/internal/api/errors.go b/internal/api/errors.go index ee229a5b..20d7c6f3 100644 --- a/internal/api/errors.go +++ b/internal/api/errors.go @@ -22,6 +22,9 @@ var ( // ErrUnauthenticatedRemote is returned when other hosts could reach the API without a token. ErrUnauthenticatedRemote = errors.New("api: no auth token set for an address other hosts can reach") + // ErrWildcardCORSWithoutToken is returned when CORS allows every origin and no token is set. + ErrWildcardCORSWithoutToken = errors.New("api: CORS origin \"*\" without an auth token lets any web page open on this host read the API") + // ErrShutdownTimeout is returned when graceful shutdown times out. ErrShutdownTimeout = errors.New("api: shutdown timed out") ) diff --git a/internal/api/exposure_test.go b/internal/api/exposure_test.go index b59c4ef6..d758e691 100644 --- a/internal/api/exposure_test.go +++ b/internal/api/exposure_test.go @@ -1,7 +1,9 @@ package api import ( + "context" "errors" + "net/http" "testing" ) @@ -38,3 +40,101 @@ func TestDefaultConfigPassesExposureCheck(t *testing.T) { t.Fatalf("default config refused: %v", err) } } + +func TestCheckExposureRefusesWildcardCORSWithoutToken(t *testing.T) { + cfg := DefaultConfig().WithCORSOrigins("*") + if err := cfg.CheckExposure(); !errors.Is(err, ErrWildcardCORSWithoutToken) { + t.Fatalf("CORS * without token: got %v, want ErrWildcardCORSWithoutToken", err) + } + cfg = cfg.WithAuthToken("secret") + if err := cfg.CheckExposure(); err != nil { + t.Fatalf("CORS * with token refused: %v", err) + } + cfg = DefaultConfig().WithCORSOrigins("http://localhost:5173") + if err := cfg.CheckExposure(); err != nil { + t.Fatalf("listed CORS origin refused: %v", err) + } +} + +func get(t *testing.T, srv *Server, path, host string, header map[string]string) *http.Response { + t.Helper() + req, err := http.NewRequest(http.MethodGet, "http://"+srv.Addr()+path, nil) + if err != nil { + t.Fatal(err) + } + if host != "" { + req.Host = host + } + for k, v := range header { + req.Header.Set(k, v) + } + resp, err := http.DefaultClient.Do(req) + if err != nil { + t.Fatal(err) + } + resp.Body.Close() + return resp +} + +func startServer(t *testing.T, cfg Config) *Server { + t.Helper() + srv, err := NewServer(cfg) + if err != nil { + t.Fatal(err) + } + if err := srv.Start(context.Background()); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { srv.Stop() }) + return srv +} + +func TestTokenlessLoopbackServerRejectsForeignHost(t *testing.T) { + srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0")) + for host, want := range map[string]int{ + "": http.StatusOK, + "localhost:8080": http.StatusOK, + "LOCALHOST": http.StatusOK, + "[::1]:8080": http.StatusOK, + "127.0.0.2": http.StatusOK, + "evil.example": http.StatusForbidden, + "evil.example:80": http.StatusForbidden, + "10.0.0.5:8080": http.StatusForbidden, + } { + if got := get(t, srv, "/api/v1/status", host, nil).StatusCode; got != want { + t.Errorf("Host %q: status %d, want %d", host, got, want) + } + } +} + +func TestTokenServerSkipsHostCheck(t *testing.T) { + srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0").WithAuthToken("secret")) + resp := get(t, srv, "/api/v1/status", "evil.example", map[string]string{"Authorization": "Bearer secret"}) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status %d, want 200", resp.StatusCode) + } +} + +func TestAuthSkipsOnlyExactPaths(t *testing.T) { + srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0").WithAuthToken("secret")) + for _, path := range []string{"/health/x", "/metrics/x"} { + if got := get(t, srv, path, "", nil).StatusCode; got != http.StatusUnauthorized { + t.Errorf("%s without token: status %d, want 401", path, got) + } + } + if got := get(t, srv, "/health", "", nil).StatusCode; got != http.StatusOK { + t.Errorf("/health without token: status %d, want 200", got) + } +} + +func TestCORSHeaders(t *testing.T) { + srv := startServer(t, DefaultConfig().WithListenAddr("127.0.0.1:0").WithCORSOrigins("http://localhost:5173")) + resp := get(t, srv, "/health", "", map[string]string{"Origin": "http://other.example"}) + if resp.Header.Get("Vary") != "Origin" { + t.Errorf("Vary = %q, want Origin", resp.Header.Get("Vary")) + } + resp = get(t, srv, "/health", "", map[string]string{"Origin": "http://localhost:5173"}) + if got := resp.Header.Get("Access-Control-Allow-Methods"); got != "GET, HEAD, OPTIONS" { + t.Errorf("Allow-Methods = %q, want GET, HEAD, OPTIONS", got) + } +} diff --git a/internal/api/middleware.go b/internal/api/middleware.go index 3d267d19..ce904213 100644 --- a/internal/api/middleware.go +++ b/internal/api/middleware.go @@ -3,6 +3,7 @@ package api import ( "crypto/subtle" "log" + "net" "net/http" "strings" "time" @@ -61,7 +62,7 @@ func AuthMiddleware(token string, skipPaths ...string) Middleware { // Check if path should skip auth for _, path := range skipPaths { - if r.URL.Path == path || strings.HasPrefix(r.URL.Path, path+"/") { + if r.URL.Path == path { next.ServeHTTP(w, r) return } @@ -103,6 +104,7 @@ func CORSMiddleware(origins []string) Middleware { next.ServeHTTP(w, r) return } + w.Header().Add("Vary", "Origin") origin := r.Header.Get("Origin") if origin == "" { @@ -111,22 +113,22 @@ func CORSMiddleware(origins []string) Middleware { } // Check if origin is allowed - allowed := false + allowOrigin := "" for _, o := range origins { if o == "*" || o == origin { - allowed = true + allowOrigin = o break } } - if !allowed { + if allowOrigin == "" { next.ServeHTTP(w, r) return } // Set CORS headers - w.Header().Set("Access-Control-Allow-Origin", origin) - w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS") + w.Header().Set("Access-Control-Allow-Origin", allowOrigin) + w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS") w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type") w.Header().Set("Access-Control-Max-Age", "86400") @@ -140,3 +142,28 @@ func CORSMiddleware(origins []string) Middleware { }) } } + +// LoopbackHostMiddleware rejects requests whose Host header is not a loopback +// name, so a DNS-rebinding web page cannot read an API that has no token. +func LoopbackHostMiddleware(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if !isLoopbackHost(r.Host) { + writeError(w, http.StatusForbidden, "host not allowed", "without an auth token, use localhost, 127.0.0.1 or [::1]") + return + } + next.ServeHTTP(w, r) + }) +} + +func isLoopbackHost(hostport string) bool { + host := hostport + if h, _, err := net.SplitHostPort(hostport); err == nil { + host = h + } + host = strings.TrimSuffix(strings.Trim(host, "[]"), ".") + if strings.EqualFold(host, "localhost") { + return true + } + ip := net.ParseIP(host) + return ip != nil && ip.IsLoopback() +} diff --git a/internal/api/middleware_test.go b/internal/api/middleware_test.go index b43e6a72..992fca55 100644 --- a/internal/api/middleware_test.go +++ b/internal/api/middleware_test.go @@ -281,8 +281,8 @@ func TestCORSMiddleware_Wildcard(t *testing.T) { defer resp.Body.Close() cors := resp.Header.Get("Access-Control-Allow-Origin") - if cors != "http://any-origin.com" { - t.Errorf("expected CORS header 'http://any-origin.com', got %q", cors) + if cors != "*" { + t.Errorf("expected CORS header '*', got %q", cors) } } diff --git a/internal/api/server.go b/internal/api/server.go index c31d1cc8..8d13356c 100644 --- a/internal/api/server.go +++ b/internal/api/server.go @@ -51,13 +51,16 @@ func NewServer(cfg Config) (*Server, error) { // Register routes s.registerRoutes() - // Build middleware chain (order: logging -> CORS -> auth) - handler := Chain( - s.router, - LoggingMiddleware, + // Build middleware chain (order: logging -> loopback Host check -> CORS -> auth) + middlewares := []Middleware{LoggingMiddleware} + if cfg.AuthToken == "" && cfg.LoopbackOnly() { + middlewares = append(middlewares, LoopbackHostMiddleware) + } + middlewares = append(middlewares, CORSMiddleware(cfg.CORSOrigins), AuthMiddleware(cfg.AuthToken, "/health", "/metrics"), ) + handler := Chain(s.router, middlewares...) // Create HTTP server s.server = &http.Server{ diff --git a/tests/integration/api_test.go b/tests/integration/api_test.go index 6e23f99e..7b7eb3c8 100644 --- a/tests/integration/api_test.go +++ b/tests/integration/api_test.go @@ -27,11 +27,8 @@ func freeLoopbackAddr(t *testing.T) string { func TestAPIServesHealthOnLoopback(t *testing.T) { mfs := NewMountedFS(t, 20) - if err := mfs.Format(); err != nil { - t.Fatalf("Format failed: %v", err) - } addr := freeLoopbackAddr(t) - mfs.ExtraArgs = []string{"-api-addr", addr} + mfs.ExtraArgs = []string{"-format", "-api-addr", addr} if err := mfs.Mount(false); err != nil { t.Fatalf("Mount failed: %v", err) } @@ -102,3 +99,55 @@ func TestMountRefusesUnauthenticatedRemoteAPI(t *testing.T) { t.Error("refused mount still wrote a superblock") } } + +func runMount(t *testing.T, args ...string) (string, error) { + t.Helper() + binary, err := findBinary() + if err != nil { + t.Fatalf("Failed to find binary: %v", err) + } + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + out, err := exec.CommandContext(ctx, binary, args...).CombinedOutput() + if ctx.Err() != nil { + t.Fatalf("goclusterfs-mount %v did not exit", args) + } + return string(out), err +} + +func TestMountPrintsVersion(t *testing.T) { + out, err := runMount(t, "-version") + if err != nil || !strings.HasPrefix(out, "goclusterfs-mount ") { + t.Fatalf("-version: err=%v output=%q", err, out) + } +} + +func TestMountWarnsWithoutBroadcastSecret(t *testing.T) { + dir := t.TempDir() + missing := filepath.Join(dir, "missing.img") + const warning = "WARNING: -broadcast is on without -broadcast-secret" + + if out, _ := runMount(t, "-device", missing, "-mount", dir); !strings.Contains(out, warning) { + t.Errorf("no warning without a secret:\n%s", out) + } + for _, flag := range []string{"-broadcast-secret=x", "-broadcast=false"} { + if out, _ := runMount(t, "-device", missing, "-mount", dir, flag); strings.Contains(out, warning) { + t.Errorf("warning with %s:\n%s", flag, out) + } + } +} + +func TestMountRejectsBadAPISettingsBeforeOpeningDevice(t *testing.T) { + dir := t.TempDir() + missing := filepath.Join(dir, "missing.img") + for _, tt := range []struct{ flag, want string }{ + {"-api-addr=127.0.0.1", "Invalid API settings"}, + {"-api-cors=not-a-url", "Invalid API settings"}, + {"-api-cors=*", "-api-cors"}, + } { + out, err := runMount(t, "-device", missing, "-mount", dir, tt.flag) + if err == nil || !strings.Contains(out, tt.want) || strings.Contains(out, "Failed to open device") { + t.Errorf("%s: err=%v, want an error mentioning %q before the device opens:\n%s", tt.flag, err, tt.want, out) + } + } +} diff --git a/tests/test-manifest.yaml b/tests/test-manifest.yaml index 205ddbff..b95b270d 100644 --- a/tests/test-manifest.yaml +++ b/tests/test-manifest.yaml @@ -2268,3 +2268,24 @@ scenarios: priority: go_only environments: go: api_test.go::TestMountRefusesUnauthenticatedRemoteAPI + + - id: mount-version-flag + name: Mount prints its version + description: goclusterfs-mount -version exits 0 and prints the version string + priority: go_only + environments: + go: api_test.go::TestMountPrintsVersion + + - id: broadcast-secret-warning + name: Mount warns about unauthenticated broadcast + description: With broadcast on and no -broadcast-secret, mount logs a WARNING line; with a secret or -broadcast=false it does not + priority: go_only + environments: + go: api_test.go::TestMountWarnsWithoutBroadcastSecret + + - id: api-settings-checked-before-device + name: Mount rejects bad API settings early + description: An -api-addr without a port, an invalid -api-cors, or -api-cors * without a token stop mount before it opens the device + priority: go_only + environments: + go: api_test.go::TestMountRejectsBadAPISettingsBeforeOpeningDevice