oshp-suite.mjs

Functions

Imports

It imports no other module of this repo. Imported by index.mjs.

Source

1/**
2 * Runs OWASP's own header test suite against a response, with no network and no venom.
3 *
4 * The suite is the OWASP Secure Headers Project's validator (oshp-tests-suite.yml, read verbatim by update-owasp.mjs
5 * from subprojects/validator/tests_suite.yml). It is a venom test plan: each test case GETs the target and asserts on
6 * `result.statuscode` and `result.headers.<Name>`. Venom is a Go binary that needs a live URL; this runs the same
7 * assertions on the headers a site's code would send, so CI proves a policy before it is deployed. Only the operators
8 * the suite uses are implemented, and any other one throws, so a changed suite fails loudly instead of passing quietly.
9 *
10 * The suite is the oracle for OSHP's recommendation, and OSHP's recommendation includes headers this package
11 * deliberately does not send everywhere (OWASP_SKIPPED), so a run is expected to fail exactly those test cases.
12 * Pass the YAML already parsed (a plain object), so this module needs no YAML parser.
13 */
14
15/** @typedef {{ status: number, headers: Headers }} SuiteResponse */
16
17/** @param {string} text the assertion's argument text @returns {string[]} */
18function argumentsOf(text) {
19  return [...text.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3] ?? "");
20}
21
22/**
23 * @param {string} assertion e.g. `result.headers.X-Frame-Options ShouldBeIn "deny" "DENY"`
24 * @param {SuiteResponse} response
25 * @returns {boolean}
26 */
27function holds(assertion, response) {
28  const match = /^(result\.statuscode|result\.headers\.[A-Za-z0-9-]+)\s+(Should[A-Za-z]+)\s*(.*)$/.exec(assertion.trim());
29  if (!match) throw new Error(`unsupported assertion: ${assertion}`);
30  const [, subject = "", operator = "", rest = ""] = match;
31  const value =
32    subject === "result.statuscode" ? String(response.status) : (response.headers.get(subject.slice("result.headers.".length)) ?? null);
33  const args = argumentsOf(rest);
34  switch (operator) {
35    case "ShouldEqual":
36      return value !== null && value === args[0];
37    case "ShouldNotBeNil":
38      return value !== null;
39    case "ShouldBeNil":
40      return value === null;
41    case "ShouldBeIn":
42      return value !== null && args.includes(value);
43    case "ShouldContainSubstring":
44      return value !== null && value.includes(args[0] ?? "");
45    case "ShouldNotContainSubstring":
46      return value !== null && !value.includes(args[0] ?? "");
47    default:
48      throw new Error(`unsupported operator ${operator} in: ${assertion}`);
49  }
50}
51
52/** @param {unknown} assertion @param {SuiteResponse} response @returns {boolean} */
53function holdsAny(assertion, response) {
54  if (typeof assertion === "string") return holds(assertion, response);
55  if (assertion && typeof assertion === "object" && Array.isArray(/** @type {any} */ (assertion).or)) {
56    return /** @type {any} */ (assertion).or.some((/** @type {unknown} */ a) => holdsAny(a, response));
57  }
58  throw new Error(`unsupported assertion shape: ${JSON.stringify(assertion)}`);
59}
60
61/**
62 * Runs every test case of the suite.
63 *
64 * @param {{ testcases: Array<{ name: string, steps: Array<{ url?: string, assertions?: unknown[] }> }> }} suite the parsed suite
65 * @param {{ page: SuiteResponse, logout?: SuiteResponse }} responses the page the suite calls `target_site`, and the
66 *   logout response it calls `target_site/logout_url` (cases that need it fail when none is given)
67 * @returns {Array<{ name: string, pass: boolean, failed: string[] }>}
68 */
69export function runOshpSuite(suite, responses) {
70  if (!Array.isArray(suite?.testcases) || suite.testcases.length === 0) throw new Error("the suite has no test cases");
71  return suite.testcases.map((testcase) => {
72    /** @type {string[]} */
73    const failed = [];
74    for (const step of testcase.steps) {
75      const response = String(step.url ?? "").includes("logout_url") ? responses.logout : responses.page;
76      for (const assertion of step.assertions ?? []) {
77        if (!response) {
78          failed.push(typeof assertion === "string" ? assertion : JSON.stringify(assertion));
79        } else if (!holdsAny(assertion, response)) {
80          failed.push(typeof assertion === "string" ? assertion : JSON.stringify(assertion));
81        }
82      }
83    }
84    return { name: testcase.name, pass: failed.length === 0, failed };
85  });
86}