Skip to content

Commit 4dc207c

Browse files
openapi3: document that a custom ReadFromURIFunc bypasses IsExternalRefsAllowed (#1191)
1 parent 8381bfc commit 4dc207c

2 files changed

Lines changed: 32 additions & 8 deletions

File tree

‎.github/docs/openapi3.txt‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1276,15 +1276,26 @@ func (links *Links) UnmarshalJSON(data []byte) (err error)
12761276
UnmarshalJSON sets Links to a copy of data.
12771277

12781278
type Loader struct {
1279-
// IsExternalRefsAllowed enables visiting other files
1279+
// IsExternalRefsAllowed enables visiting other files. Enforced only when
1280+
// ReadFromURIFunc is nil; a custom ReadFromURIFunc bypasses this flag and
1281+
// owns the access policy itself — see ReadFromURIFunc.
12801282
IsExternalRefsAllowed bool
12811283

12821284
// IncludeOrigin enables recording the file/line/column of each OpenAPI element.
12831285
// Prefer this over the package-level IncludeOrigin global, which is not safe for
12841286
// concurrent use.
12851287
IncludeOrigin bool
12861288

1287-
// ReadFromURIFunc allows overriding the any file/URL reading func
1289+
// ReadFromURIFunc overrides how the loader reads a referenced file or URL.
1290+
//
1291+
// SECURITY: when a custom ReadFromURIFunc is set, IsExternalRefsAllowed is
1292+
// NOT enforced — this function alone decides which locations may be read. A
1293+
// func that reads whatever URI it is handed (e.g. by delegating to
1294+
// DefaultReadFromURI) resolves external $refs even when IsExternalRefsAllowed
1295+
// is false, which on untrusted documents enables local file reads
1296+
// (`$ref: "/etc/passwd"`) and SSRF (`$ref: "http://169.254.169.254/..."`).
1297+
// A custom func must apply its own scheme/host allowlist, or re-check
1298+
// IsExternalRefsAllowed, before reading.
12881299
ReadFromURIFunc ReadFromURIFunc
12891300

12901301
// JoinFunc allows overriding how relative $ref paths are resolved against

‎openapi3/loader.go‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,15 +26,26 @@ func failedToResolveRefFragmentPart(value, what string) error {
2626

2727
// Loader helps deserialize an OpenAPIv3 document
2828
type Loader struct {
29-
// IsExternalRefsAllowed enables visiting other files
29+
// IsExternalRefsAllowed enables visiting other files. Enforced only when
30+
// ReadFromURIFunc is nil; a custom ReadFromURIFunc bypasses this flag and
31+
// owns the access policy itself — see ReadFromURIFunc.
3032
IsExternalRefsAllowed bool
3133

3234
// IncludeOrigin enables recording the file/line/column of each OpenAPI element.
3335
// Prefer this over the package-level IncludeOrigin global, which is not safe for
3436
// concurrent use.
3537
IncludeOrigin bool
3638

37-
// ReadFromURIFunc allows overriding the any file/URL reading func
39+
// ReadFromURIFunc overrides how the loader reads a referenced file or URL.
40+
//
41+
// SECURITY: when a custom ReadFromURIFunc is set, IsExternalRefsAllowed is
42+
// NOT enforced — this function alone decides which locations may be read. A
43+
// func that reads whatever URI it is handed (e.g. by delegating to
44+
// DefaultReadFromURI) resolves external $refs even when IsExternalRefsAllowed
45+
// is false, which on untrusted documents enables local file reads
46+
// (`$ref: "/etc/passwd"`) and SSRF (`$ref: "http://169.254.169.254/..."`).
47+
// A custom func must apply its own scheme/host allowlist, or re-check
48+
// IsExternalRefsAllowed, before reading.
3849
ReadFromURIFunc ReadFromURIFunc
3950

4051
// JoinFunc allows overriding how relative $ref paths are resolved against
@@ -101,9 +112,9 @@ func (loader *Loader) allowsExternalRefs(ref string) (err error) {
101112
}
102113

103114
func (loader *Loader) loadSingleElementFromURI(ref string, rootPath *url.URL, element any) (*url.URL, error) {
104-
// When a custom ReadFromURIFunc is installed, defer the external-ref decision to it;
105-
// the function itself is responsible for enforcing any access policy.
106-
// Otherwise enforce IsExternalRefsAllowed here before attempting any I/O.
115+
// IsExternalRefsAllowed is enforced here only when no custom ReadFromURIFunc
116+
// is installed; otherwise the custom func owns the access policy (see the
117+
// SECURITY note on the ReadFromURIFunc field).
107118
if loader.ReadFromURIFunc == nil {
108119
if err := loader.allowsExternalRefs(ref); err != nil {
109120
return nil, err
@@ -331,7 +342,9 @@ func (loader *Loader) resolveRefPath(ref string, path *url.URL) (*url.URL, error
331342
return path, nil
332343
}
333344

334-
// When a custom ReadFromURIFunc is installed, defer the external-ref decision to it.
345+
// IsExternalRefsAllowed is enforced here only when no custom ReadFromURIFunc
346+
// is installed; otherwise the custom func owns the access policy (see the
347+
// SECURITY note on the ReadFromURIFunc field).
335348
if loader.ReadFromURIFunc == nil {
336349
if err := loader.allowsExternalRefs(ref); err != nil {
337350
return nil, err

0 commit comments

Comments
 (0)