specshield 3.4.13 → 3.4.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +27 -1
- package/README.md +10 -3
- package/package.json +1 -1
- package/src/core/normalizeSpec.js +67 -11
- package/src/core/usage/impact.js +20 -4
- package/src/core/usage/logParsers.js +39 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
# SpecShield CLI changelog
|
|
2
2
|
|
|
3
|
-
## Unreleased —
|
|
3
|
+
## Unreleased — Kubernetes audit logs, Swagger 2.0 bodies
|
|
4
|
+
|
|
5
|
+
Tested on the Kubernetes project's own published data: the API-server audit log of
|
|
6
|
+
CI job `ci-kubernetes-audit-kind-conformance` (219,507 events, k8s master `765dd1d`) and
|
|
7
|
+
the official `api/openapi-spec/swagger.json` at `765dd1d` and `v1.37.1`. Impact numbers
|
|
8
|
+
were checked against counts taken directly from the raw audit events.
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- `usage import` reads **Kubernetes API-server audit logs** (`audit.k8s.io` Events):
|
|
13
|
+
verbs map to HTTP methods, and only the final stage (`ResponseComplete`/`Panic`) is
|
|
14
|
+
counted — the same request is otherwise logged up to three times.
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
|
|
18
|
+
- **Swagger 2.0 request and response bodies were not compared.** `#/definitions/` refs,
|
|
19
|
+
the `in: body` parameter and `responses.<code>.schema` were ignored, so a removed or
|
|
20
|
+
newly required field reported "No changes". Comparing Kubernetes v1.37.1 → master now
|
|
21
|
+
finds the 18 schemas whose fields became required.
|
|
22
|
+
- Path-level parameters and `$ref` parameters/responses (OpenAPI 3 and Swagger 2.0) are
|
|
23
|
+
now resolved; they were skipped before.
|
|
24
|
+
- Usage impact of request-body changes no longer counts `GET`/`HEAD`/`OPTIONS` calls, and a
|
|
25
|
+
merged change listing the same endpoint twice no longer double-counts its traffic (on
|
|
26
|
+
Kubernetes data: 551 → 12 calls for `events.k8s.io/v1` Event fields, matching the raw
|
|
27
|
+
log exactly).
|
|
28
|
+
|
|
29
|
+
## 3.4.13 — 2026-10-25 — usage-aware compare: "who does this change break?"
|
|
4
30
|
|
|
5
31
|
### Added
|
|
6
32
|
|
package/README.md
CHANGED
|
@@ -278,8 +278,13 @@ specshield usage import /var/log/nginx/access.log* --spec api/openapi.yaml
|
|
|
278
278
|
```
|
|
279
279
|
|
|
280
280
|
- **Formats:** nginx/Apache combined & common, AWS ALB, and JSON lines (nginx JSON
|
|
281
|
-
`log_format`, Kong file-log, API Gateway,
|
|
282
|
-
|
|
281
|
+
`log_format`, Kong file-log, API Gateway, Caddy, Traefik, Envoy, Google Cloud LB, ECS,
|
|
282
|
+
and **Kubernetes API-server audit logs**). Auto-detected; `.gz` files and stdin (`-`)
|
|
283
|
+
work. Force one with `--format combined|alb|json`.
|
|
284
|
+
- **Kubernetes:** point it at the API-server audit log and the cluster's
|
|
285
|
+
`swagger.json`, and identify clients by their authenticated identity:
|
|
286
|
+
`specshield usage import audit.log --spec swagger.json --client field:user.username`.
|
|
287
|
+
Each request is counted once (final audit stage only).
|
|
283
288
|
- **Clients** are identified by User-Agent by default (`MyShop-iOS/5.2.1` → `MyShop-iOS/5.2`).
|
|
284
289
|
Use a better signal if you log one: `--client field:consumer.username` (JSON logs),
|
|
285
290
|
`--client extra:1` (first quoted field after the User-Agent in combined logs), and prefix
|
|
@@ -304,7 +309,9 @@ specshield compare base.yaml target.yaml --usage usage.json --fail-on-breaking
|
|
|
304
309
|
|
|
305
310
|
- **Endpoint and method removals, body/response field changes** → the clients calling that
|
|
306
311
|
operation. Access logs don't show which response fields a client reads, so for field
|
|
307
|
-
changes this is "clients that may be affected", and the report says so.
|
|
312
|
+
changes this is "clients that may be affected", and the report says so. Request-body
|
|
313
|
+
changes (a field removed or made required) count only calls that send a body — `GET`
|
|
314
|
+
traffic can't be affected by them.
|
|
308
315
|
- **Query parameters** are judged exactly: a removed parameter affects only clients that
|
|
309
316
|
*send* it; a parameter that became required affects only clients that *omit* it.
|
|
310
317
|
- **Zero calls → "breaking but unused"**: listed separately and excluded from
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specshield",
|
|
3
|
-
"version": "3.4.
|
|
3
|
+
"version": "3.4.14",
|
|
4
4
|
"description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
|
|
5
5
|
"main": "src/cli.js",
|
|
6
6
|
"homepage": "https://specshield.io",
|
|
@@ -3,6 +3,12 @@
|
|
|
3
3
|
/**
|
|
4
4
|
* Normalize an OpenAPI spec into a flat, consistent internal model.
|
|
5
5
|
* Resolves simple $ref references from components.schemas.
|
|
6
|
+
*
|
|
7
|
+
* Swagger 2.0 is mapped onto the same model: `definitions` stand in for
|
|
8
|
+
* components.schemas, the `in: body` parameter becomes the request body,
|
|
9
|
+
* `responses.<code>.schema` is the response schema, and non-body parameters
|
|
10
|
+
* carry their type inline instead of under `schema`. Path-level parameters
|
|
11
|
+
* and `$ref` parameters/responses are resolved for both versions.
|
|
6
12
|
*/
|
|
7
13
|
function normalizeSpec(spec) {
|
|
8
14
|
if (!spec || typeof spec !== 'object') {
|
|
@@ -10,7 +16,12 @@ function normalizeSpec(spec) {
|
|
|
10
16
|
}
|
|
11
17
|
|
|
12
18
|
const components = spec.components || {};
|
|
13
|
-
const schemas = components.schemas || {};
|
|
19
|
+
const schemas = components.schemas || spec.definitions || {};
|
|
20
|
+
const ctx = {
|
|
21
|
+
schemas,
|
|
22
|
+
parameters: components.parameters || spec.parameters || {},
|
|
23
|
+
responses: components.responses || spec.responses || {},
|
|
24
|
+
};
|
|
14
25
|
|
|
15
26
|
const endpoints = {};
|
|
16
27
|
|
|
@@ -24,7 +35,7 @@ function normalizeSpec(spec) {
|
|
|
24
35
|
for (const method of HTTP_METHODS) {
|
|
25
36
|
if (!pathItem[method]) continue;
|
|
26
37
|
const operation = pathItem[method];
|
|
27
|
-
methods[method] = normalizeOperation(operation,
|
|
38
|
+
methods[method] = normalizeOperation(operation, pathItem.parameters, ctx);
|
|
28
39
|
}
|
|
29
40
|
|
|
30
41
|
if (Object.keys(methods).length > 0) {
|
|
@@ -39,25 +50,62 @@ function normalizeSpec(spec) {
|
|
|
39
50
|
};
|
|
40
51
|
}
|
|
41
52
|
|
|
42
|
-
function normalizeOperation(operation,
|
|
53
|
+
function normalizeOperation(operation, pathParams, ctx) {
|
|
54
|
+
const { schemas } = ctx;
|
|
55
|
+
const params = mergeParameters(pathParams, operation.parameters, ctx);
|
|
56
|
+
const body = params.find((p) => p.in === 'body'); // Swagger 2.0
|
|
43
57
|
return {
|
|
44
58
|
operationId: operation.operationId || null,
|
|
45
59
|
summary: operation.summary || null,
|
|
46
|
-
parameters: normalizeParameters(
|
|
47
|
-
requestBody:
|
|
48
|
-
|
|
60
|
+
parameters: normalizeParameters(params.filter((p) => p.in !== 'body'), schemas),
|
|
61
|
+
requestBody: body
|
|
62
|
+
? (body.schema ? resolveSchema(body.schema, schemas) : null)
|
|
63
|
+
: normalizeRequestBody(operation.requestBody, schemas),
|
|
64
|
+
responses: normalizeResponses(operation.responses || {}, ctx),
|
|
49
65
|
};
|
|
50
66
|
}
|
|
51
67
|
|
|
68
|
+
/** Path-level parameters apply to every operation; an operation-level one with the same (in, name) overrides. */
|
|
69
|
+
function mergeParameters(pathParams, opParams, ctx) {
|
|
70
|
+
const byKey = new Map();
|
|
71
|
+
for (const raw of [...(Array.isArray(pathParams) ? pathParams : []), ...(Array.isArray(opParams) ? opParams : [])]) {
|
|
72
|
+
const p = derefParameter(raw, ctx);
|
|
73
|
+
if (!p || !p.name || !p.in) continue;
|
|
74
|
+
byKey.set(`${p.in}:${p.name}`, p);
|
|
75
|
+
}
|
|
76
|
+
return [...byKey.values()];
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function derefParameter(p, ctx) {
|
|
80
|
+
if (!p || typeof p !== 'object' || !p.$ref) return p;
|
|
81
|
+
const name = refName(p.$ref, ['#/components/parameters/', '#/parameters/']);
|
|
82
|
+
return name ? ctx.parameters[name] || null : null;
|
|
83
|
+
}
|
|
84
|
+
|
|
52
85
|
function normalizeParameters(params, schemas) {
|
|
53
86
|
return params.map((p) => ({
|
|
54
87
|
name: p.name,
|
|
55
88
|
in: p.in,
|
|
56
89
|
required: Boolean(p.required),
|
|
57
|
-
|
|
90
|
+
// Swagger 2.0 non-body parameters declare type/format/items/enum inline.
|
|
91
|
+
schema: p.schema
|
|
92
|
+
? resolveSchema(p.schema, schemas)
|
|
93
|
+
: p.type ? resolveSchema(inlineParamSchema(p), schemas) : null,
|
|
58
94
|
}));
|
|
59
95
|
}
|
|
60
96
|
|
|
97
|
+
function inlineParamSchema(p) {
|
|
98
|
+
const { name, in: _in, required, description, collectionFormat, allowEmptyValue, ...schema } = p;
|
|
99
|
+
return schema;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function refName(ref, prefixes) {
|
|
103
|
+
for (const prefix of prefixes) {
|
|
104
|
+
if (typeof ref === 'string' && ref.startsWith(prefix)) return ref.slice(prefix.length);
|
|
105
|
+
}
|
|
106
|
+
return null;
|
|
107
|
+
}
|
|
108
|
+
|
|
61
109
|
function normalizeRequestBody(requestBody, schemas) {
|
|
62
110
|
if (!requestBody) return null;
|
|
63
111
|
const content = requestBody.content || {};
|
|
@@ -66,10 +114,18 @@ function normalizeRequestBody(requestBody, schemas) {
|
|
|
66
114
|
return resolveSchema(mediaType.schema, schemas);
|
|
67
115
|
}
|
|
68
116
|
|
|
69
|
-
function normalizeResponses(responses,
|
|
117
|
+
function normalizeResponses(responses, ctx) {
|
|
118
|
+
const { schemas } = ctx;
|
|
70
119
|
const result = {};
|
|
71
|
-
for (const [statusCode,
|
|
120
|
+
for (const [statusCode, raw] of Object.entries(responses)) {
|
|
121
|
+
const response = raw && raw.$ref
|
|
122
|
+
? ctx.responses[refName(raw.$ref, ['#/components/responses/', '#/responses/'])]
|
|
123
|
+
: raw;
|
|
72
124
|
if (!response) continue;
|
|
125
|
+
if (response.schema) { // Swagger 2.0
|
|
126
|
+
result[statusCode] = resolveSchema(response.schema, schemas);
|
|
127
|
+
continue;
|
|
128
|
+
}
|
|
73
129
|
const content = response.content || {};
|
|
74
130
|
const mediaType = content['application/json'] || Object.values(content)[0];
|
|
75
131
|
result[statusCode] = mediaType && mediaType.schema
|
|
@@ -96,8 +152,8 @@ function resolveSchema(schema, schemas, depth = 0) {
|
|
|
96
152
|
if (depth > 10) return { type: 'circular' };
|
|
97
153
|
|
|
98
154
|
if (schema.$ref) {
|
|
99
|
-
const
|
|
100
|
-
const resolved = schemas[
|
|
155
|
+
const name = refName(schema.$ref, ['#/components/schemas/', '#/definitions/']);
|
|
156
|
+
const resolved = name ? schemas[name] : undefined;
|
|
101
157
|
if (!resolved) return { type: 'unknown', ref: schema.$ref };
|
|
102
158
|
return resolveSchema(resolved, schemas, depth + 1);
|
|
103
159
|
}
|
package/src/core/usage/impact.js
CHANGED
|
@@ -24,6 +24,17 @@ const { toMs } = require('./usageStore');
|
|
|
24
24
|
|
|
25
25
|
const DAY = 86400e3;
|
|
26
26
|
|
|
27
|
+
// Changes that only matter to clients SENDING a body. GET/HEAD/OPTIONS carry
|
|
28
|
+
// no body, so their calls can't be affected — counting them (list/watch
|
|
29
|
+
// traffic dominates real logs) inflated impact several-fold in real Kubernetes
|
|
30
|
+
// audit data. FIELD_BECAME_REQUIRED is listed because it only breaks senders;
|
|
31
|
+
// on the response side it is a stronger guarantee, not a break.
|
|
32
|
+
const REQUEST_BODY_TYPES = new Set([
|
|
33
|
+
'REQUEST_FIELD_REMOVED', 'REQUEST_FIELD_TYPE_CHANGED', 'REQUEST_REQUIRED_FIELD_ADDED',
|
|
34
|
+
'REQUEST_TYPE_CHANGED', 'FIELD_BECAME_REQUIRED',
|
|
35
|
+
]);
|
|
36
|
+
const BODYLESS_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
|
|
37
|
+
|
|
27
38
|
function applyUsageImpact(result, opts) {
|
|
28
39
|
const {
|
|
29
40
|
usage, baseSpec, baseNorm, file = 'usage.json',
|
|
@@ -124,13 +135,16 @@ function downgradeBlocker(meta, { downgrade, minDays, maxAgeDays, minCoverage })
|
|
|
124
135
|
}
|
|
125
136
|
|
|
126
137
|
function computeImpact(change, { opIndex, baseSpec, baseNorm }) {
|
|
127
|
-
|
|
138
|
+
let endpoints = endpointsOf(change);
|
|
128
139
|
if (endpoints.length === 0) {
|
|
129
140
|
return { verdict: 'unknown', basis: null, reason: 'not tied to a specific endpoint' };
|
|
130
141
|
}
|
|
131
142
|
if (!endpoints.every(([m, p]) => operationExists(baseSpec, m, p))) {
|
|
132
143
|
return { verdict: 'unknown', basis: null, reason: 'endpoint not found in the base spec' };
|
|
133
144
|
}
|
|
145
|
+
if (REQUEST_BODY_TYPES.has(change.type)) {
|
|
146
|
+
endpoints = endpoints.filter(([m]) => !BODYLESS_METHODS.has(m));
|
|
147
|
+
}
|
|
134
148
|
|
|
135
149
|
// Query-parameter changes can be judged per parameter: logs record the
|
|
136
150
|
// query string. Header/path/cookie params and bodies can't — fall back to
|
|
@@ -195,12 +209,14 @@ function computeImpact(change, { opIndex, baseSpec, baseNorm }) {
|
|
|
195
209
|
|
|
196
210
|
function endpointsOf(change) {
|
|
197
211
|
if (change.path && change.method) return [[change.method.toUpperCase(), change.path]];
|
|
198
|
-
|
|
212
|
+
// A merged $ref change lists an endpoint once per occurrence (request AND
|
|
213
|
+
// response); count each endpoint's traffic once.
|
|
214
|
+
const seen = new Map();
|
|
199
215
|
for (const e of change.affectedEndpoints || []) {
|
|
200
216
|
const m = /^([A-Za-z]+) (\S+)$/.exec(e);
|
|
201
|
-
if (m)
|
|
217
|
+
if (m) seen.set(`${m[1].toUpperCase()} ${m[2]}`, [m[1].toUpperCase(), m[2]]);
|
|
202
218
|
}
|
|
203
|
-
return
|
|
219
|
+
return [...seen.values()];
|
|
204
220
|
}
|
|
205
221
|
|
|
206
222
|
function operationExists(spec, method, path) {
|
|
@@ -25,7 +25,8 @@
|
|
|
25
25
|
* combined nginx / Apache "combined" and "common" log formats
|
|
26
26
|
* alb AWS Application Load Balancer access logs
|
|
27
27
|
* json one JSON object per line — nginx JSON log_format, Kong file-log,
|
|
28
|
-
* API Gateway JSON access logs, Envoy/Traefik JSON, ECS-style logs
|
|
28
|
+
* API Gateway JSON access logs, Envoy/Traefik JSON, ECS-style logs,
|
|
29
|
+
* and Kubernetes API-server audit logs (audit.k8s.io Events)
|
|
29
30
|
*/
|
|
30
31
|
|
|
31
32
|
const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']);
|
|
@@ -114,6 +115,9 @@ function parseJsonLine(line) {
|
|
|
114
115
|
let obj;
|
|
115
116
|
try { obj = JSON.parse(trimmed); } catch { return null; }
|
|
116
117
|
if (!obj || typeof obj !== 'object') return null;
|
|
118
|
+
if (obj.kind === 'Event' && typeof obj.apiVersion === 'string' && obj.apiVersion.startsWith('audit.k8s.io/')) {
|
|
119
|
+
return parseK8sAuditEvent(obj);
|
|
120
|
+
}
|
|
117
121
|
|
|
118
122
|
let method = pick(obj, JSON_KEYS.method);
|
|
119
123
|
let target = pick(obj, JSON_KEYS.path);
|
|
@@ -146,6 +150,40 @@ function parseJsonLine(line) {
|
|
|
146
150
|
};
|
|
147
151
|
}
|
|
148
152
|
|
|
153
|
+
// ─── Kubernetes audit events ────────────────────────────────────────────────
|
|
154
|
+
|
|
155
|
+
// Kubernetes verbs → HTTP methods (kubernetes.io/docs/reference/access-authn-authz/authorization/#determine-the-request-verb)
|
|
156
|
+
const K8S_VERBS = {
|
|
157
|
+
get: 'GET', list: 'GET', watch: 'GET',
|
|
158
|
+
create: 'POST', update: 'PUT', patch: 'PATCH',
|
|
159
|
+
delete: 'DELETE', deletecollection: 'DELETE',
|
|
160
|
+
};
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* One request is logged once per audit stage (RequestReceived,
|
|
164
|
+
* ResponseStarted for long-running calls, ResponseComplete). Count only the
|
|
165
|
+
* final stage so each request is counted once.
|
|
166
|
+
*/
|
|
167
|
+
function parseK8sAuditEvent(obj) {
|
|
168
|
+
if (obj.stage !== 'ResponseComplete' && obj.stage !== 'Panic') return null;
|
|
169
|
+
const method = K8S_VERBS[obj.verb];
|
|
170
|
+
if (!method || typeof obj.requestURI !== 'string') return null;
|
|
171
|
+
const { path, query } = splitTarget(obj.requestURI);
|
|
172
|
+
if (!path) return null;
|
|
173
|
+
const code = obj.responseStatus && Number(obj.responseStatus.code);
|
|
174
|
+
return {
|
|
175
|
+
method,
|
|
176
|
+
path,
|
|
177
|
+
query,
|
|
178
|
+
host: null,
|
|
179
|
+
status: Number.isInteger(code) && code >= 100 && code <= 599 ? code : null,
|
|
180
|
+
time: parseAnyTime(obj.requestReceivedTimestamp || obj.stageTimestamp),
|
|
181
|
+
userAgent: nullIfDash(asString(obj.userAgent)),
|
|
182
|
+
extras: [],
|
|
183
|
+
json: obj,
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
|
|
149
187
|
/** Value at a dotted path. Tries the literal key first ("user_agent.original" as one key). */
|
|
150
188
|
function lookup(obj, dotted) {
|
|
151
189
|
if (obj == null) return undefined;
|