@contrast/assess 1.1.0 → 1.2.0

package/lib/response-scanning/handlers/utils.js

@@ -0,0 +1,394 @@
+/*
+ * Copyright: 2022 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';
+
+const { join, substring, toLowerCase, split, trim } = require('@contrast/common');
+
+//
+// General HTML utils
+//
+const htmlEscapes = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;'
+};
+const reUnescapedHtml = /[&<>"']/g;
+const reHasUnescapedHtml = RegExp(reUnescapedHtml.source);
+
+function escapeHtml(string) {
+  return (string && reHasUnescapedHtml.test(string))
+    ? string.replace(reUnescapedHtml, (chr) => htmlEscapes[chr])
+    : (string || '');
+}
+
+function getHtmlTagRange(htmlTag, content, offset) {
+  const htmlTagStart = content.indexOf(`<${htmlTag}`, offset);
+  if (htmlTagStart < 0) return [-1, 0];
+
+  const htmlTagEnd = content.indexOf('>', htmlTagStart);
+  return [htmlTagStart, htmlTagEnd - htmlTagStart + 1];
+}
+
+function getElements(htmlTag, content = '') {
+  const elements = [];
+  let offset = 0;
+  let htmlTagRangeStart = -1;
+  let htmlTagRangeLength = 0;
+
+  do {
+    [htmlTagRangeStart, htmlTagRangeLength] = getHtmlTagRange(htmlTag, content, offset);
+    if (htmlTagRangeStart >= 0) {
+      offset = htmlTagRangeStart + htmlTagRangeLength;
+      elements.push(substring(content, htmlTagRangeStart, offset));
+    }
+  } while (htmlTagRangeStart >= 0);
+
+  return elements;
+}
+
+function isHtmlContent(responseHeaders) {
+  if (!responseHeaders) {
+    // this should never happen, but better safe than sorry;
+    // worst case, we parse image data or something
+    return true;
+  }
+
+  // we may want to do a case-insensitive search through object keys here
+  const contentType = toLowerCase(responseHeaders['Content-Type'] || responseHeaders['content-type'] || '');
+
+  return (
+    !contentType ||
+    contentType.includes('text') ||
+    contentType.includes('html')
+  );
+}
+
+function isParseableResponse(responseHeaders) {
+  if (!responseHeaders) {
+    // this should never happen, but better safe than sorry;
+    // worst case, we parse image data or something
+    return true;
+  }
+
+  // we may want to do a case-insensitive search through object keys here
+  let contentType =
+    responseHeaders['Content-Type'] || responseHeaders['content-type'];
+  if (contentType) contentType = toLowerCase(contentType);
+
+  return (
+    !contentType ||
+    contentType.includes('text') ||
+    contentType.includes('html') ||
+    contentType.includes('xml') ||
+    contentType.includes('json') ||
+    contentType.includes('soap') ||
+    contentType.includes('pdf')
+  );
+}
+
+function getAttribute(attribute, htmlTag = '') {
+  let attrStart = htmlTag.indexOf(`${attribute}=`);
+  if (attrStart === -1) return undefined;
+
+  attrStart += attribute.length + 1;
+  const quoteChar = htmlTag[attrStart];
+  if (quoteChar === ' ') return undefined;
+
+  let attrEnd = -1;
+  if (quoteChar === '"' || quoteChar === "'") {
+    attrStart += 1;
+    attrEnd = htmlTag.indexOf(quoteChar, attrStart);
+  } else {
+    // handle unquoted <form method=post >
+    attrEnd = htmlTag.indexOf(' ', attrStart);
+
+    // handle unquoted and last attribute <form method=post>
+    if (attrEnd === -1) {
+      attrEnd = htmlTag[htmlTag.length - 2] === '/' ? htmlTag.length - 2 : htmlTag.length - 1;
+    }
+  }
+
+  return substring(htmlTag, attrStart, attrEnd);
+}
+
+/**
+ * Checks if http-equiv is one of the following
+ * below
+ *
+ * @param {String} httpequiv value of http-equiv meta attr
+ */
+function applicableHttpEquiv(httpequiv) {
+  return (
+    httpequiv == 'cache-control' ||
+    httpequiv == 'pragma' ||
+    httpequiv == 'expires'
+  );
+}
+/**
+ * Checks every meta html tag from body for http-equiv attributes.
+ * If attr exists it will check the content attr if http-equiv is cache-control
+ * Otherwise it will add value of attr if cache-control, pragma or expires
+ */
+function checkMetaTags({ body, cacheControlHeader, instructions }) {
+  const metaTags = getElements('meta', body);
+  metaTags.forEach((tag) => {
+    const httpequiv = getAttribute('http-equiv', tag);
+    if (httpequiv) {
+      const content = getAttribute('content', tag);
+      if (httpequiv == 'cache-control') {
+        const [
+          containsMetaNoCache,
+          containsMetaNoStore
+        ] = checkCacheControlValue(content);
+        if (containsMetaNoCache && containsMetaNoStore) {
+          return;
+        }
+
+        const [containsNoCache, containsNoStore] = checkCacheControlValue(
+          cacheControlHeader
+        );
+
+        // got no-store from headers and no-cache from meta
+        // or no-cache from headers and no-store from meta
+        if (
+          (containsNoStore && containsMetaNoCache) ||
+          (containsNoCache && containsMetaNoStore)
+        ) {
+          return;
+        }
+      }
+
+      // if we make it this far push the values into instructions
+      if (applicableHttpEquiv(httpequiv)) {
+        instructions.push({
+          type: 'META tag',
+          name: httpequiv,
+          value: tag
+        });
+      }
+    }
+  });
+}
+
+
+//
+// Utils regarding Content Security Policy headers rules
+//
+
+/**
+ * Terminology for Content Security Policies
+ * See https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+ *  csp - Content Security Policy
+ *  policy - the entire csp header value
+ *  directive - a specific key of the policy(e.g default-src, media-src)
+ *  sources - the value(s) of the directive(default-src foobar.com;)
+ */
+
+/**
+ * Checks the value of cache-control
+ * either header or meta content attr value
+ * for if it contains no-cache or no-store
+ *
+ * @param {String} value value of cache-control
+ * @return {Array} [no-cache present, no-store present]
+ */
+function checkCacheControlValue(value = '') {
+  if (Array.isArray(value)) {
+    let noCache = false;
+    let noStore = false;
+
+    value.forEach((directive) => {
+      if (toLowerCase(directive).includes('no-cache')) {
+        noCache = true;
+      }
+      if (toLowerCase(directive).includes('no-store')) {
+        noStore = true;
+      }
+    });
+    return [noCache, noStore];
+  } else {
+    value = toLowerCase(value);
+    return [value.includes('no-cache'), value.includes('no-store')];
+  }
+}
+
+/**
+ * Special evaluator for any -src directives
+ * If it is empty and default is secure then it is secure
+ *
+ * @param {Array} sources sources for a given -src directive
+ * @param {Array} defaultSources sources for the default-src directive
+ * @return {Boolean}
+ */
+function isSrcSecure(sources, defaultSources) {
+  return sources.length === 0
+    ? isSourceSecure(defaultSources)
+    : isSourceSecure(sources);
+}
+
+/**
+ * Checks if a given source(s) for a directive is defined and is secure(does not contain a '*')
+ *
+ * @param {Array} sources sources for a given csp directive
+ * @return {Boolean} whether a directive is secure
+ */
+function isSourceSecure(sources) {
+  return (
+    sources.length > 0 &&
+    sources.every((source) => !!source && !/\*/.test(source))
+  );
+}
+
+/**
+ * Evaluator for reflected-xss directive.  Checks if the value is not
+ * equal to 1
+ * Note: If empty it is secure
+ * @param {Array} sources sources for a given csp directive
+ * @return {Boolean} whether a directive is secure
+ */
+function xssCheck(sources) {
+  return sources.every((source) => parseInt(source) === 1);
+}
+
+/**
+ * Evaluator for referrer directive. Checks if value is not *
+ * or contains unsafe-url
+ * @param {Array} sources sources for a given csp directive
+ * @return {Boolean} whether a directive is secure
+ */
+function referrerCheck(sources) {
+  return sources.every((source) => !/unsafe-url|\*/.test(source));
+}
+
+const KNOWN_DIRECTIVES = [
+  { name: 'default-src', camelCasedName: 'defaultSrc', evaluator: isSourceSecure },
+  { name: 'base-uri', camelCasedName: 'baseUri', evaluator: isSourceSecure },
+  { name: 'child-src', camelCasedName: 'childSrc' },
+  { name: 'connect-src', camelCasedName: 'connectSrc' },
+  { name: 'frame-src', camelCasedName: 'frameSrc' },
+  { name: 'media-src', camelCasedName: 'mediaSrc' },
+  { name: 'object-src', camelCasedName: 'objectSrc' },
+  { name: 'script-src', camelCasedName: 'scriptSrc' },
+  { name: 'style-src', camelCasedName: 'styleSrc' },
+  { name: 'form-action', camelCasedName: 'formAction', evaluator: isSourceSecure },
+  { name: 'frame-ancestors', camelCasedName: 'frameAncestors', evaluator: isSourceSecure },
+  { name: 'plugin-types', camelCasedName: 'pluginTypes', evaluator: isSourceSecure },
+  { name: 'reflected-xss', camelCasedName: 'reflectedXss', evaluator: xssCheck },
+  { name: 'referrer', evaluator: referrerCheck }
+];
+
+/**
+ * Convenience method for formatting a given directive's
+ * secure and value properties. It also camel cases the key
+ * to match the spec for the rule's finding
+ *
+ * @param {Object} params
+ * @param {Object} params.data obj to store the full props object
+ * @param {String} params.key the csp header directive
+ * @param {Array} params.value array of sources for the directive
+ * @param {Boolean} params.isSecure flag indicating if directive is secure
+ */
+function formatSource({
+  data,
+  key,
+  sources = [],
+  defaultSources = [],
+  evaluator = isSrcSecure,
+}) {
+  const isSecure = evaluator(sources, defaultSources);
+
+  if (!isSecure && !data.insecure) {
+    data.insecure = true;
+  }
+
+  data[`${key}Secure`] = isSecure;
+  data[`${key}Value`] = join(sources, ' ');
+}
+
+/**
+ * This will take a Content Security Policy string and parse it
+ */
+function policyParser(policy) {
+  const result = {};
+  for (const directive of split(policy, ';')) {
+    const [directiveKey, ...directiveValue] = split(trim(directive), /\s+/g);
+    if (
+      directiveKey &&
+      !Object.prototype.hasOwnProperty.call(result, directiveKey)
+    ) {
+      result[directiveKey] = directiveValue;
+    }
+  }
+  return result;
+}
+
+/**
+ * This will parse a CSP header value into an object
+ * It will then iterate over all known keys and build
+ * which are secure and which aren't with the values
+ * for each. If a directive is undefined, it assumed
+ * insecure and will provide '' as the value
+ *
+ * See: https://contrast.atlassian.net/wiki/spaces/ENG/pages/805503460/Content-Security-Policy+Header+Misconfigured
+ */
+function checkCspSources(policy) {
+  const csp = policyParser(policy);
+  const data = {};
+
+  KNOWN_DIRECTIVES.forEach(({ name, evaluator, camelCasedName }) => {
+    const sources = csp[name];
+    formatSource({
+      data,
+      defaultSources: csp['default-src'],
+      key: camelCasedName || name,
+      sources,
+      evaluator,
+    });
+  });
+
+  return data;
+}
+
+/**
+ * Extracts the Content Security Policy from headers
+ * in one of the CSP_HEADERS constants
+ *
+ * @param {Object} responseHeaders
+ * @return {*} the csp header value or false(if not present)
+ */
+function getCspHeaders(responseHeaders) {
+  const CSP_HEADERS = [
+    'content-security-policy',
+    'x-content-security-policy',
+    'x-webkit-csp'
+  ];
+  const headerName = CSP_HEADERS.filter((header) => responseHeaders[header]);
+  return headerName.length ? responseHeaders[headerName[0]] : false;
+}
+
+module.exports = {
+  escapeHtml,
+  isHtmlContent,
+  getElements,
+  getAttribute,
+  isParseableResponse,
+  checkCacheControlValue,
+  checkMetaTags,
+  getCspHeaders,
+  checkCspSources
+};

