@roboteby/parry 1.1.0-rc.1

package/src/core/engine.js

@@ -0,0 +1,264 @@
+'use strict';
+
+const {
+  SQLInjectionDetector,
+  XSSDetector,
+  NoSQLDetector,
+  HPPDetector,
+  PrototypePollutionDetector,
+  PathTraversalDetector,
+  RequestShapeGuard,
+} = require('../detectors');
+const { safeStringify } = require('../utils/normalize');
+const { severityForThreats } = require('./scoring');
+const {
+  createThreatEvent,
+  createBanEvent,
+  createRateLimitEvent,
+  createStoreFailureEvent,
+} = require('./threat-event');
+
+async function analyzeRequest(requestData, context) {
+  const { config, rateLimiter, logger } = context;
+  const timestamp = requestData.timestamp || new Date().toISOString();
+  const rateLimit = await checkRateLimit(requestData, { config, rateLimiter, logger, timestamp });
+
+  if (rateLimit?.storeFailure && rateLimit.failClosed) {
+    return {
+      allowed: false,
+      blocked: true,
+      reason: 'STORE_FAILURE',
+      statusCode: 503,
+      message: 'Rate limit store unavailable.',
+      severity: 'medium',
+      detector: null,
+      threats: [],
+      event: rateLimit.event,
+      rateLimit: null,
+      responseExtra: {},
+    };
+  }
+
+  if (rateLimit?.banned) {
+    return {
+      allowed: false,
+      blocked: true,
+      reason: 'BAN',
+      statusCode: 429,
+      message: 'Too many suspicious requests. IP temporarily banned.',
+      severity: 'high',
+      detector: null,
+      threats: [],
+      event: createBanEvent(createRequestEventContext(requestData, timestamp)),
+      rateLimit,
+      responseExtra: { banExpiresAt: rateLimit.banExpiresAt },
+    };
+  }
+
+  if (rateLimit?.limited) {
+    return {
+      allowed: false,
+      blocked: true,
+      reason: 'RATE_LIMIT',
+      statusCode: 429,
+      message: 'Request limit reached. Please try again shortly.',
+      severity: 'medium',
+      detector: null,
+      threats: [],
+      event: createRateLimitEvent(createRequestEventContext(requestData, timestamp)),
+      rateLimit,
+      responseExtra: {},
+    };
+  }
+
+  const threats = [
+    ...scanApplicationLayerGuards(requestData, config),
+    ...scanTargets(requestData.targets || [], config),
+  ];
+
+  if (threats.length > 0) {
+    if (config.rateLimit && rateLimiter) {
+      await recordSuspicious(requestData, { config, rateLimiter, logger, timestamp });
+    }
+    const normalizedThreats = enrichThreats(threats);
+
+    const event = createThreatEvent({
+      ip: requestData.ip,
+      timestamp,
+      method: requestData.method,
+      url: requestData.url,
+      path: requestData.path,
+      requestId: requestData.requestId,
+      userAgent: requestData.userAgent,
+      threats: normalizedThreats,
+    });
+
+    return {
+      allowed: false,
+      blocked: true,
+      reason: 'THREAT',
+      statusCode: 400,
+      message: 'Request blocked: malicious pattern detected.',
+      severity: severityForThreats(normalizedThreats),
+      detector: normalizedThreats[0].detector,
+      threats: normalizedThreats,
+      event,
+      rateLimit,
+      responseExtra: {
+        threats: normalizedThreats.map(toResponseThreat),
+      },
+    };
+  }
+
+  return {
+    allowed: true,
+    blocked: false,
+    reason: null,
+    statusCode: null,
+    message: null,
+    severity: 'none',
+    detector: null,
+    threats: [],
+    event: null,
+    rateLimit,
+    responseExtra: {},
+  };
+}
+
+async function checkRateLimit(requestData, context) {
+  const { config, rateLimiter, logger, timestamp } = context;
+  if (!config.rateLimit || !rateLimiter) return null;
+
+  try {
+    return await rateLimiter.check(requestData.ip);
+  } catch (error) {
+    const mode = config.storeFailureMode === 'fail-closed' ? 'fail-closed' : 'fail-open';
+    const event = createStoreFailureEvent({
+      ...createRequestEventContext(requestData, timestamp),
+      error,
+      mode,
+      module: 'rate-limit',
+    });
+    if (logger && typeof logger.logStoreError === 'function') logger.logStoreError(error, event);
+
+    if (mode === 'fail-open') return null;
+
+    return { storeFailure: true, failClosed: true, event };
+  }
+}
+
+async function recordSuspicious(requestData, context) {
+  const { config, rateLimiter, logger, timestamp } = context;
+
+  try {
+    const result = await rateLimiter.recordSuspicious(requestData.ip);
+    if (result?.banned && logger && typeof logger.log === 'function') {
+      logger.log({
+        type: 'TEMPORARY_BAN_CREATED',
+        module: 'rate-limit',
+        severity: 'high',
+        action: 'created',
+        reason: 'Suspicious activity threshold reached',
+        ...createRequestEventContext(requestData, timestamp),
+        metadata: {
+          banExpiresAt: result.banExpiresAt,
+        },
+      });
+    }
+  } catch (error) {
+    const mode = config.storeFailureMode === 'fail-closed' ? 'fail-closed' : 'fail-open';
+    const event = createStoreFailureEvent({
+      ...createRequestEventContext(requestData, timestamp),
+      error,
+      mode,
+      module: 'rate-limit',
+    });
+    if (logger && typeof logger.logStoreError === 'function') logger.logStoreError(error, event);
+  }
+}
+
+function createRequestEventContext(requestData, timestamp) {
+  return {
+    ip: requestData.ip,
+    timestamp,
+    method: requestData.method,
+    path: requestData.path,
+    requestId: requestData.requestId,
+    userAgent: requestData.userAgent,
+  };
+}
+
+function scanApplicationLayerGuards(requestData, config) {
+  const threats = [];
+  const surfaces = {
+    query: requestData.query || {},
+    params: requestData.params || {},
+    body: requestData.body,
+  };
+
+  if (config.requestShape?.enabled) {
+    const hit = RequestShapeGuard.scan(surfaces, config.requestShape);
+    if (hit) return [hit];
+  }
+
+  if (config.hpp?.enabled) {
+    const hit = HPPDetector.scan(surfaces.query, config.hpp);
+    if (hit) threats.push(hit);
+  }
+
+  if (config.prototypePollution?.enabled) {
+    const hit = PrototypePollutionDetector.scan(surfaces);
+    if (hit) threats.push(hit);
+  }
+
+  if (config.pathTraversal?.enabled) {
+    const hit = PathTraversalDetector.scan(requestData.targets || []);
+    if (hit) threats.push(hit);
+  }
+
+  return threats;
+}
+
+function scanTargets(targets, config) {
+  const threats = [];
+
+  for (const { label, value, stringValue } of targets) {
+    const str = stringValue != null ? stringValue : safeStringify(value);
+
+    if (config.sql) {
+      const hit = SQLInjectionDetector.scan(str);
+      if (hit) threats.push({ detector: 'SQL_INJECTION', field: label, pattern: hit });
+    }
+
+    if (config.xss) {
+      const hit = XSSDetector.scan(str);
+      if (hit) threats.push({ detector: 'XSS', field: label, pattern: hit });
+    }
+
+    if (config.nosql) {
+      const hit = NoSQLDetector.scan(value);
+      if (hit) threats.push({ detector: 'NOSQL_INJECTION', field: label, pattern: hit });
+    }
+  }
+
+  return threats;
+}
+
+function enrichThreats(threats) {
+  return threats.map((threat) => ({
+    ...threat,
+    severity: threat.severity || severityForThreats([threat]),
+  }));
+}
+
+function toResponseThreat(threat) {
+  const responseThreat = {
+    detector: threat.detector,
+    field: threat.field,
+  };
+
+  if (threat.reason) responseThreat.reason = threat.reason;
+  return responseThreat;
+}
+
+module.exports = { analyzeRequest, scanTargets, scanApplicationLayerGuards };

