specshield 3.5.0 → 3.5.2

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.
@@ -0,0 +1,304 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Security regressions between two specs. Works on the raw documents, because
5
+ * normalizeSpec has no notion of `security`.
6
+ *
7
+ * breaking AUTH_REMOVED, AUTH_SCOPE_REDUCED, AUTH_WEAKENED,
8
+ * ENDPOINT_ADDED_WITHOUT_AUTH, SENSITIVE_FIELD_EXPOSED
9
+ * warnings AUTH_CHANGED, PUBLIC_ENDPOINT_ADDED, SENSITIVE_FIELD_EXPOSED (lower tiers)
10
+ *
11
+ * A requirement is a list of alternatives (OR), each a map of scheme → scopes
12
+ * (AND). The new requirement is at least as strict when every new alternative
13
+ * implies some old one: a credential that passes it would have passed before.
14
+ */
15
+
16
+ const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
17
+ const MAX_DEPTH = 12;
18
+
19
+ function securityDiff(baseDoc, headDoc) {
20
+ const base = operations(baseDoc);
21
+ const head = operations(headDoc);
22
+ const found = [];
23
+ for (const [key, h] of head) {
24
+ const b = base.get(key);
25
+ const headReq = requirement(headDoc, h.op);
26
+ if (!b) found.push(...addedEndpoint(h, headReq, headDoc));
27
+ else found.push(...authChange(b, h, requirement(baseDoc, b.op), headReq, baseDoc, headDoc));
28
+ found.push(...exposedFields(b, h, baseDoc, headDoc, headReq));
29
+ }
30
+ const merged = merge(found);
31
+ return {
32
+ breaking: merged.filter((f) => f.severity === 'error'),
33
+ warnings: merged.filter((f) => f.severity !== 'error'),
34
+ };
35
+ }
36
+
37
+ function operations(doc) {
38
+ const ops = new Map();
39
+ for (const [path, item] of Object.entries((doc && doc.paths) || {})) {
40
+ if (!item || typeof item !== 'object') continue;
41
+ for (const method of METHODS) {
42
+ if (!item[method] || typeof item[method] !== 'object') continue;
43
+ // A renamed path parameter is the same operation.
44
+ ops.set(`${method} ${path.replace(/\{[^}]+\}/g, '{}')}`, { path, method, op: item[method] });
45
+ }
46
+ }
47
+ return ops;
48
+ }
49
+
50
+ // ─── authentication ─────────────────────────────────────────────────────────
51
+
52
+ /** An operation's own `security` wins, even when empty; otherwise the document's. */
53
+ function requirement(doc, op) {
54
+ const source = Array.isArray(op.security) ? 'operation' : Array.isArray(doc.security) ? 'global' : 'none';
55
+ const raw = source === 'operation' ? op.security : source === 'global' ? doc.security : [];
56
+ const alts = raw.filter((a) => a && typeof a === 'object').map((a) => {
57
+ const out = {};
58
+ for (const [scheme, scopes] of Object.entries(a)) out[scheme] = Array.isArray(scopes) ? scopes : [];
59
+ return out;
60
+ });
61
+ return { source, alternatives: alts.length ? alts : [{}] };
62
+ }
63
+
64
+ const isAnonymous = (alt) => Object.keys(alt).length === 0;
65
+ const allowsAnonymous = (req) => req.alternatives.some(isAnonymous);
66
+ const subset = (a, b) => a.every((x) => b.includes(x));
67
+
68
+ function schemeOf(doc, name) {
69
+ const all = (doc.components && doc.components.securitySchemes) || doc.securityDefinitions || {};
70
+ let s = all[name];
71
+ if (s && s.$ref) s = all[String(s.$ref).split('/').pop()];
72
+ return s && typeof s === 'object' ? s : null;
73
+ }
74
+
75
+ /** Relative strength of one scheme; null when the spec doesn't define it. */
76
+ function strength(doc, name) {
77
+ const s = schemeOf(doc, name);
78
+ if (!s) return null;
79
+ const type = String(s.type || '').toLowerCase();
80
+ if (type === 'mutualtls') return 4;
81
+ if (type === 'oauth2' || type === 'openidconnect') return 3;
82
+ if (type === 'basic') return 1; // Swagger 2.0
83
+ if (type === 'apikey') return String(s.in).toLowerCase() === 'query' ? 1 : 2; // in a URL it ends up in logs
84
+ if (type === 'http') return String(s.scheme).toLowerCase() === 'basic' ? 1 : 3;
85
+ return null;
86
+ }
87
+
88
+ /** An alternative is as strong as its strongest scheme. */
89
+ function altStrength(doc, alt) {
90
+ const names = Object.keys(alt);
91
+ if (!names.length) return 0;
92
+ const all = names.map((n) => strength(doc, n));
93
+ return all.includes(null) ? null : Math.max(...all);
94
+ }
95
+
96
+ function implies(h, b, headDoc, baseDoc) {
97
+ if (!Object.keys(b).every((s) => s in h && subset(b[s], h[s]))) return false;
98
+ const hs = altStrength(headDoc, h);
99
+ const bs = altStrength(baseDoc, b);
100
+ return hs === null || bs === null || hs >= bs;
101
+ }
102
+
103
+ function authChange(b, h, baseReq, headReq, baseDoc, headDoc) {
104
+ const loose = headReq.alternatives.filter((alt) => !baseReq.alternatives.some((x) => implies(alt, x, headDoc, baseDoc)));
105
+ if (!loose.length) return [];
106
+ const ep = endpoint(h);
107
+ const was = describeReq(baseReq);
108
+ const global = baseReq.source === 'global' && headReq.source !== 'operation';
109
+ const at = global ? 'The API-wide security requirement' : ep;
110
+ const finding = (type, severity, field, description) => ({
111
+ ...change(type, h, severity, field, description),
112
+ ...(global ? { mergeAs: `${type}|${field || ''}|${description}` } : {}),
113
+ });
114
+
115
+ if (loose.some(isAnonymous)) {
116
+ return [finding('AUTH_REMOVED', 'error', null, `Security: ${at} no longer requires authentication (was ${was}) — anyone can call ${global ? 'these endpoints' : 'it'}`)];
117
+ }
118
+ for (const alt of loose) {
119
+ for (const x of baseReq.alternatives) {
120
+ const names = Object.keys(x);
121
+ if (names.length !== Object.keys(alt).length || !names.every((s) => s in alt)) continue;
122
+ const scheme = names.find((s) => !subset(x[s], alt[s]));
123
+ if (scheme && names.every((s) => subset(alt[s], x[s]))) {
124
+ const dropped = x[scheme].filter((s) => !alt[scheme].includes(s));
125
+ return [finding('AUTH_SCOPE_REDUCED', 'error', scheme, `Security: ${at} no longer requires ${dropped.length === 1 ? 'scope' : 'scopes'} ${dropped.join(', ')} on ${scheme}`)];
126
+ }
127
+ }
128
+ }
129
+ const floor = Math.min(...baseReq.alternatives.map((x) => altStrength(baseDoc, x) ?? Infinity));
130
+ for (const alt of loose) {
131
+ const s = altStrength(headDoc, alt);
132
+ const fewer = baseReq.alternatives.some((x) => Object.keys(alt).length < Object.keys(x).length && Object.keys(alt).every((n) => n in x));
133
+ if (fewer || (s !== null && s < floor)) {
134
+ return [finding('AUTH_WEAKENED', 'error', Object.keys(alt).join('+'), `Security: ${at} now accepts weaker authentication: ${describeAlt(alt, headDoc)} (was ${was})`)];
135
+ }
136
+ }
137
+ return [finding('AUTH_CHANGED', 'warning', Object.keys(loose[0]).join('+'), `Security: ${at} now accepts ${describeAlt(loose[0], headDoc)} (was ${was}) — check it grants no more than before`)];
138
+ }
139
+
140
+ /**
141
+ * A new endpoint with no security at all, in an API that protects others, was
142
+ * most likely forgotten; `security: []` was written on purpose, so it's only flagged.
143
+ */
144
+ function addedEndpoint(h, req, doc) {
145
+ if (!allowsAnonymous(req)) return [];
146
+ if (req.source === 'operation') {
147
+ return [change('PUBLIC_ENDPOINT_ADDED', h, 'warning', null, `Security: new endpoint ${endpoint(h)} is public (security: [])`)];
148
+ }
149
+ if (!declaresAuth(doc)) return [];
150
+ return [change('ENDPOINT_ADDED_WITHOUT_AUTH', h, 'error', null, `Security: new endpoint ${endpoint(h)} has no authentication, unlike the rest of this API — add security, or "security: []" if it is meant to be public`)];
151
+ }
152
+
153
+ /** Specs that declare no auth anywhere say nothing about which endpoints are public. */
154
+ function declaresAuth(doc) {
155
+ return [...operations(doc).values()].some((o) => !allowsAnonymous(requirement(doc, o.op)));
156
+ }
157
+
158
+ function describeAlt(alt, doc) {
159
+ return Object.entries(alt).map(([name, scopes]) => {
160
+ const s = schemeOf(doc, name);
161
+ const kind = !s ? '' : s.type === 'apiKey' ? ` (API key in ${s.in})` : s.type === 'http' ? ` (${s.scheme})` : s.type === 'basic' ? ' (basic)' : '';
162
+ return `${name}${kind}${scopes.length ? ` [${scopes.join(', ')}]` : ''}`;
163
+ }).join(' + ') || 'no authentication';
164
+ }
165
+
166
+ function describeReq(req) {
167
+ return req.alternatives.map((a) => (isAnonymous(a) ? 'anonymous' : Object.entries(a).map(([n, s]) => `${n}${s.length ? ` [${s.join(', ')}]` : ''}`).join(' + '))).join(' or ');
168
+ }
169
+
170
+ // ─── sensitive fields in responses ──────────────────────────────────────────
171
+
172
+ const CREDENTIAL = /(^|_)(password|passwd|pwd|passphrase|secret|private_key|api_key|apikey)$/;
173
+ const REGULATED = /(^|_)(ssn|social_security_number|aadhaar|cvv|cvc|card_number|credit_card_number|passport_number|tax_id|bank_account_number)$/;
174
+ const TOKEN = /(^|_)(access_token|refresh_token|id_token|auth_token|session_token|bearer_token|jwt|session_id)$/;
175
+ const PERSONAL = /(^|_)(email|email_address|phone|phone_number|date_of_birth|dob|birthdate|birth_date|home_address)$/;
176
+ // The name has to end in the term: password_changed_at, secret_scanning_status and
177
+ // cvc_check are facts about a secret, not the secret.
178
+ const words = (name) => String(name)
179
+ .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
180
+ .replace(/[^A-Za-z0-9]+/g, '_')
181
+ .toLowerCase();
182
+
183
+ /** credential | regulated | token | personal | null */
184
+ function sensitivity(name, schema) {
185
+ const types = [].concat((schema && schema.type) || 'string');
186
+ if (!types.includes('string')) return null;
187
+ const w = words(name);
188
+ if (schema && schema.format === 'password') return 'credential';
189
+ if (CREDENTIAL.test(w)) return 'credential';
190
+ if (REGULATED.test(w)) return 'regulated';
191
+ if (TOKEN.test(w)) return 'token';
192
+ if (PERSONAL.test(w) || (schema && schema.format === 'email')) return 'personal';
193
+ return null;
194
+ }
195
+
196
+ const LABEL = { credential: 'a credential', regulated: 'regulated personal data', token: 'a token', personal: 'personal data' };
197
+
198
+ function exposedFields(b, h, baseDoc, headDoc, headReq) {
199
+ const before = new Set(b ? sensitiveResponseFields(baseDoc, b.op).map((f) => leaf(f.path)) : []);
200
+ const isPublic = allowsAnonymous(headReq) && (headReq.source === 'operation' || declaresAuth(headDoc));
201
+ const seen = new Set();
202
+ const out = [];
203
+ for (const f of sensitiveResponseFields(headDoc, h.op)) {
204
+ const name = leaf(f.path);
205
+ if (before.has(name) || seen.has(name)) continue;
206
+ seen.add(name);
207
+ const high = f.tier === 'credential' || f.tier === 'regulated' || isPublic;
208
+ const where = isPublic ? 'a public response' : 'a response';
209
+ const via = f.path === name ? '' : ` (at ${f.path})`;
210
+ out.push({
211
+ ...change('SENSITIVE_FIELD_EXPOSED', h, high ? 'error' : 'warning', name, `Security: new field "${name}"${via} in ${where} looks like ${LABEL[f.tier]}`),
212
+ mergeAs: `exposed|${name}|${f.tier}|${isPublic}`,
213
+ });
214
+ }
215
+ return out;
216
+ }
217
+
218
+ const leaf = (p) => p.split('.').pop().replace(/\[\]$/, '');
219
+
220
+ /** Sensitive fields a 2xx response can carry, with their paths. */
221
+ function sensitiveResponseFields(doc, op) {
222
+ const out = [];
223
+ const memo = memoFor(doc);
224
+ for (const [status, raw] of Object.entries(op.responses || {})) {
225
+ if (!/^2/.test(status)) continue;
226
+ const res = deref(doc, raw);
227
+ if (!res) continue;
228
+ const schemas = res.schema ? [res.schema] : Object.entries(res.content || {})
229
+ .filter(([type]) => /json/i.test(type)).map(([, m]) => m && m.schema).filter(Boolean);
230
+ for (const s of schemas) out.push(...walk(doc, s, memo, new Set(), 0));
231
+ }
232
+ return out;
233
+ }
234
+
235
+ const memos = new WeakMap();
236
+ function memoFor(doc) {
237
+ if (!memos.has(doc)) memos.set(doc, new Map());
238
+ return memos.get(doc);
239
+ }
240
+
241
+ function deref(doc, node) {
242
+ let n = node;
243
+ for (let i = 0; n && n.$ref && i < 20; i++) {
244
+ if (typeof n.$ref !== 'string' || !n.$ref.startsWith('#/')) return null;
245
+ n = n.$ref.slice(2).split('/').reduce((o, k) => (o ? o[k.replace(/~1/g, '/').replace(/~0/g, '~')] : undefined), doc);
246
+ }
247
+ return n && typeof n === 'object' ? n : null;
248
+ }
249
+
250
+ /** [{path, tier}] relative to this schema. Named schemas are memoized; cycles are cut. */
251
+ function walk(doc, node, memo, stack, depth) {
252
+ if (!node || depth > MAX_DEPTH) return [];
253
+ if (node.$ref) {
254
+ if (memo.has(node.$ref)) return memo.get(node.$ref);
255
+ if (stack.has(node.$ref)) return [];
256
+ stack.add(node.$ref);
257
+ const r = walk(doc, deref(doc, node), memo, stack, depth + 1);
258
+ stack.delete(node.$ref);
259
+ memo.set(node.$ref, r);
260
+ return r;
261
+ }
262
+ const out = [];
263
+ for (const key of ['allOf', 'oneOf', 'anyOf']) {
264
+ if (Array.isArray(node[key])) for (const s of node[key]) out.push(...walk(doc, s, memo, stack, depth + 1));
265
+ }
266
+ if (node.items) out.push(...walk(doc, node.items, memo, stack, depth + 1).map((f) => ({ ...f, path: `[].${f.path}` })));
267
+ if (node.additionalProperties && typeof node.additionalProperties === 'object') {
268
+ out.push(...walk(doc, node.additionalProperties, memo, stack, depth + 1));
269
+ }
270
+ for (const [name, raw] of Object.entries(node.properties || {})) {
271
+ const prop = deref(doc, raw);
272
+ if (!prop || prop.writeOnly) continue;
273
+ const tier = sensitivity(name, prop);
274
+ if (tier) out.push({ path: name, tier });
275
+ out.push(...walk(doc, raw, memo, stack, depth + 1).map((f) => ({ ...f, path: `${name}.${f.path}` })));
276
+ }
277
+ return out.map((f) => ({ ...f, path: f.path.replace(/^\[\]\./, '') }));
278
+ }
279
+
280
+ // ─── findings ───────────────────────────────────────────────────────────────
281
+
282
+ const endpoint = (h) => `${h.method.toUpperCase()} ${h.path}`;
283
+
284
+ function change(type, h, severity, field, description) {
285
+ return { type, category: 'security', path: h.path, method: h.method, field, severity, description };
286
+ }
287
+
288
+ /** One finding for a cause shared by many endpoints: a global requirement or a shared schema. */
289
+ function merge(found) {
290
+ const out = [];
291
+ const groups = new Map();
292
+ for (const f of found) {
293
+ const { mergeAs, ...c } = f;
294
+ const ep = `${c.method.toUpperCase()} ${c.path}`;
295
+ const g = mergeAs && groups.get(mergeAs);
296
+ if (g) { g.affectedEndpoints.push(ep); continue; }
297
+ const item = { ...c, affectedEndpoints: [ep] };
298
+ if (mergeAs) groups.set(mergeAs, item);
299
+ out.push(item);
300
+ }
301
+ return out;
302
+ }
303
+
304
+ module.exports = { securityDiff, requirement, sensitivity };