Skip to content

Commit d76a1a4

Browse files
fredbiclaude
andcommitted
fix(expander): cap $ref expansion node count to prevent amplification DoS
ExpandSpec/ExpandSchema* inline every $ref with no memoization and no global budget. A self-contained spec where each of N definitions references the next one twice (via allOf/anyOf/oneOf/properties/items) drives 2^N schema expansions from O(N) bytes of input. A ~1.5 KB document expands into tens of GB of heap and >30 s of CPU, letting an unauthenticated caller exhaust resources in any service that expands untrusted specs. All refs can be fragment-only, so a restrictive PathLoader is not a mitigation. The expanded output itself is exponential (expansion inlines by value), so a memoization cache would bound CPU but not memory. The only guard that bounds memory is refusing to build the tree past a budget. Add ExpandOptions.MaxExpansionNodes, a per-call cap on the number of expanded schema nodes, enforced by a counter in the shared resolverContext incremented at the top of expandSchema: 0 (zero value): DefaultMaxExpansionNodes (500,000) -- every caller protected <0: unbounded (trusted specs only) >0: explicit cap 500,000 leaves ~10x headroom over the largest real spec we test (the full Kubernetes API expands to ~47,000 nodes) while stopping the attack well before it hurts. The metric is nodes, not $ref resolutions: measurement showed resolution counts do not grow with the attack (document-level caching collapses them), so a resolution cap would miss the blow-up entirely. Exceeding the budget returns ErrExpandTooManyNodes. This is a resource-exhaustion safeguard, so it is terminal even under ContinueOnError, rather than leaving the caller with a silently truncated spec. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 1688f14 commit d76a1a4

4 files changed

Lines changed: 214 additions & 3 deletions

File tree

‎errors.go‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,13 @@ var (
2020
// ErrExpandUnsupportedType indicates that $ref expansion is attempted on some invalid type.
2121
ErrExpandUnsupportedType = errors.New("expand: unsupported type. Input should be of type *Parameter or *Response")
2222

23+
// ErrExpandTooManyNodes indicates that $ref expansion exceeded the maximum number of schema nodes
24+
// allowed for a single expansion (see ExpandOptions.MaxExpansionNodes).
25+
//
26+
// This is a safeguard against maliciously crafted specifications that expand to an exponential
27+
// number of nodes from a small input (a $ref amplification / "billion laughs" style attack).
28+
ErrExpandTooManyNodes = errors.New("expand: too many schema nodes: expansion budget exceeded (see ExpandOptions.MaxExpansionNodes)")
29+
2330
// ErrSpec is an error raised by the spec package.
2431
ErrSpec = errors.New("spec error")
2532
)

