From 76d30eb20bda3974962cd2d37e427b91201989ca Mon Sep 17 00:00:00 2001 From: fraxken Date: Wed, 29 Nov 2023 23:05:12 +0100 Subject: [PATCH] docs: improve warnings markdown docs --- docs/encoded-literal.md | 4 ++-- docs/obfuscated-code.md | 7 +++++-- docs/parsing-error.md | 5 +++-- docs/shady-link.md | 5 +++-- docs/short-identifiers.md | 4 +++- docs/suspicious-literal.md | 14 ++++++++++---- docs/unsafe-import.md | 7 ++++--- docs/unsafe-regex.md | 3 ++- docs/unsafe-stmt.md | 2 +- docs/weak-crypto.md | 2 +- 10 files changed, 34 insertions(+), 19 deletions(-) diff --git a/docs/encoded-literal.md b/docs/encoded-literal.md index c608dca5..da4b7001 100644 --- a/docs/encoded-literal.md +++ b/docs/encoded-literal.md @@ -6,12 +6,12 @@ ## Introduction -The SAST scanner assert all Literals in the tree and search for encoded values. JS-X-Ray currently supports three types of detection: +JS-X-Ray assert all Literals in the tree and search for **encoded values**. It currently supports `three` types of detection: - Hexadecimal sequence: `'\x72\x4b\x58\x6e\x75\x65\x38\x3d'` - Unicode sequence: `\u03B1` - Base64 encryption: `z0PgB0O=` -Hexadecimal and Unicode sequence are tested directly on the raw Literal provided by meriyah. For base64 detection we use the npm package [is-base64](https://github.com/miguelmota/is-base64). +Hexadecimal and Unicode sequence are tested directly on the **raw Literal** provided by meriyah. For base64 detection we use the npm package [is-base64](https://github.com/miguelmota/is-base64). Example of a JavaScript implementation: ```js diff --git a/docs/obfuscated-code.md b/docs/obfuscated-code.md index 41a2d5bf..bb2c5753 100644 --- a/docs/obfuscated-code.md +++ b/docs/obfuscated-code.md @@ -6,7 +6,9 @@ ## Introduction -An **experimental** warning capable of detecting obfuscation and sometimes the tool used. The scanner is capable to detect: +An **experimental** warning capable of detecting obfuscation and sometimes the tool used. + +JS-X-Ray is capable to detect the following internet tools: - [freejsobfuscator](http://www.freejsobfuscator.com/) - [jjencode](https://utf-8.jp/public/jjencode.html) @@ -22,7 +24,8 @@ A complete G.Drive document has been written to describe the patterns of obfusca - [JSXRay - Patterns of obfuscated JavaScript code](https://docs.google.com/document/d/11ZrfW0bDQ-kd7Gr_Ixqyk8p3TGvxckmhFH3Z8dFoPhY/edit?usp=sharing) -> **Note** There is no frozen implementation and this is an early implementation +> [!CAUTION] +> This is an early (beta) implementation ## Example diff --git a/docs/parsing-error.md b/docs/parsing-error.md index 5c511e8d..d93a9794 100644 --- a/docs/parsing-error.md +++ b/docs/parsing-error.md @@ -6,9 +6,10 @@ ## Introduction -Parsing Error is throw when the library [meriyah](https://github.com/meriyah/meriyah) fail to parse the javascript source code into an AST. But it can also happen when the AST analysis fails because we don't manage a case properly. +parsing-error warning is throw when the library [meriyah](https://github.com/meriyah/meriyah) **fail to parse** the javascript source code into an AST. But it can also happen when the AST analysis fails because we don't manage a case properly. -> **Note** If you are in the second case, please open an issue [here](https://github.com/NodeSecure/js-x-ray/issues) +> [!IMPORTANT] +> If you are in the second case, please open an issue [here](https://github.com/NodeSecure/js-x-ray/issues) ## Example diff --git a/docs/shady-link.md b/docs/shady-link.md index d2537dd1..9ec867f9 100644 --- a/docs/shady-link.md +++ b/docs/shady-link.md @@ -5,9 +5,10 @@ ## Introduction -Identify when a Literal (string) contains an URL to a domain with a suspicious extension. +Identify when a Literal (string) contains an URL to a domain with a **suspicious extension**. -> **Note** credit goes to the [guarddog](https://github.dev/DataDog/guarddog) team. +> [!IMPORTANT] +> Credit goes to the [guarddog](https://github.dev/DataDog/guarddog) team. ## Example diff --git a/docs/short-identifiers.md b/docs/short-identifiers.md index eb9ee509..4c1b779e 100644 --- a/docs/short-identifiers.md +++ b/docs/short-identifiers.md @@ -6,8 +6,10 @@ ## Introduction -The SAST store in memory all Identifiers id so we are able later to sum the length of all ids. We are looking at several ESTree Node in the tree: +JS-X-Ray store in memory all Identifiers so we are able later to sum the length of all of them. We are looking at several ESTree Node in the tree: - VariableDeclarator: `var boo;` +- ClassDeclaration: `class boo {}` +- MethodDefinition - AssignmentExpression: `(boo = 5)` - FunctionDeclaration: `function boo() {}` - Property of ObjectExpression: `{ boo: 5 }` diff --git a/docs/suspicious-literal.md b/docs/suspicious-literal.md index d1380128..fcdccb5a 100644 --- a/docs/suspicious-literal.md +++ b/docs/suspicious-literal.md @@ -41,15 +41,21 @@ function stringSuspicionScore(str) { } const includeSpace = str.includes(" "); - const includeSpaceAtStart = includeSpace ? str.slice(0, kMaxSafeStringLen).includes(" ") : false; + const includeSpaceAtStart = includeSpace ? + str.slice(0, kMaxSafeStringLen).includes(" ") : + false; let suspectScore = includeSpaceAtStart ? 0 : 1; if (strLen > kMinUnsafeStringLenThreshold) { - suspectScore += Math.ceil(strLen / kScoreStringLengthThreshold); + suspectScore += Math.ceil( + strLen / kScoreStringLengthThreshold + ); } - return stringCharDiversity(str) >= kMaxSafeStringCharDiversity ? suspectScore + 2 : suspectScore; + return stringCharDiversity(str) >= kMaxSafeStringCharDiversity ? + suspectScore + 2 : suspectScore; } ``` -> **Note** The warning is generated only if the sum of all scores exceeds **three**. +> [!IMPORTANT] +> The warning is generated only if the sum of all scores exceeds **three**. diff --git a/docs/unsafe-import.md b/docs/unsafe-import.md index ec1a3005..1afa3657 100644 --- a/docs/unsafe-import.md +++ b/docs/unsafe-import.md @@ -6,9 +6,10 @@ ## Introduction -On JS-X-Ray we intensively track the use of `require` CallExpression and also ESM Import declarations. Knowing the dependencies used is really important for our analysis and that why when the SAST fail to follow an important it will throw an `unsafe-import` warning. +JS-X-Ray intensively track the use of `require` CallExpression and also ESM Import declarations. Knowing the dependencies used is really important for our analysis and that why when the SAST fail to follow an important it will throw an `unsafe-import` warning. -> **Note** Sometimes we trigger this warning on purpose because we have detected a malicious import +> [!CAUTION] +> Sometimes we trigger this warning on purpose because we have detected a malicious import ### CJS Note We analyze and trace several ways to require in Node.js (with CJS): @@ -19,7 +20,7 @@ We analyze and trace several ways to require in Node.js (with CJS): ## Example -The code below try to require Node.js core dependency `http`. JS-X-Ray sucessfully detect it and throw an `unsafe-import` warning. +The code below try to require Node.js core dependency `http`. JS-X-Ray sucessfully detect it and throw an unsafe-import warning. ```js function unhex(r) { diff --git a/docs/unsafe-regex.md b/docs/unsafe-regex.md index 3449687a..20cd0afd 100644 --- a/docs/unsafe-regex.md +++ b/docs/unsafe-regex.md @@ -15,7 +15,8 @@ Learn more: - [Why Aren’t Regexes a Lingua Franca?](https://davisjam.medium.com/why-arent-regexes-a-lingua-franca-esecfse19-a36348df3a2) - [Comparing regex matching algorithms](https://swtch.com/~rsc/regexp/regexp1.html) -> **Note** credit goes to the `safe-regex` package author for the last three resources. +> [!NOTE] +> Credit goes to the `safe-regex` package author for the last three resources. ### Technical implementation diff --git a/docs/unsafe-stmt.md b/docs/unsafe-stmt.md index 29d944e5..e2d8d100 100644 --- a/docs/unsafe-stmt.md +++ b/docs/unsafe-stmt.md @@ -6,7 +6,7 @@ ## Introduction -Warning to notify of the usage of `eval()` or `Function()` in the source code. Their use is not recommended and can be used to execute insecure code (for example to retrieve the `globalThis` / `window` object). +Warning about the usage of eval() or Function() in the source code. Their use is not recommended and can be used to execute insecure code (for example to retrieve the **globalThis** / **window** object). - [MDN - Never use eval()!](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval#never_use_eval!) diff --git a/docs/weak-crypto.md b/docs/weak-crypto.md index 2cc450f2..251273e5 100644 --- a/docs/weak-crypto.md +++ b/docs/weak-crypto.md @@ -6,7 +6,7 @@ ## Introduction -Detect usage of weak crypto algorithm with the Node.js core `Crypto` dependency. Algorithm considered to be weak are: +Detect usage of **weak crypto** algorithm with the Node.js core `Crypto` dependency. Algorithm considered to be weak are: - md5 - md4