serverless-openapi-documenter/src/owasp.js

Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config

"use strict";

const https = require("https");

const defaultOWASP = require("../json/owasp.json");

/**
 * @typedef {Object} Header
 * @property {string} name - The name of the header
 * @property {string} value - The default value of the header
 */

/**
 * @typedef {Object} OWASPHeaders
 * @property {string} last_update_utc - When the headers were last updated in UTC
 * @property {Array.<Header>} headers - An array of headers
 */

class OWASP {
  constructor() {
    this.DEFAULT_OWASP_HEADERS = {
      "Cache-Control": {
        description:
          "The Cache-Control HTTP header field holds directives (instructions) — in both requests and responses — that control [caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) in browsers and shared caches (e.g. Proxies, CDNs). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)",
      },
      "Clear-Site-Data": {
        description:
          "The Clear-Site-Data header clears browsing data (cookies, storage, cache) associated with the requesting website. It allows web developers to have more control over the data stored by a client browser for their origins. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Clear-Site-Data)",
      },
      "Content-Security-Policy": {
        description:
          "The HTTP Content-Security-Policy response header allows website administrators to control resources the user agent is allowed to load for a given page. With a few exceptions, policies mostly involve specifying server origins and script endpoints. This helps guard against cross-site scripting attacks ([Cross-site scripting](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting)). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)",
      },
      "Cross-Origin-Embedder-Policy": {
        description:
          "The HTTP Cross-Origin-Embedder-Policy (COEP) response header configures embedding cross-origin resources into the document. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy)",
      },
      "Cross-Origin-Opener-Policy": {
        description:
          "The HTTP Cross-Origin-Opener-Policy (COOP) response header allows you to ensure a top-level document does not share a browsing context group with cross-origin documents. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy)",
      },
      "Cross-Origin-Resource-Policy": {
        description:
          "Cross-Origin Resource Policy is a policy set by the Cross-Origin-Resource-Policy HTTP header that lets websites and applications opt in to protection against certain requests from other origins (such as those issued with elements like <script> and <img>), to mitigate speculative side-channel attacks, like Spectre, as well as Cross-Site Script Inclusion attacks. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy)",
      },
      "Permissions-Policy": {
        description:
          "The HTTP Permissions-Policy header provides a mechanism to allow and deny the use of browser features in a document or within any [<iframe>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) elements in the document. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy)",
      },
      "Referrer-Policy": {
        description:
          "The Referrer-Policy [HTTP header](https://developer.mozilla.org/en-US/docs/Glossary/HTTP_header) controls how much [referrer information](https://developer.mozilla.org/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns) (sent with the [Referer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header) should be included with requests. Aside from the HTTP header, you can [set this policy in HTML](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy#integration_with_html). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)",
      },
      "Strict-Transport-Security": {
        description:
          "The HTTP Strict-Transport-Security response header (often abbreviated as [HSTS](https://developer.mozilla.org/en-US/docs/Glossary/HSTS)) informs browsers that the site should only be accessed using HTTPS, and that any future attempts to access it using HTTP should automatically be converted to HTTPS. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)",
      },
      "X-Content-Type-Options": {
        description:
          "The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) advertised in the [Content-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) headers should be followed and not be changed. The header allows you to avoid [MIME type sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) by saying that the MIME types are deliberately configured. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options)",
      },
      "X-Frame-Options": {
        description:
          "The X-Frame-Options [HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) response header can be used to indicate whether or not a browser should be allowed to render a page in a [<frame>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame), [<iframe>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe), [<embed>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed) or [<object>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object). Sites can use this to avoid [click-jacking](https://developer.mozilla.org/en-US/docs/Web/Security/Types_of_attacks#click-jacking) attacks, by ensuring that their content is not embedded into other sites. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options)",
      },
      "X-Permitted-Cross-Domain-Policies": {
        description:
          "A cross-domain policy file is an XML document that grants a web client, such as Adobe Flash Player or Adobe Acrobat (though not necessarily limited to these), permission to handle data across domains. When clients request content hosted on a particular source domain and that content makes requests directed towards a domain other than its own, the remote domain needs to host a cross-domain policy file that grants access to the source domain, allowing the client to continue the transaction. Normally a meta-policy is declared in the master policy file, but for those who can't write to the root directory, they can also declare a meta-policy using the X-Permitted-Cross-Domain-Policies HTTP response header. - [OWASP Link](https://owasp.org/www-project-secure-headers/#x-permitted-cross-domain-policies)",
      },
      "X-DNS-Prefetch-Control": {
        description:
          "The HTTP X-DNS-Prefetch-Control response header controls DNS prefetching, a feature by which browsers proactively perform domain name resolution on links that the user may choose to follow as well as URLs for items referenced by the document, including images, CSS, JavaScript, and so forth. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-DNS-Prefetch-Control)",
      },
    };

    this.headerMap = {
      cacheControl: "Cache-Control",
      clearSiteData: "Clear-Site-Data",
      contentSecurityPolicy: "Content-Security-Policy",
      crossOriginEmbedderPolicy: "Cross-Origin-Embedder-Policy",
      crossOriginOpenerPolicy: "Cross-Origin-Opener-Policy",
      crossOriginResourcePolicy: "Cross-Origin-Resource-Policy",
      permissionsPolicy: "Permissions-Policy",
      pragma: "Pragma",
      referrerPolicy: "Referrer-Policy",
      strictTransportSecurity: "Strict-Transport-Security",
      xContentTypeOptions: "X-Content-Type-Options",
      xFrameOptions: "X-Frame-Options",
      xPermittedCrossDomainPolicies: "X-Permitted-Cross-Domain-Policies",
      xDNSPrefetchControl: "X-DNS-Prefetch-Control",
    };
  }

