JavaScript/Node.js 安全分析工具 js-x-ray 使用指南

一、工具概述

js-x-ray 是一款功能强大的开源 SAST (静态应用程序安全测试) 扫描工具，专门用于检测 JavaScript 和 Node.js 代码中的常见恶意行为和模式。该工具通过执行 JavaScript AST (抽象语法树) 分析来识别潜在的安全风险。

主要特点

• 基于 Node-Secure AST Analysis 实现，提供更好的代码演化支持
• 旨在帮助开发人员和安全研究人员快速识别危险代码和模式
• 专注于检测明显出于恶意目的添加或注入的代码
• 能够识别攻击者常用的代码隐藏和混淆技术

二、核心功能

1. 依赖项分析

   • 检索 JavaScript 文件所需的依赖项
   • 跟踪文件中的 require 语句

2. 安全检测

   • 检测不安全的正则表达式 (可能导致 ReDoS 攻击)
   • 识别危险的全局变量使用
   • 发现常见的攻击模式和可疑 API 调用

3. 代码混淆检测

   • 识别可能经过混淆处理的代码
   • 在可能的情况下检测使用的混淆工具

4. 异常检测

   • 当 AST 分析遇到问题或无法跟踪语句时发出警告
   • 检测编码文本 (十六进制、Unicode 序列、Base64 等)

5. 代码质量分析

   • 检测过短的标识符 (平均长度低于 1.5)
   • 识别可疑的文字组合 (可疑分数总和大于 3)

三、安装方法

js-x-ray 可以通过 npm 或 yarn 安装：

# 使用 npm 安装
$ npm i js-x-ray

# 或使用 yarn 安装
$ yarn add js-x-ray

四、基本使用方法

1. 基本分析示例

创建一个测试文件 file.js：

try {
  require("http");
} catch (err) {
  // do nothing
}

const lib = "crypto";
require(lib);
require("util");
require(Buffer.from("6673", "hex").toString());

使用 js-x-ray 进行分析：

const { runASTAnalysis } = require("js-x-ray");
const { readFileSync } = require("fs");

// 读取文件内容
const str = readFileSync("./file.js", "utf-8");

// 执行分析
const { warnings, dependencies } = runASTAnalysis(str);

// 获取依赖项名称
const dependenciesName = [...dependencies];
// 获取 try 语句中的依赖项
const inTryDeps = [...dependencies.getDependenciesInTryStatement()];

console.log(dependenciesName); // 输出: ['http', 'crypto', 'util', 'fs']
console.log(inTryDeps);       // 输出: ['http']
console.log(warnings);        // 输出警告信息

2. API 详解

runASTAnalysis(str: string, options?: RuntimeOptions): Report

参数:

• str: 要分析的 JavaScript 代码字符串
• options: 可选配置对象
  • module: 布尔值，表示是否为模块代码
  • isMinified: 布尔值，表示代码是否经过压缩

返回值 (Report 对象):

interface Report {
  dependencies: ASTDeps;        // 检测到的依赖项
  warnings: Warning[];          // 安全警告列表
  idsLengthAvg: number;         // 标识符平均长度
  stringScore: number;          // 字符串可疑分数
  isOneLineRequire: boolean;    // 是否为单行 require
}

generateWarning(kind: string, options?: WarningOptions): Warning

用于生成自定义警告。

参数:

• kind: 警告类型
• options: 警告选项
  • location: 代码位置信息
  • file: 可选，文件名
  • value: 可选，相关值

五、警告类型详解

js-x-ray 可以返回多种类型的警告，每种警告对应不同的安全问题：

六、高级使用技巧

1. 分析 try-catch 中的依赖项

const { dependencies } = runASTAnalysis(code);
const depsInTry = dependencies.getDependenciesInTryStatement();

2. 检测特定类型的警告

const { warnings } = runASTAnalysis(code);
const unsafeRegexWarnings = warnings.filter(
  w => w.kind === 'unsafe-regex'
);

3. 处理编码文本

const encodedWarnings = warnings.filter(
  w => w.kind === 'encoded-literal'
);

七、实际应用场景

1. 检测潜在恶意代码

const { runASTAnalysis } = require('js-x-ray');

function detectMalicious(code) {
  const { warnings } = runASTAnalysis(code);
  return warnings.some(w => 
    ['unsafe-stmt', 'obfuscated-code'].includes(w.kind)
  );
}

2. 依赖项安全检查

function checkDependencies(code) {
  const { dependencies, warnings } = runASTAnalysis(code);
  const unsafeDeps = ['child_process', 'fs', 'eval'];
  
  return {
    deps: [...dependencies],
    hasUnsafe: [...dependencies].some(d => unsafeDeps.includes(d)),
    warnings
  };
}

八、项目资源

• 许可证: MIT 开源许可证
• 项目地址: GitHub 仓库
• 案例研究: 项目中的 cases 目录包含多个可分析的可疑代码示例

九、最佳实践

1. 集成到开发流程

   • 在代码提交前运行 js-x-ray 检查
   • 作为 CI/CD 管道的一部分

2. 结果分析

   • 优先处理 unsafe-stmt 和 unsafe-regex 警告
   • 对 obfuscated-code 警告进行人工审查

3. 性能考虑

   • 对大文件或项目考虑增量分析
   • 对关键代码路径进行重点分析

十、限制与注意事项

1. 静态分析的局限性

   • 无法检测运行时动态生成的恶意代码
   • 某些复杂混淆技术可能绕过检测

2. 误报处理

   • 需要安全知识来正确解读结果
   • 某些合法代码可能触发警告 (如编码的配置值)

3. 实验性功能

   • 混淆代码检测 (obfuscated-code) 仍处于实验阶段

通过合理使用 js-x-ray，开发团队可以显著提高 JavaScript/Node.js 应用程序的安全性，及早发现潜在的安全风险。建议将本工具作为完整安全策略的一部分，与其他安全工具和实践结合使用。