**JS-X-Ray** is a JavaScript & TypeScript [SAST](https://github.com/resources/articles/what-is-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](https://github.com/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
- Track `require()`, `import`, and dynamic imports with full variable tracing
- Detect obfuscated code and identify the tool used (jsfuck, jjencode, obfuscator.io, and more)
- Flag malicious patterns: data exfiltration, `process.env` serialization, unsafe shell commands
- Detect vulnerable code: `eval()`, `Function()` constructor, ReDoS-prone regexes, SQL injection
- Flag weak cryptographic algorithms (MD5, SHA1, etc.)
- Extract infrastructure indicators: URLs, IPs, hostnames, emails
- Configurable sensitivity modes (conservative/aggressive) and extensible probe system
- Supports both JavaScript and TypeScript
## π Getting Started
These packages are available in the Node package repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ npm i @nodesecure/js-x-ray
# or
$ yarn add @nodesecure/js-x-ray
```
## π Usage
```js
import { AstAnalyser } from "@nodesecure/js-x-ray";
const scanner = new AstAnalyser();
const { warnings, dependencies } = await scanner.analyseFile("./file.js");
console.log(dependencies);
console.dir(warnings, { depth: null });
```
For the full API documentation, warning catalog, and advanced usage, see the [@nodesecure/js-x-ray package README](./workspaces/js-x-ray/README.md).
## Workspaces
- [@nodesecure/js-x-ray](./workspaces/js-x-ray)
- [@nodesecure/js-x-ray-ai](./workspaces/js-x-ray-ai)
## π₯ Contributors guide
If you are a developer **looking to contribute** to the project, you must first read the [CONTRIBUTING](./CONTRIBUTING.md) guide.
Once you have finished your development, check that the tests (and linter) are still good by running the following script:
```bash
$ npm run check
```
> [!CAUTION]
> In case you introduce a new feature or fix a bug, make sure to include tests for it as well.
### Internal APIs
For contributors working on the JS-X-Ray internals, the following resources document low-level utilities and AST manipulation patterns:
- [ESTree utilities](./workspaces/js-x-ray/src/estree/README.md) - Low-level helpers to manipulate ESTree AST nodes
- [ESTree assignment and declaration patterns (french)](./workspaces/js-x-ray/docs/estree/patterns-french.md) - Reference guide for JavaScript assignment and declaration patterns in AST form
### Benchmarks
The performance of js-x-ray is measured and tracked using [mitata](https://github.com/evanwashere/mitata).
To run the benchmarks:
1. Navigate to `workspaces/js-x-ray`.
2. Run `npm run bench`.
The benchmark results are stored in workspaces/js-x-ray/benchmark/report.json. Do not edit this file manually; it is automatically updated on every pull request.
## Contributors β¨
[](#contributors-)
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
