new_audit: csp-xss

.eslintignore

@@ -13,7 +13,7 @@ coverage/**
 
 lighthouse-core/scripts/legacy-javascript/variants
 
-third-party/chromium-webtests
+third-party/**
 
 # ignore d.ts files until we can properly lint them
 *.d.ts

lighthouse-core/audits/csp-xss.js

@@ -0,0 +1,186 @@
+/**
+ * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+const Audit = require('./audit.js');
+const MainResource = require('../computed/main-resource.js');
+const i18n = require('../lib/i18n/i18n.js');
+const {
+  evaluateRawCspForFailures,
+  evaluateRawCspForWarnings,
+  evaluateRawCspForSyntax,
+  getTranslatedDescription,
+} = require('../lib/csp-evaluator.js');
+
+/** @typedef {import('../lib/csp-evaluator.js').Finding} Finding */
+
+const UIStrings = {
+  /** Title of a Lighthouse audit that evaluates the security of a page's CSP. "CSP" stands for "Content Security Policy". "XSS" stands for "Cross Site Scripting". "CSP" and "XSS" do not need to be translated. */
+  title: 'Ensure CSP is effective against XSS attacks',
+  /** Description of a Lighthouse audit that evaluates the security of a page's CSP. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. "CSP" stands for "Content Security Policy". "XSS" stands for "Cross Site Scripting". "CSP" and "XSS" do not need to be translated. */
+  description: 'A strong Content Security Policy (CSP) significantly ' +
+    'reduces the risk of XSS attacks. ' +
+    '[Learn more](https://csp.withgoogle.com/docs/index.html)',
+  /** Summary text for the results of a Lighthouse audit that evaluates the security of a page's CSP. This is displayed if no CSP is being enforced. "CSP" stands for "Content Security Policy". "CSP" does not need to be translated. */
+  noCsp: 'No CSP found in enforcement mode',
+  /** Message shown when one or more CSPs are defined in a <meta> tag. Shown in a table with a list of other CSP bypasses and warnings. "CSP" stands for "Content Security Policy". "CSP" and "HTTP" do not need to be translated. */
+  metaTagMessage: 'The page contains a CSP defined in a <meta> tag. ' +
+    'Consider defining the CSP in an HTTP header if you can.',
+  /** Message shown when a CSP has no syntax errors. Shown in a table with a list of other CSP bypasses and warnings. "CSP" stands for "Content Security Policy". */
+  noSyntaxErrors: 'No syntax errors.',
+  /** Label for a column in a data table; entries will be a directive of a CSP. "CSP" stands for "Content Security Policy". */
+  columnDirective: 'Directive',
+};
+
+const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+class CspXss extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'csp-xss',
+      scoreDisplayMode: Audit.SCORING_MODES.INFORMATIVE,
+      title: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      requiredArtifacts: ['devtoolsLogs', 'MetaElements', 'URL'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<{cspHeaders: string[], cspMetaTags: string[]}>}
+   */
+  static async getRawCsps(artifacts, context) {
+    const devtoolsLog = artifacts.devtoolsLogs[Audit.DEFAULT_PASS];
+    const mainResource = await MainResource.request({devtoolsLog, URL: artifacts.URL}, context);
+
+    const cspMetaTags = artifacts.MetaElements
+      .filter(m => {
+        return m.httpEquiv && m.httpEquiv.toLowerCase() === 'content-security-policy';
+      })
+      .flatMap(m => (m.content || '').split(','))
+      .filter(rawCsp => rawCsp.replace(/\s/g, ''));
+    const cspHeaders = mainResource.responseHeaders
+      .filter(h => {
+        return h.name.toLowerCase() === 'content-security-policy';
+      })
+      .flatMap(h => h.value.split(','))
+      .filter(rawCsp => rawCsp.replace(/\s/g, ''));
+
+    return {cspHeaders, cspMetaTags};
+  }
+
+  /**
+   * @param {Finding} finding
+   * @return {LH.Audit.Details.TableItem}
+   */
+  static findingToTableItem(finding) {
+    return {
+      directive: finding.directive,
+      description: getTranslatedDescription(finding),
+    };
+  }
+
+  /**
+   * @param {string[]} rawCsps
+   * @return {LH.Audit.Details.TableItem[]}
+   */
+  static collectSyntaxResults(rawCsps) {
+    /** @type {LH.Audit.Details.TableItem[]} */
+    const results = [];
+
+    const syntaxFindingsByCsp = evaluateRawCspForSyntax(rawCsps);
+    for (let i = 0; i < rawCsps.length; ++i) {
+      const items = syntaxFindingsByCsp[i].map(this.findingToTableItem);
+      if (!items.length) {
+        items.push({description: str_(UIStrings.noSyntaxErrors)});
+      }
+
+      results.push({
+        description: {
+          type: 'code',
+          value: rawCsps[i],
+        },
+        subItems: {
+          type: 'subitems',
+          items,
+        },
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * @param {string[]} rawCsps
+   * @return {LH.Audit.Details.TableItem[]}
+   */
+  static collectBypassResults(rawCsps) {
+    const findings = evaluateRawCspForFailures(rawCsps);
+    return findings.map(this.findingToTableItem);
+  }
+
+  /**
+   * @param {string[]} rawCsps
+   * @return {LH.Audit.Details.TableItem[]}
+   */
+  static collectWarningResults(rawCsps) {
+    const findings = evaluateRawCspForWarnings(rawCsps);
+    const results = [
+      ...findings.map(this.findingToTableItem),
+    ];
+    return results;
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    const {cspHeaders, cspMetaTags} = await this.getRawCsps(artifacts, context);
+    const rawCsps = [...cspHeaders, ...cspMetaTags];
+    if (!rawCsps.length) {
+      return {
+        score: 0,
+        notApplicable: false,
+        displayValue: str_(UIStrings.noCsp),
+      };
+    }
+
+    // TODO: Add severity icons for bypasses and warnings.
+    const bypasses = this.collectBypassResults(rawCsps);
+    const warnings = this.collectWarningResults(rawCsps);
+    const syntax = this.collectSyntaxResults(rawCsps);
+
+    // Add extra warning for a CSP defined in a meta tag.
+    if (cspMetaTags.length) {
+      warnings.push({description: str_(UIStrings.metaTagMessage), directive: undefined});
+    }
+
+    const results = [...syntax, ...bypasses, ...warnings];
+
+    /** @type {LH.Audit.Details.Table['headings']} */
+    const headings = [
+      /* eslint-disable max-len */
+      {key: 'description', itemType: 'text', subItemsHeading: {key: 'description'}, text: str_(i18n.UIStrings.columnDescription)},
+      {key: 'directive', itemType: 'code', subItemsHeading: {key: 'directive'}, text: str_(UIStrings.columnDirective)},
+      /* eslint-enable max-len */
+    ];
+    const details = Audit.makeTableDetails(headings, results);
+    return {
+      score: bypasses.length ? 0 : 1,
+      notApplicable: false,
+      details,
+    };
+  }
+}
+
+module.exports = CspXss;
+module.exports.UIStrings = UIStrings;

lighthouse-core/config/experimental-config.js

@@ -17,6 +17,7 @@ const config = {
     'autocomplete',
     'large-javascript-libraries',
     'script-treemap-data',
+    'csp-xss',
   ],
   categories: {
     // @ts-ignore: `title` is required in CategoryJson. setting to the same value as the default
@@ -30,6 +31,7 @@ const config = {
     // config is awkward - easier to omit the property here. Will defer to default config.
     'best-practices': {
       auditRefs: [
+        {id: 'csp-xss', weight: 0, group: 'best-practices-trust-safety'},
         {id: 'autocomplete', weight: 0, group: 'best-practices-ux'},
       ],
     },

lighthouse-core/lib/csp-evaluator.js

@@ -0,0 +1,172 @@
+/**
+ * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+/**
+ * @typedef Finding
+ * @property {number} type
+ * @property {string} description
+ * @property {number} severity Severity value 0-100 where 0 is the most severe.
+ * @property {string} directive The directive the finding applies to.
+ * @property {string|undefined} value Keyword if the finding applies to one.
+ */
+
+const log = require('lighthouse-logger');
+const i18n = require('../lib/i18n/i18n.js');
+const {
+  Parser,
+  Type,
+  Directive,
+  evaluateForFailure,
+  evaluateForSyntaxErrors,
+  evaluateForWarnings,
+} = require('../../third-party/csp-evaluator/optimized_binary.js');
+
+const UIStrings = {
+  /** Message shown when a CSP does not have a base-uri directive. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "base-uri", "'none'", and "'self'" do not need to be translated. */
+  missingBaseUri: 'Missing base-uri allows the injection of <base> tags. ' +
+    'They can be used to set the base URL for all relative (script) ' +
+    'URLs to an attacker controlled domain. ' +
+    'Can you set it to \'none\' or \'self\'?',
+  /** Message shown when a CSP does not have a script-src directive. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "script-src" does not need to be translated. */
+  missingScriptSrc: 'script-src directive is missing. ' +
+    'This can allow the execution of unsafe scripts.',
+  /** Message shown when a CSP does not have a script-src directive. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "object-src" and "'none'" do not need to be translated. */
+  missingObjectSrc: 'Elements controlled by object-src are considered legacy features. ' +
+    'Consider setting object-src to \'none\' to prevent the injection of ' +
+    'plugins that execute unsafe scripts.',
+  /** Message shown when a CSP uses a domain allowlist to filter out malicious scripts. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "CSP", "'strict-dynamic'", "nonces", and "hashes" do not need to be translated. "allowlists" can be interpreted as "whitelist". */
+  strictDynamic: 'Host allowlists can frequently be bypassed. Consider using ' +
+    '\'strict-dynamic\' in combination with CSP nonces or hashes.',
+  /** Message shown when a CSP allows inline scripts to be run in the page. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "CSP", "'unsafe-inline'", "nonces", and "hashes" do not need to be translated. */
+  unsafeInline: '\'unsafe-inline\' allows the execution of unsafe in-page scripts ' +
+    'and event handlers. Consider using CSP nonces or hashes to allow scripts individually.',
+  /** Message shown when a CSP is not backwards compatible with browsers that do not support CSP nonces/hashes. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "'unsafe-inline'", "nonces", and "hashes" do not need to be translated. */
+  unsafeInlineFallback: 'Consider adding \'unsafe-inline\' (ignored by browsers supporting ' +
+    'nonces/hashes) to be backward compatible with older browsers.',
+  /** Message shown when a CSP is not backwards compatible with browsers that do not support the 'strict-dynamic' keyword. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "http:", "https:", and "'strict-dynamic'" do not need to be translated. */
+  allowlistFallback: 'Consider adding https: and http: URL schemes (ignored by browsers ' +
+    'supporting \'strict-dynamic\') to be backward compatible with older browsers.',
+  /** Message shown when a CSP only provides a reporting destination through the report-to directive. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "report-to", "report-uri", and "Chromium" do not need to be translated. */
+  reportToOnly: 'The reporting destination is only configured via the report-to directive. ' +
+    'This directive is only supported in Chromium-based browsers so it is ' +
+    'recommended to also use a report-uri directive.',
+  /** Message shown when a CSP does not provide a reporting destination. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "CSP" does not need to be translated. */
+  reportingDestinationMissing: 'No CSP configures a reporting destination. ' +
+    'This makes it difficult to maintain the CSP over time and monitor for any breakages.',
+  /** Message shown when a CSP nonce has less than 8 characters. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "Nonces" does not need to be translated. */
+  nonceLength: 'Nonces should be at least 8 characters long.',
+  /** Message shown when a CSP nonce does not use teh base64 charset. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "Nonces" and "base84" do not need to be translated. "charset" can be interpreted as "a set of characters". */
+  nonceCharset: 'Nonces should use the base64 charset.',
+  /**
+   * @description Message shown when a CSP is missing a semicolon. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy".
+   * @example {'object-src'} keyword
+   */
+  missingSemicolon: 'Did you forget the semicolon? ' +
+    '{keyword} seems to be a directive, not a keyword.',
+  /** Message shown when a CSP contains an unknown keyword. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "CSP" does not need to be translated. */
+  unknownDirective: 'Unknown CSP directive.',
+  /**
+   * @description Message shown when a CSP contains an invalid keyword. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy".
+   * @example {'invalid-keyword'} keyword
+   */
+  unknownKeyword: '{keyword} seems to be an invalid keyword.',
+  /** Message shown when a CSP uses the deprecated reflected-xss directive. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "reflected-xss", "CSP2" and "X-XSS-Protection" do not need to be translated. */
+  deprecatedReflectedXSS: 'reflected-xss is deprecated since CSP2. ' +
+    'Please, use the X-XSS-Protection header instead.',
+  /** Message shown when a CSP uses the deprecated referrer directive. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "referrer", "CSP2" and "Referrer-Policy" do not need to be translated. */
+  deprecatedReferrer: 'referrer is deprecated since CSP2. ' +
+    'Please, use the Referrer-Policy header instead.',
+  /** Message shown when a CSP uses the deprecated disown-opener directive. Shown in a table with a list of other CSP vulnerabilities and suggestions. "CSP" stands for "Content Security Policy". "disown-opener", "CSP3" and "Cross-Origin-Opener-Policy" do not need to be translated. */
+  deprecatedDisownOpener: 'disown-opener is deprecated since CSP3. ' +
+    'Please, use the Cross-Origin-Opener-Policy header instead.',
+};
+
+const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+/** @type {Record<number, string|LH.IcuMessage|Record<string, LH.IcuMessage>>} */
+const FINDING_TO_UI_STRING = {
+  [Type.MISSING_SEMICOLON]: UIStrings.missingSemicolon,
+  [Type.UNKNOWN_DIRECTIVE]: str_(UIStrings.unknownDirective),
+  [Type.INVALID_KEYWORD]: UIStrings.unknownKeyword,
+  [Type.MISSING_DIRECTIVES]: {
+    [Directive.BASE_URI]: str_(UIStrings.missingBaseUri),
+    [Directive.SCRIPT_SRC]: str_(UIStrings.missingScriptSrc),
+    [Directive.OBJECT_SRC]: str_(UIStrings.missingObjectSrc),
+  },
+  [Type.SCRIPT_UNSAFE_INLINE]: str_(UIStrings.unsafeInline),
+  [Type.NONCE_LENGTH]: str_(UIStrings.nonceLength),
+  [Type.NONCE_CHARSET]: str_(UIStrings.nonceCharset),
+  [Type.DEPRECATED_DIRECTIVE]: {
+    [Directive.REFLECTED_XSS]: str_(UIStrings.deprecatedReflectedXSS),
+    [Directive.REFERRER]: str_(UIStrings.deprecatedReferrer),
+    [Directive.DISOWN_OPENER]: str_(UIStrings.deprecatedDisownOpener),
+  },
+  [Type.STRICT_DYNAMIC]: str_(UIStrings.strictDynamic),
+  [Type.UNSAFE_INLINE_FALLBACK]: str_(UIStrings.unsafeInlineFallback),
+  [Type.ALLOWLIST_FALLBACK]: str_(UIStrings.allowlistFallback),
+  [Type.REPORTING_DESTINATION_MISSING]: str_(UIStrings.reportingDestinationMissing),
+  [Type.REPORT_TO_ONLY]: str_(UIStrings.reportToOnly),
+};
+
+/**
+ * @param {Finding} finding
+ * @return {LH.IcuMessage|string}
+ */
+function getTranslatedDescription(finding) {
+  let result = FINDING_TO_UI_STRING[finding.type];
+  if (!result) {
+    log.warn('CSP Evaluator', `No translation found for description: ${finding.description}`);
+    return finding.description;
+  }
+
+  // Return if translated result found.
+  if (i18n.isIcuMessage(result)) return result;
+
+  // If result was not translated, that means `finding.value` is included in the UI string.
+  if (typeof result === 'string') return str_(result, {keyword: finding.value || ''});
+
+  // Result is a record object, UI string depends on the directive.
+  result = result[finding.directive];
+  if (!result) {
+    log.warn('CSP Evaluator', `No translation found for description: ${finding.description}`);
+    return finding.description;
+  }
+
+  return result;
+}
+
+/**
+ * @param {string[]} rawCsps
+ * @return {Finding[]}
+ */
+function evaluateRawCspForFailures(rawCsps) {
+  return evaluateForFailure(rawCsps.map(c => new Parser(c).csp));
+}
+
+/**
+ * @param {string[]} rawCsps
+ * @return {Finding[]}
+ */
+function evaluateRawCspForWarnings(rawCsps) {
+  return evaluateForWarnings(rawCsps.map(c => new Parser(c).csp));
+}
+
+/**
+ * @param {string[]} rawCsps
+ * @return {Finding[][]} Entries are a list of findings corresponding to the CSP at the same index in `rawCsps`.
+ */
+function evaluateRawCspForSyntax(rawCsps) {
+  return evaluateForSyntaxErrors(rawCsps.map(c => new Parser(c).csp));
+}
+
+module.exports = {
+  evaluateRawCspForFailures,
+  evaluateRawCspForWarnings,
+  evaluateRawCspForSyntax,
+  getTranslatedDescription,
+  UIStrings,
+};