serverless-openapi-documenter 0.0.107 → 0.0.109

package/README.md

@@ -928,7 +928,7 @@ The generator will interpret your settings for CORS and automatically add the re
 
 You can make use of the [OWASP Secure Headers](https://owasp.org/www-project-secure-headers/#x-permitted-cross-domain-policies) to generate response headers. These are a selection of response headers with default values that OWASP recommends returning with your response to help secure your application.
 
-The OWASP Secure Headers Project contains a set of recommended headers to return with recommended values, when generating the documentation, the generator will attempt to get the latest version of this document and apply the latest recommendations. If you do not allow outside connections, it will default to a version of recommendations from **2023-05-26 12:22:30 UTC**.
+The OWASP Secure Headers Project contains a set of recommended headers to return with recommended values, when generating the documentation, the generator will attempt to get the latest version of this document and apply the latest recommendations. If you do not allow outside connections, it will default to a version of recommendations from **2024-09-19 21:29:28 UTC**.
 
 Like CORS, if you have already set any of the OWASP Secure headers via `responseHeaders`, it will not overwrite them.
 
@@ -973,13 +973,14 @@ The full list of OWASP Secure Headers you can set are:
 - 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
 
+You should note that `Pragma` has been [deprecated by owasp](https://owasp.org/www-project-secure-headers/#pragma), this plugin will issue a warning when you are still using Pragma and might drop support.
+
 ###### Subset of OWASP Secure Headers with user defined values
 
 If you wish to override the OWASP Secure Headers, you can write your `methodResponse` like:

package/json/owasp.json

@@ -1,57 +1,53 @@
 {
-    "last_update_utc": "2023-05-26 12:22:30",
-    "headers": [
-      {
-        "name": "Cache-Control",
-        "value": "no-store, max-age=0"
-      },
-      {
-        "name": "Clear-Site-Data",
-        "value": "\"cache\",\"cookies\",\"storage\""
-      },
-      {
-        "name": "Content-Security-Policy",
-        "value": "default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
-      },
-      {
-        "name": "Cross-Origin-Embedder-Policy",
-        "value": "require-corp"
-      },
-      {
-        "name": "Cross-Origin-Opener-Policy",
-        "value": "same-origin"
-      },
-      {
-        "name": "Cross-Origin-Resource-Policy",
-        "value": "same-origin"
-      },
-      {
-        "name": "Permissions-Policy",
-        "value": "accelerometer=(),ambient-light-sensor=(),autoplay=(),battery=(),camera=(),display-capture=(),document-domain=(),encrypted-media=(),fullscreen=(),gamepad=(),geolocation=(),gyroscope=(),layout-animations=(self),legacy-image-formats=(self),magnetometer=(),microphone=(),midi=(),oversized-images=(self),payment=(),picture-in-picture=(),publickey-credentials-get=(),speaker-selection=(),sync-xhr=(self),unoptimized-images=(self),unsized-media=(self),usb=(),screen-wake-lock=(),web-share=(),xr-spatial-tracking=()"
-      },
-      {
-        "name": "Pragma",
-        "value": "no-cache"
-      },
-      {
-        "name": "Referrer-Policy",
-        "value": "no-referrer"
-      },
-      {
-        "name": "Strict-Transport-Security",
-        "value": "max-age=31536000 ; includeSubDomains"
-      },
-      {
-        "name": "X-Content-Type-Options",
-        "value": "nosniff"
-      },
-      {
-        "name": "X-Frame-Options",
-        "value": "deny"
-      },
-      {
-        "name": "X-Permitted-Cross-Domain-Policies",
-        "value": "none"
-      }
-    ]
-  }
+  "last_update_utc": "2024-09-19 21:29:28",
+  "headers": [
+    {
+      "name": "Cache-Control",
+      "value": "no-store, max-age=0"
+    },
+    {
+      "name": "Clear-Site-Data",
+      "value": "\"cache\",\"cookies\",\"storage\""
+    },
+    {
+      "name": "Content-Security-Policy",
+      "value": "default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
+    },
+    {
+      "name": "Cross-Origin-Embedder-Policy",
+      "value": "require-corp"
+    },
+    {
+      "name": "Cross-Origin-Opener-Policy",
+      "value": "same-origin"
+    },
+    {
+      "name": "Cross-Origin-Resource-Policy",
+      "value": "same-origin"
+    },
+    {
+      "name": "Permissions-Policy",
+      "value": "accelerometer=(), autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(), hid=(), idle-detection=(), interest-cohort=(), serial=(), unload=()"
+    },
+    {
+      "name": "Referrer-Policy",
+      "value": "no-referrer"
+    },
+    {
+      "name": "Strict-Transport-Security",
+      "value": "max-age=31536000; includeSubDomains"
+    },
+    {
+      "name": "X-Content-Type-Options",
+      "value": "nosniff"
+    },
+    {
+      "name": "X-Frame-Options",
+      "value": "deny"
+    },
+    {
+      "name": "X-Permitted-Cross-Domain-Policies",
+      "value": "none"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.107",
+  "version": "0.0.109",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -27,7 +27,8 @@
     "Api Gateway",
     "APIGateway",
     "AWSAPIGateway",
-    "Serverless OpenAPI"
+    "Serverless OpenAPI",
+    "serverless openapi"
   ],
   "scripts": {
     "test": "mocha --config './test/.mocharc.js'"

package/src/definitionGenerator.js

@@ -15,7 +15,9 @@ const SchemaHandler = require("./schemaHandler");
 const oWASP = require("./owasp");
 
 class DefinitionGenerator {
-  constructor(serverless, options = {}) {
+  constructor(serverless, logger) {
+    this.logger = logger;
+
     this.version =
       serverless?.processedInput?.options?.openApiVersion || "3.0.0";
 
@@ -70,6 +72,12 @@ class DefinitionGenerator {
     };
 
     try {
+      this.logger.verbose(
+        `Trying to resolve Redocly rules from: ${path.resolve(
+          "options",
+          "redocly.json"
+        )}`
+      );
       this.REDOCLY_RULES = require(path.resolve("options", "redocly.json"));
     } catch (err) {
       this.REDOCLY_RULES = {
@@ -83,6 +91,12 @@ class DefinitionGenerator {
     }
 
     try {
+      this.logger.verbose(
+        `Trying to resolve Ref-Parser options from: ${path.resolve(
+          "options",
+          "ref-parser.js"
+        )}`
+      );
       this.refParserOptions = require(path.resolve("options", "ref-parser.js"));
     } catch (err) {
       this.refParserOptions = {};
@@ -539,6 +553,12 @@ class DefinitionGenerator {
             throw err;
           });
         } else {
+          if (Object.keys(response.owasp).includes("pragma")) {
+            this.logger.warn(
+              "Pragma has been deprecated by owasp (https://owasp.org/www-project-secure-headers/#pragma) and support for defaults will be dropped by this plugin."
+            );
+          }
+
           owaspHeaders = await this.createResponseHeaders(
             oWASP.getHeaders(response.owasp)
           ).catch((err) => {
@@ -589,7 +609,7 @@ class DefinitionGenerator {
       ).catch((err) => {
         throw err;
       });
-    } else if (this.currentEvent.cors) {
+    } else if (this.currentEvent?.cors) {
       const newHeaders = {};
       for (const key of Object.keys(this.DEFAULT_CORS_HEADERS)) {
         if (

package/src/logger.js

@@ -0,0 +1,74 @@
+"use strict";
+
+class Logger {
+  constructor(serverless, log) {
+    this.serverless = serverless;
+    this.logOutput = log;
+
+    this.logTypes = {
+      NOTICE: "notice",
+      DEBUG: "debug",
+      ERROR: "error",
+      WARNING: "warning",
+      INFO: "info",
+      VERBOSE: "verbose",
+      SUCCESS: "success",
+    };
+
+    this.defaultLog = this.logTypes.NOTICE;
+  }
+
+  log(str, type = this.defaultLog) {
+    switch (this.serverless.version[0]) {
+      case "2":
+        let colouredString = str;
+        if (type === "error") {
+          colouredString = chalk.bold.red(`✖ ${str}`);
+        } else if (type === "success") {
+          colouredString = chalk.bold.green(`✓ ${str}`);
+        }
+
+        this.serverless.cli.log(colouredString);
+        break;
+
+      case "4":
+      case "3":
+        this.logOutput[type](str);
+        break;
+
+      default:
+        process.stdout.write(str.join(" "));
+        break;
+    }
+  }
+
+  debug(str) {
+    this.log(str, this.logTypes.DEBUG);
+  }
+
+  error(str) {
+    this.log(str, this.logTypes.ERROR);
+  }
+
+  info(str) {
+    this.log(str, this.logTypes.INFO);
+  }
+
+  notice(str) {
+    this.log(str, this.logTypes.NOTICE);
+  }
+
+  success(str) {
+    this.log(str, this.logTypes.SUCCESS);
+  }
+
+  verbose(str) {
+    this.log(str, this.logTypes.VERBOSE);
+  }
+
+  warning(str) {
+    this.log(str, this.logTypes.WARNING);
+  }
+}
+
+module.exports = Logger;

package/src/openAPIGenerator.js

@@ -5,6 +5,7 @@ const yaml = require("js-yaml");
 const chalk = require("chalk");
 
 const DefinitionGenerator = require("./definitionGenerator");
+const Logger = require("./logger");
 const PostmanGenerator = require("openapi-to-postmanv2");
 
 class OpenAPIGenerator {
@@ -12,18 +13,7 @@ class OpenAPIGenerator {
     this.logOutput = log;
     this.serverless = serverless;
     this.options = options;
-
-    this.logTypes = {
-      NOTICE: "notice",
-      DEBUG: "debug",
-      ERROR: "error",
-      WARNING: "warning",
-      INFO: "info",
-      VERBOSE: "verbose",
-      SUCCESS: "success",
-    };
-
-    this.defaultLog = this.logTypes.NOTICE;
+    this.logger = new Logger(this.serverless, this.logOutput);
 
     this.commands = {
       openapi: {
@@ -145,7 +135,9 @@ class OpenAPIGenerator {
   }
 
   async generate() {
-    this.log(chalk.bold.underline("OpenAPI v3 Description Generation"));
+    this.logger.notice(
+      chalk.bold.underline("OpenAPI v3 Description Generation")
+    );
     this.processCliInput();
 
     const validOpenAPI = await this.generationAndValidation().catch((err) => {
@@ -168,37 +160,31 @@ class OpenAPIGenerator {
     }
     try {
       fs.writeFileSync(this.config.file, output);
-      this.log(
-        "OpenAPI v3 Description Successfully Written",
-        this.logTypes.SUCCESS
-      );
+      this.logger.success("OpenAPI v3 Description Successfully Written");
     } catch (err) {
-      this.log(
-        `ERROR: An error was thrown whilst writing the OpenAPI Description`,
-        this.logTypes.ERROR
+      this.logger.error(
+        `ERROR: An error was thrown whilst writing the OpenAPI Description`
       );
       throw new this.serverless.classes.Error(err);
     }
   }
 
   async generationAndValidation() {
-    const generator = new DefinitionGenerator(this.serverless);
+    const generator = new DefinitionGenerator(this.serverless, this.logger);
 
-    this.log(`Generating OpenAPI Description`, this.logTypes.NOTICE);
+    this.logger.notice(`Generating OpenAPI Description`);
     await generator.parse().catch((err) => {
-      this.log(
-        `ERROR: An error was thrown generating the OpenAPI v3 Description`,
-        this.logTypes.ERROR
+      this.logger.error(
+        `ERROR: An error was thrown generating the OpenAPI v3 Description`
       );
       throw new this.serverless.classes.Error(err);
     });
 
-    this.log(`Validating generated OpenAPI Description`, this.logTypes.NOTICE);
+    this.logger.notice(`Validating generated OpenAPI Description`);
 
     const validationResults = await generator.validate().catch((err) => {
-      this.log(
-        `ERROR: An error was thrown validating the OpenAPI v3 Description`,
-        this.logTypes.ERROR
+      this.logger.error(
+        `ERROR: An error was thrown validating the OpenAPI v3 Description`
       );
 
       throw new this.serverless.classes.Error(err);
@@ -219,10 +205,7 @@ class OpenAPIGenerator {
       if (shouldThrow) throw new this.serverless.classes.Error(message);
     }
 
-    this.log(
-      "OpenAPI v3 Description Successfully Generated",
-      this.logTypes.SUCCESS
-    );
+    this.logger.success("OpenAPI v3 Description Successfully Generated");
 
     return generator.openAPI;
   }
@@ -230,31 +213,29 @@ class OpenAPIGenerator {
   createPostman(openAPI) {
     const postmanGeneration = (err, result) => {
       if (err) {
-        this.log(
-          `ERROR: An error was thrown when generating the postman collection`,
-          this.logTypes.ERROR
+        this.logger.error(
+          `ERROR: An error was thrown when generating the postman collection`
         );
         throw new this.serverless.classes.Error(err);
       }
 
-      this.log(
-        "postman collection v2 Documentation Successfully Generated",
-        this.logTypes.SUCCESS
+      this.logger.success(
+        "postman collection v2 Documentation Successfully Generated"
       );
+
       try {
         fs.writeFileSync(
           this.config.postmanCollection,
           JSON.stringify(result.output[0].data)
         );
-        this.log(
-          "postman collection v2 Documentation Successfully Written",
-          this.logTypes.SUCCESS
+        this.logger.success(
+          "postman collection v2 Documentation Successfully Written"
         );
       } catch (err) {
-        this.log(
-          `ERROR: An error was thrown whilst writing the postman collection`,
-          this.logTypes.ERROR
+        this.logger.error(
+          `ERROR: An error was thrown whilst writing the postman collection`
         );
+
         throw new this.serverless.classes.Error(err);
       }
     };
@@ -295,7 +276,7 @@ class OpenAPIGenerator {
       this.serverless.processedInput.options.output ||
       (config.format === "yaml" ? "openapi.yml" : "openapi.json");
 
-    this.log(
+    this.logger.notice(
       `${chalk.bold.green("[OPTIONS]")}
   openApiVersion: "${chalk.bold.green(String(config.openApiVersion))}"
   format: "${chalk.bold.green(config.format)}"
@@ -314,26 +295,18 @@ class OpenAPIGenerator {
 
   validationErrorDetails(validationErrors) {
     if (validationErrors.length) {
-      this.log(
+      this.logger.error(
         `${chalk.bold.yellow(
           "[VALIDATION]"
-        )} Validation errors found in OpenAPI Description: \n`,
-        this.logTypes.ERROR
+        )} Validation errors found in OpenAPI Description: \n`
       );
 
       for (const error of validationErrors) {
-        this.log(
-          `${chalk.bold.red("Severity:")} ${error.severity}`,
-          this.logTypes.ERROR
-        );
-        this.log(
-          `${chalk.bold.yellow("Message:")} ${error.message}`,
-          this.logTypes.ERROR
-        );
+        this.logger.error(`${chalk.bold.red("Severity:")} ${error.severity}`);
+        this.logger.error(`${chalk.bold.yellow("Message:")} ${error.message}`);
         for (const location of error.location) {
-          this.log(
-            `${chalk.bold.yellow("found at location:")} ${location.pointer}`,
-            this.logTypes.ERROR
+          this.logger.error(
+            `${chalk.bold.yellow("found at location:")} ${location.pointer}`
           );
         }
       }

package/src/owasp.js

@@ -47,11 +47,6 @@ class OWASP {
         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)",
       },
-      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,
-      },
       "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)",
@@ -153,13 +148,44 @@ class OWASP {
   getHeaders(headerList) {
     const obj = {};
     for (const headerName of Object.keys(headerList)) {
-      const defaultHeader =
-        this.DEFAULT_OWASP_HEADERS[this.headerMap[headerName]];
-      Object.assign(obj, { [this.headerMap[headerName]]: defaultHeader });
+      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;
+        if (typeof headerList[headerName] !== "boolean") {
+          obj[this.headerMap[headerName]].schema.default =
+            headerList[headerName].value;
+        }
       }
     }
 

package/test/json/newOWASP.json

@@ -1,57 +1,53 @@
 {
-    "last_update_utc": "2023-05-26 12:22:30",
-    "headers": [
-      {
-        "name": "Cache-Control",
-        "value": "no-store, max-age=0"
-      },
-      {
-        "name": "Clear-Site-Data",
-        "value": "\"cache\",\"cookies\",\"storage\""
-      },
-      {
-        "name": "Content-Security-Policy",
-        "value": "default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
-      },
-      {
-        "name": "Cross-Origin-Embedder-Policy",
-        "value": "credentialless"
-      },
-      {
-        "name": "Cross-Origin-Opener-Policy",
-        "value": "same-origin"
-      },
-      {
-        "name": "Cross-Origin-Resource-Policy",
-        "value": "same-origin"
-      },
-      {
-        "name": "Permissions-Policy",
-        "value": "accelerometer=(),ambient-light-sensor=(),autoplay=(),battery=(),camera=(),display-capture=(),document-domain=(),encrypted-media=(),fullscreen=(),gamepad=(),geolocation=(),gyroscope=(),layout-animations=(self),legacy-image-formats=(self),magnetometer=(),microphone=(),midi=(),oversized-images=(self),payment=(),picture-in-picture=(),publickey-credentials-get=(),speaker-selection=(),sync-xhr=(self),unoptimized-images=(self),unsized-media=(self),usb=(),screen-wake-lock=(),web-share=(),xr-spatial-tracking=()"
-      },
-      {
-        "name": "Pragma",
-        "value": "no-cache"
-      },
-      {
-        "name": "Referrer-Policy",
-        "value": "no-referrer"
-      },
-      {
-        "name": "Strict-Transport-Security",
-        "value": "max-age=31536000 ; includeSubDomains"
-      },
-      {
-        "name": "X-Content-Type-Options",
-        "value": "nosniff"
-      },
-      {
-        "name": "X-Frame-Options",
-        "value": "deny"
-      },
-      {
-        "name": "X-Permitted-Cross-Domain-Policies",
-        "value": "none"
-      }
-    ]
-  }
+  "last_update_utc": "2024-09-19 21:29:28",
+  "headers": [
+    {
+      "name": "Cache-Control",
+      "value": "no-store, max-age=0"
+    },
+    {
+      "name": "Clear-Site-Data",
+      "value": "\"cache\",\"cookies\",\"storage\""
+    },
+    {
+      "name": "Content-Security-Policy",
+      "value": "default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
+    },
+    {
+      "name": "Cross-Origin-Embedder-Policy",
+      "value": "require-corp"
+    },
+    {
+      "name": "Cross-Origin-Opener-Policy",
+      "value": "same-origin"
+    },
+    {
+      "name": "Cross-Origin-Resource-Policy",
+      "value": "same-origin"
+    },
+    {
+      "name": "Permissions-Policy",
+      "value": "accelerometer=(), autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(), hid=(), idle-detection=(), interest-cohort=(), serial=(), unload=()"
+    },
+    {
+      "name": "Referrer-Policy",
+      "value": "no-referrer"
+    },
+    {
+      "name": "Strict-Transport-Security",
+      "value": "max-age=31536000; includeSubDomains"
+    },
+    {
+      "name": "X-Content-Type-Options",
+      "value": "nosniff"
+    },
+    {
+      "name": "X-Frame-Options",
+      "value": "deny"
+    },
+    {
+      "name": "X-Permitted-Cross-Domain-Policies",
+      "value": "none"
+    }
+  ]
+}