Skip to content

Commit eefaba1

Browse files
fredbiclaude
andauthored
feat(loading): sandbox local loading with WithRoot (GHSA-v2xp-g8xf-22pf) (#203)
* feat(loading): sandbox local loading with WithRoot (GHSA-v2xp-g8xf-22pf) Allow for optional secure sandboxing of the spec loader when reading local files. The defaults remain non-secure as it would introduce severe breaking changes downstream. Sandboxing therefore remains opt-in. LoadFromFileOrHTTP resolved file:// URIs and bare paths straight to os.ReadFile with no confinement, so a caller that forwards untrusted input could read any file the process can access (file:///etc/passwd, absolute paths, etc.). The advised mitigation, WithFS(os.DirFS(dir)), blocks ".." traversal but not symlinks that escape the root. Add WithRoot(dir): an opt-in, non-breaking option that confines local reads to dir via os.Root. It resolves every requested path relative to dir and rejects absolute paths, ".." traversal, and escaping symlinks -- including the symlink case os.DirFS misses. The root is opened per read and closed (no fd leak); the open error is wrapped with ErrLoader. WithRoot and WithFS are mutually exclusive (last applied wins). Also fix a latent bug in LoadStrategy: it applied native separators (filepath.FromSlash) to fs-backed loaders, breaking multi-segment paths on Windows for any fs.FS. fs-backed loaders now receive forward slashes on all platforms, preserving embed.FS's existing always-"/" rule; the native path is kept only for the default os.ReadFile loader. Document the default permissive behavior and steer untrusted-input callers to WithRoot in the package and function godoc. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com> * docs(loading): document SSRF exposure; fix http-prefix misrouting The remote loader is a thin wrapper over a standard net/http client and, like http.DefaultClient, follows redirects and applies no destination filtering. A caller that forwards untrusted URLs can thus trigger server-side request forgery (internal services, cloud metadata). Embedding a network policy (IP denylists, allowlists) in a general fetch utility is the wrong layer and invites false confidence: the existing WithHTTPClient option already lets a caller install a guarded transport that filters destinations at dial time, which is the only point that survives redirects and DNS rebinding. Document the exposure in the package godoc and add a runnable, self-validating example showing the WithHTTPClient + net.Dialer.Control recipe. Separately, fix a latent correctness bug: LoadStrategy routed any path with a bare "http" prefix to the remote loader, so a local file named e.g. "httpbin.json" was misrouted, and an uppercase "HTTP://" URL was sent to the local loader. Require a real, case-insensitive http:// or https:// scheme instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com> --------- Signed-off-by: Frederic BIDON <fredbi@yahoo.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 2e99502 commit eefaba1

6 files changed

Lines changed: 298 additions & 5 deletions

File tree

‎loading/doc.go‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,24 @@
22
// SPDX-License-Identifier: Apache-2.0
33

44
// Package loading provides tools to load a file from http or from a local file system.
5+
//
6+
// # Security
7+
//
8+
// By default, the local loader reads any path the process can access, including absolute
9+
// paths and "file://" URIs (for example "file:///etc/passwd"). Applications that pass
10+
// untrusted input to [LoadFromFileOrHTTP], [JSONDoc] (or to downstream consumers such as
11+
// go-openapi/loads) must confine local loading to a trusted directory.
12+
//
13+
// Use [WithRoot] to do so: it resolves every requested path relative to a chosen directory
14+
// and rejects anything that escapes it, including via symlink. It is built on [os.Root]
15+
// and is therefore safer than passing an [os.DirFS] to [WithFS], which does not block
16+
// symlink escapes.
17+
//
18+
// Remote loading uses a standard [net/http] client. By default it follows redirects and
19+
// performs no destination filtering — exactly like [net/http.DefaultClient]. A
20+
// caller-controlled URL may therefore reach internal services or cloud metadata endpoints
21+
// (server-side request forgery). This package does not, and should not, embed a network
22+
// policy: when the URL may derive from untrusted input, supply a restricted client with
23+
// [WithHTTPClient] whose transport rejects unwanted destinations at dial time — which also
24+
// covers redirects and DNS rebinding. See the example on [LoadFromFileOrHTTP].
525
package loading

‎loading/example_test.go‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package loading_test
5+
6+
import (
7+
"errors"
8+
"fmt"
9+
"net"
10+
"net/http"
11+
"net/http/httptest"
12+
"net/netip"
13+
"syscall"
14+
15+
"github.com/go-openapi/swag/loading"
16+
)
17+
18+
// errForbiddenAddr is returned by the dial guard when a destination is not allowed.
19+
var errForbiddenAddr = errors.New("blocked dial to a forbidden address")
20+
21+
// ExampleLoadFromFileOrHTTP_restrictNetwork shows how to confine remote spec loading so a
22+
// caller-controlled URL cannot reach loopback, private, or link-local (cloud metadata)
23+
// addresses.
24+
//
25+
// The [net.Dialer] Control hook runs after DNS resolution and before connect, on every
26+
// connection, so the check also covers HTTP redirects and DNS rebinding — neither of which
27+
// a URL-string allowlist can defend against. Here a loopback test server stands in for an
28+
// internal endpoint that the guard must refuse to reach.
29+
func ExampleLoadFromFileOrHTTP_restrictNetwork() {
30+
control := func(_, address string, _ syscall.RawConn) error {
31+
host, _, err := net.SplitHostPort(address)
32+
if err != nil {
33+
return err
34+
}
35+
addr, err := netip.ParseAddr(host)
36+
if err != nil {
37+
return err
38+
}
39+
if a := addr.Unmap(); a.IsLoopback() || a.IsPrivate() || a.IsLinkLocalUnicast() || a.IsUnspecified() {
40+
return errForbiddenAddr
41+
}
42+
43+
return nil
44+
}
45+
46+
client := &http.Client{
47+
Transport: &http.Transport{
48+
DialContext: (&net.Dialer{Control: control}).DialContext,
49+
},
50+
}
51+
52+
// An internal service the application must not let untrusted input reach.
53+
internal := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
54+
_, _ = w.Write([]byte("internal secret"))
55+
}))
56+
defer internal.Close()
57+
58+
// internal.URL is a loopback address (the untrusted URL in a real attack).
59+
_, err := loading.LoadFromFileOrHTTP(internal.URL, loading.WithHTTPClient(client))
60+
fmt.Println("blocked:", errors.Is(err, errForbiddenAddr))
61+
62+
// Output:
63+
// blocked: true
64+
}

