specshield 3.5.2 → 3.5.4

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,12 +1,25 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
- ## Unreleased — security regressions in the gate
3
+ ## Unreleased — shadow APIs
4
+
5
+ ### Added
6
+
7
+ - `specshield audit --logs <files>` compares real traffic with the spec (OWASP API9). It reports undocumented endpoints and methods that answer requests, retired versions still served, operations past their `x-sunset`, and exposed files such as `/.env`. Severity follows the response status; redirects count as no evidence. Catch-all pages are recognised by response size (the home page's, or one shared by other probes). Routes are folded by structure, and trailing `{path}` parameters span segments. A HAR passed with `--har` gets the same checks. Validated on six real public log datasets, 9.9M requests in all.
8
+ - Log import records the response size (combined format) and recognises combined logs whose first lines have an empty request (OpenLiteSpeed).
9
+
10
+ ## 3.5.3 — 2026-11-10 — security audit
11
+
12
+ ### Added
13
+
14
+ - `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.
15
+
16
+ ## 3.5.2 — 2026-11-10 — security regressions in the gate
4
17
 
5
18
  ### Added
6
19
 
7
20
  - `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
21
 
9
- ## Unreleased — proof, not opinion: `specshield prove` and `specshield replay`
22
+ ## 3.5.1 — 2026-10-29 — proof, not opinion: `specshield prove` and `specshield replay`
10
23
 
11
24
  ### Added
12
25
 
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) · [**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)
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)
@@ -597,6 +597,51 @@ A new requirement counts as safe only when every credential that passes it would
597
597
 
