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.
@@ -0,0 +1,68 @@
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
+ // Traffic vs spec
52
+ 'shadow-endpoint': ['API9', 'Undocumented endpoint receiving traffic', 'Document it and give it the same review as the rest, or remove it.'],
53
+ 'undocumented-method': ['API5', 'Undocumented method on a documented path', 'Answer 405 for it, or document and secure it.'],
54
+ 'zombie-version': ['API9', 'Retired API version still served', 'Turn the old version off, or keep patching it like the current one.'],
55
+ 'sunset-passed': ['API9', 'Still served after its sunset date', 'Turn it off as announced, or move x-sunset in the spec.'],
56
+ 'exposed-sensitive-path': ['API8', 'Sensitive file or debug endpoint served', 'Block it at the server or proxy, and rotate anything it exposed.'],
57
+ 'stack-trace': ['API8', 'Stack trace in an error response', 'Return a generic error and log the detail on the server.'],
58
+ };
59
+
60
+ const SEVERITIES = ['high', 'medium', 'low'];
61
+
62
+ /** One finding, shaped so the gate's waivers apply: `type` is the rule. */
63
+ function finding(rule, severity, { endpoint = null, field = null, detail = null, source = 'spec' } = {}) {
64
+ const [owasp, title, fix] = RULES[rule];
65
+ return { type: rule, rule, owasp, severity, title, fix, detail, field, source, affectedEndpoints: endpoint ? [endpoint] : [] };
66
+ }
67
+
68
+ module.exports = { OWASP, RULES, SEVERITIES, finding };
@@ -15,6 +15,7 @@
15
15
  * JSON with a host field, absolute request URLs), else null
16
16
  * query raw query string without the leading '?' ('' when absent)
17
17
  * status numeric status code, or null
18
+ * bytes response body size (combined format only), or null
18
19
  * time epoch ms, or null when the line carries no parseable timestamp
19
20
  * userAgent raw User-Agent, or null
20
21
  * extras quoted fields after the User-Agent (combined format only) —
@@ -34,7 +35,7 @@ const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', '
34
35
  // ─── combined / common ──────────────────────────────────────────────────────
35
36
 
36
37
  // host ident authuser [time] "request" status bytes ["referer" "user-agent"] [extras...]
37
- const COMBINED_RE = /^(\S+) \S+ \S+ \[([^\]]+)\] "((?:[^"\\]|\\.)*)" (\d{3}|-) \S+(?: "((?:[^"\\]|\\.)*)" "((?:[^"\\]|\\.)*)")?(.*)$/;
38
+ const COMBINED_RE = /^(\S+) \S+ \S+ \[([^\]]+)\] "((?:[^"\\]|\\.)*)" (\d{3}|-) (\S+)(?: "((?:[^"\\]|\\.)*)" "((?:[^"\\]|\\.)*)")?(.*)$/;
38
39
 
39
40
  function parseCombined(line) {
40
41
  const m = COMBINED_RE.exec(line);
@@ -44,9 +45,10 @@ function parseCombined(line) {
44
45
  return {
45
46
  ...req,
46
47
  status: m[4] === '-' ? null : Number(m[4]),
48
+ bytes: /^\d+$/.test(m[5]) ? Number(m[5]) : null,
47
49
  time: parseClfTime(m[2]),
48
- userAgent: m[6] !== undefined ? nullIfDash(unescape(m[6])) : null,
49
- extras: m[7] ? tokenize(m[7]).map(nullIfDash) : [],
50
+ userAgent: m[7] !== undefined ? nullIfDash(unescape(m[7])) : null,
51
+ extras: m[8] ? tokenize(m[8]).map(nullIfDash) : [],
50
52
  json: null,
51
53
  };
52
54
  }
@@ -221,12 +223,17 @@ function parseAnyTime(v) {
221
223
 
222
224
  const PARSERS = { combined: parseCombined, alb: parseAlb, json: parseJsonLine };
223
225
 
224
- /** Picks the format that parses the most of the sample lines. */
226
+ // A line can have a format's shape without being a request: OpenLiteSpeed logs
227
+ // TLS probes and dropped connections as `"" 200`. They still say which format it is.
228
+ const SHAPES = { combined: COMBINED_RE };
229
+
230
+ /** Picks the format that parses (or at least fits) the most of the sample lines. */
225
231
  function detectFormat(sampleLines) {
226
232
  let best = null;
227
233
  let bestHits = 0;
228
234
  for (const [name, parse] of Object.entries(PARSERS)) {
229
- const hits = sampleLines.filter((l) => parse(l)).length;
235
+ const shape = SHAPES[name];
236
+ const hits = sampleLines.filter((l) => parse(l) || (shape && shape.test(l))).length;
230
237
  if (hits > bestHits) { best = name; bestHits = hits; }
231
238
  }
232
239
  return best;
@@ -241,9 +248,9 @@ function splitRequestLine(s) {
241
248
  if (parts.length < 2) return null;
242
249
  const method = parts[0].toUpperCase();
243
250
  if (!HTTP_METHODS.has(method)) return null;
244
- const { path, query, host } = splitTarget(parts[1]);
251
+ const { path, query, host, trailingSlash } = splitTarget(parts[1]);
245
252
  if (!path) return null;
246
- return { method, path, query, host };
253
+ return { method, path, query, host, trailingSlash };
247
254
  }
248
255
 
249
256
  function splitTarget(target) {
@@ -262,8 +269,9 @@ function splitTarget(target) {
262
269
  let path = q >= 0 ? t.slice(0, q) : t;
263
270
  const query = q >= 0 ? t.slice(q + 1) : '';
264
271
  path = path.replace(/\/{2,}/g, '/');
265
- if (path.length > 1 && path.endsWith('/')) path = path.slice(0, -1);
266
- return { path, query, host };
272
+ const trailingSlash = path.length > 1 && path.endsWith('/');
273
+ if (trailingSlash) path = path.slice(0, -1);
274
+ return { path, query, host, trailingSlash };
267
275
  }
268
276
 
269
277
  /** "API.Example.com:443" → "api.example.com"; "[::1]:80" → "[::1]". */