JS-X-Ray is a JavaScript & TypeScript SAST for identifying malicious patterns, security vulnerabilities, and code anomalies. Think of it as ESLint, but dedicated to security analysis. Originally created for NodeSecure CLI, JS-X-Ray has become an independent and serious option for supply chain protection.

🔎 How It Works

JS-X-Ray parses code into an Abstract Syntax Tree (AST) using Meriyah with no extensive usage of RegEx or Semgrep rules. This enables variable tracing, dynamic import resolution, and detection of sophisticated obfuscation that pattern-matching tools miss. The tradeoff is that JS-X-Ray is purely dedicated to the JavaScript/TypeScript ecosystem.

💡 Features

• Retrieve required dependencies and files for Node.js
  • Track require(), import, and dynamic imports with full tracing capabilities
  • Detect untraceable and malicious import patterns
• Scan entire projects with multi-file analysis capabilities
• Extract infrastructure components (URLs, IPs, hostnames, emails)
• Detect malicious code patterns
  • Obfuscated code with tool identification (freejsobfuscator, jsfuck, jjencode, obfuscator.io, morse, Trojan Source)
  • Data exfiltration and unauthorized system information collection
  • Suspicious files with excessive encoded literals
• Identify vulnerable code patterns
  • Unsafe statements (eval(), Function() constructor)
  • ReDoS vulnerabilities in regular expressions
  • SQL injection vulnerabilities
  • Unsafe shell commands in spawn() or exec() calls
  • process.env serialization attempts
• Flag weak cryptographic usage
  • Deprecated algorithms (MD5, SHA1, MD4, MD2, RIPEMD160)
• Detect code quality issues
  • Monkey-patching of built-in prototypes
  • Encoded literals (hex, Unicode, base64)
  • Suspicious URLs and links
  • Short identifier lengths (obfuscation indicators)
  • Synchronous I/O and logging usage (optional)
• Configurable sensitivity modes (conservative/aggressive) and extensible probe system

💃 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.

Scanning a complete project

By itself, JS-X-Ray does not provide utilities to walk and scan a complete project. However, NodeSecure has packages to achieve that:

import { ManifestManager } from "@nodesecure/mama";
import { NpmTarball } from "@nodesecure/tarball";

const mama = await ManifestManager.fromPackageJSON(
  "./path/to/package.json"
);
const extractor = new NpmTarball(mama);

const {
  composition, // Project composition (files, dependencies, extensions)
  conformance, // License conformance (SPDX)
  code         // JS-X-Ray analysis results
} = await extractor.scanFiles();

console.log(code);

The NpmTarball class uses JS-X-Ray under the hood, and ManifestManager locates entry (input) files for analysis.

Alternatively, you can use EntryFilesAnalyser directly for multi-file analysis. See the EntryFilesAnalyser API documentation for more details.

📚 API

• AstAnalyser
• EntryFilesAnalyser
• CollectableSet
• VariableTracer

Warnings

type OptionalWarningName =
  | "synchronous-io"
  | "log-usage";

type WarningName =
  | "parsing-error"
  | "encoded-literal"
  | "unsafe-regex"
  | "unsafe-stmt"
  | "short-identifiers"
  | "suspicious-literal"
  | "suspicious-file"
  | "obfuscated-code"
  | "weak-crypto"
  | "shady-link"
  | "unsafe-command"
  | "unsafe-import"
  | "serialize-environment"
  | "data-exfiltration"
  | "sql-injection"
  | "monkey-patch"
  | OptionalWarningName;

interface Warning<T = WarningName> {
  kind: T | (string & {});
  file?: string;
  value: string | null;
  source: string;
  location: null | SourceArrayLocation | SourceArrayLocation[];
  i18n: string;
  severity: "Information" | "Warning" | "Critical";
  experimental?: boolean;
}

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

Optional Warnings

Some warnings are not included by default and must be explicitly requested through the AstAnalyser API.

import { AstAnalyser } from "@nodesecure/js-x-ray";

// Enable all optional warnings
const scanner = new AstAnalyser({
  optionalWarnings: true
});

// Or enable specific optional warnings
const scannerSpecific = new AstAnalyser({
  optionalWarnings: ["synchronous-io", "log-usage"]
});

The following warnings are optional:

• synchronous-io - Detects synchronous I/O operations that could impact performance
• log-usage - Tracks usage of logging functions (console.log, logger.info, etc.)

Internationalization (i18n)

Warnings support internationalization through the @nodesecure/i18n package. Each warning has an i18n key that can be used to retrieve localized descriptions.

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

await i18n.extendFromSystemPath(jsxray.i18nLocation());

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

Warning Catalog

Click on the warning name for detailed documentation and examples.

Critical Severity

Name	Experimental	Description
suspicious-file	No	Suspicious file containing more than ten encoded literals
obfuscated-code	Yes	High probability of code obfuscation detected

Warning Severity

Name	Experimental	Description
unsafe-import	No	Unable to follow an import (require, require.resolve) statement
unsafe-regex	No	Unsafe regular expression that may be vulnerable to ReDoS attacks
unsafe-stmt	No	Usage of dangerous statements like eval() or Function("")
unsafe-command	Yes	Suspicious commands detected in spawn() or exec()
short-identifiers	No	Average identifier length below 1.5 characters (possible obfuscation)
suspicious-literal	No	Suspicious literal values detected in source code
weak-crypto	No	Usage of weak cryptographic algorithms (MD5, SHA1, etc.)
shady-link	No	Suspicious or potentially malicious URLs detected
synchronous-io ⚠️	Yes	Synchronous I/O operations that may impact performance
serialize-environment	No	Attempts to serialize process.env (potential data exfiltration)
data-exfiltration	No	Potential unauthorized transfer of sensitive data
sql-injection	No	Potential SQL injection vulnerability detected
monkey-patch	No	Modification of built-in JavaScript prototype properties

Information Severity

Name	Experimental	Description
parsing-error	No	AST parser encountered an error while analyzing the code
encoded-literal	No	Encoded literal detected (hexadecimal, Unicode, base64)
log-usage ⚠️	No	Usage of logging functions (console.log, logger methods, etc.)

Note

Warnings marked with ⚠️ are optional and must be explicitly enabled (see Optional Warnings section).

Contributors guide

If you are a developer looking to contribute to the project, you must first read the CONTRIBUTING guide.

Once you have finished your development, check that the tests (and linter) are still good by running the following script:

$ npm run check

Caution

In case you introduce a new feature or fix a bug, make sure to include tests for it as well.

Benchmarks

The performance of js-x-ray is measured and tracked using mitata.

To run the benchmarks:

1. Navigate to workspaces/js-x-ray.
2. Run npm run bench.

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
js-x-ray-ai	@nodesecure/js-x-ray-ai
estree-ast-utils	@nodesecure/estree-ast-utils
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 📖
Hamed Mohamed 💻

License

MIT