fix(static): reject encoded path separators that bypass route-level middleware

An encoded path separator in a static file URL could bypass route-level access
control and disclose files (GHSA-vfp3-v2gw-7wfq, CWE-22). The router matches
routes against the raw, still-encoded request path (by default), so %2F is not a
segment separator -- /admin%2Fsecret.txt never matches a protected /admin/* group
and falls through to the static handler, which then unescaped %2F back to "/" and
served admin/secret.txt from disk. The auth middleware on the group never ran.

Fixes, across both static serving paths:

- StaticDirectoryHandler (echo.go) and the static middleware (middleware/static.go)
  now reject a wildcard containing an encoded separator (%2F/%2f or %5C/%5c) with
  404 before unescaping, via a shared internal helper (internal/pathutil). No real
  filename contains a separator, so legitimate requests are unaffected.
- StaticDirectoryHandler resolves the file name with path.Clean instead of the
  OS-specific filepath.Clean. fs.FS paths are always forward-slash, so a decoded
  backslash must stay a literal character rather than being treated as a separator
  on Windows (the GHSA-pgvm-wxw2-hrv9 backslash traversal class), matching what
  middleware/static.go already does.
- Rejections return NewHTTPError(404).Wrap(...) carrying the offending path as an
  internal error, so logging middleware can observe the attempt while the client
  still sees a plain 404.

Tests cover the bypass and non-disclosure for %2F, %5C, double-encoded %252F, the
group StaticFS path, and the static middleware on a group, plus a unit test for
the separator detector.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vishr

echo.go

@@ -53,11 +53,14 @@ import (
 	"net/url"
 	"os"
 	"os/signal"
+	"path"
 	"path/filepath"
 	"strings"
 	"sync"
 	"sync/atomic"
 	"syscall"
+
+	"github.com/labstack/echo/v5/internal/pathutil"
 )
 
 // Echo is the top-level framework instance.
@@ -589,15 +592,28 @@ func StaticDirectoryHandler(fileSystem fs.FS, disablePathUnescaping bool) Handle
 	return func(c *Context) error {
 		p := c.Param("*")
 		if !disablePathUnescaping { // when router is already unescaping we do not want to do is twice
+			// By default the router matches routes against the raw, still-encoded request path
+			// (unless UseEscapedPathForMatching is enabled), so an encoded path separator is not
+			// treated as a segment boundary during routing. Unescaping it here would let it act as
+			// a separator and resolve a file outside the path the router authorized, bypassing
+			// route-level middleware (e.g. auth on a sibling route). No real filename contains a
+			// separator, so reject it as not found, carrying the reason internally for operators.
+			if pathutil.HasEncodedPathSeparator(p) {
+				return NewHTTPError(http.StatusNotFound, http.StatusText(http.StatusNotFound)).
+					Wrap(fmt.Errorf("rejected encoded path separator in static path %q", p))
+			}
 			tmpPath, err := url.PathUnescape(p)
 			if err != nil {
 				return fmt.Errorf("failed to unescape path variable: %w", err)
 			}
 			p = tmpPath
 		}
 
-		// fs.FS.Open() already assumes that file names are relative to FS root path and considers name with prefix `/` as invalid
-		name := filepath.ToSlash(filepath.Clean(strings.TrimPrefix(p, "/")))
+		// fs.FS.Open() already assumes that file names are relative to FS root path and considers name with prefix `/` as invalid.
+		// Use path.Clean (not filepath.Clean): fs.FS paths are always forward-slash, so a backslash must stay a literal
+		// character rather than being interpreted as a separator on Windows (which would resolve a file across a boundary
+		// the router never matched on, the same Windows backslash traversal class as GHSA-pgvm-wxw2-hrv9).
+		name := path.Clean(strings.TrimPrefix(p, "/"))
 		fi, err := fs.Stat(fileSystem, name)
 		if err != nil {
 			return ErrNotFound

echo_test.go

@@ -259,13 +259,16 @@ func TestEcho_StaticFS(t *testing.T) {
 			expectBodyStartsWith: "{\"message\":\"Not Found\"}\n",
 		},
 		{
-			name:                 "open redirect vulnerability",
+			// An encoded slash (%2f) is rejected outright (GHSA-vfp3-v2gw-7wfq): by default the
+			// router matches on the raw path so %2f is not a separator, and unescaping it here
+			// would let it act as one. No redirect is emitted, closing the open-redirect vector.
+			name:                 "encoded slash is rejected, not redirected",
 			givenPrefix:          "/",
 			givenFs:              os.DirFS("_fixture/"),
 			whenURL:              "/open.redirect.hackercom%2f..",
-			expectStatus:         http.StatusMovedPermanently,
-			expectHeaderLocation: "/open.redirect.hackercom/../", // location starting with `//open` would be very bad
-			expectBodyStartsWith: "",
+			expectStatus:         http.StatusNotFound,
+			expectHeaderLocation: "",
+			expectBodyStartsWith: "{\"message\":\"Not Found\"}\n",
 		},
 	}
 

internal/pathutil/pathutil.go

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: © 2015 LabStack LLC and Echo contributors
+
+// Package pathutil holds internal helpers for safely handling request and file
+// paths. It is internal so it can be shared between the echo package and the
+// middleware package without becoming part of the public API.
+package pathutil
+
+// HasEncodedPathSeparator reports whether s contains a percent-encoded path
+// separator, case-insensitively: %2F/%2f (forward slash) or %5C/%5c (backslash).
+// Backslash is included as defense-in-depth against Windows-style separators even
+// though fs.FS itself only uses forward slashes.
+//
+// Such sequences let an attacker smuggle a separator past the router, which by
+// default matches on the raw encoded path, so they must be rejected before
+// unescaping when resolving static files.
+func HasEncodedPathSeparator(s string) bool {
+	for i := 0; i+2 < len(s); i++ {
+		if s[i] != '%' {
+			continue
+		}
+		switch {
+		case s[i+1] == '2' && (s[i+2] == 'f' || s[i+2] == 'F'): // %2F
+			return true
+		case s[i+1] == '5' && (s[i+2] == 'c' || s[i+2] == 'C'): // %5C
+			return true
+		}
+	}
+	return false
+}

internal/pathutil/pathutil_test.go

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: © 2015 LabStack LLC and Echo contributors
+
+package pathutil
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHasEncodedPathSeparator(t *testing.T) {
+	for s, want := range map[string]bool{
+		"foo/bar.txt": false,
+		"100%25.txt":  false, // encoded percent, not a separator
+		"a%2Fb":       true,
+		"a%2fb":       true,
+		"a%5Cb":       true,
+		"a%5cb":       true,
+		"trailing%2F": true,
+		"%2F":         true,
+		"%2":          false, // truncated, not a full sequence
+		"":            false,
+	} {
+		assert.Equal(t, want, HasEncodedPathSeparator(s), "input=%q", s)
+	}
+}

middleware/static.go

@@ -18,6 +18,7 @@ import (
 	"sync"
 
 	"github.com/labstack/echo/v5"
+	"github.com/labstack/echo/v5/internal/pathutil"
 )
 
 // StaticConfig defines the config for Static middleware.
@@ -205,6 +206,14 @@ func (config StaticConfig) ToMiddleware() (echo.MiddlewareFunc, error) {
 				pathUnescape = !config.DisablePathUnescaping // because router could already do PathUnescape
 			}
 			if pathUnescape {
+				// The router matched on the raw, still-encoded path (by default), so an encoded
+				// path separator in the wildcard would only now become a real separator and
+				// resolve a file the matched route never authorized, bypassing route-level
+				// middleware. Reject it before unescaping (see echo.StaticDirectoryHandler).
+				if pathutil.HasEncodedPathSeparator(p) {
+					return echo.NewHTTPError(http.StatusNotFound, http.StatusText(http.StatusNotFound)).
+						Wrap(fmt.Errorf("rejected encoded path separator in static path %q", p))
+				}
 				p, err = url.PathUnescape(p)
 				if err != nil {
 					return err

middleware/static_test.go

@@ -280,6 +280,35 @@ func TestStatic(t *testing.T) {
 	}
 }
 
+// Regression for GHSA-vfp3-v2gw-7wfq: the static middleware mounted on a group
+// must not let an encoded separator in the wildcard bypass route-level middleware
+// and disclose a file the matched route never authorized.
+func TestStatic_EncodedSeparatorDoesNotBypassRoute(t *testing.T) {
+	fsys := fstest.MapFS{
+		"admin/secret.txt": {Data: []byte("TOP-SECRET")},
+		"index.html":       {Data: []byte("public")},
+	}
+	e := echo.New()
+	g := e.Group("/files", StaticWithConfig(StaticConfig{Filesystem: fsys}))
+	g.GET("/*", func(c *echo.Context) error { return echo.ErrNotFound })
+
+	cases := []struct {
+		target   string
+		wantCode int
+	}{
+		{"/files/index.html", http.StatusOK},
+		{"/files/admin%2Fsecret.txt", http.StatusNotFound},
+		{"/files/admin%5Csecret.txt", http.StatusNotFound},
+	}
+	for _, tc := range cases {
+		req := httptest.NewRequest(http.MethodGet, tc.target, nil)
+		rec := httptest.NewRecorder()
+		e.ServeHTTP(rec, req)
+		assert.Equal(t, tc.wantCode, rec.Code, "GET %s", tc.target)
+		assert.NotContains(t, rec.Body.String(), "TOP-SECRET", "GET %s leaked protected file", tc.target)
+	}
+}
+
 func TestMustStaticWithConfig_panicsInvalidDirListTemplate(t *testing.T) {
 	assert.Panics(t, func() {
 		StaticWithConfig(StaticConfig{DirectoryListTemplate: `{{}`})

static_encoded_separator_test.go

@@ -0,0 +1,76 @@
+package echo
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"testing/fstest"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// Regression for GHSA-vfp3-v2gw-7wfq: an encoded slash (%2F) must not let a static
+// file request resolve across a path separator and bypass route-level middleware.
+func TestStaticDirectoryHandler_EncodedSeparatorDoesNotBypassRoute(t *testing.T) {
+	fsys := fstest.MapFS{
+		"admin/secret.txt": {Data: []byte("TOP-SECRET")},
+		"index.html":       {Data: []byte("public")},
+	}
+	e := New()
+	g := e.Group("/admin", func(next HandlerFunc) HandlerFunc {
+		return func(c *Context) error { return c.String(http.StatusForbidden, "denied") }
+	})
+	g.GET("/*", func(c *Context) error { return c.String(http.StatusOK, "reached-protected-handler") })
+	e.StaticFS("/", fsys)
+
+	cases := []struct {
+		target   string
+		wantCode int
+		wantBody string
+	}{
+		{"/admin/secret.txt", http.StatusForbidden, "denied"}, // protected route fires
+		{"/admin%2Fsecret.txt", http.StatusNotFound, ""},      // encoded slash rejected, no disclosure
+		{"/admin%2fsecret.txt", http.StatusNotFound, ""},      // lower-case hex variant
+		{"/admin%5Csecret.txt", http.StatusNotFound, ""},      // encoded backslash variant
+		{"/admin%252Fsecret.txt", http.StatusNotFound, ""},    // double-encoded: single unescape -> literal filename, not a separator
+		{"/index.html", http.StatusOK, "public"},              // legitimate static file still served
+	}
+	for _, tc := range cases {
+		req := httptest.NewRequest(http.MethodGet, tc.target, nil)
+		rec := httptest.NewRecorder()
+		e.ServeHTTP(rec, req)
+		assert.Equal(t, tc.wantCode, rec.Code, "GET %s", tc.target)
+		if tc.wantBody != "" {
+			assert.Equal(t, tc.wantBody, rec.Body.String(), "GET %s", tc.target)
+		}
+		assert.NotContains(t, rec.Body.String(), "TOP-SECRET", "GET %s leaked protected file", tc.target)
+	}
+}
+
+// A Group-mounted StaticFS shares StaticDirectoryHandler, so it must reject the
+// same encoded separators when served under a non-root prefix.
+func TestGroupStaticFS_EncodedSeparatorDoesNotBypassRoute(t *testing.T) {
+	fsys := fstest.MapFS{
+		"admin/secret.txt": {Data: []byte("TOP-SECRET")},
+		"index.html":       {Data: []byte("public")},
+	}
+	e := New()
+	g := e.Group("/files")
+	g.StaticFS("/", fsys)
+
+	cases := []struct {
+		target   string
+		wantCode int
+	}{
+		{"/files/index.html", http.StatusOK},
+		{"/files/admin%2Fsecret.txt", http.StatusNotFound},
+		{"/files/admin%5Csecret.txt", http.StatusNotFound},
+	}
+	for _, tc := range cases {
+		req := httptest.NewRequest(http.MethodGet, tc.target, nil)
+		rec := httptest.NewRecorder()
+		e.ServeHTTP(rec, req)
+		assert.Equal(t, tc.wantCode, rec.Code, "GET %s", tc.target)
+		assert.NotContains(t, rec.Body.String(), "TOP-SECRET", "GET %s leaked protected file", tc.target)
+	}
+}