‎expander.go‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,17 @@ import (
1010

1111
const smallPrealloc = 10
1212

13+
// DefaultMaxExpansionNodes is the default upper bound on the number of schema nodes
14+
// expanded during a single ExpandSpec / ExpandSchema* call.
15+
//
16+
// It guards against maliciously crafted specifications whose $ref graph expands to an
17+
// exponential number of nodes from a few kilobytes of input. For reference, expanding the
18+
// full Kubernetes API specification (the largest real-world spec we test against) visits
19+
// roughly 47,000 nodes, so this default leaves ample headroom for legitimate documents.
20+
//
21+
// See ExpandOptions.MaxExpansionNodes to tune or disable this budget.
22+
const DefaultMaxExpansionNodes = 500_000
23+
1324
// ExpandOptions provides options for the spec expander.
1425
//
1526
// RelativeBase is the path to the root document. This can be a remote URL or a path to a local file.
@@ -24,6 +35,34 @@ type ExpandOptions struct {
2435
ContinueOnError bool // continue expanding even after and error is found
2536
PathLoader func(string) (json.RawMessage, error) `json:"-"` // the document loading method that takes a path as input and yields a json document
2637
AbsoluteCircularRef bool // circular $ref remaining after expansion remain absolute URLs
38+
39+
// MaxExpansionNodes caps the number of schema nodes expanded during a single expansion call,
40+
// as a safeguard against $ref amplification attacks (see ErrExpandTooManyNodes).
41+
//
42+
// The value is interpreted as follows:
43+
//
44+
// 0 (the zero value): use DefaultMaxExpansionNodes. Every caller is protected by default.
45+
// <0: no limit (unbounded expansion). Use only with fully trusted specifications.
46+
// >0: cap the expansion at this number of nodes.
47+
//
48+
// When the budget is exceeded, expansion stops and ErrExpandTooManyNodes is returned.
49+
// Because this is a resource-exhaustion safeguard, the error is always returned, even when
50+
// ContinueOnError is set.
51+
MaxExpansionNodes int
52+
}
53+
54+
// maxExpansionNodes resolves the tri-state MaxExpansionNodes option into an effective budget.
55+
//
56+
// A returned value of 0 means "unbounded".
57+
func (o *ExpandOptions) maxExpansionNodes() int {
58+
switch {
59+
case o.MaxExpansionNodes == 0:
60+
return DefaultMaxExpansionNodes
61+
case o.MaxExpansionNodes < 0:
62+
return 0 // unbounded
63+
default:
64+
return o.MaxExpansionNodes
65+
}
2766
}
2867

2968
func optionsOrDefault(opts *ExpandOptions) *ExpandOptions {
@@ -192,6 +231,10 @@ func expandItems(target Schema, parentRefs []string, resolver *schemaLoader, bas
192231

193232
//nolint:gocognit,gocyclo,cyclop // complex but well-tested $ref expansion logic; refactoring deferred to dedicated PR
194233
func expandSchema(target Schema, parentRefs []string, resolver *schemaLoader, basePath string) (*Schema, error) {
234+
if err := resolver.context.countNode(); err != nil {
235+
return &target, err
236+
}
237+
195238
if target.Ref.String() == "" && target.Ref.IsRoot() {
196239
newRef := normalizeRef(&target.Ref, basePath)
197240
target.Ref = *newRef

‎expander_budget_test.go‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package spec
5+
6+
import (
7+
"encoding/json"
8+
"errors"
9+
"fmt"
10+
"testing"
11+
12+
"github.com/go-openapi/testify/v2/assert"
13+
"github.com/go-openapi/testify/v2/require"
14+
)
15+
16+
// errNoExternalLoads is returned by the deny-all PathLoader used to prove that refusing
17+
// external loads is not, on its own, a mitigation for the amplification attack.
18+
var errNoExternalLoads = errors.New("no external loads allowed")
19+
20+
// buildAmplificationSpec builds a self-contained spec where each of n definitions references
21+
// the next one twice via allOf. Without an expansion budget, expanding d0 inlines a tree with
22+
// 2^(n-1) leaves from O(n) bytes of input (a $ref amplification / "billion laughs" attack).
23+
func buildAmplificationSpec(t testing.TB, n int) []byte {
24+
t.Helper()
25+
26+
defs := make(map[string]any, n)
27+
for i := range n {
28+
var sch any
29+
if i == n-1 {
30+
sch = map[string]any{"type": "string"}
31+
} else {
32+
next := fmt.Sprintf("#/definitions/d%d", i+1)
33+
sch = map[string]any{"allOf": []any{
34+
map[string]any{"$ref": next},
35+
map[string]any{"$ref": next},
36+
}}
37+
}
38+
defs[fmt.Sprintf("d%d", i)] = sch
39+
}
40+
41+
doc := map[string]any{
42+
"swagger": "2.0",
43+
"info": map[string]any{"title": "x", "version": "1"},
44+
"paths": map[string]any{},
45+
"definitions": defs,
46+
}
47+
raw, err := json.Marshal(doc)
48+
require.NoError(t, err)
49+
50+
return raw
51+
}
52+
53+
func TestMaxExpansionNodesTriState(t *testing.T) {
54+
// 0 (zero value): default budget, so every caller is protected out of the box.
55+
assert.EqualT(t, DefaultMaxExpansionNodes, (&ExpandOptions{}).maxExpansionNodes())
56+
57+
// negative: unbounded.
58+
assert.EqualT(t, 0, (&ExpandOptions{MaxExpansionNodes: -1}).maxExpansionNodes())
59+
60+
// positive: explicit budget.
61+
assert.EqualT(t, 1234, (&ExpandOptions{MaxExpansionNodes: 1234}).maxExpansionNodes())
62+
}
63+
64+
func TestExpand_AmplificationBudget(t *testing.T) {
65+
// A deep amplification spec. Even a modest depth would explode without a budget.
66+
const depth = 40
67+
raw := buildAmplificationSpec(t, depth)
68+
69+
t.Run("explicit budget trips the guard", func(t *testing.T) {
70+
var sw Swagger
71+
require.NoError(t, json.Unmarshal(raw, &sw))
72+
73+
err := ExpandSpec(&sw, &ExpandOptions{MaxExpansionNodes: 2000})
74+
require.ErrorIs(t, err, ErrExpandTooManyNodes)
75+
})
76+
77+
t.Run("deny-all PathLoader is not a mitigation on its own", func(t *testing.T) {
78+
// All refs are fragment-only and resolve against the in-memory root, so refusing
79+
// external loads does not prevent the blow-up: the budget is what stops it.
80+
var sw Swagger
81+
require.NoError(t, json.Unmarshal(raw, &sw))
82+
83+
loaderCalled := false
84+
err := ExpandSpec(&sw, &ExpandOptions{
85+
MaxExpansionNodes: 2000,
86+
PathLoader: func(p string) (json.RawMessage, error) {
87+
loaderCalled = true
88+
return nil, fmt.Errorf("%w: %s", errNoExternalLoads, p)
89+
},
90+
})
91+
require.ErrorIs(t, err, ErrExpandTooManyNodes)
92+
assert.FalseT(t, loaderCalled, "expected no external load attempts")
93+
})
94+
95+
t.Run("ContinueOnError does not suppress a budget breach", func(t *testing.T) {
96+
// The budget is a hard resource-exhaustion safeguard: unlike an unresolvable $ref,
97+
// it must surface even when the caller tolerates errors.
98+
var sw Swagger
99+
require.NoError(t, json.Unmarshal(raw, &sw))
100+
101+
err := ExpandSpec(&sw, &ExpandOptions{MaxExpansionNodes: 2000, ContinueOnError: true})
102+
require.ErrorIs(t, err, ErrExpandTooManyNodes)
103+
})
104+
105+
t.Run("negative budget disables the guard", func(t *testing.T) {
106+
// A shallow spec that stays well under any real budget must expand fully when unbounded.
107+
shallow := buildAmplificationSpec(t, 8)
108+
var sw Swagger
109+
require.NoError(t, json.Unmarshal(shallow, &sw))
110+
111+
require.NoError(t, ExpandSpec(&sw, &ExpandOptions{MaxExpansionNodes: -1}))
112+
})
113+
}
114+
115+
func TestExpand_BudgetAllowsLegitSpec(t *testing.T) {
116+
// A shallow amplification spec (small node count) must expand cleanly under the default budget.
117+
raw := buildAmplificationSpec(t, 8)
118+
var sw Swagger
119+
require.NoError(t, json.Unmarshal(raw, &sw))
120+
121+
require.NoError(t, ExpandSpec(&sw, nil)) // nil options => default budget
122+
// d0 fully expanded: no $ref remains in the leaf chain.
123+
out, err := json.Marshal(sw.Definitions["d0"])
124+
require.NoError(t, err)
125+
assert.StringNotContainsT(t, string(out), `"$ref"`)
126+
}
127+
128+
func TestExpand_BudgetErrorIsSentinel(t *testing.T) {
129+
raw := buildAmplificationSpec(t, 40)
130+
var sw Swagger
131+
require.NoError(t, json.Unmarshal(raw, &sw))
132+
133+
err := ExpandSpec(&sw, &ExpandOptions{MaxExpansionNodes: 100})
134+
require.Error(t, err)
135+
assert.TrueT(t, errors.Is(err, ErrExpandTooManyNodes))
136+
}

‎schema_loader.go‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ package spec
55

66
import (
77
"encoding/json"
8+
"errors"
89
"fmt"
910
"log"
1011
"net/url"
@@ -43,6 +44,11 @@ type resolverContext struct {
4344
basePath string
4445
loadDoc func(string) (json.RawMessage, error)
4546
rootID string
47+
48+
// nodes counts the schema nodes expanded so far, capped by maxNodes to guard against
49+
// $ref amplification. maxNodes == 0 means unbounded. Shared, single-threaded: no locking needed.
50+
nodes int
51+
maxNodes int
4652
}
4753

4854
func newResolverContext(options *ExpandOptions) *resolverContext {
@@ -60,9 +66,20 @@ func newResolverContext(options *ExpandOptions) *resolverContext {
6066
circulars: make(map[string]bool),
6167
basePath: expandOptions.RelativeBase, // keep the root base path in context
6268
loadDoc: loader,
69+
maxNodes: expandOptions.maxExpansionNodes(),
6370
}
6471
}
6572

73+
// countNode accounts for one expanded schema node and reports whether the expansion budget
74+
// has been exceeded. A maxNodes of 0 disables the budget (unbounded expansion).
75+
func (c *resolverContext) countNode() error {
76+
c.nodes++
77+
if c.maxNodes > 0 && c.nodes > c.maxNodes {
78+
return ErrExpandTooManyNodes
79+
}
80+
return nil
81+
}
82+
6683
type schemaLoader struct {
6784
root any
6885
options *ExpandOptions
@@ -246,14 +263,22 @@ func (r *schemaLoader) deref(input any, parentRefs []string, basePath string) er
246263
}
247264

248265
func (r *schemaLoader) shouldStopOnError(err error) bool {
249-
if err != nil && !r.options.ContinueOnError {
266+
if err == nil {
267+
return false
268+
}
269+
270+
if errors.Is(err, ErrExpandTooManyNodes) {
271+
// a blown expansion budget is a hard, document-level failure: it is a safeguard against
272+
// resource exhaustion and is never suppressed by ContinueOnError.
250273
return true
251274
}
252275

253-
if err != nil {
254-
log.Println(err)
276+
if !r.options.ContinueOnError {
277+
return true
255278
}
256279

280+
log.Println(err)
281+
257282
return false
258283
}
259284

0 commit comments

Comments
 (0)
⌂ 换网址