package/src/core/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const { RateLimiter } = require('./rateLimiter');
+const { ThreatLogger } = require('./logger');
+const { MemoryStore, RedisStore } = require('../stores');
+
+module.exports = { RateLimiter, ThreatLogger, MemoryStore, RedisStore };

package/src/core/logger.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../logger/console-reporter');

package/src/core/rate-limit-result.js

@@ -0,0 +1,13 @@
+'use strict';
+
+function createRateLimitResult({ limited, banned, remaining, resetAt, banExpiresAt }) {
+  return {
+    limited: Boolean(limited),
+    banned: Boolean(banned),
+    remaining: Math.max(0, Number(remaining || 0)),
+    resetAt: resetAt || null,
+    banExpiresAt: banExpiresAt || null,
+  };
+}
+
+module.exports = { createRateLimitResult };

package/src/core/rateLimiter.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../rate-limit/limiter');

package/src/core/scoring.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const THREAT_SEVERITY = {
+  SQL_INJECTION: 'high',
+  XSS: 'high',
+  NOSQL_INJECTION: 'high',
+  HTTP_PARAMETER_POLLUTION: 'medium',
+  PROTOTYPE_POLLUTION: 'high',
+  PATH_TRAVERSAL: 'high',
+  REQUEST_SHAPE: 'medium',
+};
+
+function severityForThreats(threats) {
+  if (!threats || threats.length === 0) return 'none';
+  return THREAT_SEVERITY[threats[0].detector] || 'medium';
+}
+
+module.exports = { severityForThreats };