  async getLatest() {
    const headerJSON = await new Promise((resolve, reject) => {
      const req = https
        .get(
          "https://owasp.org/www-project-secure-headers/ci/headers_add.json",
          (res) => {
            let data = [];

            if (res.statusCode !== 200) {
              resolve(defaultOWASP);
            }

            res.on("error", (err) => {
              resolve(defaultOWASP);
            });

            res.on("data", (chunk) => {
              data.push(chunk);
            });

            res.on("end", () => {
              resolve(JSON.parse(Buffer.concat(data).toString()));
            });
          }
        )
        .on("error", (err) => {
          resolve(defaultOWASP);
        });

      req.end();
    });

    this.populateDefaults(headerJSON);
  }

  /**
   * @funtion populateDefaults
   * @param {OWASPHeaders} headerJSON
   */
  populateDefaults(headerJSON) {
    for (const header of headerJSON.headers) {
      const headerObj = {
        schema: {
          type: "string",
          default: header.value,
          example: header.value,
        },
      };

      if (this.DEFAULT_OWASP_HEADERS?.[header.name]) {
        Object.assign(this.DEFAULT_OWASP_HEADERS[header.name], headerObj);
      } else {
        Object.assign(this.DEFAULT_OWASP_HEADERS, {
          [header.name]: headerObj,
        });
      }
    }
  }

  getHeaders(headerList) {
    const obj = {};
    for (const headerName of Object.keys(headerList)) {
      if (headerName === "pragma") {
        const pragma = {
          Pragma: {
            description:
              "The Pragma HTTP/1.0 general header is an implementation-specific header that may have various effects along the request-response chain. This header serves for backwards compatibility with the HTTP/1.0 caches that do not have a [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) HTTP/1.1 header. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Pragma)",
            deprecated: true,
          },
        };

        if (typeof headerList["pragma"] !== "boolean") {
          Object.assign(pragma["Pragma"], {
            schema: {
              type: "string",
              default: headerList["pragma"].value,
              example: headerList["pragma"].value,
            },
          });
        } else {
          Object.assign(pragma["Pragma"], {
            schema: {
              default: "no-cache",
              type: "string",
              example: "no-cache",
            },
          });
        }

        Object.assign(obj, pragma);
      } else {
        const defaultHeader =
          this.DEFAULT_OWASP_HEADERS[this.headerMap[headerName]];

        Object.assign(obj, { [this.headerMap[headerName]]: defaultHeader });

        if (typeof headerList[headerName] !== "boolean") {
          obj[this.headerMap[headerName]].schema.default =
            headerList[headerName].value;
        }
      }
    }

    return obj;
  }
}

module.exports = new OWASP();