README.md

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 JS or TS code into an Abstract Syntax Tree (AST) 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)
  • Weak scrypt parameters (insufficient cost, short or hardcoded salt)
• 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
• Support both JavaScript and TypeScript

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

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
• SourceParser
• VariableTracer

Warnings

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

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"
  | "prototype-pollution"
  | "unsafe-vm-context"
  | 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", "weak-scrypt"]
});

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.)
• weak-scrypt - Detects weak scrypt parameters (low cost, short or hardcoded salt)

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
prototype-pollution	No	Detected use of __proto__ to pollute object prototypes
weak-scrypt ⚠️	Yes	Usage of weak scrypt parameters (low cost, short or hardcoded salt)
unsafe-vm-context ⚠️	No	Usage of dangerous vm.runInNewContext and (vm.Script(code,options)).runInContext

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

License

MIT