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 CHANGED
@@ -1,6 +1,32 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
- ## Unreleased — usage-aware compare: "who does this change break?"
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, Envoy/Traefik, ECS). Auto-detected; `.gz`
282
- files and stdin (`-`) work. Force one with `--format combined|alb|json`.
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.13",
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, schemas);
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, schemas) {
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(operation.parameters || [], schemas),
47
- requestBody: normalizeRequestBody(operation.requestBody, schemas),
48
- responses: normalizeResponses(operation.responses || {}, schemas),
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
- schema: p.schema ? resolveSchema(p.schema, schemas) : null,
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, schemas) {
117
+ function normalizeResponses(responses, ctx) {
118
+ const { schemas } = ctx;
70
119
  const result = {};
71
- for (const [statusCode, response] of Object.entries(responses)) {
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 refName = schema.$ref.replace('#/components/schemas/', '');
100
- const resolved = schemas[refName];
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
  }
@@ -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
- const endpoints = endpointsOf(change);
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
- const out = [];
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) out.push([m[1].toUpperCase(), m[2]]);
217
+ if (m) seen.set(`${m[1].toUpperCase()} ${m[2]}`, [m[1].toUpperCase(), m[2]]);
202
218
  }
203
- return out;
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;