package/lib/response-scanning/index.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright: 2022 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';
+
+const { callChildComponentMethodsSync, Event } = require('@contrast/common');
+
+module.exports = function(core) {
+  const { messages } = core;
+  const responseScanning = core.assess.responseScanning = {
+    reportFindings(_sourceContext, vulnerabilityMetadata) {
+      messages.emit(Event.ASSESS_RESPONSE_SCANNING_FINDING, vulnerabilityMetadata);
+    },
+  };
+
+  require('./handlers')(core);
+  require('./install/http')(core);
+
+  responseScanning.install = function() {
+    callChildComponentMethodsSync(responseScanning, 'install');
+  };
+
+  return responseScanning;
+};

package/lib/response-scanning/install/http.js

@@ -0,0 +1,119 @@
+/*
+ * Copyright: 2022 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';
+
+const { split, substring, toLowerCase, trim } = require('@contrast/common');
+
+module.exports = function(core) {
+  const {
+    depHooks,
+    patcher,
+    scopes: { sources },
+    assess: {
+      responseScanning: {
+        handleAutoCompleteMissing,
+        handleCacheControlsMissing,
+        handleClickJackingControlsMissing,
+        handleParameterPollution,
+        handleCspHeader,
+        handleHstsHeaderMissing,
+        handlePoweredByHeader,
+        handleXContentTypeHeaderMissing,
+        handleXxsProtectionHeaderDisabled,
+      }
+    }
+  } = core;
+  const http = core.assess.responseScanning.httpInstrumentation = {};
+
+  function parseHeaders(rawHeaders = '') {
+    const headersArray = split(rawHeaders, '\r\n').filter(Boolean);
+    return headersArray.reduce((acc, header) => {
+      const idx = header.indexOf(':');
+
+      if (idx > -1) {
+        const name = toLowerCase(substring(header, 0, idx));
+        const value = trim(substring(header, idx + 1));
+        const currentValue = acc[name];
+        acc[name] = currentValue
+          ? Array.isArray(currentValue)
+            ? currentValue.push(value) && currentValue
+            : [currentValue, value]
+          : value;
+      }
+
+      return acc;
+    }, {});
+  }
+
+  const patchType = 'response-scanning';
+
+  http.install = function() {
+    depHooks.resolve({ name: 'http' }, (http) => {
+      {
+        const name = 'http.ServerResponse.prototype.write';
+        patcher.patch(http.ServerResponse.prototype, 'write', {
+          name,
+          patchType,
+          post(data) {
+            const sourceContext = sources.getStore()?.assess;
+            if (!sourceContext) return;
+
+            const evaluationContext = {
+              responseBody: toLowerCase(data.args[0] || ''),
+              responseHeaders: parseHeaders(data.result._header),
+            };
+
+            // Check only the rules concerning the response body
+            handleAutoCompleteMissing(sourceContext, evaluationContext);
+            handleCacheControlsMissing(sourceContext, evaluationContext);
+            handleParameterPollution(sourceContext, evaluationContext);
+            handleXxsProtectionHeaderDisabled(sourceContext, evaluationContext);
+          }
+        });
+      }
+      {
+        const name = 'http.ServerResponse.prototype.end';
+        patcher.patch(http.ServerResponse.prototype, 'end', {
+          name,
+          patchType,
+          post(data) {
+            const sourceContext = sources.getStore()?.assess;
+            if (!sourceContext) return;
+
+            const evaluationContext = {
+              responseBody: toLowerCase(data.args[0] || ''),
+              responseHeaders: parseHeaders(data.result._header),
+            };
+
+            // Check all the response scanning rules
+            handleAutoCompleteMissing(sourceContext, evaluationContext);
+            handleCacheControlsMissing(sourceContext, evaluationContext);
+            handleClickJackingControlsMissing(sourceContext, evaluationContext);
+            handleParameterPollution(sourceContext, evaluationContext);
+            handleCspHeader(sourceContext, evaluationContext);
+            handleHstsHeaderMissing(sourceContext, evaluationContext);
+            handlePoweredByHeader(sourceContext, evaluationContext);
+            handleXContentTypeHeaderMissing(sourceContext, evaluationContext);
+            handleXxsProtectionHeaderDisabled(sourceContext, evaluationContext);
+          }
+        });
+      }
+    });
+  };
+
+  return http;
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/assess",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "",
   "main": "lib/index.js",
   "scripts": {
@@ -15,7 +15,7 @@
   "dependencies": {
     "@contrast/distringuish": "^4.1.0",
     "@contrast/scopes": "1.3.0",
-    "@contrast/common": "1.4.0",
+    "@contrast/common": "1.5.0",
     "parseurl": "^1.3.3"
   }
-}
+}