‎loading/loading.go‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,11 @@ import (
1717
"strings"
1818
)
1919

20-
// LoadFromFileOrHTTP loads the bytes from a file or a remote http server based on the path passed in
20+
// LoadFromFileOrHTTP loads the bytes from a file or a remote http server based on the path passed in.
21+
//
22+
// Security: by default a local path is read with no confinement, so a caller-controlled path
23+
// (including a "file://" URI or an absolute path) may read any file the process can access.
24+
// When the path may derive from untrusted input, confine local loading with [WithRoot].
2125
func LoadFromFileOrHTTP(pth string, opts ...Option) ([]byte, error) {
2226
o := optionsWithDefaults(opts)
2327
return LoadStrategy(pth, o.ReadFileFunc(), loadHTTPBytes(opts...), opts...)(pth)
@@ -54,11 +58,14 @@ func LoadFromFileOrHTTP(pth string, opts ...Option) ([]byte, error) {
5458
// - `file:///c:/folder/file` becomes `C:\folder\file`
5559
// - `file://c:/folder/file` is tolerated (without leading `/`) and becomes `c:\folder\file`
5660
func LoadStrategy(pth string, local, remote func(string) ([]byte, error), opts ...Option) func(string) ([]byte, error) {
57-
if strings.HasPrefix(pth, "http") {
61+
if hasHTTPScheme(pth) {
5862
return remote
5963
}
6064
o := optionsWithDefaults(opts)
6165
_, isEmbedFS := o.fs.(embed.FS)
66+
// any loader backed by an fs.FS or an os.Root consumes forward-slash paths on every
67+
// platform, so it must not go through the windows-native file:// preprocessing below.
68+
isFSBacked := o.fs != nil || o.root != ""
6269

6370
return func(p string) ([]byte, error) {
6471
upth, err := url.PathUnescape(p)
@@ -67,14 +74,20 @@ func LoadStrategy(pth string, local, remote func(string) ([]byte, error), opts .
6774
}
6875

6976
cpth, hasPrefix := strings.CutPrefix(upth, "file://")
70-
if !hasPrefix || isEmbedFS || runtime.GOOS != "windows" {
77+
if !hasPrefix || isFSBacked || runtime.GOOS != "windows" {
7178
// crude processing: trim the file:// prefix. This leaves full URIs with a host with a (mostly) unexpected result
7279
// regular file path provided: just normalize slashes
7380
if isEmbedFS {
74-
// on windows, we need to slash the path if FS is an embed FS.
81+
// embed.FS always uses "/" as separator, even on windows, and rejects leading "./" or "/".
7582
return local(strings.TrimLeft(filepath.ToSlash(cpth), "./")) // remove invalid leading characters for embed FS
7683
}
7784

85+
if isFSBacked {
86+
// other fs.FS (e.g. os.DirFS) and os.Root loaders also use "/" on every platform.
87+
// Escaping paths (absolute, "..", escaping symlinks) are rejected by the loader, not rewritten here.
88+
return local(filepath.ToSlash(cpth))
89+
}
90+
7891
return local(filepath.FromSlash(cpth))
7992
}
8093

@@ -113,6 +126,21 @@ func LoadStrategy(pth string, local, remote func(string) ([]byte, error), opts .
113126
}
114127
}
115128

129+
// hasHTTPScheme reports whether pth is an absolute URL with an http or https scheme,
130+
// selecting the remote loader. The comparison is case-insensitive, as URL schemes are.
131+
//
132+
// Requiring the "://" separator (rather than a bare "http" prefix) avoids misrouting a
133+
// local file whose name merely starts with "http" (e.g. "httpbin.json") to the remote loader.
134+
func hasHTTPScheme(pth string) bool {
135+
for _, scheme := range [...]string{"http://", "https://"} {
136+
if len(pth) >= len(scheme) && strings.EqualFold(pth[:len(scheme)], scheme) {
137+
return true
138+
}
139+
}
140+
141+
return false
142+
}
143+
116144
func loadHTTPBytes(opts ...Option) func(path string) ([]byte, error) {
117145
o := optionsWithDefaults(opts)
118146

‎loading/loading_test.go‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,28 @@ func TestLoadStrategy(t *testing.T) {
221221
b, _ := ldr("")
222222
assert.EqualT(t, thisIsNotIt, string(b))
223223
})
224+
225+
t.Run("should serve remote strategy with an uppercase scheme", func(t *testing.T) {
226+
// URL schemes are case-insensitive
227+
for _, pth := range []string{"HTTP://blah", "HTTPS://blah", "HtTp://blah"} {
228+
t.Run(pth, func(t *testing.T) {
229+
ldr := LoadStrategy(pth, loader, remLoader)
230+
b, _ := ldr("")
231+
assert.EqualT(t, thisIsNotIt, string(b))
232+
})
233+
}
234+
})
235+
236+
t.Run("should serve local strategy for a local file named like an http URL", func(t *testing.T) {
237+
// a bare "http" prefix must not misroute a local file to the remote loader
238+
for _, pth := range []string{"httpbin.json", "http2-spec.yaml", "http"} {
239+
t.Run(pth, func(t *testing.T) {
240+
ldr := LoadStrategy(pth, loader, remLoader)
241+
b, _ := ldr("")
242+
assert.YAMLEqT(t, string(yamlPetStore), string(b))
243+
})
244+
}
245+
})
224246
}
225247

226248
func TestLoadStrategyFile(t *testing.T) {

‎loading/options.go‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
package loading
55

66
import (
7+
"errors"
78
"io/fs"
89
"net/http"
910
"os"
@@ -23,7 +24,8 @@ type (
2324
}
2425

2526
fileOptions struct {
26-
fs fs.ReadFileFS
27+
fs fs.ReadFileFS
28+
root string // when non-empty, local reads are confined to this directory via os.Root
2729
}
2830

2931
options struct {
@@ -33,6 +35,20 @@ type (
3335
)
3436

3537
func (fo fileOptions) ReadFileFunc() func(string) ([]byte, error) {
38+
if fo.root != "" {
39+
root := fo.root
40+
41+
return func(name string) ([]byte, error) {
42+
r, err := os.OpenRoot(root)
43+
if err != nil {
44+
return nil, errors.Join(err, ErrLoader)
45+
}
46+
defer func() { _ = r.Close() }()
47+
48+
return r.ReadFile(name)
49+
}
50+
}
51+
3652
if fo.fs == nil {
3753
return os.ReadFile
3854
}
@@ -87,8 +103,15 @@ func WithHTTPClient(client *http.Client) Option {
87103
// By default, the file system is the one provided by the os package.
88104
//
89105
// For example, this may be set to consume from an embedded file system, or a rooted FS.
106+
//
107+
// WithFS and [WithRoot] are mutually exclusive: the last one applied wins.
108+
//
109+
// Security note: a file system built from [os.DirFS] confines paths but does NOT protect
110+
// against symlinks that escape the root. To load from a directory derived from untrusted
111+
// input, prefer [WithRoot], which is symlink-escape resistant.
90112
func WithFS(filesystem fs.FS) Option {
91113
return func(o *options) {
114+
o.root = "" // last-wins vs WithRoot
92115
if rfs, ok := filesystem.(fs.ReadFileFS); ok {
93116
o.fs = rfs
94117

@@ -98,6 +121,28 @@ func WithFS(filesystem fs.FS) Option {
98121
}
99122
}
100123

124+
// WithRoot confines local file loading to dir.
125+
//
126+
// Every requested path is resolved relative to dir, and any path that would escape dir —
127+
// whether through an absolute path, ".." traversal, or a symlink pointing outside dir — is
128+
// rejected. This is built on [os.Root] and is therefore resistant to the symlink escapes
129+
// that a plain [os.DirFS] does not prevent.
130+
//
131+
// WithRoot is the recommended option when loading specs from a location derived from
132+
// untrusted input. It applies to local loading only and has no effect on remote
133+
// (http/https) loading. WithRoot and [WithFS] are mutually exclusive: the last one applied
134+
// wins.
135+
//
136+
// Note: [os.Root] confines path resolution but does not, by itself, protect against
137+
// traversal of mount/bind boundaries, /proc special files, or device files. Point WithRoot
138+
// at a directory that holds only the documents you intend to expose.
139+
func WithRoot(dir string) Option {
140+
return func(o *options) {
141+
o.root = dir
142+
o.fs = nil // last-wins vs WithFS
143+
}
144+
}
145+
101146
type readFileFS struct {
102147
fs.FS
103148
}

‎loading/withroot_test.go‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package loading
5+
6+
import (
7+
"io/fs"
8+
"os"
9+
"path/filepath"
10+
"testing"
11+
"testing/fstest"
12+
13+
"github.com/go-openapi/testify/v2/assert"
14+
"github.com/go-openapi/testify/v2/require"
15+
)
16+
17+
func TestWithRoot(t *testing.T) {
18+
const (
19+
inside = "inside the root"
20+
nested = "nested in the root"
21+
secret = "this is a secret outside the root"
22+
)
23+
24+
// layout:
25+
// <parent>/secret.txt (outside the root)
26+
// <parent>/root/api.yaml
27+
// <parent>/root/sub/api.yaml
28+
parent := t.TempDir()
29+
root := filepath.Join(parent, "root")
30+
require.NoError(t, os.MkdirAll(filepath.Join(root, "sub"), 0o750))
31+
require.NoError(t, os.WriteFile(filepath.Join(parent, "secret.txt"), []byte(secret), 0o600))
32+
require.NoError(t, os.WriteFile(filepath.Join(root, "api.yaml"), []byte(inside), 0o600))
33+
require.NoError(t, os.WriteFile(filepath.Join(root, "sub", "api.yaml"), []byte(nested), 0o600))
34+
35+
t.Run("should load paths confined to the root", func(t *testing.T) {
36+
for _, pth := range []string{
37+
"api.yaml",
38+
"./api.yaml",
39+
"file://api.yaml",
40+
"sub/../api.yaml",
41+
} {
42+
t.Run(pth, func(t *testing.T) {
43+
b, err := LoadFromFileOrHTTP(pth, WithRoot(root))
44+
require.NoError(t, err)
45+
assert.EqualT(t, inside, string(b))
46+
})
47+
}
48+
49+
t.Run("nested path", func(t *testing.T) {
50+
b, err := LoadFromFileOrHTTP("sub/api.yaml", WithRoot(root))
51+
require.NoError(t, err)
52+
assert.EqualT(t, nested, string(b))
53+
})
54+
})
55+
56+
t.Run("should reject paths escaping the root", func(t *testing.T) {
57+
for _, pth := range []string{
58+
"file:///etc/passwd", // absolute via file:// URI
59+
filepath.Join(parent, "secret.txt"), // absolute path to an existing sibling file
60+
"../secret.txt", // traversal
61+
"file://../secret.txt", // traversal via file:// URI
62+
} {
63+
t.Run(pth, func(t *testing.T) {
64+
b, err := LoadFromFileOrHTTP(pth, WithRoot(root))
65+
require.Error(t, err)
66+
// the rejected read must not leak any bytes
67+
assert.Empty(t, b)
68+
})
69+
}
70+
})
71+
72+
t.Run("should reject a symlink escaping the root", func(t *testing.T) {
73+
// <root>/escape.yaml -> <parent>/secret.txt (escapes the root)
74+
if err := os.Symlink(filepath.Join(parent, "secret.txt"), filepath.Join(root, "escape.yaml")); err != nil {
75+
t.Skipf("symlinks not supported on this platform/filesystem: %v", err)
76+
}
77+
78+
b, err := LoadFromFileOrHTTP("escape.yaml", WithRoot(root))
79+
require.Error(t, err)
80+
assert.Empty(t, b)
81+
// this is exactly the case os.DirFS would NOT block
82+
assert.NotContains(t, string(b), secret)
83+
})
84+
85+
t.Run("should surface an error for a missing root", func(t *testing.T) {
86+
b, err := LoadFromFileOrHTTP("api.yaml", WithRoot(filepath.Join(parent, "does-not-exist")))
87+
require.Error(t, err)
88+
require.ErrorIs(t, err, ErrLoader)
89+
assert.Empty(t, b)
90+
})
91+
92+
t.Run("WithRoot and WithFS are mutually exclusive (last wins)", func(t *testing.T) {
93+
mapfs := fstest.MapFS{"api.yaml": &fstest.MapFile{Data: []byte("from map fs"), Mode: fs.ModePerm}}
94+
95+
t.Run("WithRoot after WithFS uses the root", func(t *testing.T) {
96+
b, err := LoadFromFileOrHTTP("api.yaml", WithFS(mapfs), WithRoot(root))
97+
require.NoError(t, err)
98+
assert.EqualT(t, inside, string(b))
99+
})
100+
101+
t.Run("WithFS after WithRoot uses the fs", func(t *testing.T) {
102+
b, err := LoadFromFileOrHTTP("api.yaml", WithRoot(root), WithFS(mapfs))
103+
require.NoError(t, err)
104+
assert.EqualT(t, "from map fs", string(b))
105+
})
106+
})
107+
108+
t.Run("default loader (no WithRoot) is unchanged and reads outside any root", func(t *testing.T) {
109+
// regression guard: the fix is opt-in and must not change default behavior
110+
b, err := LoadFromFileOrHTTP(filepath.Join(parent, "secret.txt"))
111+
require.NoError(t, err)
112+
assert.EqualT(t, secret, string(b))
113+
})
114+
}

0 commit comments

Comments
 (0)
⌂ 换网址