package/src/core/threat-event.js

@@ -0,0 +1,69 @@
+'use strict';
+
+function createThreatEvent({ ip, timestamp, method, url, path, threats, requestId, userAgent }) {
+  const firstThreat = threats?.[0] || {};
+  return {
+    type: 'THREAT',
+    detector: firstThreat.detector,
+    severity: firstThreat.severity,
+    reason: firstThreat.reason,
+    target: firstThreat.field,
+    ip,
+    timestamp,
+    method,
+    url,
+    path,
+    requestId,
+    userAgent,
+    threats,
+  };
+}
+
+function createBanEvent({ ip, timestamp, method, path, requestId, userAgent }) {
+  return {
+    type: 'BAN',
+    ip,
+    reason: 'Ban for suspicious activity',
+    timestamp,
+    method,
+    path,
+    requestId,
+    userAgent,
+  };
+}
+
+function createRateLimitEvent({ ip, timestamp, method, path, requestId, userAgent }) {
+  return { type: 'RATE_LIMIT', ip, timestamp, method, path, requestId, userAgent };
+}
+
+function createStoreFailureEvent({
+  ip,
+  timestamp,
+  error,
+  mode,
+  method,
+  path,
+  requestId,
+  userAgent,
+  module,
+}) {
+  return {
+    type: 'STORE_FAILURE',
+    module,
+    ip,
+    timestamp,
+    reason: error && error.message ? error.message : String(error),
+    mode,
+    method,
+    path,
+    requestId,
+    userAgent,
+  };
+}
+
+module.exports = {
+  createThreatEvent,
+  createBanEvent,
+  createRateLimitEvent,
+  createStoreFailureEvent,
+};

package/src/detectors/hpp.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const HPPDetector = {
+  scan(query, options = {}) {
+    if (!query || typeof query !== 'object') return null;
+
+    const allowed = new Set(options.allowDuplicateParamsFor || []);
+
+    try {
+      for (const [key, value] of Object.entries(query)) {
+        if (allowed.has(key)) continue;
+
+        if (Array.isArray(value) && value.length > 1) {
+          return {
+            detector: 'HTTP_PARAMETER_POLLUTION',
+            field: `query.${key}`,
+            pattern: 'duplicate-query-param',
+            reason: `Duplicate query parameter: ${key}`,
+          };
+        }
+      }
+    } catch (_) {
+      return null;
+    }
+
+    return null;
+  },
+};
+
+module.exports = { HPPDetector };

