@contrast/agent 4.2.0

package/lib/protect/service.js

@@ -0,0 +1,556 @@
+/**
+Copyright: 2021 Contrast Security, Inc
+  Contact: support@contrastsecurity.com
+  License: Commercial
+
+  NOTICE: This Software and the patented inventions embodied within may only be
+  used as part of Contrast Security’s commercial offerings. Even though it is
+  made available through public repositories, use of this Software is subject to
+  the applicable End User Licensing Agreement found at
+  https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+  between Contrast Security and the End User. The Software may not be reverse
+  engineered, modified, repackaged, sold, redistributed or otherwise used in a
+  way not consistent with the End User License Agreement.
+*/
+'use strict';
+
+/**
+ * @module lib/rules/protect/service
+ */
+
+const _ = require('lodash');
+
+const { IMPORTANCE, SAFE_HEADER_VALUES, INPUT_TYPES } = require('../constants');
+const agentEmitter = require('../agent-emitter');
+const SampleAggregator = require('./sample-aggregator');
+const RuleFactory = require('./rules/rule-factory');
+const ExclusionFactory = require('../core/exclusions/exclusion-factory.js');
+const { IpAnalyzer } = require('../util/ip-analyzer');
+const logger = require('../core/logger')('contrast:rules:protect:service');
+const headerValidators = require('./validators');
+const UserInputKit = require('../reporter/models/utils/user-input-kit');
+const UserInputFactory = require('../reporter/models/utils/user-input-factory');
+const blockRequest = require('../util/block-request');
+
+class ProtectService {
+  /**
+   * Configures the service to use the provided agent.
+   * @param {Agent} agent
+   */
+  constructor(agent, reporter) {
+    this.reporter = reporter;
+    this.config = agent.config;
+    this.enabled = agent.isInDefendMode();
+    this.assessEnabled = agent.isInAssessMode();
+
+    this._exclusionFactory = new ExclusionFactory({
+      featureSet: agent.tsFeatureSet,
+      protect: this.enabled,
+      assess: this.assessEnabled
+    });
+    this._ruleFactory = new RuleFactory({
+      featureSet: agent.tsFeatureSet,
+      enabled: this.enabled
+    });
+    this.rules = this._ruleFactory.getRules();
+    this.updateIpAllowlist(agent.tsFeatureSet.serverFeatures);
+
+    this.urlExclusions = this._exclusionFactory.getUrlExclusions();
+    this.inputExclusions = this._exclusionFactory.getInputExclusions();
+    this.rules = this._ruleFactory.getRules();
+
+    agentEmitter.on('server-features', (serverFeatures) => {
+      this.enabled = agent.isInDefendMode();
+      this.assessEnabled = agent.isInAssessMode();
+      this.updateRules(serverFeatures);
+      this.updateExclusions(serverFeatures);
+      this.updateIpAllowlist(serverFeatures);
+    });
+
+    agentEmitter.on('application-settings', (applicationSettings) => {
+      this.updateRules(applicationSettings);
+      this.updateExclusions(applicationSettings);
+    });
+  }
+
+  /**
+   * Sends Connection/Header/URI data to SR to perform input analysis.
+   * @param {IncomingMessage} req The current request
+   * @param {ServerResponse} res The current response
+   * @returns {Boolean} Returning `true` allows instrumentation to resume app code
+   */
+  analyzeRequest({ meta, req, res, appContext }) {
+    return this.reporter
+      .sendMessage('request', { incomingMessage: req })
+      .then((agentSettings) => {
+        meta.requestId = _.get(agentSettings, 'protectState.uuid');
+
+        return this.handleAnalysisResponse({
+          asyncStorageContext: meta.asyncStorageContext,
+          appContext,
+          agentSettings,
+          req,
+          res
+        });
+      });
+  }
+
+  /**
+   * Send request data to SR for analysis
+   * @param {Object} meta input analysis request metadata
+   * @param {IncomingMessage} req The current request
+   * @param {ServerResponse} res The current response
+   * @param {Buffer[]} chunks The chunks being handled
+   * @returns {Boolean} Returning `true` allows instrumentation to resume app code
+   */
+  analyzeRequestStream({ meta, req, res, appContext }) {
+    const { requestId, chunks } = meta;
+
+    return this.reporter
+      .sendMessage('request', { requestId, chunks })
+      .then((agentSettings) =>
+        this.handleAnalysisResponse({
+          asyncStorageContext: meta.asyncStorageContext,
+          appContext,
+          agentSettings,
+          req,
+          res
+        })
+      );
+  }
+
+  /**
+   * Independent of the part(s) of the HTTP message being analyzed, there is a
+   * common process for handling the analysis response from S-R.
+   * @param {AgentSettings} agentSettings SR model containing state and results
+   * @param {IncomingMessage} req The current request
+   * @param {ServerResponse} res The current response
+   * @returns {Boolean}
+   */
+  handleAnalysisResponse({
+    asyncStorageContext,
+    appContext,
+    agentSettings,
+    req,
+    res
+  }) {
+    if (_.get(agentSettings, 'protectState.securityException')) {
+      return this.handleBlockAtPerimeter(res);
+    }
+
+    // If we're not blocking, then save results for input tracing.
+    this.collectSamples(
+      asyncStorageContext,
+      _.get(agentSettings, 'inputAnalysis.resultsList'),
+      appContext
+    );
+
+    return true;
+  }
+
+  /**
+   * Block at perimeter when instructed to do so by S-R.
+   * @param {IncomingMessage} req The current request
+   * @param {ServerResponse} res The current response
+   * @returns {Boolean} false which halts executing of original method
+   */
+  handleBlockAtPerimeter(res) {
+    blockRequest(res);
+    // halts further execution of user code
+    return false;
+  }
+
+  /**
+   * When results are returned from S-R, save them to to input tracing.
+   * @param {Object[]} resultsList
+   * @param {ApplicationContext} appContext
+   */
+  collectSamples(asyncStorageContext, resultsList = [], appContext = {}) {
+    if (!resultsList.length) {
+      return;
+    }
+
+    /*
+     * this shouldn't happen as this is retrieved when the request event
+     * is processed, and will be available.
+     */
+    if (!asyncStorageContext) {
+      logger.error(
+        'StorageContext not found - Unable to create samples from results list'
+      );
+      return;
+    }
+
+    const {
+      request,
+      defend: { samples }
+    } = asyncStorageContext;
+
+    if (!appContext.request) {
+      appContext.request = request;
+    }
+
+    for (const {
+      scoreLevel,
+      ruleId,
+      inputType: type,
+      path,
+      key: name,
+      value,
+      idsList
+    } of resultsList) {
+      if (scoreLevel === IMPORTANCE.NONE) {
+        return;
+      }
+
+      const sample = samples.addRuleSample({
+        id: ruleId,
+        input: UserInputFactory.makeOne({ name, path, type, value }),
+        evaluation: { results: { importance: scoreLevel } },
+        appContext
+      });
+      sample.filters.push(...idsList);
+    }
+  }
+
+  updateRules(settings) {
+    if (settings) {
+      this._ruleFactory.updateSettings(settings, this.enabled);
+      this.rules = this._ruleFactory.getRules();
+    }
+  }
+
+  updateExclusions(settings) {
+    if (settings) {
+      this._exclusionFactory.updateSettings({
+        settings,
+        assess: this.assessEnabled,
+        protect: this.protectEnabled
+      });
+      this.urlExclusions = this._exclusionFactory.getUrlExclusions();
+      this.inputExclusions = this._exclusionFactory.getInputExclusions();
+    }
+  }
+
+  /**
+   * Checks if the IP matches the current IP allowlist
+   *
+   * @param {UserInput} ipInput
+   * @return {boolean}
+   */
+  checkIpAllowList(ipEvent) {
+    if (!(this.ipAllowlist && ipEvent)) {
+      return;
+    }
+
+    const inputKit = new UserInputKit();
+    const { data } = ipEvent;
+    // hack; we don't have a proper rule to create the inputs from
+    const inputs = inputKit.create({}, data, ipEvent.type);
+    // length should always just be 1
+    const input = inputs[0];
+    return this.ipAllowlist.evaluate(input);
+  }
+
+  /**
+   * Loads IP analyzer for allowist analysis given TS settings.
+   */
+  updateIpAllowlist(settings) {
+    const list = _.get(settings, 'defend.ipWhitelistsList');
+    if (list && list.length) {
+      this.ipAllowlist = new IpAnalyzer(list);
+      this.ipAllowlist.on('expired', (dtm) => {
+        const dtms = this.ipAllowlist.dtms.filter((item) => item.id !== dtm.id);
+        logger.info(`Defend allowlist item expired: ${dtm.id}.`);
+        this.ipAllowlist = new IpAnalyzer(dtms);
+      });
+    } else {
+      this.ipAllowlist = null;
+    }
+  }
+
+  /**
+   * Loads the rules for context storage based on current url exclusions
+   *
+   * @param {string} path
+   * @param {UserInput} ipInput
+   */
+  getEnabledRules(path, ipEvent) {
+    if (!this.enabled) {
+      return [];
+    }
+
+    if (this.checkIpAllowList(ipEvent)) {
+      return [];
+    }
+
+    return this.rules.filter((rule) => {
+      const { id } = rule;
+
+      for (const exclusion of this.urlExclusions) {
+        if (exclusion.appliesToProtectRule(id) && exclusion.matchesUrl(path)) {
+          return false;
+        }
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Loads the input exclusions for context storage based on current request url
+   *
+   * @param {string} path
+   */
+  getEnabledInputExclusions(path) {
+    if (!this.enabled) {
+      return [];
+    }
+
+    const { inputExclusions } = this;
+
+    return inputExclusions.filter(
+      (exclusion) => exclusion.defend && exclusion.matchesUrl(path)
+    );
+  }
+
+  /**
+   * Dispatches to the appropriate <code>preFilter</code> handler
+   * based on the <code>SourceEvent</code>'s input type.
+   *
+   * @param {SourceEvent} event Source event providing data and context
+   */
+  handleSourceEvent(event, rules, inputExclusions, samples) {
+    if (this.skipEventHandling(rules)) {
+      return;
+    }
+
+    const data = this.filterSafeData(event);
+
+    if (_.isEmpty(data)) {
+      return;
+    }
+
+    const inputKit = new UserInputKit();
+    rules = rules.filter((rule) => rule.appliesToInputType(event.type));
+
+    for (const rule of rules) {
+      const inputs = inputKit.create(rule, data, event.type);
+
+      for (const input of inputs) {
+        if (this.isUserInputExcluded({ inputExclusions, rule, event, input })) {
+          continue;
+        }
+
+        logger.debug(`Starting rule analysis: ${input.type} ${input.name}`);
+        rule.preFilterUserInput(input, event, samples);
+      }
+    }
+  }
+
+  isUserInputExcluded({ inputExclusions, rule, event, input }) {
+    let excluded;
+    for (const exclusion of inputExclusions) {
+      excluded =
+        exclusion.appliesToInputType(event.type) &&
+        exclusion.appliesToProtectRule(rule.id) &&
+        exclusion.matches(input.name);
+
+      if (excluded) {
+        logger.debug(
+          `EXCLUSION: ${exclusion.name} - ${input.type} '${input.name}'`
+        );
+        break;
+      }
+    }
+    return excluded;
+  }
+
+  skipEventHandling(rules) {
+    return _.isEmpty(rules) || !this._ruleFactory.enabled;
+  }
+
+  /**
+   * Given a SinkEvent, will run applicable rule evaluations.
+   * @param {Object} params
+   * @param {SinkEvent} params.event
+   * @param {[Rule]} params.rules
+   * @param {[Samples]} params.samples worthWatching/definite
+   */
+  handleSinkEvent({ event, rules, samples }) {
+    if (this.skipEventHandling(rules)) {
+      return;
+    }
+
+    const { request } = event;
+    for (const rule of rules) {
+      if (!rule.appliesToSink(event.type)) {
+        continue;
+      }
+
+      const applicableSamples = samples.getAll(rule.id);
+      rule.evaluateAtSink({ event, samples, applicableSamples, request });
+    }
+  }
+
+  /**
+   * Filters out data that is "safe" meaning not applicable to any
+   * protect rule evaluations
+   *
+   * Related Ticket: https://contrast.atlassian.net/browse/CONTRAST-35257
+   *
+   * @param {event.type} type This is an INPUT_TYPE
+   * @param {event.data} data Data pertaining to the SourceEvent
+   */
+  filterSafeData({ type, data }) {
+    switch (type) {
+      case INPUT_TYPES.HEADER:
+        return this.filterSafeHeaders(data);
+      default:
+        return data;
+    }
+  }
+
+  /**
+   *
+   * Filters out any headers that either match a list of "safe" values
+   * or match the specification for specific header see ./validators
+   * for info on each header validator
+   *
+   * @param   {Object} data key/value of request headers
+   * @returns {Object} A headers object with safe headers filtered out
+   */
+  filterSafeHeaders(data) {
+    return _.reduce(
+      data,
+      (accum, value, key) => {
+        const headerName = key.toLowerCase();
+
+        if (SAFE_HEADER_VALUES.indexOf(value) !== -1) {
+          return accum;
+        }
+
+        const isSafeHeader = headerValidators[headerName];
+
+        if (typeof isSafeHeader === 'function' && isSafeHeader(value)) {
+          return accum;
+        }
+
+        accum[headerName] = value;
+        return accum;
+      },
+      {}
+    );
+  }
+
+  /**
+   * Samples collected for the current request will be processed.
+   * The security logger will make an entry for each sample collected;
+   *
+   * @param {Array<Rule>} rules
+   * @param {Samples} samples
+   */
+  submitFindings(rules, samples) {
+    const findings = this.createFindings(rules, samples);
+    const aggregated = SampleAggregator.aggregate(findings);
+    for (const finding of aggregated) {
+      agentEmitter.emit('attack', finding);
+    }
+  }
+
+  /**
+   * checks if samples already contain input types of PARAMETER_VALUE or PARAMETER_NAME
+   *
+   * @param {boolean} isEffective
+   * @param {string} inputType
+   * @return {boolean}
+   */
+  static paramInputs(inputType) {
+    return [INPUT_TYPES.PARAMETER_VALUE, INPUT_TYPES.PARAMETER_NAME].includes(
+      inputType
+    );
+  }
+
+  /**
+   * See: https://contrast.atlassian.net/browse/NODE-670
+   * The way we collect findings in SR vs node
+   * input analysis differs.  It may be because of bugs in
+   * node input analysis but since that is going away soon
+   * we have forked how we add findings from SR input analysis
+   * from node agent
+   *
+   * @param {Object} params
+   * @param {Array} findings to report
+   * @param {Set} set of all samples for a given rule
+   * @param {Rule} protect rule object
+   */
+  addSRFindings({ findings, ruleSamples, rule }) {
+    let qsSample = null;
+    let hasEffectiveParamInputs = false;
+
+    for (const sample of ruleSamples) {
+      hasEffectiveParamInputs =
+        hasEffectiveParamInputs ||
+        ProtectService.paramInputs(sample.input.type);
+
+      // saving reference to QUERYSTRING sample in case
+      // there are no Parameter type samples for rule
+      if (sample.input.type === INPUT_TYPES.QUERYSTRING) {
+        qsSample = sample;
+      } else {
+        findings.push({
+          rule,
+          ruleId: rule.id,
+          sample,
+          status: sample.getStatus()
+        });
+      }
+    }
+
+    // https://contrast.atlassian.net/browse/NODE-660 - only report one attack
+    // when there are both QUERYSTRING and PARAMETER_VALUE types for a given rule
+    if (qsSample && !hasEffectiveParamInputs) {
+      findings.push({
+        rule,
+        ruleId: rule.id,
+        sample: qsSample,
+        status: qsSample.getStatus()
+      });
+    }
+  }
+
+  /**
+   * From a set of rules, it creates a collection "findings"
+   * for all samples collected from each rule.
+   *
+   * @param   {Rule[]} rules Rules from which to build findings
+   * @returns {Object[]}     The findings from the rules
+   */
+  createFindings(rules = [], samples) {
+    const findings = [];
+    for (const rule of rules) {
+      const { id } = rule;
+      const ruleSamples = samples.getAll(id);
+
+      if (
+        this.reporter.speedracer &&
+        this.config.agent.node.speedracer_input_analysis
+      ) {
+        this.addSRFindings({ findings, ruleSamples, rule });
+      } else {
+        for (const sample of ruleSamples) {
+          findings.push({
+            rule,
+            ruleId: id,
+            sample,
+            status: sample.getStatus()
+          });
+        }
+      }
+    }
+
+    return findings;
+  }
+}
+
+module.exports = ProtectService;

package/lib/protect/sinks/child-process.js

@@ -0,0 +1,65 @@
+/**
+Copyright: 2021 Contrast Security, Inc
+  Contact: support@contrastsecurity.com
+  License: Commercial
+
+  NOTICE: This Software and the patented inventions embodied within may only be
+  used as part of Contrast Security’s commercial offerings. Even though it is
+  made available through public repositories, use of this Software is subject to
+  the applicable End User Licensing Agreement found at
+  https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+  between Contrast Security and the End User. The Software may not be reverse
+  engineered, modified, repackaged, sold, redistributed or otherwise used in a
+  way not consistent with the End User License Agreement.
+*/
+'use strict';
+
+/**
+ * Hooks for child-process sink
+ * @module lib/hooks/sensors/child-process.js
+ */
+
+const BaseSensor = require('../../hooks/frameworks/base');
+const constants = require('../../constants');
+const patcher = require('../../hooks/patcher');
+const { PATCH_TYPES } = require('../../constants');
+const { emitSinkEvent } = require('../../hooks/frameworks/common');
+
+const { SINK_TYPES } = constants;
+const ID = 'child_process';
+
+class ChildProcessSensor extends BaseSensor {
+  constructor(agent) {
+    super({ id: ID, agent });
+  }
+
+  install({ ModuleHook }) {
+    ModuleHook.resolve({ name: 'child_process' }, (cp) => {
+      patcher.patch(cp, 'execSync', {
+        alwaysRun: true,
+        name: 'child_process',
+        patchType: PATCH_TYPES.PROTECT_SINK,
+        pre: (wrapCtx) => {
+          emitSinkEvent(wrapCtx.args[0], SINK_TYPES.COMMAND, ID);
+          emitSinkEvent(wrapCtx.args[0], SINK_TYPES.FILE_PATH, ID);
+          emitSinkEvent(wrapCtx.args[0], SINK_TYPES.CODE_STRING, ID);
+        }
+      });
+
+      patcher.patch(cp, 'exec', {
+        alwaysRun: true,
+        name: 'child_process',
+        patchType: PATCH_TYPES.PROTECT_SINK,
+        pre: (wrapCtx) => {
+          emitSinkEvent(wrapCtx.args[0], SINK_TYPES.COMMAND, ID);
+          emitSinkEvent(wrapCtx.args[0], SINK_TYPES.FILE_PATH, ID);
+          emitSinkEvent(wrapCtx.args[0], SINK_TYPES.CODE_STRING, ID);
+        }
+      });
+    });
+
+    return this;
+  }
+}
+
+module.exports = ChildProcessSensor;

package/lib/protect/sinks/eval.js

@@ -0,0 +1,57 @@
+/**
+Copyright: 2021 Contrast Security, Inc
+  Contact: support@contrastsecurity.com
+  License: Commercial
+
+  NOTICE: This Software and the patented inventions embodied within may only be
+  used as part of Contrast Security’s commercial offerings. Even though it is
+  made available through public repositories, use of this Software is subject to
+  the applicable End User Licensing Agreement found at
+  https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+  between Contrast Security and the End User. The Software may not be reverse
+  engineered, modified, repackaged, sold, redistributed or otherwise used in a
+  way not consistent with the End User License Agreement.
+*/
+'use strict';
+
+/**
+ * @module lib/rules/protect/in-filters/Object
+ * InFilter hooks for Object methods.
+ */
+
+const _ = require('lodash');
+
+const BaseSensor = require('../../hooks/frameworks/base');
+const constants = require('../../constants');
+const patcher = require('../../hooks/patcher');
+const { PATCH_TYPES } = require('../../constants');
+const { emitSinkEvent } = require('../../hooks/frameworks/common');
+
+const ID = 'eval';
+const { SINK_TYPES } = constants;
+
+class EvalSensor extends BaseSensor {
+  constructor(agent) {
+    super({ id: ID, agent });
+  }
+
+  install() {
+    if (!_.get(global, 'ContrastMethods.__contrastEval')) {
+      throw new Error('Cannot install `eval` sensor - Contrast method DNE.');
+    }
+
+    patcher.patch(global.ContrastMethods, '__contrastEval', {
+      name: 'global.ContrastMethods',
+      patchType: PATCH_TYPES.PROTECT_SINK,
+      alwaysRun: true,
+      pre: (wrapCtx) => {
+        const data = wrapCtx.args[0];
+        emitSinkEvent(data, SINK_TYPES.CODE_STRING, ID);
+      }
+    });
+
+    return this;
+  }
+}
+
+module.exports = EvalSensor;