JavaScript AST analysis. This package has been created to export the NodeSecure AST analysis to enable better code evolution and allow better access to developers and researchers.

The goal is to quickly identify dangerous code and patterns for developers and security researchers. Interpreting the results of this tool will still require you to have basic knowledge of secure coding.

Goals

The objective of the project is to detect potentially suspicious JavaScript code. The target is code that is added or injected for malicious purposes.

Most of the time hackers will try to hide the behaviour of their code as much as possible to avoid being spotted or easily understood. The work of the library is to understand and analyze these patterns that will allow us to detect malicious code.

Feature Highlight

• Retrieve required dependencies and files for Node.js
• Detect unsafe regular expressions
• Get warnings when the AST analysis detects a problem or is unable to follow a statement
• Highlight common attack patterns and API usages
• Follow the usage of dangerous Node.js globals
• Detect obfuscated code and, when possible, the tool that has been used
• Detect potential performance issues related to usage of synchronous API from Node.js core.

Getting Started

This package is available in the Node package repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/js-x-ray
# or
$ yarn add @nodesecure/js-x-ray

Usage example

Create a local .js file with the following content:

try  {
    require("http");
}
catch (err) {
    // do nothing
}
const lib = "crypto";
require(lib);
require("util");
require(Buffer.from("6673", "hex").toString());

---

Then use js-x-ray to run an analysis of the JavaScript code:

import { AstAnalyser } from "@nodesecure/js-x-ray";
import { readFileSync } from "node:fs";

const scanner = new AstAnalyser();

const { warnings, dependencies } = await scanner.analyseFile(
  "./file.js"
);

console.log(dependencies);
console.dir(warnings, { depth: null });

The analysis will return: http (in try), crypto, util and fs.

Tip

There are also a lot of suspicious code examples in the ./workspaces/js-x-ray/examples directory. Feel free to try the tool on these files.

API

• AstAnalyser
• EntryFilesAnalyser

Warnings

This section describes how use the warnings export.

type WarningName = "parsing-error"
| "encoded-literal"
| "unsafe-regex"
| "unsafe-stmt"
| "short-identifiers"
| "suspicious-literal"
| "suspicious-file"
| "obfuscated-code"
| "weak-crypto"
| "unsafe-import"
| "unsafe-command"
| "shady-link"
| "synchronous-io";

declare const warnings: Record<WarningName, {
  i18n: string;
  severity: "Information" | "Warning" | "Critical";
  experimental?: boolean;
}>;

We make a call to i18n through the package NodeSecure/i18n to get the translation.

import * as jsxray from "@nodesecure/js-x-ray";
import * as i18n from "@nodesecure/i18n";

console.log(i18n.getTokenSync(jsxray.warnings["parsing-error"].i18n));

Legends

This section describes all the possible warnings returned by JSXRay. Click on the warning name for additional information and examples.

name	experimental	description
parsing-error	❌	The AST parser throw an error
unsafe-import	❌	Unable to follow an import (require, require.resolve) statement/expr.
unsafe-regex	❌	A regular expression has been detected as unsafe and may be used for a ReDoS attack
unsafe-stmt	❌	Usage of dangerous statements like eval() or Function("")
unsafe-command	✔️	Usage of suspicious commands in spawn() or exec()
encoded-literal	❌	An encoded literal has been detected (it can be an hexadecimal value, Unicode sequence or a base64 string)
short-identifiers	❌	This means that all identifiers have an average length below 1.5
suspicious-literal	❌	A suspicious literal has been found in the source code
suspicious-file	❌	A suspicious file with more than ten encoded literals in it
obfuscated-code	✔️	There's a very high probability that the code is obfuscated
weak-crypto	❌	The code probably contains a weak crypto algorithm (e.g., MD5, SHA1, …)
shady-link	❌	The code contains a shady/unsafe link
synchronous-io	✔️	The code contains a synchronous IO call.

Workspaces

Click on one of the links to access the documentation of the workspace:

name	package and link
js-x-ray	@nodesecure/js-x-ray
estree-ast-utils	@nodesecure/estree-ast-utils
tracer	@nodesecure/tracer
sec-literal	@nodesecure/sec-literal
ts-source-parser	@nodesecure/ts-source-parser

These packages are available in the Node package repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/estree-ast-util
# or
$ yarn add @nodesecure/estree-ast-util

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Gentilhomme 💻 📖 👀 🛡️ 🐛	Nicolas Hallaert 📖	Antoine 💻	Mathieu 💻	Vincent Dhennin 💻 ⚠️	Tony Gorez 💻 📖 ⚠️	PierreD ⚠️ 💻
Franck Hallaert 💻	Maji 💻	Michaël Zasso 💻 🐛	Kouadio Fabrice Nguessan 🚧 💻	Jean ⚠️ 💻 📖	tchapacan 💻 ⚠️	mkarkkainen 💻
FredGuiou 📖 💻	Madina 💻	SairussDev 💻	Abdou-Raouf ATARMLA 💻	Clement Gombauld 💻 ⚠️	Ajāy 💻	Michael Mior 📖

License

MIT