docs: automate docs with eslint-doc-generator (#101)

Author: bmish

.eslint-doc-generatorrc.js

@@ -0,0 +1,9 @@
+const { format } = require('prettier');
+const { prettier: prettierRC } = require('./.prettierrc.json');
+
+/** @type {import('eslint-doc-generator').GenerateOptions} */
+const config = {
+  postprocess: (doc) => format(doc, { ...prettierRC, parser: 'markdown' }),
+};
+
+module.exports = config;

.eslintrc

@@ -13,11 +13,12 @@
   },
   "rules": {
     "eslint-plugin/prefer-message-ids": "off", // TODO: enable
+    "eslint-plugin/require-meta-docs-description": ["error", { "pattern": "^(Detects|Enforces|Requires|Disallows) .+\\.$" }],
     "eslint-plugin/require-meta-docs-url": [
       "error",
       {
         "pattern":
-          "https://github.com/nodesecurity/eslint-plugin-security#{{name}}",
+          "https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/{{name}}.md",
       },
     ],
     "eslint-plugin/require-meta-schema": "off", // TODO: enable

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "line-length": false,
+  "no-inline-html": { "allowed_elements": ["kbd"]}
+}

.markdownlintignore

@@ -0,0 +1,3 @@
+CHANGELOG.md
+LICENSE
+node_modules

README.md

@@ -6,11 +6,19 @@ ESLint rules for Node Security
 
 This project will help identify potential security hotspots, but finds a lot of false positives which need triage by a human.
 
-### Installation
+## Installation
 
-`npm install --save-dev eslint-plugin-security` or `yarn add eslint-plugin-security --dev`
+```sh
+npm install --save-dev eslint-plugin-security
+```
+
+or
+
+```sh
+yarn add --dev eslint-plugin-security
+```
 
-### Usage
+## Usage
 
 Add the following to your `.eslintrc` file:
 