package/src/detectors/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { SQLInjectionDetector } = require('./sql');
+const { XSSDetector } = require('./xss');
+const { NoSQLDetector } = require('./nosql');
+const { HPPDetector } = require('./hpp');
+const { PrototypePollutionDetector } = require('./prototype-pollution');
+const { PathTraversalDetector } = require('./path-traversal');
+const { RequestShapeGuard } = require('./request-shape');
+
+module.exports = {
+  SQLInjectionDetector,
+  XSSDetector,
+  NoSQLDetector,
+  HPPDetector,
+  PrototypePollutionDetector,
+  PathTraversalDetector,
+  RequestShapeGuard,
+};

package/src/detectors/nosql.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const {
+  NOSQL_DANGEROUS_OPERATORS,
+  NOSQL_SUSPICIOUS_OPERATORS,
+  NOSQL_STRING_PATTERNS,
+} = require('../../constants/patterns');
+
+const NoSQLDetector = {
+  /** @param {*} value @returns {string|null} */
+  scan(value) {
+    if (value !== null && typeof value === 'object') return _scanObject(value);
+    if (typeof value === 'string') return _scanString(value);
+    return null;
+  },
+};
+
+function _scanObject(obj, depth = 0) {
+  if (depth > 6) return null;
+  for (const key of Object.keys(obj)) {
+    if (NOSQL_DANGEROUS_OPERATORS.has(key)) return `Operador perigoso: ${key}`;
+    if (NOSQL_SUSPICIOUS_OPERATORS.has(key)) return `Operador suspeito: ${key}`;
+    const val = obj[key];
+    if (val && typeof val === 'object') {
+      const nested = _scanObject(val, depth + 1);
+      if (nested) return nested;
+    }
+    if (typeof val === 'string') {
+      const hit = _scanString(val);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+function _scanString(value) {
+  if (!value || value.trim() === '') return null;
+  if (value.trim().startsWith('{') || value.trim().startsWith('[')) {
+    try {
+      const parsed = JSON.parse(value);
+      if (parsed && typeof parsed === 'object') {
+        const hit = _scanObject(parsed);
+        if (hit) return hit;
+      }
+    } catch (_) {}
+  }
+  for (const pattern of NOSQL_STRING_PATTERNS) {
+    if (pattern.test(value)) return pattern.toString();
+  }
+  return null;
+}
+
+module.exports = { NoSQLDetector };

package/src/detectors/path-traversal.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const { decodeUrlValue } = require('../utils/decode');
+
+const TRAVERSAL_PATTERN = /(^|[\\/])\.\.([\\/]|$)/;
+
+const PathTraversalDetector = {
+  scan(targets) {
+    for (const target of targets || []) {
+      const hit = scanTarget(target);
+      if (hit) return hit;
+    }
+    return null;
+  },
+};
+
+function scanTarget(target) {
+  if (!target || !isRequestValueTarget(target.label)) return null;
+
+  const strings = collectStrings(target.value, target.label);
+  for (const item of strings) {
+    const normalized = normalizePathCandidate(item.value);
+    if (TRAVERSAL_PATTERN.test(normalized)) {
+      return {
+        detector: 'PATH_TRAVERSAL',
+        field: item.label,
+        pattern: 'path-traversal-segment',
+        reason: 'Path traversal sequence detected',
+      };
+    }
+  }
+
+  return null;
+}
+
+function isRequestValueTarget(label) {
+  return (
+    label === 'body' ||
+    label.startsWith('body.') ||
+    label.startsWith('query.') ||
+    label.startsWith('params.')
+  );
+}
+
+function collectStrings(value, label, seen = new WeakSet()) {
+  if (typeof value === 'string') return [{ label, value }];
+  if (!value || typeof value !== 'object') return [];
+  if (seen.has(value)) return [];
+  seen.add(value);
+
+  const strings = [];
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      strings.push(...collectStrings(value[i], `${label}[${i}]`, seen));
+    }
+    return strings;
+  }
+
+  try {
+    for (const [key, child] of Object.entries(value)) {
+      strings.push(...collectStrings(child, `${label}.${key}`, seen));
+    }
+  } catch (_) {}
+
+  return strings;
+}
+
+function normalizePathCandidate(value) {
+  return decodeUrlValue(value, 2).replace(/\\/g, '/');
+}
+
+module.exports = { PathTraversalDetector };

package/src/detectors/prototype-pollution.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const { decodeUrlValue } = require('../utils/decode');
+
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+const PrototypePollutionDetector = {
+  scan(surfaces) {
+    const seen = new WeakSet();
+
+    for (const [surface, value] of Object.entries(surfaces || {})) {
+      const hit = scanValue(value, surface, seen);
+      if (hit) return hit;
+    }
+
+    return null;
+  },
+};
+
+function scanValue(value, path, seen) {
+  if (!value || typeof value !== 'object') return null;
+  if (seen.has(value)) return null;
+  seen.add(value);
+
+  let keys;
+  try {
+    keys = Reflect.ownKeys(value);
+  } catch (_) {
+    return null;
+  }
+
+  for (const key of keys) {
+    if (typeof key !== 'string') continue;
+
+    const childPath = Array.isArray(value) ? `${path}[${key}]` : `${path}.${key}`;
+    const dangerousKey = findDangerousKey(key);
+    if (dangerousKey) {
+      return {
+        detector: 'PROTOTYPE_POLLUTION',
+        field: childPath,
+        pattern: dangerousKey,
+        reason: `Dangerous object key: ${dangerousKey}`,
+      };
+    }
+
+    const nested = scanValue(value[key], childPath, seen);
+    if (nested) return nested;
+  }
+
+  return null;
+}
+
+function findDangerousKey(key) {
+  const candidates = new Set([key]);
+  const decoded = decodeUrlValue(key, 2);
+  candidates.add(decoded);
+
+  for (const candidate of [...candidates]) {
+    for (const part of String(candidate).split('.')) candidates.add(part);
+  }
+
+  for (const candidate of candidates) {
+    if (DANGEROUS_KEYS.has(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+module.exports = { PrototypePollutionDetector };

package/src/detectors/request-shape.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const RequestShapeGuard = {
+  scan(surfaces, options) {
+    const limits = {
+      maxDepth: options.maxDepth,
+      maxKeys: options.maxKeys,
+      maxArrayLength: options.maxArrayLength,
+      maxStringLength: options.maxStringLength,
+    };
+    const state = { keyCount: 0, seen: new WeakSet() };
+
+    for (const [surface, value] of Object.entries(surfaces || {})) {
+      const hit = scanValue(value, surface, 0, limits, state);
+      if (hit) return hit;
+    }
+
+    return null;
+  },
+};
+
+function scanValue(value, path, depth, limits, state) {
+  if (typeof value === 'string' && value.length > limits.maxStringLength) {
+    return shapeThreat(path, 'maxStringLength', `String length exceeds ${limits.maxStringLength}`);
+  }
+
+  if (!value || typeof value !== 'object') return null;
+  if (state.seen.has(value)) return null;
+  state.seen.add(value);
+
+  if (depth > limits.maxDepth) {
+    return shapeThreat(path, 'maxDepth', `Object depth exceeds ${limits.maxDepth}`);
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length > limits.maxArrayLength) {
+      return shapeThreat(path, 'maxArrayLength', `Array length exceeds ${limits.maxArrayLength}`);
+    }
+
+    for (let i = 0; i < value.length; i++) {
+      const hit = scanValue(value[i], `${path}[${i}]`, depth + 1, limits, state);
+      if (hit) return hit;
+    }
+    return null;
+  }
+
+  let entries;
+  try {
+    entries = Object.entries(value);
+  } catch (_) {
+    return null;
+  }
+
+  state.keyCount += entries.length;
+  if (state.keyCount > limits.maxKeys) {
+    return shapeThreat(path, 'maxKeys', `Object key count exceeds ${limits.maxKeys}`);
+  }
+
+  for (const [key, child] of entries) {
+    const hit = scanValue(child, `${path}.${key}`, depth + 1, limits, state);
+    if (hit) return hit;
+  }
+
+  return null;
+}
+
+function shapeThreat(field, pattern, reason) {
+  return {
+    detector: 'REQUEST_SHAPE',
+    field,
+    pattern,
+    reason,
+  };
+}
+
+module.exports = { RequestShapeGuard };