specshield 3.5.1 → 3.5.3

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,18 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
- ## Unreleased — proof, not opinion: `specshield prove` and `specshield replay`
3
+ ## Unreleased — security audit
4
+
5
+ ### Added
6
+
7
+ - `specshield audit <spec>` audits a spec by OWASP API Security Top 10 category. `--har` adds passive checks on captured traffic: leaked secrets, personal data, CORS, cookies and missing headers. Secret values are never printed. Supports `--fail-on`, waivers, SARIF output and the GitHub job summary. Sends no requests.
8
+
9
+ ## 3.5.2 — 2026-11-10 — security regressions in the gate
10
+
11
+ ### Added
12
+
13
+ - `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.
14
+
15
+ ## 3.5.1 — 2026-10-29 — proof, not opinion: `specshield prove` and `specshield replay`
4
16
 
5
17
  ### Added
6
18
 
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) · [**Security audit: `audit`**](#security-audit-specshield-audit) · [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,49 @@ 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
+
600
+ ## Security audit: `specshield audit`
601
+
602
+ Audits a whole spec and, optionally, captured traffic, by [OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) category. It sends no requests.
603
+
604
+ ```bash
605
+ specshield audit openapi.yaml
606
+ specshield audit openapi.yaml --har staging.har --host api.acme.com
607
+ specshield audit openapi.yaml --fail-on medium --sarif audit.sarif
608
+ ```
609
+
610
+ **From the spec:** missing or undefined authentication, public writes and admin endpoints, API keys and secrets in URLs, basic auth, deprecated OAuth flows, OAuth over HTTP, credentials in responses, personal data on public endpoints, privileged request fields, page sizes with no maximum, client-supplied URLs, plain-HTTP and non-production servers.
611
+
612
+ **From a HAR file (`--har`):** secrets in URLs and responses, regulated and personal data, plain HTTP, missing HSTS and `nosniff`, risky CORS, unprotected session cookies, version banners, stack traces. Findings say where a secret was seen and never print its value. Only API responses are checked, so use `--host` to leave out third parties in a browser capture.
613
+
614
+ | Option | Default | |
615
+ |---|---|---|
616
+ | `--fail-on <severity>` | `high` | Exit 1 at or above `high`, `medium` or `low`; `none` never fails |
617
+ | `--waivers <file>` | `.specshield/waivers.yml` | Accepted findings, with an owner, a reason and an expiry. The `change` is the rule id |
618
+ | `--sarif <file>` | | SARIF 2.1.0, for GitHub code scanning |
619
+ | `--all` | | List every low-severity finding |
620
+ | `--json` | | Machine-readable output |
621
+
622
+ A spec shows what is declared, not what the service enforces, so "nothing found" is not a pass. Most categories are only partly checkable this way, and API6 and API10 need runtime testing.
623
+
581
624
  ## Proof, not opinion: `specshield prove` and `specshield replay`
582
625
 
583
626
  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.1",
3
+ "version": "3.5.3",
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/cli.js CHANGED
@@ -18,6 +18,7 @@ const gateCommand = require('./commands/gate');
18
18
  const waiversCommand = require('./commands/waivers');
19
19
  const proveCommand = require('./commands/prove');
20
20
  const replayCommand = require('./commands/replay');
21
+ const auditCommand = require('./commands/audit');
21
22
 
22
23
  const program = new Command();
23
24
 
@@ -46,6 +47,7 @@ program.addCommand(gateCommand);
46
47
  program.addCommand(waiversCommand);
47
48
  program.addCommand(proveCommand);
48
49
  program.addCommand(replayCommand);
50
+ program.addCommand(auditCommand);
49
51
 
50
52
  program.parseAsync(process.argv).catch((err) => {
51
53
  const logger = require('./utils/logger');
@@ -0,0 +1,179 @@
1
+ 'use strict';
2
+
3
+ const { Command } = require('commander');
4
+ const chalk = require('chalk');
5
+ const fs = require('fs');
6
+ const path = require('path');
7
+ const { loadSpec } = require('../core/loadSpec');
8
+ const { parseSpec } = require('../core/parseSpec');
9
+ const { auditSpec, consolidate } = require('../core/security/audit');
10
+ const { auditHar } = require('../core/security/auditHar');
11
+ const { OWASP, RULES, SEVERITIES } = require('../core/security/rules');
12
+ const W = require('../core/gate/waivers');
13
+ const { plural } = require('../core/usage/format');
14
+ const logger = require('../utils/logger');
15
+ const exitAfterFlush = require('../utils/exitAfterFlush');
16
+ const pkg = require('../../package.json');
17
+
18
+ const FAIL_ON = [...SEVERITIES, 'none'];
19
+
20
+ const audit = new Command('audit')
21
+ .description('Security audit of an OpenAPI spec and captured traffic, by OWASP API Security Top 10 category. Sends no requests')
22
+ .argument('[spec]', 'The OpenAPI spec to audit')
23
+ .option('--har <file...>', 'HAR capture(s) to check for leaked secrets, personal data and missing protections')
24
+ .option('--host <host...>', 'Only check these hosts in the capture')
25
+ .option('--fail-on <severity>', 'Exit 1 at or above this severity: high, medium, low, or none', 'high')
26
+ .option('--waivers <file>', `Waiver file (default: ${W.DEFAULT_FILE})`, W.DEFAULT_FILE)
27
+ .option('--all', 'List every low-severity finding')
28
+ .option('--sarif <file>', 'Also write SARIF, for GitHub code scanning')
29
+ .option('--no-summary', 'Skip the GitHub Actions job summary')
30
+ .option('--json', 'Output machine-readable JSON')
31
+ .action(async (specPath, opts) => {
32
+ try {
33
+ if (!specPath && !opts.har) throw new Error('Nothing to audit: pass a spec, --har <file>, or both');
34
+ if (!FAIL_ON.includes(opts.failOn)) throw new Error(`--fail-on must be one of ${FAIL_ON.join(', ')}`);
35
+
36
+ let specText = null;
37
+ let doc = null;
38
+ if (specPath) { specText = await loadSpec(specPath); doc = parseSpec(specText, specPath); }
39
+ const har = opts.har ? auditHar(opts.har, { hosts: opts.host ? new Set(opts.host.map((h) => h.toLowerCase())) : null }) : null;
40
+
41
+ const now = Date.now();
42
+ const { waivers } = await W.loadWaivers(path.resolve(opts.waivers), { maxDays: W.DEFAULT_MAX_DAYS, now, file: opts.waivers });
43
+ const all = [...(doc ? auditSpec(doc) : []), ...(har ? har.findings : [])];
44
+ const { blocking, waived } = W.applyWaivers(all, waivers, now);
45
+ const findings = sort(consolidate(blocking));
46
+ const failing = findings.filter((f) => atLeast(f.severity, opts.failOn));
47
+ const r = {
48
+ spec: specPath || null,
49
+ title: doc && doc.info ? doc.info.title || null : null,
50
+ har: har ? { files: opts.har, ...har.stats } : null,
51
+ failOn: opts.failOn,
52
+ counts: count(findings),
53
+ owasp: byOwasp(findings),
54
+ findings,
55
+ waived,
56
+ verdict: failing.length ? 'fail' : 'pass',
57
+ };
58
+
59
+ if (opts.sarif) fs.writeFileSync(opts.sarif, JSON.stringify(sarif(r, specText, opts.har), null, 2) + '\n');
60
+ process.stdout.write((opts.json ? JSON.stringify(r, null, 2) : render(r, opts)) + '\n');
61
+ if (opts.summary !== false && process.env.GITHUB_ACTIONS === 'true' && process.env.GITHUB_STEP_SUMMARY) {
62
+ try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown(r) + '\n'); } catch { /* summary is best-effort */ }
63
+ }
64
+ exitAfterFlush(failing.length ? 1 : 0);
65
+ } catch (err) {
66
+ logger.error(`Error: ${err.message}`);
67
+ process.exit(2);
68
+ }
69
+ });
70
+
71
+ const rank = (s) => SEVERITIES.indexOf(s);
72
+ const atLeast = (s, min) => min !== 'none' && rank(s) <= rank(min);
73
+ const sort = (list) => [...list].sort((a, b) => rank(a.severity) - rank(b.severity) || a.rule.localeCompare(b.rule));
74
+ const count = (list) => Object.fromEntries(SEVERITIES.map((s) => [s, list.filter((f) => f.severity === s).length]));
75
+
76
+ function byOwasp(findings) {
77
+ return Object.entries(OWASP).map(([id, o]) => ({ id, name: o.name, coverage: o.coverage, ...count(findings.filter((f) => f.owasp === id)) }));
78
+ }
79
+
80
+ /** Findings with the same rule and severity, for display. */
81
+ function groups(findings) {
82
+ const map = new Map();
83
+ for (const f of findings) {
84
+ const k = `${f.severity}|${f.rule}`;
85
+ if (!map.has(k)) map.set(k, { ...f, items: [] });
86
+ map.get(k).items.push(f);
87
+ }
88
+ return [...map.values()];
89
+ }
90
+
91
+ function where(f) {
92
+ const n = f.affectedEndpoints.length;
93
+ const place = n > 1 ? `${f.affectedEndpoints[0]} and ${n - 1} more` : f.affectedEndpoints[0];
94
+ const what = [f.field, f.detail].filter(Boolean);
95
+ const note = what.length ? (what.length === 2 ? `${what[0]} (${what[1]})` : what[0]) : '';
96
+ return place ? (note ? `${place} · ${note}` : place) : note;
97
+ }
98
+
99
+ const COLOR = { high: chalk.red, medium: chalk.yellow, low: chalk.gray };
100
+ const MAX_LISTED = 5;
101
+
102
+ function render(r, opts) {
103
+ const lines = ['', chalk.bold(` SpecShield™ Audit — ${r.title || r.spec || 'captured traffic'}`), chalk.gray(' ─────────────────────────────────────────')];
104
+ if (r.har) lines.push(chalk.gray(` Capture: ${plural(r.har.api, 'API response')} checked of ${plural(r.har.entries, 'request')}, ${plural(r.har.hosts, 'host')}`));
105
+ if (r.har && r.har.hosts > 1) lines.push(chalk.gray(' Several hosts in this capture: use --host to check only your own.'));
106
+ lines.push('');
107
+ lines.push(` ${chalk.red(`${r.counts.high} high`)} · ${chalk.yellow(`${r.counts.medium} medium`)} · ${chalk.gray(`${r.counts.low} low`)}${r.waived.length ? chalk.gray(` · ${r.waived.length} waived`) : ''}`);
108
+
109
+ for (const g of groups(r.findings)) {
110
+ lines.push('');
111
+ if (g.severity === 'low' && !opts.all) {
112
+ lines.push(` ${COLOR.low('●')} ${g.title} ${chalk.gray(`(${g.owasp}, ${g.items.length})`)}`);
113
+ continue;
114
+ }
115
+ lines.push(` ${COLOR[g.severity]('●')} ${chalk.bold(g.title)} ${chalk.gray(`${g.severity} · ${g.owasp} · ${g.rule}${g.items.length > 1 ? ` · ${g.items.length}` : ''}`)}`);
116
+ const listed = opts.all ? g.items : g.items.slice(0, MAX_LISTED);
117
+ for (const f of listed) { const w = where(f); if (w) lines.push(` ${w}`); }
118
+ if (listed.length < g.items.length) lines.push(chalk.gray(` and ${g.items.length - listed.length} more (--all, or --json)`));
119
+ lines.push(chalk.gray(` fix: ${g.fix}`));
120
+ }
121
+
122
+ lines.push('', chalk.bold(' OWASP API Security Top 10'));
123
+ for (const o of r.owasp) {
124
+ const label = `${o.id.padEnd(6)}${o.name}`;
125
+ const total = o.high + o.medium + o.low;
126
+ const status = o.coverage === 'none' ? chalk.gray('needs runtime testing') : total ? `${o.high} high, ${o.medium} medium, ${o.low} low` : chalk.green('nothing found');
127
+ lines.push(` ${label.padEnd(58)} ${status}`);
128
+ }
129
+ lines.push('', chalk.gray(' Static checks show what the spec declares, not what the service enforces. "Nothing found" is not a pass.'));
130
+ if (r.verdict === 'fail') lines.push(chalk.gray(` Accepted risk? specshield waivers add <rule> --operation "GET /path" --owner <you> --reason "<why>" --days 30`));
131
+ lines.push('');
132
+ return lines.join('\n');
133
+ }
134
+
135
+ function cell(s) {
136
+ return String(s).replace(/\|/g, '\\|').replace(/\n/g, ' ');
137
+ }
138
+
139
+ function markdown(r) {
140
+ const md = [`### ${r.verdict === 'pass' ? '✅' : '❌'} SpecShield audit — ${cell(r.title || r.spec || 'captured traffic')}`, '', `**${r.counts.high} high**, ${r.counts.medium} medium, ${r.counts.low} low${r.waived.length ? `, ${r.waived.length} waived` : ''}.`, ''];
141
+ md.push('| Severity | Finding | OWASP | Count | Example |', '|---|---|---|---|---|');
142
+ for (const g of groups(r.findings)) md.push(`| ${g.severity} | ${cell(g.title)} | ${g.owasp} | ${g.items.length} | ${cell(where(g.items[0]) || '—')} |`);
143
+ return md.join('\n');
144
+ }
145
+
146
+ /** The line a path is declared on, so code scanning can point at it. */
147
+ function lineOf(text, needle) {
148
+ if (!text || !needle) return 1;
149
+ const i = text.split('\n').findIndex((l) => l.includes(needle));
150
+ return i < 0 ? 1 : i + 1;
151
+ }
152
+
153
+ function sarif(r, specText, harFiles) {
154
+ const LEVEL = { high: 'error', medium: 'warning', low: 'note' };
155
+ const used = [...new Set(r.findings.map((f) => f.rule))];
156
+ return {
157
+ version: '2.1.0',
158
+ $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
159
+ runs: [{
160
+ tool: { driver: {
161
+ name: 'SpecShield', version: pkg.version, informationUri: 'https://specshield.io',
162
+ rules: used.map((id) => ({ id, shortDescription: { text: RULES[id][1] }, help: { text: RULES[id][2] }, properties: { tags: ['security', `OWASP-${RULES[id][0]}`] } })),
163
+ } },
164
+ results: r.findings.map((f) => ({
165
+ ruleId: f.rule,
166
+ ruleIndex: used.indexOf(f.rule),
167
+ level: LEVEL[f.severity],
168
+ message: { text: `${f.title}${where(f) ? `: ${where(f)}` : ''}` },
169
+ locations: [{ physicalLocation: {
170
+ artifactLocation: { uri: f.source === 'spec' ? r.spec : harFiles[0] },
171
+ region: { startLine: f.source === 'spec' ? lineOf(specText, (f.affectedEndpoints[0] || '').split(' ')[1] || f.field) : 1 },
172
+ } }],
173
+ })),
174
+ }],
175
+ };
176
+ }
177
+
178
+ module.exports = audit;
179
+ module.exports._internal = { sarif, render };
@@ -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, 'breaking change')}`)
176
- : chalk.red.bold(` ✖ ${plural(r.blocking.length, 'breaking change')} block${r.blocking.length === 1 ? 's' : ''} this change`);
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 title = r.verdict === 'would-block' ? 'Breaking API change (shadow mode)' : 'Breaking API change';
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, 'breaking change')}.`
277
- : `**${plural(r.blocking.length, 'breaking change')}** block this change.`);
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>');
@@ -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
  }
