specshield 3.5.1 → 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.
- package/CHANGELOG.md +6 -0
- package/README.md +20 -1
- package/package.json +1 -1
- package/src/commands/gate.js +29 -5
- package/src/core/configLoader.js +2 -1
- package/src/core/gate/runGate.js +10 -1
- package/src/core/security/diff.js +304 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# SpecShield CLI changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased — security regressions in the gate
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- `specshield gate --security` (or `gate.security: true`) blocks removed or weakened authentication, dropped OAuth scopes, new endpoints with forgotten auth, and newly exposed credentials or regulated data. Lower-risk changes are reported for review. Off by default. Findings use the existing shadow mode and waivers.
|
|
8
|
+
|
|
3
9
|
## Unreleased — proof, not opinion: `specshield prove` and `specshield replay`
|
|
4
10
|
|
|
5
11
|
### Added
|
package/README.md
CHANGED
|
@@ -42,7 +42,7 @@ What the CLI does:
|
|
|
42
42
|
- [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
|
|
43
43
|
|
|
44
44
|
**Commands — local & hosted compare**
|
|
45
|
-
- [Local Compare](#local-compare) · [**Who does a change break? (usage-aware compare)**](#who-does-a-change-break--usage-aware-compare) · [**Safe removal: deprecate → drain → remove**](#safe-removal-deprecate--watch-traffic-drain--remove) · [**Break → fix: `specshield fix`**](#break--fix-generate-the-non-breaking-version) · [**CI gate: `specshield gate`**](#a-gate-you-can-leave-blocking-specshield-gate) · [**Proof: `prove` & `replay`**](#proof-not-opinion-specshield-prove-and-specshield-replay) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
|
|
45
|
+
- [Local Compare](#local-compare) · [**Who does a change break? (usage-aware compare)**](#who-does-a-change-break--usage-aware-compare) · [**Safe removal: deprecate → drain → remove**](#safe-removal-deprecate--watch-traffic-drain--remove) · [**Break → fix: `specshield fix`**](#break--fix-generate-the-non-breaking-version) · [**CI gate: `specshield gate`**](#a-gate-you-can-leave-blocking-specshield-gate) · [**Proof: `prove` & `replay`**](#proof-not-opinion-specshield-prove-and-specshield-replay) · [**Security regressions: `gate --security`**](#security-regressions-in-the-gate-specshield-gate---security) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
|
|
46
46
|
|
|
47
47
|
**Governance — lint & gate**
|
|
48
48
|
- [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
|
|
@@ -578,6 +578,25 @@ In GitHub Actions the gate also writes a job summary and annotations (`--no-summ
|
|
|
578
578
|
|
|
579
579
|
---
|
|
580
580
|
|
|
581
|
+
## Security regressions in the gate: `specshield gate --security`
|
|
582
|
+
|
|
583
|
+
The gate also blocks a PR that makes the API less safe. Turn it on with `--security`, or `gate.security: true` in `.specshield.yml`.
|
|
584
|
+
|
|
585
|
+
| Finding (waiver `change`) | Blocks? | Example |
|
|
586
|
+
|---|---|---|
|
|
587
|
+
| `auth-removed` | yes | An operation, or the API-wide `security`, now allows anonymous calls |
|
|
588
|
+
| `auth-scope-reduced` | yes | `[refunds:write, admin]` became `[refunds:write]` |
|
|
589
|
+
| `auth-weakened` | yes | Bearer became basic, an API key moved to the query string, or one required scheme was dropped |
|
|
590
|
+
| `endpoint-added-without-auth` | yes | A new endpoint declares no security while others in the API do |
|
|
591
|
+
| `sensitive-field-exposed` | credentials and regulated data; personal data on public endpoints | New response field `password`, `client_secret`, `cardNumber`, `ssn`; `writeOnly` dropped |
|
|
592
|
+
| `sensitive-field-exposed` | no, reported for review | New `email`, `phone` or token field on an authenticated endpoint |
|
|
593
|
+
| `auth-changed` | no, reported for review | Moved to a different scheme of equal strength |
|
|
594
|
+
| `public-endpoint-added` | no, reported for review | A new endpoint with an explicit `security: []` |
|
|
595
|
+
|
|
596
|
+
A new requirement counts as safe only when every credential that passes it would have passed the old one. Moving a requirement between global and operation level, or adding a scope, reports nothing.
|
|
597
|
+
|
|
598
|
+
Findings work like every other gate finding: `--shadow` reports without failing, and a waiver needs an owner, a reason and an expiry. Usage data never hides them. This reads what the spec declares; it doesn't test what the running service enforces. Sensitive fields are matched by name and `format`, so expect the occasional miss on unusual names.
|
|
599
|
+
|
|
581
600
|
## Proof, not opinion: `specshield prove` and `specshield replay`
|
|
582
601
|
|
|
583
602
|
A diff says *"breaking change"*. A reviewer asks *"does it actually break anything?"* — and a gate that can't answer gets overruled. `prove` answers with the exact request that worked before and fails now; `replay` answers with real traffic.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specshield",
|
|
3
|
-
"version": "3.5.
|
|
3
|
+
"version": "3.5.2",
|
|
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",
|
package/src/commands/gate.js
CHANGED
|
@@ -27,6 +27,7 @@ const gate = new Command('gate')
|
|
|
27
27
|
.option('--no-fetch', 'Never run git fetch, even when the baseline commit is missing from a shallow clone')
|
|
28
28
|
.option('--usage <file>', 'usage.json from "specshield usage import" — breaking changes no client uses stop blocking')
|
|
29
29
|
.option('--prove', 'Attach a proof to every breaking change: the request that worked at the baseline and fails now')
|
|
30
|
+
.option('--security', 'Also block security regressions: authentication removed or weakened, scopes dropped, sensitive fields newly exposed')
|
|
30
31
|
.option('--no-summary', 'Skip the GitHub Actions job summary and annotations')
|
|
31
32
|
.option('--upload', 'Record this run on your SpecShield dashboard, for the shadow-mode graduation report (Team plan)')
|
|
32
33
|
.option('--org <key>', 'Org key for --upload (default: gate.org or bdct.org in .specshield.yml)')
|
|
@@ -53,6 +54,7 @@ const gate = new Command('gate')
|
|
|
53
54
|
ignore: config.ignore || [],
|
|
54
55
|
usage: usage.usage ? usage : null,
|
|
55
56
|
prove: Boolean(opts.prove || g.prove),
|
|
57
|
+
security: Boolean(opts.security || g.security),
|
|
56
58
|
});
|
|
57
59
|
|
|
58
60
|
if (opts.upload || g.upload) r.upload = await upload(r, { ...opts, org: opts.org || g.org });
|
|
@@ -151,6 +153,9 @@ function label(c) {
|
|
|
151
153
|
return { where, what };
|
|
152
154
|
}
|
|
153
155
|
|
|
156
|
+
const isSecurity = (c) => c.category === 'security';
|
|
157
|
+
const noun = (list) => (list.every(isSecurity) ? 'security regression' : list.some(isSecurity) ? 'blocking change' : 'breaking change');
|
|
158
|
+
|
|
154
159
|
function render(r) {
|
|
155
160
|
const lines = [''];
|
|
156
161
|
lines.push(chalk.bold(` SpecShield™ Gate — ${r.spec}`));
|
|
@@ -172,8 +177,8 @@ function render(r) {
|
|
|
172
177
|
(r.nonBreaking ? chalk.gray(` · ${plural(r.nonBreaking, 'non-breaking change')}`) : ''));
|
|
173
178
|
} else {
|
|
174
179
|
const head = r.verdict === 'would-block'
|
|
175
|
-
? chalk.yellow.bold(` ▲ Shadow mode: would have blocked this change — ${plural(r.blocking.length,
|
|
176
|
-
: chalk.red.bold(` ✖ ${plural(r.blocking.length,
|
|
180
|
+
? chalk.yellow.bold(` ▲ Shadow mode: would have blocked this change — ${plural(r.blocking.length, noun(r.blocking))}`)
|
|
181
|
+
: chalk.red.bold(` ✖ ${plural(r.blocking.length, noun(r.blocking))} block${r.blocking.length === 1 ? 's' : ''} this change`);
|
|
177
182
|
lines.push(head);
|
|
178
183
|
for (const c of r.blocking) {
|
|
179
184
|
const { where, what } = label(c);
|
|
@@ -188,6 +193,15 @@ function render(r) {
|
|
|
188
193
|
}
|
|
189
194
|
}
|
|
190
195
|
|
|
196
|
+
if (r.security && r.security.warnings.length) {
|
|
197
|
+
lines.push('');
|
|
198
|
+
lines.push(chalk.bold(` Security review (${r.security.warnings.length}, not blocking)`));
|
|
199
|
+
for (const c of r.security.warnings) {
|
|
200
|
+
const { where, what } = label(c);
|
|
201
|
+
lines.push(` ${chalk.yellow('▲')} ${what}${where ? chalk.gray(` · ${where}`) : ''}`);
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
191
205
|
if (r.waived.length) {
|
|
192
206
|
lines.push('');
|
|
193
207
|
lines.push(chalk.bold(` Waived (${r.waived.length})`));
|
|
@@ -249,7 +263,8 @@ function annotate(r) {
|
|
|
249
263
|
const file = `file=${escProp(r.spec)}`;
|
|
250
264
|
for (const c of r.blocking) {
|
|
251
265
|
const { where, what } = label(c);
|
|
252
|
-
const
|
|
266
|
+
const kind = isSecurity(c) ? 'API security regression' : 'Breaking API change';
|
|
267
|
+
const title = r.verdict === 'would-block' ? `${kind} (shadow mode)` : kind;
|
|
253
268
|
const extra = c.expiredWaiver ? ` — waiver expired ${c.expiredWaiver.expires}` : '';
|
|
254
269
|
process.stdout.write(`::${level} ${file},title=${escProp(title)}::${esc(`${what}${where ? ` (${where})` : ''}${extra}`)}\n`);
|
|
255
270
|
}
|
|
@@ -273,8 +288,8 @@ function markdown(r) {
|
|
|
273
288
|
else if (r.blocking.length === 0) md.push(`No breaking changes block this change${r.waived.length ? ` (${r.waived.length} waived)` : ''}.`);
|
|
274
289
|
else {
|
|
275
290
|
md.push(r.verdict === 'would-block'
|
|
276
|
-
? `**Shadow mode:** would have blocked this change — ${plural(r.blocking.length,
|
|
277
|
-
: `**${plural(r.blocking.length,
|
|
291
|
+
? `**Shadow mode:** would have blocked this change — ${plural(r.blocking.length, noun(r.blocking))}.`
|
|
292
|
+
: `**${plural(r.blocking.length, noun(r.blocking))}** block this change.`);
|
|
278
293
|
md.push('');
|
|
279
294
|
md.push('| Change | Where | |');
|
|
280
295
|
md.push('|---|---|---|');
|
|
@@ -294,6 +309,15 @@ function markdown(r) {
|
|
|
294
309
|
md.push('');
|
|
295
310
|
md.push(`Intended? Add a waiver with an owner, a reason and an expiry: \`${waiveCommand(r.blocking[0], r.waivers.file)}\``);
|
|
296
311
|
}
|
|
312
|
+
if (r.security && r.security.warnings.length) {
|
|
313
|
+
md.push('');
|
|
314
|
+
md.push(`**Security review (not blocking):**`);
|
|
315
|
+
md.push('');
|
|
316
|
+
for (const c of r.security.warnings) {
|
|
317
|
+
const { where, what } = label(c);
|
|
318
|
+
md.push(`- ${cell(what)}${where ? ` — ${cell(where)}` : ''}`);
|
|
319
|
+
}
|
|
320
|
+
}
|
|
297
321
|
if (r.waived.length) {
|
|
298
322
|
md.push('');
|
|
299
323
|
md.push('<details><summary>Waived</summary>');
|
package/src/core/configLoader.js
CHANGED
|
@@ -158,7 +158,7 @@ function validateConfig(config, filePath) {
|
|
|
158
158
|
throw new Error(`Config error in "${filePath}": gate.${key} must be a string`);
|
|
159
159
|
}
|
|
160
160
|
}
|
|
161
|
-
for (const key of ['upload', 'prove']) {
|
|
161
|
+
for (const key of ['upload', 'prove', 'security']) {
|
|
162
162
|
if (g[key] !== undefined && typeof g[key] !== 'boolean') {
|
|
163
163
|
throw new Error(`Config error in "${filePath}": gate.${key} must be a boolean`);
|
|
164
164
|
}
|
|
@@ -170,6 +170,7 @@ function validateConfig(config, filePath) {
|
|
|
170
170
|
maxWaiverDays: g.maxWaiverDays !== undefined ? Number(g.maxWaiverDays) : undefined,
|
|
171
171
|
upload: g.upload,
|
|
172
172
|
prove: g.prove,
|
|
173
|
+
security: g.security,
|
|
173
174
|
org: g.org,
|
|
174
175
|
};
|
|
175
176
|
}
|
package/src/core/gate/runGate.js
CHANGED
|
@@ -11,6 +11,7 @@ const { resolveBaseline } = require('./baseline');
|
|
|
11
11
|
const G = require('./git');
|
|
12
12
|
const W = require('./waivers');
|
|
13
13
|
const P = require('../prove');
|
|
14
|
+
const { securityDiff } = require('../security/diff');
|
|
14
15
|
|
|
15
16
|
/**
|
|
16
17
|
* One gate run: the spec at the merge base vs the spec in the working tree,
|
|
@@ -24,7 +25,7 @@ async function runGate(opts) {
|
|
|
24
25
|
const {
|
|
25
26
|
spec, cwd = process.cwd(), base, env = process.env, fetch = true,
|
|
26
27
|
mode = 'blocking', waiversFile = W.DEFAULT_FILE, maxWaiverDays = W.DEFAULT_MAX_DAYS,
|
|
27
|
-
ignore = [], usage = null, now = Date.now(), prove = false,
|
|
28
|
+
ignore = [], usage = null, now = Date.now(), prove = false, security = false,
|
|
28
29
|
} = opts;
|
|
29
30
|
if (!['blocking', 'shadow'].includes(mode)) throw new Error(`mode must be "blocking" or "shadow", got "${mode}"`);
|
|
30
31
|
|
|
@@ -100,6 +101,14 @@ async function runGate(opts) {
|
|
|
100
101
|
out.breaking = out.breaking.map((c) => ({ ...c, proof: P.proofFor(c, proofs) }));
|
|
101
102
|
out.proofs = P.summarize(out.breaking);
|
|
102
103
|
}
|
|
104
|
+
if (security && docs) {
|
|
105
|
+
// Not subject to usage data: an endpoint nobody calls yet can still be left open.
|
|
106
|
+
const s = securityDiff(docs.baseDoc, docs.headDoc);
|
|
107
|
+
const hit = (c) => ignore.some((p) => (c.description || '').includes(p));
|
|
108
|
+
out.ignored = [...out.ignored, ...s.breaking.filter(hit)];
|
|
109
|
+
out.breaking = [...s.breaking.filter((c) => !hit(c)).map(withKey), ...out.breaking];
|
|
110
|
+
out.security = { warnings: s.warnings.filter((c) => !hit(c)).map(withKey) };
|
|
111
|
+
}
|
|
103
112
|
const { blocking, waived, used } = W.applyWaivers(out.breaking, headW.waivers, now);
|
|
104
113
|
out.blocking = blocking;
|
|
105
114
|
out.waived = waived;
|
|
@@ -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 };
|