From dad247eb73a25ba9f8aa02def0378dfe7eac62df Mon Sep 17 00:00:00 2001 From: Thomas GENTILHOMME Date: Fri, 3 Jun 2022 23:54:39 +0200 Subject: [PATCH] chore: add few jsdoc to probes (with links to estree and code examples) --- src/probes/isArrayExpression.js | 8 +++++++- src/probes/isAssignmentExpression.js | 7 +++++++ src/probes/isBinaryExpression.js | 14 ++++++++++++++ src/probes/isFunctionDeclaration.js | 7 +++++++ src/probes/isImportDeclaration.js | 11 +++++++++-- src/probes/isLiteral.js | 7 ++++++- src/probes/isLiteralRegex.js | 9 +++++++-- src/probes/isObjectExpression.js | 6 ++++++ src/probes/isRegexObject.js | 9 +++++++-- src/probes/isUnaryExpression.js | 8 ++++++++ src/probes/isUnsafeCallee.js | 7 ++++++- 11 files changed, 84 insertions(+), 9 deletions(-) diff --git a/src/probes/isArrayExpression.js b/src/probes/isArrayExpression.js index e2006a07..dd0610f8 100644 --- a/src/probes/isArrayExpression.js +++ b/src/probes/isArrayExpression.js @@ -1,4 +1,10 @@ -// Search for Array +/** + * @description Search for ArrayExpression AST Node (Commonly known as JS Arrays) + * + * @see https://github.com/estree/estree/blob/master/es5.md#arrayexpression + * @example + * ["foo", "bar", 1] + */ function validateNode(node) { return [ node.type === "ArrayExpression" diff --git a/src/probes/isAssignmentExpression.js b/src/probes/isAssignmentExpression.js index 9524959c..2a28beae 100644 --- a/src/probes/isAssignmentExpression.js +++ b/src/probes/isAssignmentExpression.js @@ -1,6 +1,13 @@ // Import Internal Dependencies import { getIdName } from "../utils.js"; +/** + * @description Search for AssignmentExpression (Not to be confused with AssignmentPattern). + * + * @see https://github.com/estree/estree/blob/master/es5.md#assignmentexpression + * @example + * (foo = 5) + */ function validateNode(node) { return [ node.type === "AssignmentExpression" diff --git a/src/probes/isBinaryExpression.js b/src/probes/isBinaryExpression.js index f0a24897..e383767f 100644 --- a/src/probes/isBinaryExpression.js +++ b/src/probes/isBinaryExpression.js @@ -1,3 +1,10 @@ +/** + * @description Search for BinaryExpression AST Node. + * + * @see https://github.com/estree/estree/blob/master/es5.md#binaryexpression + * @example + * 5 + 5 + 10 + */ function validateNode(node) { return [ node.type === "BinaryExpression" @@ -13,6 +20,13 @@ function main(node, options) { } } +/** + * @description Look for suspicious BinaryExpression (read the Obfuscator.io section of the linked G.Doc) + * @see https://docs.google.com/document/d/11ZrfW0bDQ-kd7Gr_Ixqyk8p3TGvxckmhFH3Z8dFoPhY/edit?usp=sharing + * @see https://github.com/estree/estree/blob/master/es5.md#unaryexpression + * @example + * 0x1*-0x12df+-0x1fb9*-0x1+0x2*-0x66d + */ function walkBinaryExpression(expr, level = 1) { const [lt, rt] = [expr.left.type, expr.right.type]; let hasUnaryExpression = lt === "UnaryExpression" || rt === "UnaryExpression"; diff --git a/src/probes/isFunctionDeclaration.js b/src/probes/isFunctionDeclaration.js index c067cd76..caf621fe 100644 --- a/src/probes/isFunctionDeclaration.js +++ b/src/probes/isFunctionDeclaration.js @@ -1,3 +1,10 @@ +/** + * @description Search for FunctionDeclaration AST Node. + * + * @see https://github.com/estree/estree/blob/master/es5.md#functiondeclaration + * @example + * function foo() {} + */ function validateNode(node) { return [ node.type === "FunctionDeclaration" diff --git a/src/probes/isImportDeclaration.js b/src/probes/isImportDeclaration.js index e1a2b0ee..db0d3318 100644 --- a/src/probes/isImportDeclaration.js +++ b/src/probes/isImportDeclaration.js @@ -1,10 +1,17 @@ // Require Internal Dependencies import { warnings } from "../constants.js"; -// Looking for ESM ImportDeclaration -// see: https://github.com/estree/estree/blob/master/es2015.md#importdeclaration +/** + * @description Search for ESM ImportDeclaration + * @see https://github.com/estree/estree/blob/master/es2015.md#importdeclaration + * @example + * import * as foo from "bar"; + * import fs from "fs"; + * import "make-promises-safe"; + */ function validateNode(node) { return [ + // Note: the source property is the right-side Literal part of the Import node.type === "ImportDeclaration" && node.source.type === "Literal" ]; } diff --git a/src/probes/isLiteral.js b/src/probes/isLiteral.js index 7b10fbdd..d32487f9 100644 --- a/src/probes/isLiteral.js +++ b/src/probes/isLiteral.js @@ -10,7 +10,12 @@ import { globalParts, warnings } from "../constants.js"; // CONSTANTS const kNodeDeps = new Set(builtinModules); -// Check all 'string' Literal values +/** + * @description Search for Literal AST Node + * @see https://github.com/estree/estree/blob/master/es5.md#literal + * @example + * "foobar" + */ function validateNode(node) { return [ node.type === "Literal" && typeof node.value === "string" diff --git a/src/probes/isLiteralRegex.js b/src/probes/isLiteralRegex.js index 43e3f29a..4968ca93 100644 --- a/src/probes/isLiteralRegex.js +++ b/src/probes/isLiteralRegex.js @@ -5,8 +5,12 @@ import { warnings } from "../constants.js"; // Require Third-party Dependencies import safeRegex from "safe-regex"; -// Search for Literal Regex. -// then we use the safe-regex package to detect whether or not regex is safe! +/** + * @description Search for RegExpLiteral AST Node + * @see https://github.com/estree/estree/blob/master/es5.md#regexpliteral + * @example + * /hello/ + */ function validateNode(node) { return [ isLiteralRegex(node) @@ -16,6 +20,7 @@ function validateNode(node) { function main(node, options) { const { analysis } = options; + // We use the safe-regex package to detect whether or not regex is safe! if (!safeRegex(node.regex.pattern)) { analysis.addWarning(warnings.unsafeRegex, node.regex.pattern, node.loc); } diff --git a/src/probes/isObjectExpression.js b/src/probes/isObjectExpression.js index 0fae804f..02f16fbf 100644 --- a/src/probes/isObjectExpression.js +++ b/src/probes/isObjectExpression.js @@ -1,3 +1,9 @@ +/** + * @description Search for ObjectExpression AST Node (commonly known as Object). + * @see https://github.com/estree/estree/blob/master/es5.md#objectexpression + * @example + * { foo: "bar" } + */ function validateNode(node) { return [ node.type === "ObjectExpression" diff --git a/src/probes/isRegexObject.js b/src/probes/isRegexObject.js index b9522052..baaacdc6 100644 --- a/src/probes/isRegexObject.js +++ b/src/probes/isRegexObject.js @@ -5,8 +5,12 @@ import { warnings } from "../constants.js"; // Import Third-party Dependencies import safeRegex from "safe-regex"; -// Search for Regex Object constructor. -// then we use the safe-regex package to detect whether or not regex is safe! +/** + * @description Search for Regex Object constructor. + * @see https://github.com/estree/estree/blob/master/es5.md#newexpression + * @example + * new RegExp("..."); + */ function validateNode(node) { return [ isRegexConstructor(node) && node.arguments.length > 0 @@ -19,6 +23,7 @@ function main(node, options) { const arg = node.arguments[0]; const pattern = isLiteralRegex(arg) ? arg.regex.pattern : arg.value; + // We use the safe-regex package to detect whether or not regex is safe! if (!safeRegex(pattern)) { analysis.addWarning(warnings.unsafeRegex, pattern, node.loc); } diff --git a/src/probes/isUnaryExpression.js b/src/probes/isUnaryExpression.js index a0957205..cab2fcc5 100644 --- a/src/probes/isUnaryExpression.js +++ b/src/probes/isUnaryExpression.js @@ -1,3 +1,9 @@ +/** + * @description Search for UnaryExpression AST Node + * @see https://github.com/estree/estree/blob/master/es5.md#unaryexpression + * @example + * -2 + */ function validateNode(node) { return [ node.type === "UnaryExpression" @@ -7,6 +13,8 @@ function validateNode(node) { function main(node, options) { const { analysis } = options; + // Example: !![] + // See: https://docs.google.com/document/d/11ZrfW0bDQ-kd7Gr_Ixqyk8p3TGvxckmhFH3Z8dFoPhY/edit# if (node.argument.type === "UnaryExpression" && node.argument.argument.type === "ArrayExpression") { analysis.counter.doubleUnaryArray++; } diff --git a/src/probes/isUnsafeCallee.js b/src/probes/isUnsafeCallee.js index b2cfc7bf..e981d640 100644 --- a/src/probes/isUnsafeCallee.js +++ b/src/probes/isUnsafeCallee.js @@ -2,7 +2,12 @@ import { isUnsafeCallee } from "../utils.js"; import { warnings } from "../constants.js"; -// Detect unsafe statement like eval("this") or Function("return this")(); +/** + * @description Detect unsafe statement + * @example + * eval("this"); + * Function("return this")(); + */ function validateNode(node) { return isUnsafeCallee(node); }