@nodesecure/js-x-ray
    TypeScript icon, indicating that this package has built-in type declarations

    5.0.1 • Public • Published

    js-x-ray

    version Maintenance Security Responsible Disclosure mit build

    JavaScript AST analysis. This package has been created to export the Node-Secure 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 a set of security notions.

    Note I have no particular background in security. I'm simply becoming more and more interested and passionate about static code analysis. But I would be more than happy to learn that my work can help prevent potential future attacks (or leaks).

    Goals

    The objective of the project is to successfully detect all potentially suspicious JavaScript codes.. The target is obviously codes that are added or injected for malicious purposes..

    Most of the time these hackers will try to hide the behaviour of their codes 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..

    Features Highlight

    • Retrieve required dependencies and files for Node.js.
    • Detect unsafe RegEx.
    • Get warnings when the AST Analysis as a problem or when not able to follow a statement.
    • Highlight common attack patterns and API usages.
    • Capable to follow the usage of dangerous Node.js globals.
    • Detect obfuscated code and when possible the tool that has been used.

    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 { runASTAnalysis } from "@nodesecure/js-x-ray";
    import { readFileSync } from "fs";
    
    const str = readFileSync("./file.js", "utf-8");
    const { warnings, dependencies } = runASTAnalysis(str);
    
    const dependenciesName = [...dependencies];
    const inTryDeps = [...dependencies.getDependenciesInTryStatement()];
    
    console.log(dependenciesName);
    console.log(inTryDeps);
    console.log(warnings);

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

    Warning There is also a lot of suspicious code example in the ./examples cases directory. Feel free to try the tool on these files.

    Warnings

    This section describes how use warnings export.

    type WarningName = "parsing-error"
    | "encoded-literal"
    | "unsafe-regex"
    | "unsafe-stmt"
    | "unsafe-assign"
    | "short-identifiers"
    | "suspicious-literal"
    | "obfuscated-code"
    | "weak-crypto"
    | "unsafe-import";
    
    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.getToken(jsxray.warnings["parsing-error"].i18n));

    Warnings Legends

    Warning versions of NodeSecure greather than v0.7.0 are no longer compatible with the warnings table below.

    This section describe 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 RegEx as been detected as unsafe and may be used for a ReDoS Attack.
    unsafe-stmt Usage of dangerous statement like eval() or Function("").
    unsafe-assign Assignment of a protected global like process or require.
    encoded-literal An encoded literal has been detected (it can be an hexa value, unicode sequence or a base64 string)
    short-identifiers This mean that all identifiers has an average length below 1.5.
    suspicious-literal A suspicious literal has been found in the source code.
    obfuscated-code ✔️ There's a very high probability that the code is obfuscated.
    weak-crypto ✔️ The code probably contains a weak crypto algorithm (md5, sha1...)

    API

    runASTAnalysis(str: string, options?: RuntimeOptions): Report
    interface RuntimeOptions {
        module?: boolean;
        isMinified?: boolean;
    }

    The method take a first argument which is the code you want to analyse. It will return a Report Object:

    interface Report {
        dependencies: ASTDeps;
        warnings: Warning[];
        idsLengthAvg: number;
        stringScore: number;
        isOneLineRequire: boolean;
    }
    runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions): Promise< ReportOnFile >
    interface RuntimeOptions {
        module?: boolean;
        isMinified?: boolean;
    }

    Run the SAST scanner on a given JavaScript file.

    export type ReportOnFile = {
      ok: true,
      warnings: Warning[];
      dependencies: ASTDeps;
      isMinified: boolean;
    } | {
      ok: false,
      warnings: Warning[];
    }

    Contributors

    All Contributors

    Thanks goes to these wonderful people (emoji key):


    Gentilhomme

    💻 📖 👀 🛡️ 🐛

    Nicolas Hallaert

    📖

    Antoine

    💻

    Mathieu

    💻

    Vincent Dhennin

    💻 ⚠️

    Tony Gorez

    💻 📖 ⚠️

    License

    MIT

    Install

    npm i @nodesecure/js-x-ray

    DownloadsWeekly Downloads

    282

    Version

    5.0.1

    License

    MIT

    Unpacked Size

    58.1 kB

    Total Files

    36

    Last publish

    Collaborators

    • antoine-coulon
    • kawacrepe
    • fraxken
    • tonygo