598
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
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 --logs /var/log/nginx/access.log*.gz
608
+ specshield audit openapi.yaml --fail-on medium --sarif audit.sarif
609
+ ```
610
+
611
+ **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.
612
+
613
+ **From access logs (`--logs`) or a HAR file, compared with the spec (OWASP API9):**
614
+
615
+ | Finding | What it means |
616
+ |---|---|
617
+ | `shadow-endpoint` | A path the spec doesn't have is answering requests |
618
+ | `undocumented-method` | A documented path answers a method the spec doesn't list, e.g. `DELETE` |
619
+ | `zombie-version` | `/v1/...` still answers where the spec documents `/v2/...` |
620
+ | `sunset-passed` | An operation past its `x-sunset` date still answers |
621
+ | `exposed-sensitive-path` | `/.env`, `/.git/config`, `/actuator/env` and similar answered 200 (checked even without a spec) |
622
+
623
+ How sure a finding is comes from the response, not the request:
624
+
625
+ - **Status.** 2xx (or 304) means the endpoint served the request: high for writes and internal paths, medium otherwise. 401/403/400 means it exists but refused (low). 404/405 means it isn't there, and redirects prove nothing (an HTTP→HTTPS redirect answers every path), so neither is reported.
626
+ - **Catch-all pages.** Many sites answer every unknown path with the same page. When the logs record response sizes, a probe answered with the site's home page size, or the same size as other probes got, is downgraded; a size no other probe got stays high. Without sizes, a site that answered 200 to three or more probes is treated as a catch-all.
627
+ - **Routes.** IDs are templated, and object names that don't look like IDs are folded once four or more sit in the same place with the same shape after them (`/things/noxus/x`, `/things/fooab/x` → `/things/{thingId}/x`). Health and discovery endpoints (`/readyz`, `/openapi/v3`…) are reported low. A trailing `{path}` parameter may span several segments, as in Kubernetes' `/proxy/{path}`.
628
+
629
+ Logs in the same formats as `specshield usage import` are supported (combined, ALB, JSON lines, Kubernetes audit events, `.gz`). Per-site logs without a host are grouped by file name, so one site's catch-all doesn't affect another's findings. A file that can't be read is skipped with a warning. `--base-path` and `--host` narrow the logs to this API.
630
+
631
+ Validated on real, published traffic: a Kubernetes CI run (250,724 API requests against the official spec, every reported route independently confirmed absent from it), NASA's 1995 web logs (1.9M lines), Elastic's Apache sample, 90 days of secrepo.com logs, and a 2025 forensic dataset of 7.4M requests from a compromised hosting server, where every probe answered 200 was correctly identified as a catch-all page.
632
+
633
+ **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.
634
+
635
+ | Option | Default | |
636
+ |---|---|---|
637
+ | `--fail-on <severity>` | `high` | Exit 1 at or above `high`, `medium` or `low`; `none` never fails |
638
+ | `--waivers <file>` | `.specshield/waivers.yml` | Accepted findings, with an owner, a reason and an expiry. The `change` is the rule id |
639
+ | `--sarif <file>` | | SARIF 2.1.0, for GitHub code scanning |
640
+ | `--all` | | List every low-severity finding |
641
+ | `--json` | | Machine-readable output |
642
+
643
+ 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.
644
+
600
645
  ## Proof, not opinion: `specshield prove` and `specshield replay`
601
646
 
602
647
  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.2",
3
+ "version": "3.5.4",
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,217 @@
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 { createInventory } = require('../core/security/inventory');
12
+ const { importLogFile } = require('../core/usage/importLogs');
13
+ const { OWASP, RULES, SEVERITIES } = require('../core/security/rules');
14
+ const W = require('../core/gate/waivers');
15
+ const { plural } = require('../core/usage/format');
16
+ const logger = require('../utils/logger');
17
+ const exitAfterFlush = require('../utils/exitAfterFlush');
18
+ const pkg = require('../../package.json');
19
+
20
+ const FAIL_ON = [...SEVERITIES, 'none'];
21
+
22
+ const audit = new Command('audit')
23
+ .description('Security audit of an OpenAPI spec and captured traffic, by OWASP API Security Top 10 category. Sends no requests')
24
+ .argument('[spec]', 'The OpenAPI spec to audit')
25
+ .option('--har <file...>', 'HAR capture(s) to check for leaked secrets, personal data and missing protections')
26
+ .option('--logs <file...>', 'Access logs (.gz ok): find undocumented endpoints, methods and old versions still answering, and exposed files like /.env')
27
+ .option('--format <format>', 'Access log format: auto | combined | alb | json', 'auto')
28
+ .option('--base-path <path>', 'Path prefix the API is served under, e.g. /api (default: from the spec servers)')
29
+ .option('--host <host...>', 'Only check these hosts in the capture and logs')
30
+ .option('--fail-on <severity>', 'Exit 1 at or above this severity: high, medium, low, or none', 'high')
31
+ .option('--waivers <file>', `Waiver file (default: ${W.DEFAULT_FILE})`, W.DEFAULT_FILE)
32
+ .option('--all', 'List every low-severity finding')
33
+ .option('--sarif <file>', 'Also write SARIF, for GitHub code scanning')
34
+ .option('--no-summary', 'Skip the GitHub Actions job summary')
35
+ .option('--json', 'Output machine-readable JSON')
36
+ .action(async (specPath, opts) => {
37
+ try {
38
+ if (!specPath && !opts.har && !opts.logs) throw new Error('Nothing to audit: pass a spec, --har <file>, --logs <file>, or a combination');
39
+ if (!FAIL_ON.includes(opts.failOn)) throw new Error(`--fail-on must be one of ${FAIL_ON.join(', ')}`);
40
+
41
+ let specText = null;
42
+ let doc = null;
43
+ if (specPath) { specText = await loadSpec(specPath); doc = parseSpec(specText, specPath); }
44
+ const hosts = opts.host ? new Set(opts.host.map((h) => h.toLowerCase())) : null;
45
+ const traffic = opts.har || opts.logs ? createInventory(doc, { basePath: opts.basePath, hosts }) : null;
46
+ const har = opts.har ? auditHar(opts.har, { hosts, inventory: traffic }) : null;
47
+ const unread = [];
48
+ for (const file of opts.logs || []) {
49
+ const site = siteOf(file);
50
+ try {
51
+ await importLogFile(file, { format: opts.format, aggregator: { add: (rec) => { rec.site = site; traffic.add(rec); } } });
52
+ } catch (err) {
53
+ unread.push({ file, reason: err.message.split('\n')[0] });
54
+ }
55
+ }
56
+ if (opts.logs && unread.length === opts.logs.length) throw new Error(`No log could be read: ${unread[0].reason}`);
57
+
58
+ const now = Date.now();
59
+ const { waivers } = await W.loadWaivers(path.resolve(opts.waivers), { maxDays: W.DEFAULT_MAX_DAYS, now, file: opts.waivers });
60
+ const all = [...(doc ? auditSpec(doc) : []), ...(har ? har.findings : []), ...(traffic ? traffic.findings() : [])];
61
+ const { blocking, waived } = W.applyWaivers(all, waivers, now);
62
+ const findings = sort(consolidate(blocking));
63
+ const failing = findings.filter((f) => atLeast(f.severity, opts.failOn));
64
+ const r = {
65
+ spec: specPath || null,
66
+ title: doc && doc.info ? doc.info.title || null : null,
67
+ har: har ? { files: opts.har, ...har.stats } : null,
68
+ traffic: traffic ? { logs: opts.logs || [], unread, ...traffic.stats } : null,
69
+ failOn: opts.failOn,
70
+ counts: count(findings),
71
+ owasp: byOwasp(findings),
72
+ findings,
73
+ waived,
74
+ verdict: failing.length ? 'fail' : 'pass',
75
+ };
76
+
77
+ if (opts.sarif) fs.writeFileSync(opts.sarif, JSON.stringify(sarif(r, specText, opts.har), null, 2) + '\n');
78
+ process.stdout.write((opts.json ? JSON.stringify(r, null, 2) : render(r, opts)) + '\n');
79
+ if (opts.summary !== false && process.env.GITHUB_ACTIONS === 'true' && process.env.GITHUB_STEP_SUMMARY) {
80
+ try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown(r) + '\n'); } catch { /* summary is best-effort */ }
81
+ }
82
+ exitAfterFlush(failing.length ? 1 : 0);
83
+ } catch (err) {
84
+ logger.error(`Error: ${err.message}`);
85
+ process.exit(2);
86
+ }
87
+ });
88
+
89
+ /** "logs/shop.example.com.access_log.2025_04_26.gz" → "shop.example.com": which site a per-site log belongs to. */
90
+ function siteOf(file) {
91
+ const name = path.basename(file)
92
+ .replace(/\.gz$/i, '')
93
+ .replace(/([._-]\d{4}[._-]\d{2}[._-]\d{2}([._]\d+)?|(\.\d+)+)$/, '')
94
+ .replace(/[._-]?(access[._-]?log|access|log)$/i, '');
95
+ return name && !/^(web|ssl|other_vhosts)?[._-]?$/i.test(name) ? name : path.basename(path.dirname(path.resolve(file)));
96
+ }
97
+
98
+ const rank = (s) => SEVERITIES.indexOf(s);
99
+ const atLeast = (s, min) => min !== 'none' && rank(s) <= rank(min);
100
+ const sort = (list) => [...list].sort((a, b) => rank(a.severity) - rank(b.severity) || a.rule.localeCompare(b.rule));
101
+ const count = (list) => Object.fromEntries(SEVERITIES.map((s) => [s, list.filter((f) => f.severity === s).length]));
102
+
103
+ function byOwasp(findings) {
104
+ return Object.entries(OWASP).map(([id, o]) => ({ id, name: o.name, coverage: o.coverage, ...count(findings.filter((f) => f.owasp === id)) }));
105
+ }
106
+
107
+ /** Findings with the same rule and severity, for display. */
108
+ function groups(findings) {
109
+ const map = new Map();
110
+ for (const f of findings) {
111
+ const k = `${f.severity}|${f.rule}`;
112
+ if (!map.has(k)) map.set(k, { ...f, items: [] });
113
+ map.get(k).items.push(f);
114
+ }
115
+ return [...map.values()];
116
+ }
117
+
118
+ function where(f) {
119
+ const n = f.affectedEndpoints.length;
120
+ const place = n > 1 ? `${f.affectedEndpoints[0]} and ${n - 1} more` : f.affectedEndpoints[0];
121
+ const what = [f.field, f.detail].filter(Boolean);
122
+ const note = what.length ? (what.length === 2 ? `${what[0]} (${what[1]})` : what[0]) : '';
123
+ return place ? (note ? `${place} · ${note}` : place) : note;
124
+ }
125
+
126
+ const COLOR = { high: chalk.red, medium: chalk.yellow, low: chalk.gray };
127
+ const MAX_LISTED = 5;
128
+
129
+ function render(r, opts) {
130
+ const lines = ['', chalk.bold(` SpecShield™ Audit — ${r.title || r.spec || 'captured traffic'}`), chalk.gray(' ─────────────────────────────────────────')];
131
+ 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')}`));
132
+ if (r.traffic && r.traffic.unread.length) {
133
+ lines.push(chalk.yellow(` ${plural(r.traffic.unread.length, 'log file')} skipped: ${r.traffic.unread.slice(0, 2).map((u) => u.reason).join('; ')}${r.traffic.unread.length > 2 ? '; …' : ''}`));
134
+ }
135
+ if (r.traffic && r.spec) {
136
+ const t = r.traffic;
137
+ lines.push(chalk.gray(` Traffic: ${plural(t.requests, 'request')}; ${t.documentedSeen} of ${t.documentedTotal} documented operations called, ${plural(t.endpoints, 'undocumented route')} seen`));
138
+ if (t.requests && t.considered === 0) lines.push(chalk.yellow(' No request matched this API. Check --host and --base-path.'));
139
+ if (t.overflow) lines.push(chalk.yellow(` ${plural(t.overflow, 'request')} not checked: too many distinct undocumented routes.`));
140
+ } else if (r.traffic) {
141
+ lines.push(chalk.gray(' Traffic: checked for exposed files only. Pass the spec to find undocumented endpoints.'));
142
+ }
143
+ if (r.har && r.har.hosts > 1) lines.push(chalk.gray(' Several hosts in this capture: use --host to check only your own.'));
144
+ lines.push('');
145
+ 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`) : ''}`);
146
+
147
+ for (const g of groups(r.findings)) {
148
+ lines.push('');
149
+ if (g.severity === 'low' && !opts.all) {
150
+ lines.push(` ${COLOR.low('●')} ${g.title} ${chalk.gray(`(${g.owasp}, ${g.items.length})`)}`);
151
+ continue;
152
+ }
153
+ lines.push(` ${COLOR[g.severity]('●')} ${chalk.bold(g.title)} ${chalk.gray(`${g.severity} · ${g.owasp} · ${g.rule}${g.items.length > 1 ? ` · ${g.items.length}` : ''}`)}`);
154
+ const listed = opts.all ? g.items : g.items.slice(0, MAX_LISTED);
155
+ for (const f of listed) { const w = where(f); if (w) lines.push(` ${w}`); }
156
+ if (listed.length < g.items.length) lines.push(chalk.gray(` and ${g.items.length - listed.length} more (--all, or --json)`));
157
+ lines.push(chalk.gray(` fix: ${g.fix}`));
158
+ }
159
+
160
+ lines.push('', chalk.bold(' OWASP API Security Top 10'));
161
+ for (const o of r.owasp) {
162
+ const label = `${o.id.padEnd(6)}${o.name}`;
163
+ const total = o.high + o.medium + o.low;
164
+ const status = o.coverage === 'none' ? chalk.gray('needs runtime testing') : total ? `${o.high} high, ${o.medium} medium, ${o.low} low` : chalk.green('nothing found');
165
+ lines.push(` ${label.padEnd(58)} ${status}`);
166
+ }
167
+ lines.push('', chalk.gray(' Static checks show what the spec declares, not what the service enforces. "Nothing found" is not a pass.'));
168
+ if (r.verdict === 'fail') lines.push(chalk.gray(` Accepted risk? specshield waivers add <rule> --operation "GET /path" --owner <you> --reason "<why>" --days 30`));
169
+ lines.push('');
170
+ return lines.join('\n');
171
+ }
172
+
173
+ function cell(s) {
174
+ return String(s).replace(/\|/g, '\\|').replace(/\n/g, ' ');
175
+ }
176
+
177
+ function markdown(r) {
178
+ 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` : ''}.`, ''];
179
+ md.push('| Severity | Finding | OWASP | Count | Example |', '|---|---|---|---|---|');
180
+ for (const g of groups(r.findings)) md.push(`| ${g.severity} | ${cell(g.title)} | ${g.owasp} | ${g.items.length} | ${cell(where(g.items[0]) || '—')} |`);
181
+ return md.join('\n');
182
+ }
183
+
184
+ /** The line a path is declared on, so code scanning can point at it. */
185
+ function lineOf(text, needle) {
186
+ if (!text || !needle) return 1;
187
+ const i = text.split('\n').findIndex((l) => l.includes(needle));
188
+ return i < 0 ? 1 : i + 1;
189
+ }
190
+
191
+ function sarif(r, specText, harFiles) {
192
+ const LEVEL = { high: 'error', medium: 'warning', low: 'note' };
193
+ const used = [...new Set(r.findings.map((f) => f.rule))];
194
+ return {
195
+ version: '2.1.0',
196
+ $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
197
+ runs: [{
198
+ tool: { driver: {
199
+ name: 'SpecShield', version: pkg.version, informationUri: 'https://specshield.io',
200
+ rules: used.map((id) => ({ id, shortDescription: { text: RULES[id][1] }, help: { text: RULES[id][2] }, properties: { tags: ['security', `OWASP-${RULES[id][0]}`] } })),
201
+ } },
202
+ results: r.findings.map((f) => ({
203
+ ruleId: f.rule,
204
+ ruleIndex: used.indexOf(f.rule),
205
+ level: LEVEL[f.severity],
206
+ message: { text: `${f.title}${where(f) ? `: ${where(f)}` : ''}` },
207
+ locations: [{ physicalLocation: {
208
+ artifactLocation: { uri: f.source === 'spec' || !harFiles ? r.spec || 'traffic' : harFiles[0] },
209
+ region: { startLine: f.source === 'spec' ? lineOf(specText, (f.affectedEndpoints[0] || '').split(' ')[1] || f.field) : 1 },
210
+ } }],
211
+ })),
212
+ }],
213
+ };
214
+ }
215
+
216
+ module.exports = audit;
217
+ module.exports._internal = { sarif, render, siteOf };
@@ -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 };