specshield 3.5.2 → 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 +8 -2
- package/README.md +25 -1
- package/package.json +1 -1
- package/src/cli.js +2 -0
- package/src/commands/audit.js +179 -0
- package/src/core/security/audit.js +187 -0
- package/src/core/security/auditHar.js +157 -0
- package/src/core/security/diff.js +26 -15
- package/src/core/security/rules.js +62 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,12 +1,18 @@
|
|
|
1
1
|
# SpecShield CLI changelog
|
|
2
2
|
|
|
3
|
-
## Unreleased — security
|
|
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
|
|
4
10
|
|
|
5
11
|
### Added
|
|
6
12
|
|
|
7
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.
|
|
8
14
|
|
|
9
|
-
##
|
|
15
|
+
## 3.5.1 — 2026-10-29 — proof, not opinion: `specshield prove` and `specshield replay`
|
|
10
16
|
|
|
11
17
|
### Added
|
|
12
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) · [**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,30 @@ 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 --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
|
+
|
|
600
624
|
## Proof, not opinion: `specshield prove` and `specshield replay`
|
|
601
625
|
|
|
602
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.
|
|
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 };
|
|
@@ -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 };
|
|
@@ -41,7 +41,7 @@ function operations(doc) {
|
|
|
41
41
|
for (const method of METHODS) {
|
|
42
42
|
if (!item[method] || typeof item[method] !== 'object') continue;
|
|
43
43
|
// A renamed path parameter is the same operation.
|
|
44
|
-
ops.set(`${method} ${path.replace(/\{[^}]+\}/g, '{}')}`, { path, method, op: item[method] });
|
|
44
|
+
ops.set(`${method} ${path.replace(/\{[^}]+\}/g, '{}')}`, { path, method, op: item[method], item });
|
|
45
45
|
}
|
|
46
46
|
}
|
|
47
47
|
return ops;
|
|
@@ -152,6 +152,7 @@ function addedEndpoint(h, req, doc) {
|
|
|
152
152
|
|
|
153
153
|
/** Specs that declare no auth anywhere say nothing about which endpoints are public. */
|
|
154
154
|
function declaresAuth(doc) {
|
|
155
|
+
if ((doc.security || []).some((a) => a && Object.keys(a).length)) return true;
|
|
155
156
|
return [...operations(doc).values()].some((o) => !allowsAnonymous(requirement(doc, o.op)));
|
|
156
157
|
}
|
|
157
158
|
|
|
@@ -220,22 +221,23 @@ const leaf = (p) => p.split('.').pop().replace(/\[\]$/, '');
|
|
|
220
221
|
/** Sensitive fields a 2xx response can carry, with their paths. */
|
|
221
222
|
function sensitiveResponseFields(doc, op) {
|
|
222
223
|
const out = [];
|
|
223
|
-
const memo = memoFor(doc);
|
|
224
224
|
for (const [status, raw] of Object.entries(op.responses || {})) {
|
|
225
225
|
if (!/^2/.test(status)) continue;
|
|
226
226
|
const res = deref(doc, raw);
|
|
227
227
|
if (!res) continue;
|
|
228
228
|
const schemas = res.schema ? [res.schema] : Object.entries(res.content || {})
|
|
229
229
|
.filter(([type]) => /json/i.test(type)).map(([, m]) => m && m.schema).filter(Boolean);
|
|
230
|
-
for (const s of schemas) out.push(...
|
|
230
|
+
for (const s of schemas) out.push(...fields(doc, s, sensitivity, 'writeOnly'));
|
|
231
231
|
}
|
|
232
232
|
return out;
|
|
233
233
|
}
|
|
234
234
|
|
|
235
235
|
const memos = new WeakMap();
|
|
236
|
-
function memoFor(doc) {
|
|
236
|
+
function memoFor(doc, classify) {
|
|
237
237
|
if (!memos.has(doc)) memos.set(doc, new Map());
|
|
238
|
-
|
|
238
|
+
const byClassifier = memos.get(doc);
|
|
239
|
+
if (!byClassifier.has(classify)) byClassifier.set(classify, new Map());
|
|
240
|
+
return byClassifier.get(classify);
|
|
239
241
|
}
|
|
240
242
|
|
|
241
243
|
function deref(doc, node) {
|
|
@@ -247,32 +249,38 @@ function deref(doc, node) {
|
|
|
247
249
|
return n && typeof n === 'object' ? n : null;
|
|
248
250
|
}
|
|
249
251
|
|
|
250
|
-
/** [{path, tier}]
|
|
251
|
-
function
|
|
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) {
|
|
252
259
|
if (!node || depth > MAX_DEPTH) return [];
|
|
260
|
+
const { doc, memo, stack } = ctx;
|
|
253
261
|
if (node.$ref) {
|
|
254
262
|
if (memo.has(node.$ref)) return memo.get(node.$ref);
|
|
255
263
|
if (stack.has(node.$ref)) return [];
|
|
256
264
|
stack.add(node.$ref);
|
|
257
|
-
const r = walk(
|
|
265
|
+
const r = walk(ctx, deref(doc, node), depth + 1);
|
|
258
266
|
stack.delete(node.$ref);
|
|
259
267
|
memo.set(node.$ref, r);
|
|
260
268
|
return r;
|
|
261
269
|
}
|
|
262
270
|
const out = [];
|
|
263
271
|
for (const key of ['allOf', 'oneOf', 'anyOf']) {
|
|
264
|
-
if (Array.isArray(node[key])) for (const s of node[key]) out.push(...walk(
|
|
272
|
+
if (Array.isArray(node[key])) for (const s of node[key]) out.push(...walk(ctx, s, depth + 1));
|
|
265
273
|
}
|
|
266
|
-
if (node.items) out.push(...walk(
|
|
274
|
+
if (node.items) out.push(...walk(ctx, node.items, depth + 1).map((f) => ({ ...f, path: `[].${f.path}` })));
|
|
267
275
|
if (node.additionalProperties && typeof node.additionalProperties === 'object') {
|
|
268
|
-
out.push(...walk(
|
|
276
|
+
out.push(...walk(ctx, node.additionalProperties, depth + 1));
|
|
269
277
|
}
|
|
270
278
|
for (const [name, raw] of Object.entries(node.properties || {})) {
|
|
271
279
|
const prop = deref(doc, raw);
|
|
272
|
-
if (!prop || prop.
|
|
273
|
-
const tier =
|
|
280
|
+
if (!prop || prop[ctx.skip]) continue;
|
|
281
|
+
const tier = ctx.classify(name, prop);
|
|
274
282
|
if (tier) out.push({ path: name, tier });
|
|
275
|
-
out.push(...walk(
|
|
283
|
+
out.push(...walk(ctx, raw, depth + 1).map((f) => ({ ...f, path: `${name}.${f.path}` })));
|
|
276
284
|
}
|
|
277
285
|
return out.map((f) => ({ ...f, path: f.path.replace(/^\[\]\./, '') }));
|
|
278
286
|
}
|
|
@@ -301,4 +309,7 @@ function merge(found) {
|
|
|
301
309
|
return out;
|
|
302
310
|
}
|
|
303
311
|
|
|
304
|
-
module.exports = {
|
|
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 };
|