@@ -31,86 +39,33 @@ Add the following to your `.eslintrc` file:
 npm run-script cont-int
 ```
 
-### Tests
+## Tests
 
 ```sh
 npm test
 ```
 
-### Rules
-
-#### `detect-unsafe-regex`
-
-Locates potentially unsafe regular expressions, which may take a very long time to run, blocking the event loop.
-
-More information: [Regular Expression DoS and Node.js](docs/regular-expression-dos-and-node.md)
-
-#### `detect-buffer-noassert`
-
-Detect calls to [`buffer`](https://nodejs.org/api/buffer.html) with `noAssert` flag set.
-
-From the Node.js API docs: "Setting `noAssert` to true skips validation of the `offset`. This allows the `offset` to be beyond the end of the `Buffer`."
-
-#### `detect-child-process`
-
-Detect instances of [`child_process`](https://nodejs.org/api/child_process.html) & non-literal [`exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
-
-More information: [Avoiding Command Injection in Node.js](docs/avoid-command-injection-node.md)
-
-#### `detect-disable-mustache-escape`
-
-Detects `object.escapeMarkup = false`, which can be used with some template engines to disable escaping of HTML entities. This can lead to Cross-Site Scripting (XSS) vulnerabilities.
-
-More information: [OWASP XSS](<https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)>)
-
-#### `detect-eval-with-expression`
-
-Detects `eval(variable)` which can allow an attacker to run arbitrary code inside your process.
-
-More information: [What are the security issues with eval in JavaScript?](http://security.stackexchange.com/questions/94017/what-are-the-security-issues-with-eval-in-javascript)
-
-#### `detect-no-csrf-before-method-override`
-
-Detects Express `csrf` middleware setup before `method-override` middleware. This can allow `GET` requests (which are not checked by `csrf`) to turn into `POST` requests later.
-
-More information: [Bypass Connect CSRF protection by abusing methodOverride Middleware](docs/bypass-connect-csrf-protection-by-abusing.md)
-
-#### `detect-non-literal-fs-filename`
-
-Detects variable in filename argument of `fs` calls, which might allow an attacker to access anything on your system.
-
-More information: [OWASP Path Traversal](https://www.owasp.org/index.php/Path_Traversal)
-
-#### `detect-non-literal-regexp`
-
-Detects `RegExp(variable)`, which might allow an attacker to DOS your server with a long-running regular expression.
-
-More information: [Regular Expression DoS and Node.js](docs/regular-expression-dos-and-node.md)
-
-#### `detect-non-literal-require`
-
-Detects `require(variable)`, which might allow an attacker to load and run arbitrary code, or access arbitrary files on disk.
-
-More information: [Where does Node.js and require look for modules?](http://www.bennadel.com/blog/2169-where-does-node-js-and-require-look-for-modules.htm)
-
-#### `detect-object-injection`
-
-Detects `variable[key]` as a left- or right-hand assignment operand.
-
-More information: [The Dangers of Square Bracket Notation](docs/the-dangers-of-square-bracket-notation.md)
-
-#### `detect-possible-timing-attacks`
-
-Detects insecure comparisons (`==`, `!=`, `!==` and `===`), which check input sequentially.
-
-More information: [A lesson in timing attacks](https://codahale.com/a-lesson-in-timing-attacks/)
-
-#### `detect-pseudoRandomBytes`
-
-Detects if `pseudoRandomBytes()` is in use, which might not give you the randomness you need and expect.
-
-More information: [Randombytes vs pseudorandombytes](http://stackoverflow.com/questions/18130254/randombytes-vs-pseudorandombytes)
-
-#### `detect-new-buffer`
-
-Detect instances of new Buffer(argument) where argument is any non-literal value.
+## Rules
+
+<!-- begin auto-generated rules list -->
+
+⚠️ Configurations set to warn in.\
+✅ Set in the `recommended` configuration.
+
+| Name                                                                                         | Description                                                                                                                   | ⚠️  |
+| :------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :-- |
+| [detect-buffer-noassert](docs/rules/detect-buffer-noassert.md)                               | Detects calls to "buffer" with "noAssert" flag set.                                                                           | ✅  |
+| [detect-child-process](docs/rules/detect-child-process.md)                                   | Detects instances of "child_process" & non-literal "exec()" calls.                                                            | ✅  |
+| [detect-disable-mustache-escape](docs/rules/detect-disable-mustache-escape.md)               | Detects "object.escapeMarkup = false", which can be used with some template engines to disable escaping of HTML entities.     | ✅  |
+| [detect-eval-with-expression](docs/rules/detect-eval-with-expression.md)                     | Detects "eval(variable)" which can allow an attacker to run arbitrary code inside your process.                               | ✅  |
+| [detect-new-buffer](docs/rules/detect-new-buffer.md)                                         | Detects instances of new Buffer(argument) where argument is any non-literal value.                                            | ✅  |
+| [detect-no-csrf-before-method-override](docs/rules/detect-no-csrf-before-method-override.md) | Detects Express "csrf" middleware setup before "method-override" middleware.                                                  | ✅  |
+| [detect-non-literal-fs-filename](docs/rules/detect-non-literal-fs-filename.md)               | Detects variable in filename argument of "fs" calls, which might allow an attacker to access anything on your system.         | ✅  |
+| [detect-non-literal-regexp](docs/rules/detect-non-literal-regexp.md)                         | Detects "RegExp(variable)", which might allow an attacker to DOS your server with a long-running regular expression.          | ✅  |
+| [detect-non-literal-require](docs/rules/detect-non-literal-require.md)                       | Detects "require(variable)", which might allow an attacker to load and run arbitrary code, or access arbitrary files on disk. | ✅  |
+| [detect-object-injection](docs/rules/detect-object-injection.md)                             | Detects "variable[key]" as a left- or right-hand assignment operand.                                                          | ✅  |
+| [detect-possible-timing-attacks](docs/rules/detect-possible-timing-attacks.md)               | Detects insecure comparisons (`==`, `!=`, `!==` and `===`), which check input sequentially.                                   | ✅  |
+| [detect-pseudoRandomBytes](docs/rules/detect-pseudoRandomBytes.md)                           | Detects if "pseudoRandomBytes()" is in use, which might not give you the randomness you need and expect.                      | ✅  |
+| [detect-unsafe-regex](docs/rules/detect-unsafe-regex.md)                                     | Detects potentially unsafe regular expressions, which may take a very long time to run, blocking the event loop.              | ✅  |
+
+<!-- end auto-generated rules list -->

docs/bypass-connect-csrf-protection-by-abusing.md

@@ -8,7 +8,7 @@ This issue was found and reported to us by [Luca Carettoni](http://twitter.com/_
 
 Connect, methodOverride middleware
 
-### Description:
+### Description
 
 **Connect's "methodOverride" middleware allows an HTTP request to override the method of the request with the value of the "\_method" post key or with the header "x-http-method-override".**
 
@@ -25,15 +25,15 @@ app.use express.methodOverride()
 
 Connect's CSRF middleware does not check csrf tokens in case of idempotent verbs (GET/HEAD/OPTIONS, see lib/middleware/csrf.js). As a result, it is possible to bypass this security control by sending a GET request with a POST MethodOverride header or key.
 
-### Example:
+### Example
 
 ```sh
 GET / HTTP/1.1
 [..]
 _method=POST
 ```
 
-### Mitigation Factors:
+### Mitigation Factors
 
 Disable methodOverride or make sure that it takes precedence over other middleware declarations.
 

docs/rules/detect-buffer-noassert.md

@@ -0,0 +1,9 @@
+# Detects calls to "buffer" with "noAssert" flag set (`security/detect-buffer-noassert`)
+
+⚠️ This rule _warns_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+Detect calls to [`buffer`](https://nodejs.org/api/buffer.html) with `noAssert` flag set.
+
+From the Node.js API docs: "Setting `noAssert` to true skips validation of the `offset`. This allows the `offset` to be beyond the end of the `Buffer`."

docs/rules/detect-child-process.md

@@ -0,0 +1,9 @@
+# Detects instances of "child_process" & non-literal "exec()" calls (`security/detect-child-process`)
+
+⚠️ This rule _warns_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+Detect instances of [`child_process`](https://nodejs.org/api/child_process.html) & non-literal [`exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
+
+More information: [Avoiding Command Injection in Node.js](../avoid-command-injection-node.md)

docs/rules/detect-disable-mustache-escape.md

@@ -0,0 +1,9 @@
+# Detects "object.escapeMarkup = false", which can be used with some template engines to disable escaping of HTML entities (`security/detect-disable-mustache-escape`)
+
+⚠️ This rule _warns_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+This can lead to Cross-Site Scripting (XSS) vulnerabilities.
+
+More information: [OWASP XSS](<https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)>)

docs/rules/detect-eval-with-expression.md

@@ -0,0 +1,7 @@
+# Detects "eval(variable)" which can allow an attacker to run arbitrary code inside your process (`security/detect-eval-with-expression`)
+
+⚠️ This rule _warns_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+More information: [What are the security issues with eval in JavaScript?](http://security.stackexchange.com/questions/94017/what-are-the-security-issues-with-eval-in-javascript)