@contrast/protect 1.66.0 → 1.67.0

package/lib/hardening/handlers.js

@@ -18,6 +18,7 @@
 const {
   BLOCKING_MODES,
   isString,
+  InputType,
   Rule: { UNTRUSTED_DESERIALIZATION }
 } = require('@contrast/common');
 
@@ -25,6 +26,7 @@ const NODE_SERIALIZE_RCE_TOKEN = '_$$ND_FUNC$$_';
 
 module.exports = function(core) {
   const {
+    protect,
     protect: {
       hardening,
       throwSecurityException,
@@ -40,32 +42,47 @@ module.exports = function(core) {
     return results;
   }
 
-  hardening.handleUntrustedDeserialization = function(sourceContext, sinkContext) {
-    const ruleId = UNTRUSTED_DESERIALIZATION;
+  function handleFindings(sourceContext, sinkContext, ruleId, result, findings) {
+    const { stacktraceOpts } = sinkContext;
+    captureStacktrace(sinkContext, stacktraceOpts);
+
     const mode = sourceContext.policy[ruleId];
-    const { name, value, stacktraceOpts } = sinkContext;
+    getResults(sourceContext, ruleId).push(result);
 
-    if (mode === 'off') return;
+    let blockInfo;
+    if (BLOCKING_MODES.includes(mode)) {
+      result.blocked = true;
+      blockInfo = [mode, ruleId];
+      sourceContext.securityException = blockInfo;
+    }
 
-    if (name === 'node-serialize.unserialize') {
-      if (!isString(value) || !value.indexOf(NODE_SERIALIZE_RCE_TOKEN)) return;
+    protect.reportFinding({ findings, result, sinkContext });
 
-      const blocked = BLOCKING_MODES.includes(mode);
-      const results = getResults(sourceContext, ruleId);
+    if (blockInfo) throwSecurityException(sourceContext);
+  }
 
-      captureStacktrace(sinkContext, stacktraceOpts);
-      results.push({
-        value: sinkContext.value,
-        blocked,
-        exploitMetadata: [{ deserializer: name, command: false }],
-        sinkContext,
-      });
+  hardening.handleUntrustedDeserialization = function (sourceContext, sinkContext) {
+    const ruleId = UNTRUSTED_DESERIALIZATION;
+    const mode = sourceContext.policy[ruleId];
+    const { name, value } = sinkContext;
 
-      if (blocked) {
-        sourceContext.securityException = [mode, ruleId];
-        throwSecurityException(sourceContext);
-      }
-    }
+    if (
+      mode === 'off' ||
+      name !== 'node-serialize.unserialize' ||
+      !isString(value) ||
+      !value.indexOf(NODE_SERIALIZE_RCE_TOKEN)
+    ) return;
+
+    const result = {
+      value: sinkContext.value,
+      ruleId: UNTRUSTED_DESERIALIZATION,
+      blocked: false,
+      exploited: true,
+      inputType: InputType.UNKNOWN,
+    };
+    const findings = { deserializer: name, command: false };
+
+    handleFindings(sourceContext, sinkContext, ruleId, result, findings);
   };
 
   return hardening;

package/lib/index.d.ts

@@ -13,7 +13,7 @@
  * way not consistent with the End User License Agreement.
  */
 
-import { ReqData, ProtectMessage, ResultMap, ProtectRuleMode, Blocker } from '@contrast/common';
+import { ReqData, ProtectMessage, ResultMap, ProtectRuleMode, Blocker, ProtectFindingEventArg } from '@contrast/common';
 import { IncomingMessage, ServerResponse } from 'node:http';
 import * as http from 'node:http';
 import * as https from 'node:https';
@@ -60,7 +60,8 @@ export interface Protect {
   makeSourceContext: (req: IncomingMessage, res: ServerResponse) => ProtectRequestStore,
   throwSecurityException: (sourceContext: ProtectRequestStore) => void,
   policy: ProtectPolicy,
-  getPolicy(): ProtectPolicy, // creates copy for request scope
+  getPolicy: () => ProtectPolicy, // creates copy for request scope
+  reportFindings: (e: ProtectFindingEventArg) => void,
   inputAnalysis: {
     handleConnect: (sourceContext: ProtectRequestStore, connectInputs: ConnectInputs) => undefined | [string, string],
     handleRequestEnd: (sourceContext: ProtectRequestStore) => void, //NYI

package/lib/index.js

@@ -16,7 +16,7 @@
 'use strict';
 
 const { isMainThread } = require('node:worker_threads');
-const { callChildComponentMethodsSync } = require('@contrast/common');
+const { callChildComponentMethodsSync, Event } = require('@contrast/common');
 const { ConfigSource } = require('@contrast/config');
 
 module.exports = function(core) {
@@ -37,7 +37,7 @@ module.exports = function(core) {
   require('./hardening')(core);
   require('./semantic-analysis')(core);
 
-  protect.install = function() {
+  protect.install = function install() {
     // only force instrumentation if assess is explicitly enabled in local config
     const forceInstrumentation =
       config.preinstrument &&
@@ -60,6 +60,13 @@ module.exports = function(core) {
     ctx.store.protect = protect.makeSourceContext(ctx);
   });
 
+  protect.reportFinding = function reportFinding(data) {
+    core.messages.emit(Event.PROTECT_FINDING, {
+      store: core.scopes.sources.getStore(),
+      ...data,
+    });
+  };
+
   return protect;
 };
 

package/lib/input-analysis/handlers.js

@@ -100,6 +100,7 @@ module.exports = Core.makeComponent({
   factory(core) {
     const {
       logger,
+      protect,
       protect: {
         agentLib,
         inputAnalysis,
@@ -183,6 +184,10 @@ module.exports = Core.makeComponent({
         block = inputAnalysis.handleMethodTampering(sourceContext, connectInputs);
       }
 
+      if (block) {
+        core.protect.reportFinding(block[2]);
+      }
+
       return block;
     };
 
@@ -216,6 +221,7 @@ module.exports = Core.makeComponent({
       const block = commonObjectAnalyzer(sourceContext, queryParams, parameterInputTypes);
 
       if (block) {
+        core.protect.reportFinding(block[2]);
         core.protect.throwSecurityException(sourceContext);
       }
     };
@@ -284,6 +290,9 @@ module.exports = Core.makeComponent({
       const block = mergeFindings(sourceContext, urlParamsFindings);
 
       if (block) {
+        if (block[2]) {
+          core.protect.reportFinding(block[2]);
+        }
         core.protect.throwSecurityException(sourceContext);
       }
     };
@@ -312,9 +321,11 @@ module.exports = Core.makeComponent({
 
       const cookieFindings = agentLib.scoreRequestConnect(rulesMask, { cookies: cookiesArr }, preferWW);
 
+
       const block = mergeFindings(sourceContext, cookieFindings);
 
       if (block) {
+        protect.reportFinding(block[2]);
         core.protect.throwSecurityException(sourceContext);
       }
     };
@@ -356,6 +367,7 @@ module.exports = Core.makeComponent({
       sourceContext.bodyType = bodyType;
 
       if (block) {
+        protect.reportFinding(block[2]);
         core.protect.throwSecurityException(sourceContext);
       }
     };
@@ -402,6 +414,7 @@ module.exports = Core.makeComponent({
       const block = mergeFindings(sourceContext, unsafeFilenameFindings);
 
       if (block) {
+        core.protect.reportFinding(block[2]);
         core.protect.throwSecurityException(sourceContext);
       }
     };
@@ -423,10 +436,17 @@ module.exports = Core.makeComponent({
               if (!sourceContext.resultsMap[ruleId]) {
                 sourceContext.resultsMap[ruleId] = [];
               }
-              sourceContext.resultsMap[ruleId].push({
-                name,
-                uuid
-              });
+
+              const result = {
+                key: name,
+                inputType: 'UNKNOWN',
+                ruleId: Rule.VIRTUAL_PATCH,
+                value: 'Virtual Patch',
+                blocked: true,
+              };
+              const eventArg = { result, findings: { uuid } };
+
+              protect.reportFinding(eventArg);
               sourceContext.securityException = ['block', ruleId];
               core.protect.throwSecurityException(sourceContext);
             }
@@ -453,7 +473,7 @@ module.exports = Core.makeComponent({
       if (!sourceContext || !ipDenylist.length) return;
 
       const { sourceInfo } = core.scopes.sources.getStore();
-      const match = ipListAnalysis(sourceInfo.Ip, sourceInfo.rawHeaders, ipDenylist);
+      const match = ipListAnalysis(sourceInfo.ip, sourceInfo.rawHeaders, ipDenylist);
 
       if (match) {
         logger.info(match, 'Found a matching IP to an entry in ipDeny list');
@@ -461,10 +481,21 @@ module.exports = Core.makeComponent({
           sourceContext.resultsMap[ruleId] = [];
         }
 
-        sourceContext.resultsMap[ruleId].push({
-          ip: match.matchedIp,
-          uuid: match.uuid,
-        });
+        const eventArg = {
+          result: {
+            key: 'IP Address',
+            inputType: 'UNKNOWN',
+            ruleId: Rule.IP_DENYLIST,
+            value: sourceInfo.ip,
+            blocked: true,
+          },
+          findings: {
+            uuid: match.uuid,
+            ip: match.matchedIp,
+          },
+        };
+        protect.reportFinding(eventArg);
+
         return ['block', 'ip-denylist'];
       }
     };
@@ -481,14 +512,14 @@ module.exports = Core.makeComponent({
             key: 'method',
             value: method,
             blocked: false,
-            exploitMetadata: null,
           };
 
           sourceContext.resultsMap[ruleId] = [result];
 
           if (BLOCKING_MODES.includes(mode)) {
+            result.exploited = true;
             result.blocked = true;
-            return sourceContext.securityException = ['block', ruleId];
+            return sourceContext.securityException = ['block', ruleId, { result }];
           }
         }
       }
@@ -502,24 +533,24 @@ module.exports = Core.makeComponent({
      * @param {Object} sourceContext
      */
     inputAnalysis.handleRequestEnd = function handleRequestEnd(sourceContext) {
-      {
-        // check status code to verify method-tampering exploitation
-        const mtResult = sourceContext.resultsMap[Rule.METHOD_TAMPERING]?.[0];
-        if (mtResult) {
-          const { statusCode } = sourceContext.resData;
-          if (statusCode !== 405 || statusCode !== 501) {
-            mtResult.exploitMetadata = [{ statusCode }];
-          }
+      // check status code to verify method-tampering exploitation
+      const mtResult = sourceContext.resultsMap[Rule.METHOD_TAMPERING]?.[0];
+      if (mtResult) {
+        const { statusCode } = sourceContext.resData;
+        if (statusCode !== 405 || statusCode !== 501) {
+          mtResult.exploited = true;
+          protect.reportFindings({ result: mtResult, finding: { statusCode } });
         }
       }
 
       if (!config.protect.probe_analysis.enable) return;
 
+      const probeReports = [];
+
       // Detecting probes
       const { resultsMap, policy: { rulesMask } } = sourceContext;
       const probesRules = [Rule.CMD_INJECTION, Rule.PATH_TRAVERSAL, Rule.SQL_INJECTION, Rule.XXE];
       const probes = {};
-
       const findingsForScoreRequest = {
         HeaderValue: {},
         ParameterValue: {},
@@ -532,7 +563,7 @@ module.exports = Core.makeComponent({
         resultsByRuleId.forEach(resultByRuleId => {
           const {
             ruleId,
-            exploitMetadata,
+            exploited,
             score,
             value,
             key,
@@ -541,9 +572,10 @@ module.exports = Core.makeComponent({
 
           if (
             !isMonitorMode(ruleId, sourceContext) ||
-            exploitMetadata.length > 0 ||
+            exploited === true || // todo: remove
             score >= 90 ||
-            !probesRules.some((rule) => rule === ruleId)
+            !probesRules.some((rule) => rule === ruleId) ||
+            inputType == InputType.UNKNOWN
           ) {
             return;
           }
@@ -562,9 +594,7 @@ module.exports = Core.makeComponent({
           valueToResultByRuleId[value] = resultByRuleId;
         });
       });
-
       const { ParameterValue, HeaderValue, CookieValue } = findingsForScoreRequest;
-
       const results =
         agentLib.scoreRequestConnect(
           rulesMask,
@@ -579,16 +609,17 @@ module.exports = Core.makeComponent({
         ).resultsList || [];
 
       Object.entries(findingsForScoreAtom).forEach(([value, inputTypes]) => {
-        Object.entries(inputTypes).forEach(([inputType, resultByRuleId]) =>
-          (
-            agentLib.scoreAtom(rulesMask, value, agentLib.InputType[inputType], {
-              preferWorthWatching: false,
-            }) || []
-          ).forEach(result => {
+        Object.entries(inputTypes).forEach(([inputType, resultByRuleId]) => {
+          if (agentLib.InputType[inputType] == null) return;
+          const alibResult = agentLib.scoreAtom(rulesMask, value, agentLib.InputType[inputType], {
+            preferWorthWatching: false,
+          }) || [];
+          alibResult.forEach(result => {
             results.push({ value, ...result });
+            probeReports.push({ value, ...result });
             valueToResultByRuleId[value] = resultByRuleId;
-          })
-        );
+          });
+        });
       });
 
       results
@@ -613,7 +644,12 @@ module.exports = Core.makeComponent({
         }
 
         resultsMap[probe.ruleId].push(probe);
+        probeReports.push(probe);
       });
+
+      for (const result of probeReports) {
+        core.protect.reportFinding({ result });
+      }
     };
 
     /**
@@ -874,11 +910,11 @@ function normalizeFindings(policy, findings) {
     // what additional augmentations are needed?
     // the name/id might need to be mapped but keep the original so it's not lost
     r.mappedId = agentLibRuleTypeToName[r.ruleId] || r.ruleId;
-    // this finding resulted in blocking, i.e., it is not a probe.
-    r.blocked = false;
 
-    // sink analysis will add findings here
-    r.exploitMetadata = [];
+    // if we block this or the value is found in sink, we'll know not to check
+    // this result for probe analysis in handleRequestEnd().
+    r.blocked = false;
+    r.exploited = false;
 
     // apply exclusions here.
     //
@@ -893,7 +929,7 @@ function normalizeFindings(policy, findings) {
     const mode = policy[r.ruleId];
     if (r.score >= 90 && BLOCKING_MODES.includes(mode)) {
       r.blocked = true;
-      findings.securityException = [mode, r.ruleId];
+      findings.securityException = [mode, r.ruleId, { result: r }];
     }
   }
 }

package/lib/input-analysis/install/http.js

@@ -16,13 +16,12 @@
 'use strict';
 
 const onFinished = require('on-finished');
-const { Event, primordials: { StringPrototypeToLowerCase, ArrayPrototypeSlice } } = require('@contrast/common');
+const { primordials: { StringPrototypeToLowerCase, ArrayPrototypeSlice } } = require('@contrast/common');
 const { patchType } = require('../constants');
 
 module.exports = function (core) {
   const {
     logger,
-    messages,
     scopes: { sources },
     instrumentation: { instrument },
     protect: {
@@ -75,8 +74,8 @@ module.exports = function (core) {
 
       onFinished(res, (/* err, req */) => {
         resData.statusCode = res.statusCode;
+        // check for probes and method-tampering outcome
         inputAnalysis.handleRequestEnd(store.protect);
-        messages.emit(Event.PROTECT, store);
       });
 
       const connectInputs = {

package/lib/input-tracing/{handlers/index.js → handlers.js}

@@ -29,6 +29,7 @@ const {
 
 module.exports = function(core) {
   const {
+    protect,
     protect: {
       agentLib,
       inputTracing,
@@ -40,16 +41,21 @@ module.exports = function(core) {
   function handleFindings(sourceContext, sinkContext, ruleId, result, findings) {
     const { stacktraceOpts } = sinkContext;
     captureStacktrace(sinkContext, stacktraceOpts);
-    result.exploitMetadata.push({ sinkContext, findings });
+    result.exploited = true;
 
     const mode = sourceContext.policy[ruleId];
+    const eventArg = { findings, result, sinkContext };
 
+    let blockInfo;
     if (BLOCKING_MODES.includes(mode)) {
       result.blocked = true;
-      const blockInfo = [mode, ruleId];
+      blockInfo = [mode, ruleId, eventArg];
       sourceContext.securityException = blockInfo;
-      throwSecurityException(sourceContext);
     }
+
+    protect.reportFinding(eventArg);
+
+    if (blockInfo) throwSecurityException(sourceContext);
   }
 
   inputTracing.handlePathTraversal = function(sourceContext, sinkContext) {
@@ -61,7 +67,6 @@ module.exports = function(core) {
     for (const result of results) {
       const idx = sinkContext.value.indexOf(result.value);
       const findings = idx !== -1 ? { path: sinkContext.value } : null;
-
       if (findings) {
         handleFindings(sourceContext, sinkContext, ruleId, result, findings);
       }
@@ -218,13 +223,7 @@ module.exports = function(core) {
         }
 
         if (stringFindings) {
-          const nosqlInjectionResult = { ...result, ruleId, mappedId: ruleId };
-
-          // don't modify ssjs-injection result items so use new exploit metadata array here
-          if (nosqlInjectionResult.idsList?.some?.((id) => id.startsWith('SSJS'))) {
-            nosqlInjectionResult.exploitMetadata = [];
-          }
-
+          const nosqlInjectionResult = { ...result, ruleId, mappedId: ruleId, exploited: false };
           const nosqlInjectionResults = sourceContext.resultsMap[ruleId];
           const isAlreadyPresentInNosqlresults = result.idsList &&
             result.idsList.some(
@@ -312,12 +311,13 @@ module.exports = function(core) {
       const findings = idx !== -1 ? { value: sinkContext.value } : null;
 
       if (findings) {
-        result.exploitMetadata.push({ sinkContext, findings });
+        result.exploited = true;
+        handleFindings(sourceContext, sinkContext, ruleId, result, findings);
+        break;
       }
     }
   };
 
-
   return inputTracing;
 };
 

package/lib/semantic-analysis/handlers.js

@@ -44,6 +44,7 @@ const getRuleResults = function(obj, prop) {
 
 module.exports = function(core) {
   const {
+    protect,
     protect: {
       agentLib,
       semanticAnalysis,
@@ -52,27 +53,32 @@ module.exports = function(core) {
     captureStacktrace,
   } = core;
 
-  function handleResult(sourceContext, sinkContext, ruleId, mode, finding) {
+  function handleResult(sourceContext, sinkContext, ruleId, mode, findings) {
     const { value, stacktraceOpts } = sinkContext;
     captureStacktrace(sinkContext, stacktraceOpts);
 
     // shoehorn findings into agent-lib result data model
     const result = {
       blocked: false,
+      inputType: InputType.UNKNOWN,
       ruleId,
       value,
       mappedId: ruleId,
-      exploitMetadata: [{ sinkContext, command: value }],
-      ...finding
+      exploited: true,
     };
+
     getRuleResults(sourceContext.resultsMap, ruleId).push(result);
 
+    let blockInfo;
     if (BLOCKING_MODES.includes(mode)) {
       result.blocked = true;
-      const blockInfo = [mode, ruleId];
+      blockInfo = [mode, ruleId];
       sourceContext.securityException = blockInfo;
-      throwSecurityException(sourceContext);
     }
+
+    protect.reportFinding({ findings, result, sinkContext });
+
+    if (blockInfo) throwSecurityException(sourceContext);
   }
 
   /**
@@ -180,7 +186,7 @@ module.exports = function(core) {
     const finding = findBackdoorInjection(sourceContext, sinkContext.value);
 
     if (finding) {
-      handleResult(sourceContext, sinkContext, Rule.CMD_INJECTION_COMMAND_BACKDOORS, mode, finding);
+      handleResult(sourceContext, sinkContext, Rule.CMD_INJECTION_COMMAND_BACKDOORS, mode);
     }
   };
 
@@ -190,9 +196,7 @@ module.exports = function(core) {
     if (mode == OFF) return;
 
     if (agentLib.isDangerousPath(sinkContext.value, true)) {
-      handleResult(sourceContext, sinkContext, Rule.PATH_TRAVERSAL_SEMANTIC_FILE_SECURITY_BYPASS, mode, {
-        exploitMetadata: [{ sinkContext, path: sinkContext.value }]
-      });
+      handleResult(sourceContext, sinkContext, Rule.PATH_TRAVERSAL_SEMANTIC_FILE_SECURITY_BYPASS, mode);
     }
   };
 
@@ -202,9 +206,7 @@ module.exports = function(core) {
 
     const findings = findExternalEntities(sinkContext.value);
     if (findings.entities.length) {
-      handleResult(sourceContext, sinkContext, Rule.XXE, mode, {
-        exploitMetadata: [{ sinkContext, ...findings }],
-      });
+      handleResult(sourceContext, sinkContext, Rule.XXE, mode, findings);
     }
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/protect",
-  "version": "1.66.0",
+  "version": "1.67.0",
   "description": "Contrast service providing framework-agnostic Protect support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -21,16 +21,16 @@
   },
   "dependencies": {
     "@contrast/agent-lib": "^9.1.0",
-    "@contrast/common": "1.36.0",
-    "@contrast/config": "1.51.0",
-    "@contrast/core": "1.56.0",
-    "@contrast/dep-hooks": "1.25.0",
-    "@contrast/esm-hooks": "2.30.0",
-    "@contrast/instrumentation": "1.35.0",
-    "@contrast/logger": "1.29.0",
-    "@contrast/patcher": "1.28.0",
-    "@contrast/rewriter": "1.32.0",
-    "@contrast/scopes": "1.26.0",
+    "@contrast/common": "1.37.0",
+    "@contrast/config": "1.52.0",
+    "@contrast/core": "1.57.0",
+    "@contrast/dep-hooks": "1.26.0",
+    "@contrast/esm-hooks": "2.31.0",
+    "@contrast/instrumentation": "1.36.0",
+    "@contrast/logger": "1.30.0",
+    "@contrast/patcher": "1.29.0",
+    "@contrast/rewriter": "1.33.0",
+    "@contrast/scopes": "1.27.0",
     "async-hook-domain": "^4.0.1",
     "ipaddr.js": "^2.0.1",
     "on-finished": "^2.4.1",