@@ -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,187 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * `specshield audit`: what a spec alone reveals about an API's security, by
5
+ * OWASP API Security Top 10 category. Only declared behaviour is judged — the
6
+ * running service may be stricter or looser.
7
+ */
8
+
9
+ const D = require('./diff');
10
+ const { finding } = require('./rules');
11
+ const { isLocalHost } = require('../prove/http');
12
+
13
+ // Writes that are public by design.
14
+ const OPEN_BY_DESIGN = /(^|\/)(login|logout|signin|sign-in|signup|sign-up|register|token|oauth2?|auth|authenticate|password|forgot|reset|webhooks?|callbacks?|health|ready|ping|verify)(\/|$)/i;
15
+ const ADMIN = /(^|\/)(admin|internal|debug|actuator)(\/|$)/i;
16
+ const NON_PROD = /(^|[.-])(dev|develop|staging|stage|test|qa|sandbox|uat|internal)([.-]|$)/i;
17
+ const PAGE_SIZE = /^(limit|per_page|page_size|size|top|max_results)$/;
18
+ const PAGING = /^(limit|per_page|page_size|size|top|max_results|page|offset|cursor|next|page_token|after|before|starting_after|skip)$/;
19
+ const ELEVATING = /^(is_)?(admin|superuser|staff|root)$/;
20
+ const PRIVILEGED = /^(role|roles|permissions|privileges|owner_id|tenant_id)$/;
21
+ const URL_FIELD = /(^|_)(url|uri|webhook|callback|redirect)$/;
22
+
23
+ function auditSpec(doc) {
24
+ const out = [...documentRules(doc)];
25
+ const declared = D.declaresAuth(doc);
26
+ for (const o of D.operations(doc).values()) out.push(...operationRules(doc, o, declared));
27
+ return out;
28
+ }
29
+
30
+ const hostOf = (url) => { const m = /^[a-z]+:\/\/([^/:?#]+)/i.exec(url); return m ? m[1].toLowerCase() : null; };
31
+ const cleartext = (url) => /^http:\/\//i.test(url) && !isLocalHost(hostOf(url) || '');
32
+
33
+ function documentRules(doc) {
34
+ const out = [];
35
+ if (D.operations(doc).size && !D.declaresAuth(doc)) out.push(finding('no-auth-declared', 'medium'));
36
+ const urls = (doc.servers || []).map((s) => s && s.url).filter((u) => typeof u === 'string');
37
+ if (doc.host) for (const scheme of doc.schemes || ['https']) urls.push(`${scheme}://${doc.host}`);
38
+ for (const url of urls) {
39
+ if (cleartext(url)) out.push(finding('insecure-server', 'high', { field: url }));
40
+ const host = hostOf(url);
41
+ if (host && !isLocalHost(host) && NON_PROD.test(host.split('.').slice(0, -1).join('.'))) {
42
+ out.push(finding('non-production-server', 'low', { field: url }));
43
+ }
44
+ }
45
+ const schemes = (doc.components && doc.components.securitySchemes) || doc.securityDefinitions || {};
46
+ for (const name of Object.keys(schemes)) {
47
+ const s = D.schemeOf(doc, name);
48
+ if (!s) continue;
49
+ const type = String(s.type).toLowerCase();
50
+ if (type === 'apikey' && String(s.in).toLowerCase() === 'query') out.push(finding('api-key-in-query', 'high', { field: name }));
51
+ if (type === 'basic' || (type === 'http' && String(s.scheme).toLowerCase() === 'basic')) out.push(finding('basic-auth', 'medium', { field: name }));
52
+ if (type === 'oauth2') out.push(...oauthRules(name, s));
53
+ if (type === 'openidconnect' && cleartext(String(s.openIdConnectUrl))) out.push(finding('oauth-insecure-url', 'high', { field: name }));
54
+ }
55
+ return out;
56
+ }
57
+
58
+ function oauthRules(name, s) {
59
+ const out = [];
60
+ const flows = s.flows ? Object.entries(s.flows) : [[s.flow, s]]; // Swagger 2.0 has one flow
61
+ for (const [flow, f] of flows) {
62
+ if (flow === 'implicit' || flow === 'password') out.push(finding('oauth-legacy-flow', 'medium', { field: name, detail: `${flow} flow` }));
63
+ if (!f) continue;
64
+ if ([f.authorizationUrl, f.tokenUrl, f.refreshUrl].some((u) => typeof u === 'string' && cleartext(u))) {
65
+ out.push(finding('oauth-insecure-url', 'high', { field: name, detail: `${flow} flow` }));
66
+ }
67
+ }
68
+ return out;
69
+ }
70
+
71
+ function parameters(doc, o) {
72
+ const merged = new Map();
73
+ for (const raw of [...(o.item.parameters || []), ...(o.op.parameters || [])]) {
74
+ const p = D.deref(doc, raw);
75
+ if (p && p.name && p.in) merged.set(`${p.in}:${p.name}`, p);
76
+ }
77
+ return [...merged.values()];
78
+ }
79
+
80
+ function operationRules(doc, o, declared) {
81
+ const out = [];
82
+ const endpoint = `${o.method.toUpperCase()} ${o.path}`;
83
+ const add = (rule, severity, extra) => out.push(finding(rule, severity, { endpoint, ...extra }));
84
+ const req = D.requirement(doc, o.op);
85
+ const params = parameters(doc, o);
86
+ const isPublic = declared && D.allowsAnonymous(req);
87
+ const write = ['post', 'put', 'patch', 'delete'].includes(o.method);
88
+ const admin = ADMIN.test(o.path);
89
+
90
+ for (const alt of req.alternatives) {
91
+ for (const name of Object.keys(alt)) {
92
+ if (!D.schemeOf(doc, name)) add('undefined-security-scheme', 'high', { field: name });
93
+ }
94
+ }
95
+ if (isPublic && admin) add('public-admin-endpoint', 'high');
96
+ else if (isPublic && write && !OPEN_BY_DESIGN.test(o.path)) add('public-write', 'high');
97
+ if (admin && !isPublic && declared && req.alternatives.every((a) => Object.entries(a).every(([n, sc]) => String((D.schemeOf(doc, n) || {}).type).toLowerCase() === 'oauth2' && !sc.length))) {
98
+ add('admin-without-scope', 'low');
99
+ }
100
+
101
+ const paramSchema = (p) => D.deref(doc, p.schema) || p;
102
+ for (const p of params) {
103
+ const s = paramSchema(p);
104
+ const w = D.words(p.name);
105
+ if (p.in === 'query') {
106
+ const tier = D.sensitivity(p.name, s);
107
+ if (tier === 'credential' || tier === 'regulated' || tier === 'token') add('secret-in-query', 'high', { field: p.name });
108
+ }
109
+ if (p.in === 'path' && /(^|_)id$/.test(w) && s.type === 'integer') {
110
+ add('enumerable-id', 'low', { field: p.name });
111
+ if (isPublic && o.method === 'get') add('public-object-read', 'medium', { field: p.name });
112
+ }
113
+ if (p.in === 'query' && PAGE_SIZE.test(w) && s.type === 'integer' && s.maximum === undefined) add('limit-without-maximum', 'low', { field: p.name });
114
+ if ((p.in === 'query' || p.in === 'formData') && urlInput(p.name, s)) add('url-input', 'low', { field: p.name });
115
+ }
116
+
117
+ if (o.method === 'get' && returnsBareList(doc, o.op) && !params.some((p) => p.in === 'query' && PAGING.test(D.words(p.name)))) {
118
+ add('list-without-pagination', 'low');
119
+ }
120
+
121
+ const seen = new Set();
122
+ for (const f of D.sensitiveResponseFields(doc, o.op)) {
123
+ const name = D.leaf(f.path);
124
+ const high = f.tier === 'credential' || f.tier === 'regulated' || isPublic;
125
+ if (!high || seen.has(name)) continue;
126
+ seen.add(name);
127
+ add('sensitive-response-field', 'high', { field: name, detail: f.path === name ? f.tier : `${f.tier}, at ${f.path}` });
128
+ }
129
+
130
+ const taken = new Set();
131
+ for (const schema of requestSchemas(doc, o)) {
132
+ for (const f of D.fields(doc, schema, classifyInput, 'readOnly')) {
133
+ const name = D.leaf(f.path);
134
+ if (taken.has(name)) continue;
135
+ taken.add(name);
136
+ if (f.tier === 'url') add('url-input', 'low', { field: name, detail: f.path === name ? null : `at ${f.path}` });
137
+ // Nested "permissions" usually configure the thing being created, not the caller.
138
+ else if (!admin && f.path === name) add('mass-assignment-risk', f.tier === 'elevating' ? 'medium' : 'low', { field: name });
139
+ }
140
+ }
141
+ return out;
142
+ }
143
+
144
+ function urlInput(name, s) {
145
+ return URL_FIELD.test(D.words(name)) && [].concat(s.type || 'string').includes('string') && !s.enum && !s.pattern;
146
+ }
147
+
148
+ function classifyInput(name, s) {
149
+ if (urlInput(name, s)) return 'url';
150
+ const w = D.words(name);
151
+ return ELEVATING.test(w) ? 'elevating' : PRIVILEGED.test(w) ? 'privileged' : null;
152
+ }
153
+
154
+ function requestSchemas(doc, o) {
155
+ if (!['post', 'put', 'patch'].includes(o.method)) return [];
156
+ const body = parameters(doc, o).find((p) => p.in === 'body');
157
+ if (body) return body.schema ? [body.schema] : [];
158
+ const rb = D.deref(doc, o.op.requestBody);
159
+ return rb ? Object.values(rb.content || {}).map((m) => m && m.schema).filter(Boolean) : [];
160
+ }
161
+
162
+ function returnsBareList(doc, op) {
163
+ return Object.entries(op.responses || {}).some(([status, raw]) => {
164
+ if (!/^2/.test(status)) return false;
165
+ const res = D.deref(doc, raw);
166
+ if (!res) return false;
167
+ const schemas = res.schema ? [res.schema] : Object.values(res.content || {}).map((m) => m && m.schema);
168
+ return schemas.some((s) => { const n = D.deref(doc, s); return n && n.type === 'array'; });
169
+ });
170
+ }
171
+
172
+ /** One finding per exposed field: a shared schema shouldn't count once per endpoint. */
173
+ function consolidate(findings) {
174
+ const out = [];
175
+ const merged = new Map();
176
+ for (const f of findings) {
177
+ if (f.rule !== 'sensitive-response-field') { out.push(f); continue; }
178
+ const k = `${f.severity}|${f.field}`;
179
+ if (merged.has(k)) { merged.get(k).affectedEndpoints.push(...f.affectedEndpoints); continue; }
180
+ const item = { ...f, affectedEndpoints: [...f.affectedEndpoints] };
181
+ merged.set(k, item);
182
+ out.push(item);
183
+ }
184
+ return out;
185
+ }
186
+
187
+ module.exports = { auditSpec, consolidate };
@@ -0,0 +1,157 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Passive checks on captured traffic. Reads a HAR file and sends nothing.
5
+ * A capture is full of real secrets, so a finding says where one was seen and
6
+ * never what it was.
7
+ */
8
+
9
+ const fs = require('fs');
10
+ const { finding } = require('./rules');
11
+ const { sensitivity } = require('./diff');
12
+ const { isLocalHost } = require('../prove/http');
13
+ const { templatePath } = require('../har/pathTemplate');
14
+
15
+ const MAX_BODY = 2 * 1024 * 1024;
16
+ const MAX_NODES = 20000;
17
+ const API_MIME = /json|xml|graphql|text\/plain/i;
18
+ const SESSION_COOKIE = /sess|sid|auth|token|jwt/i;
19
+ const MASKED = /^[*xX•.\-\s]*$|^\*+|\*{3,}|x{4,}|redacted|^null$|^undefined$/i;
20
+
21
+ const SECRET_VALUES = [
22
+ ['AWS access key', /\bAKIA[0-9A-Z]{16}\b/],
23
+ ['private key', /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----/],
24
+ ['GitHub token', /\b(?:gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{40,})\b/],
25
+ ['Stripe live key', /\b[sr]k_live_[A-Za-z0-9]{16,}\b/],
26
+ ['Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/],
27
+ ['Google API key', /\bAIza[0-9A-Za-z_-]{35}\b/],
28
+ ];
29
+ const STACK = /Traceback \(most recent call last\)|Exception in thread "|\n\s+at [\w.$<>]+\([\w.]+\.(?:java|kt|scala):\d+\)|\n\s+at .+ \(.+\.[jt]s:\d+:\d+\)|\.php on line \d+/;
30
+
31
+ function auditHar(files, { hosts = null } = {}) {
32
+ const found = new Map();
33
+ const stats = { entries: 0, api: 0, otherHosts: 0, hosts: new Set() };
34
+ const add = (rule, severity, opts) => {
35
+ const key = [rule, opts.endpoint || '', opts.field || ''].join('|');
36
+ if (!found.has(key)) found.set(key, finding(rule, severity, { ...opts, source: 'har' }));
37
+ };
38
+ for (const file of files) {
39
+ for (const e of entriesOf(file)) {
40
+ stats.entries++;
41
+ checkEntry(e, { add, hosts, stats });
42
+ }
43
+ }
44
+ return { findings: [...found.values()], stats: { ...stats, hosts: stats.hosts.size } };
45
+ }
46
+
47
+ function entriesOf(file) {
48
+ let doc;
49
+ try { doc = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`${file} is not valid HAR JSON (${e.message})`); }
50
+ if (!doc || !doc.log || !Array.isArray(doc.log.entries)) throw new Error(`${file} is not a HAR file (no log.entries)`);
51
+ return doc.log.entries.filter((e) => e && e.request && e.request.url && e.response);
52
+ }
53
+
54
+ function headerMap(list) {
55
+ const map = new Map();
56
+ for (const h of list || []) {
57
+ if (!h || typeof h.name !== 'string') continue;
58
+ const k = h.name.toLowerCase();
59
+ map.set(k, [...(map.get(k) || []), String(h.value)]);
60
+ }
61
+ return map;
62
+ }
63
+
64
+ function bodyOf(res) {
65
+ const c = res.content;
66
+ if (!c || typeof c.text !== 'string') return null;
67
+ const text = c.encoding === 'base64' ? Buffer.from(c.text.slice(0, MAX_BODY * 2), 'base64').toString('utf8') : c.text;
68
+ return text.slice(0, MAX_BODY);
69
+ }
70
+
71
+ function checkEntry(e, { add, hosts, stats }) {
72
+ let url;
73
+ try { url = new URL(e.request.url); } catch { return; }
74
+ if (!/^https?:$/.test(url.protocol)) return;
75
+ const host = url.hostname.toLowerCase();
76
+ if (hosts && !hosts.has(host)) { stats.otherHosts++; return; }
77
+ const res = headerMap(e.response.headers);
78
+ const mime = String((e.response.content && e.response.content.mimeType) || (res.get('content-type') || [''])[0]);
79
+ // A browser capture is mostly pages and assets; these checks are about the API.
80
+ if (!API_MIME.test(mime)) return;
81
+ stats.api++;
82
+ stats.hosts.add(host);
83
+
84
+ const endpoint = `${String(e.request.method || 'GET').toUpperCase()} ${templatePath(url.pathname).templated}`;
85
+ const local = isLocalHost(host);
86
+ const https = url.protocol === 'https:';
87
+
88
+ if (!https && !local) add('cleartext-traffic', 'high', { field: host });
89
+ if (https && !local) {
90
+ if (!res.has('strict-transport-security')) add('missing-hsts', 'medium', { field: host });
91
+ }
92
+ if (!res.has('x-content-type-options')) add('missing-nosniff', 'low', { field: host });
93
+
94
+ for (const [name, value] of url.searchParams) {
95
+ const tier = sensitivity(name, { type: 'string' });
96
+ if (value && (tier === 'credential' || tier === 'regulated' || tier === 'token')) add('secret-in-url', 'high', { endpoint, field: name });
97
+ const hit = SECRET_VALUES.find(([, re]) => re.test(value));
98
+ if (hit) add('secret-in-url', 'high', { endpoint, field: name, detail: hit[0] });
99
+ }
100
+
101
+ checkCors(res, { add, host });
102
+ checkCookies(res, { add, host, https, local });
103
+ for (const h of ['server', 'x-powered-by', 'x-aspnet-version']) {
104
+ if ((res.get(h) || []).some((v) => /\d+\.\d+/.test(v))) add('version-disclosure', 'low', { field: host, detail: h });
105
+ }
106
+
107
+ const body = bodyOf(e.response);
108
+ if (!body) return;
109
+ if (e.response.status >= 400 && STACK.test(body)) add('stack-trace', 'medium', { endpoint });
110
+ for (const [label, re] of SECRET_VALUES) if (re.test(body)) add('secret-in-response', 'high', { endpoint, field: label });
111
+ if (/^\s*[[{]/.test(body)) {
112
+ try { scanJson(JSON.parse(body), { add, endpoint }); } catch { /* truncated or not JSON after all */ }
113
+ }
114
+ }
115
+
116
+ function checkCors(res, { add, host }) {
117
+ const origin = (res.get('access-control-allow-origin') || [])[0];
118
+ if (!origin) return;
119
+ const credentials = (res.get('access-control-allow-credentials') || [])[0] === 'true';
120
+ if (origin === '*' && credentials) add('cors-wildcard-credentials', 'high', { field: host });
121
+ else if (origin === '*') add('cors-any-origin', 'low', { field: host });
122
+ else if (origin === 'null') add('cors-null-origin', 'medium', { field: host });
123
+ }
124
+
125
+ function checkCookies(res, { add, host, https, local }) {
126
+ for (const raw of res.get('set-cookie') || []) {
127
+ const [pair, ...attrs] = raw.split(';');
128
+ const name = pair.split('=')[0].trim();
129
+ if (!SESSION_COOKIE.test(name)) continue;
130
+ const has = (a) => attrs.some((x) => x.trim().toLowerCase().startsWith(a));
131
+ const missing = [
132
+ https && !local && !has('secure') ? 'Secure' : null,
133
+ !has('httponly') ? 'HttpOnly' : null,
134
+ !has('samesite') ? 'SameSite' : null,
135
+ ].filter(Boolean);
136
+ if (missing.length) add('insecure-cookie', 'medium', { field: name, detail: `${host}: no ${missing.join(', ')}` });
137
+ }
138
+ }
139
+
140
+ function scanJson(root, { add, endpoint }) {
141
+ let nodes = 0;
142
+ const visit = (v, key) => {
143
+ if (++nodes > MAX_NODES || v === null || v === undefined) return;
144
+ if (Array.isArray(v)) { for (const x of v) visit(x, key); return; }
145
+ if (typeof v === 'object') { for (const [k, x] of Object.entries(v)) visit(x, k); return; }
146
+ if (typeof v !== 'string' && typeof v !== 'number') return;
147
+ const text = String(v);
148
+ if (!key || !text || MASKED.test(text)) return;
149
+ const tier = sensitivity(key, { type: 'string' });
150
+ if (tier === 'credential') add('secret-in-response', 'high', { endpoint, field: key });
151
+ else if (tier === 'regulated') add('regulated-data-in-response', 'high', { endpoint, field: key });
152
+ else if (tier === 'personal') add('personal-data-in-response', 'low', { endpoint, field: key });
153
+ };
154
+ visit(root, null);
155
+ }
156
+
157
+ module.exports = { auditHar };
@@ -0,0 +1,315 @@
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], item });
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
+ if ((doc.security || []).some((a) => a && Object.keys(a).length)) return true;
156
+ return [...operations(doc).values()].some((o) => !allowsAnonymous(requirement(doc, o.op)));
157
+ }
158
+
159
+ function describeAlt(alt, doc) {
160
+ return Object.entries(alt).map(([name, scopes]) => {
161
+ const s = schemeOf(doc, name);
162
+ const kind = !s ? '' : s.type === 'apiKey' ? ` (API key in ${s.in})` : s.type === 'http' ? ` (${s.scheme})` : s.type === 'basic' ? ' (basic)' : '';
163
+ return `${name}${kind}${scopes.length ? ` [${scopes.join(', ')}]` : ''}`;
164
+ }).join(' + ') || 'no authentication';
165
+ }
166
+
167
+ function describeReq(req) {
168
+ return req.alternatives.map((a) => (isAnonymous(a) ? 'anonymous' : Object.entries(a).map(([n, s]) => `${n}${s.length ? ` [${s.join(', ')}]` : ''}`).join(' + '))).join(' or ');
169
+ }
170
+
171
+ // ─── sensitive fields in responses ──────────────────────────────────────────
172
+
173
+ const CREDENTIAL = /(^|_)(password|passwd|pwd|passphrase|secret|private_key|api_key|apikey)$/;
174
+ const REGULATED = /(^|_)(ssn|social_security_number|aadhaar|cvv|cvc|card_number|credit_card_number|passport_number|tax_id|bank_account_number)$/;
175
+ const TOKEN = /(^|_)(access_token|refresh_token|id_token|auth_token|session_token|bearer_token|jwt|session_id)$/;
176
+ const PERSONAL = /(^|_)(email|email_address|phone|phone_number|date_of_birth|dob|birthdate|birth_date|home_address)$/;
177
+ // The name has to end in the term: password_changed_at, secret_scanning_status and
178
+ // cvc_check are facts about a secret, not the secret.
179
+ const words = (name) => String(name)
180
+ .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
181
+ .replace(/[^A-Za-z0-9]+/g, '_')
182
+ .toLowerCase();
183
+
184
+ /** credential | regulated | token | personal | null */
185
+ function sensitivity(name, schema) {
186
+ const types = [].concat((schema && schema.type) || 'string');
187
+ if (!types.includes('string')) return null;
188
+ const w = words(name);
189
+ if (schema && schema.format === 'password') return 'credential';
190
+ if (CREDENTIAL.test(w)) return 'credential';
191
+ if (REGULATED.test(w)) return 'regulated';
192
+ if (TOKEN.test(w)) return 'token';
193
+ if (PERSONAL.test(w) || (schema && schema.format === 'email')) return 'personal';
194
+ return null;
195
+ }
196
+
197
+ const LABEL = { credential: 'a credential', regulated: 'regulated personal data', token: 'a token', personal: 'personal data' };
198
+
199
+ function exposedFields(b, h, baseDoc, headDoc, headReq) {
200
+ const before = new Set(b ? sensitiveResponseFields(baseDoc, b.op).map((f) => leaf(f.path)) : []);
201
+ const isPublic = allowsAnonymous(headReq) && (headReq.source === 'operation' || declaresAuth(headDoc));
202
+ const seen = new Set();
203
+ const out = [];
204
+ for (const f of sensitiveResponseFields(headDoc, h.op)) {
205
+ const name = leaf(f.path);
206
+ if (before.has(name) || seen.has(name)) continue;
207
+ seen.add(name);
208
+ const high = f.tier === 'credential' || f.tier === 'regulated' || isPublic;
209
+ const where = isPublic ? 'a public response' : 'a response';
210
+ const via = f.path === name ? '' : ` (at ${f.path})`;
211
+ out.push({
212
+ ...change('SENSITIVE_FIELD_EXPOSED', h, high ? 'error' : 'warning', name, `Security: new field "${name}"${via} in ${where} looks like ${LABEL[f.tier]}`),
213
+ mergeAs: `exposed|${name}|${f.tier}|${isPublic}`,
214
+ });
215
+ }
216
+ return out;
217
+ }
218
+
219
+ const leaf = (p) => p.split('.').pop().replace(/\[\]$/, '');
220
+
221
+ /** Sensitive fields a 2xx response can carry, with their paths. */
222
+ function sensitiveResponseFields(doc, op) {
223
+ const out = [];
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(...fields(doc, s, sensitivity, 'writeOnly'));
231
+ }
232
+ return out;
233
+ }
234
+
235
+ const memos = new WeakMap();
236
+ function memoFor(doc, classify) {
237
+ if (!memos.has(doc)) memos.set(doc, new Map());
238
+ const byClassifier = memos.get(doc);
239
+ if (!byClassifier.has(classify)) byClassifier.set(classify, new Map());
240
+ return byClassifier.get(classify);
241
+ }
242
+
243
+ function deref(doc, node) {
244
+ let n = node;
245
+ for (let i = 0; n && n.$ref && i < 20; i++) {
246
+ if (typeof n.$ref !== 'string' || !n.$ref.startsWith('#/')) return null;
247
+ n = n.$ref.slice(2).split('/').reduce((o, k) => (o ? o[k.replace(/~1/g, '/').replace(/~0/g, '~')] : undefined), doc);
248
+ }
249
+ return n && typeof n === 'object' ? n : null;
250
+ }
251
+
252
+ /** [{path, tier}] for each property `classify(name, schema)` tags; `skip` names a flag that hides a property. */
253
+ function fields(doc, schema, classify, skip) {
254
+ return walk({ doc, classify, skip, memo: memoFor(doc, classify), stack: new Set() }, schema, 0);
255
+ }
256
+
257
+ /** Named schemas are memoized; cycles are cut. */
258
+ function walk(ctx, node, depth) {
259
+ if (!node || depth > MAX_DEPTH) return [];
260
+ const { doc, memo, stack } = ctx;
261
+ if (node.$ref) {
262
+ if (memo.has(node.$ref)) return memo.get(node.$ref);
263
+ if (stack.has(node.$ref)) return [];
264
+ stack.add(node.$ref);
265
+ const r = walk(ctx, deref(doc, node), depth + 1);
266
+ stack.delete(node.$ref);
267
+ memo.set(node.$ref, r);
268
+ return r;
269
+ }
270
+ const out = [];
271
+ for (const key of ['allOf', 'oneOf', 'anyOf']) {
272
+ if (Array.isArray(node[key])) for (const s of node[key]) out.push(...walk(ctx, s, depth + 1));
273
+ }
274
+ if (node.items) out.push(...walk(ctx, node.items, depth + 1).map((f) => ({ ...f, path: `[].${f.path}` })));
275
+ if (node.additionalProperties && typeof node.additionalProperties === 'object') {
276
+ out.push(...walk(ctx, node.additionalProperties, depth + 1));
277
+ }
278
+ for (const [name, raw] of Object.entries(node.properties || {})) {
279
+ const prop = deref(doc, raw);
280
+ if (!prop || prop[ctx.skip]) continue;
281
+ const tier = ctx.classify(name, prop);
282
+ if (tier) out.push({ path: name, tier });
283
+ out.push(...walk(ctx, raw, depth + 1).map((f) => ({ ...f, path: `${name}.${f.path}` })));
284
+ }
285
+ return out.map((f) => ({ ...f, path: f.path.replace(/^\[\]\./, '') }));
286
+ }
287
+
288
+ // ─── findings ───────────────────────────────────────────────────────────────
289
+
290
+ const endpoint = (h) => `${h.method.toUpperCase()} ${h.path}`;
291
+
292
+ function change(type, h, severity, field, description) {
293
+ return { type, category: 'security', path: h.path, method: h.method, field, severity, description };
294
+ }
295
+
296
+ /** One finding for a cause shared by many endpoints: a global requirement or a shared schema. */
297
+ function merge(found) {
298
+ const out = [];
299
+ const groups = new Map();
300
+ for (const f of found) {
301
+ const { mergeAs, ...c } = f;
302
+ const ep = `${c.method.toUpperCase()} ${c.path}`;
303
+ const g = mergeAs && groups.get(mergeAs);
304
+ if (g) { g.affectedEndpoints.push(ep); continue; }
305
+ const item = { ...c, affectedEndpoints: [ep] };
306
+ if (mergeAs) groups.set(mergeAs, item);
307
+ out.push(item);
308
+ }
309
+ return out;
310
+ }
311
+
312
+ module.exports = {
313
+ securityDiff, requirement, sensitivity, operations, allowsAnonymous, declaresAuth,
314
+ schemeOf, deref, fields, sensitiveResponseFields, leaf, words,
315
+ };
@@ -0,0 +1,62 @@
1
+ 'use strict';
2
+
3
+ /** The OWASP API Security Top 10 (2023), and what a spec or a capture can say about each. */
4
+ const OWASP = {
5
+ API1: { name: 'Broken Object Level Authorization', coverage: 'partial' },
6
+ API2: { name: 'Broken Authentication', coverage: 'partial' },
7
+ API3: { name: 'Broken Object Property Level Authorization', coverage: 'partial' },
8
+ API4: { name: 'Unrestricted Resource Consumption', coverage: 'partial' },
9
+ API5: { name: 'Broken Function Level Authorization', coverage: 'partial' },
10
+ API6: { name: 'Unrestricted Access to Sensitive Business Flows', coverage: 'none' },
11
+ API7: { name: 'Server Side Request Forgery', coverage: 'partial' },
12
+ API8: { name: 'Security Misconfiguration', coverage: 'partial' },
13
+ API9: { name: 'Improper Inventory Management', coverage: 'partial' },
14
+ API10: { name: 'Unsafe Consumption of APIs', coverage: 'none' },
15
+ };
16
+
17
+ const RULES = {
18
+ // Spec
19
+ 'no-auth-declared': ['API2', 'The spec declares no authentication', 'Document the real scheme under securitySchemes and apply it with "security". Until then nothing can be checked about who may call this API.'],
20
+ 'undefined-security-scheme': ['API2', 'Uses a security scheme the spec doesn\'t define', 'Define the scheme, or fix the name.'],
21
+ 'public-write': ['API2', 'Anyone can change data', 'Require authentication, or waive it if this write is meant to be public.'],
22
+ 'api-key-in-query': ['API2', 'API key sent in the URL', 'Send it in a header: URLs end up in logs, browser history and Referer headers.'],
23
+ 'basic-auth': ['API2', 'HTTP basic authentication', 'Prefer short-lived tokens: basic auth sends a long-lived credential on every request.'],
24
+ 'oauth-legacy-flow': ['API2', 'Deprecated OAuth flow', 'Use the authorization code flow with PKCE, or client credentials between services.'],
25
+ 'oauth-insecure-url': ['API2', 'OAuth endpoint over plain HTTP', 'Serve token and authorization endpoints over HTTPS.'],
26
+ 'secret-in-query': ['API2', 'Secret passed as a query parameter', 'Move it to a header or the request body.'],
27
+ 'enumerable-id': ['API1', 'Sequential integer ID in the path', 'Check object ownership on every request; opaque IDs make guessing harder but don\'t replace that check.'],
28
+ 'public-object-read': ['API1', 'Anyone can read an object by ID', 'Require authentication, or confirm these objects are meant to be public.'],
29
+ 'sensitive-response-field': ['API3', 'Response returns sensitive data', 'Remove it from the response, mask it, or mark it writeOnly.'],
30
+ 'mass-assignment-risk': ['API3', 'Client can set a privileged field', 'Accept this field only on an admin operation, and bind request bodies to an explicit allow-list.'],
31
+ 'limit-without-maximum': ['API4', 'Page size has no maximum', 'Add "maximum" to the parameter and enforce it.'],
32
+ 'list-without-pagination': ['API4', 'List has no pagination', 'Add limit and cursor (or page) parameters.'],
33
+ 'public-admin-endpoint': ['API5', 'Administrative endpoint is public', 'Require authentication and an admin role or scope.'],
34
+ 'admin-without-scope': ['API5', 'Administrative endpoint requires no scope', 'Require a dedicated admin scope, so any valid token can\'t call it.'],
35
+ 'url-input': ['API7', 'Client-supplied URL', 'Validate against an allow-list of hosts and block internal addresses before the server fetches it.'],
36
+ 'insecure-server': ['API8', 'Server URL uses plain HTTP', 'Use HTTPS.'],
37
+ 'non-production-server': ['API9', 'Non-production server in the published spec', 'Remove internal hosts from the spec you publish.'],
38
+ // Capture
39
+ 'cleartext-traffic': ['API8', 'API called over plain HTTP', 'Use HTTPS and redirect or refuse HTTP.'],
40
+ 'secret-in-url': ['API2', 'Secret seen in a request URL', 'Rotate it, and move it to a header or the request body.'],
41
+ 'secret-in-response': ['API3', 'Secret seen in a response', 'Rotate it, and stop returning it.'],
42
+ 'regulated-data-in-response': ['API3', 'Regulated personal data in a response', 'Remove or mask it.'],
43
+ 'personal-data-in-response': ['API3', 'Personal data in a response', 'Confirm the caller needs it.'],
44
+ 'missing-hsts': ['API8', 'No Strict-Transport-Security header', 'Send Strict-Transport-Security on HTTPS responses.'],
45
+ 'missing-nosniff': ['API8', 'No X-Content-Type-Options header', 'Send X-Content-Type-Options: nosniff.'],
46
+ 'cors-wildcard-credentials': ['API8', 'CORS allows any origin with credentials', 'Allow specific origins only.'],
47
+ 'cors-null-origin': ['API8', 'CORS allows the "null" origin', 'Remove "null" from allowed origins: sandboxed pages can send it.'],
48
+ 'cors-any-origin': ['API8', 'CORS allows any origin', 'Confirm this API holds nothing private; otherwise allow specific origins.'],
49
+ 'insecure-cookie': ['API8', 'Session cookie missing protections', 'Set Secure, HttpOnly and SameSite.'],
50
+ 'version-disclosure': ['API8', 'Server software version disclosed', 'Remove version details from response headers.'],
51
+ 'stack-trace': ['API8', 'Stack trace in an error response', 'Return a generic error and log the detail on the server.'],
52
+ };
53
+
54
+ const SEVERITIES = ['high', 'medium', 'low'];
55
+
56
+ /** One finding, shaped so the gate's waivers apply: `type` is the rule. */
57
+ function finding(rule, severity, { endpoint = null, field = null, detail = null, source = 'spec' } = {}) {
58
+ const [owasp, title, fix] = RULES[rule];
59
+ return { type: rule, rule, owasp, severity, title, fix, detail, field, source, affectedEndpoints: endpoint ? [endpoint] : [] };
60
+ }
61
+
62
+ module.exports = { OWASP, RULES, SEVERITIES, finding };