npm-api-analyzer

v1.0.3

Published

5 months ago

CLI tool to analyze npm packages for network API usage, prototype pollution, and security vulnerabilities

0High
0Medium
0Low

galenyuan

npm security analysis cli vulnerability network-api prototype-pollution code-scanning

NPM 安全分析工具

一个强大的 TypeScript 工具，用于深度分析 npm 包的安全风险，检测网络请求、DOM 操作、动态 JavaScript 执行和原型链污染等潜在风险行为。

🎯 功能特性

📡 全面的网络 API 检测

Fetch API：fetch()、window.fetch()、globalThis.fetch()
XMLHttpRequest：new XMLHttpRequest()、各种XHR方法
WebSocket：new WebSocket()、WebSocket连接
图片加载：new Image()、动态图片请求
Node.js 网络模块：require("http/https")、axios、node-fetch等
其他网络 API：EventSource、navigator.sendBeacon()、缓存API等

🔧 DOM 操作检测

元素创建：document.createElement()、动态HTML元素
内容操作：innerHTML、outerHTML、insertAdjacentHTML()
元素查询：querySelector()、getElementById()等
文档操作：document.write()、document.open()
节点操作：appendChild()、removeChild()、replaceChild()

⚡ 动态 JavaScript 执行检测

代码执行：eval()、new Function()、window.eval()
定时器执行：setTimeout()、setInterval() 与字符串参数
动态脚本：动态创建和插入 <script> 标签
动态导入：import()、动态 require() 调用
Web Workers：new Worker()、new SharedWorker()
Blob URL：URL.createObjectURL() 用于脚本执行

🚨 原型链污染检测 (NEW!)

直接原型修改：Object.prototype.polluted = true、Array.prototype[key] = value
proto 操作：obj.__proto__ = evil、obj["__proto__"] = malicious
构造器污染：obj.constructor.prototype[key] = value
对象方法污染：Object.setPrototypeOf()、Object.defineProperty()
JSON 解析风险：JSON.parse('{"__proto__": {"admin": true}}')
动态属性访问：obj["constructor"]["prototype"]、动态键访问
循环污染：for-in 循环中的动态属性赋值
代理陷阱：Proxy 的 setPrototypeOf、defineProperty 陷阱

📊 智能风险评估

多维度风险分析：基于API类型、数量和危险程度
上下文代码提取：显示API调用前后的代码片段
精确定位：文件路径、行号、列号定位
风险等级标识：🟢 低风险、🟡 中等风险、🔴 高风险
原型污染专项评估：识别所有主要的原型链攻击向量

📝 多格式报告输出

Markdown 报告：结构化、易读的安全分析报告
文本报告：简洁的控制台输出格式
JSON 报告：机器可读的结构化数据

🚀 快速开始

全局安装（推荐）

# 全局安装
npm install -g npm-api-analyzer

# 直接使用
npm-api-analyzer <包名> <版本>

# 示例：分析 express 4.18.2
npm-api-analyzer express 4.18.2

# 生成 Markdown 报告
npm-api-analyzer lodash 4.17.21 --format markdown --output report.md

# 生成 JSON 报告
npm-api-analyzer react 18.2.0 --format json --output analysis.json

本地开发使用

# 克隆仓库
git clone https://github.com/yourusername/npm-security-analyzer.git
cd npm-security-analyzer

# 安装依赖
npm install
npm run build

# 使用
npm start <包名> <版本>

# 示例：分析 express 4.18.2
npm start express 4.18.2

# 生成 Markdown 报告
npm start lodash 4.17.21 -- --format markdown --output report.md

# 生成 JSON 报告
npm start react 18.2.0 -- --format json --output analysis.json

命令行参数

npm-api-analyzer <package-name> <version> [options]

Options:
  --format <format>   输出格式: text, json, markdown (默认: text)
  --output <file>     保存报告到指定文件
  -h, --help         显示帮助信息

Examples:
  npm-api-analyzer axios 1.6.0
  npm-api-analyzer express 4.18.2 --format markdown
  npm-api-analyzer lodash 4.17.21 --output report.txt
  npm-api-analyzer react 18.2.0 --format json --output analysis.json

🧪 测试套件

项目包含完整的原型链污染检测测试套件：

运行测试

# 基础单元测试
npm test

# 全面测试套件 (74个测试场景)
npm run test:comprehensive

# 边缘情况和性能测试
npm run test:edge-cases

# 验证和准确性测试
npm run test:validation

# 运行所有测试
npm run test:all

# 演示测试样例
npm run test:demo

# 快速演示 (推荐)
npm run demo

测试覆盖率

74个测试场景，覆盖所有原型污染攻击向量
97.1% 准确率，零误报率
超高性能：142,857 次检测/秒
全面覆盖：高、中、低风险场景完整测试

测试分类

直接原型修改测试：点符号和括号访问
proto 操作测试：所有变体和嵌套访问
构造器原型测试：constructor.prototype 链污染
对象方法测试：defineProperty、setPrototypeOf等
动态访问测试：变量键和计算属性
JSON 解析测试：危险的 JSON.parse 模式
循环污染测试：for-in 循环中的动态赋值
代理陷阱测试：Proxy 启用的污染向量
边缘情况测试：空白变体、混淆代码、性能测试
误报防护测试：确保合法代码不被误报

🎯 快速演示

# 运行交互式演示，查看原型污染检测效果
npm run demo

此命令将展示检测器如何识别各种原型污染模式，包括：

直接原型修改 (Object.prototype.polluted = true)
JSON 解析风险 (JSON.parse 包含 __proto__)
动态 __proto__ 访问
循环中的动态赋值污染
安全代码的正确忽略

📖 编程接口

import { NPMSecurityAnalyzer } from './src/analyzer';
import { Reporter } from './src/reporter';

const analyzer = new NPMSecurityAnalyzer();

async function analyzePackage() {
  try {
    const result = await analyzer.analyzePackage('package-name', '1.0.0');
    
    // 生成不同格式的报告
    const textReport = Reporter.generateReport(result);
    const markdownReport = Reporter.generateMarkdownReport(result);
    const jsonReport = Reporter.generateJSONReport(result);
    
    console.log(markdownReport);
  } finally {
    analyzer.cleanup();
  }
}

📋 报告样例

Markdown 格式报告预览

# NPM Package Security Analysis Report

**Package:** `[email protected]`  
**Analysis Date:** 2025-07-23T03:19:55.228Z  
**Risk Level:** 🟡 MEDIUM

## 📊 Executive Summary

- **Total API Calls Detected:** 8
- **Network APIs:** 5
- **DOM Operations:** 0
- **Dynamic JavaScript:** 3
- **🚨 Prototype Pollution:** 0

### ⚠️ Risk Factors

- Dynamic JavaScript execution detected (3 instances)

## 🌐 Network API Usage

### 🟡 MEDIUM `require("http/https")`

**Occurrences:** 5

- **lib/application.js:23**
  ```javascript
  var http = require('http');

🛡️ Security Recommendations

🟡 MEDIUM Medium Risk Package

This package requires careful evaluation:

Review all network API usage for legitimate purposes
Implement network monitoring if using in production


## 🔍 检测的API类别

### 🌐 网络 APIs
| API类型 | 风险等级 | 示例 |
|---------|----------|------|
| `fetch` | 🟡 中等 | `fetch()`, `window.fetch()` |
| `xhr` | 🟡 中等 | `new XMLHttpRequest()` |
| `websocket` | 🔴 高 | `new WebSocket()` |
| `node` | 🟡 中等 | `require("https")`, `import from "axios"` |
| `other` | 🟢-🟡 低到中等 | `new Image()`, `EventSource`, `navigator.sendBeacon()` |

### 🔧 DOM 操作 APIs
| API类型 | 风险等级 | 示例 |
|---------|----------|------|
| `dom-manipulation` | 🟢-🔴 低到高 | `createElement()`, `innerHTML`, `appendChild()` |

### ⚡ 动态 JavaScript APIs
| API类型 | 风险等级 | 示例 |
|---------|----------|------|
| `eval` | 🔴 高 | `eval()`, `new Function()`, `setTimeout("code")` |
| `dynamic-script` | 🟡-🔴 中等到高 | 动态脚本插入, `import()`, Web Workers |

### 🚨 原型链污染 APIs
| API类型 | 风险等级 | 示例 |
|---------|----------|------|
| `prototype-modification` | 🔴 高 | `Object.prototype.polluted = true`, `obj.__proto__ = evil` |
| `prototype-modification` | 🟡 中等 | `for-in` 循环动态赋值, 动态属性访问 |

## 🛡️ 风险等级说明

- **🟢 低风险**：最少或无安全隐患的API使用
- **🟡 中等风险**：需要审查的API使用，可能存在安全隐患
- **🔴 高风险**：危险的API使用，需要重点关注和审查

## 🎯 安全考虑

此工具帮助识别npm包中的潜在安全风险：

### 网络安全风险
- 未授权的数据泄露和外发
- 与恶意服务器的通信
- 绕过网络安全策略

### DOM安全风险  
- XSS (跨站脚本) 攻击向量
- 恶意内容注入
- DOM污染和篡改

### 动态执行风险
- 代码注入攻击
- 任意代码执行
- 绕过安全沙箱

### 原型链污染风险
- 全局对象污染和权限提升
- 应用逻辑绕过和安全策略规避
- 拒绝服务攻击 (DoS)
- 远程代码执行 (RCE) 潜在风险
- 数据完整性破坏

## ⚠️ 使用限制

- **静态分析**：仅检测源代码中的静态API调用
- **误报可能**：合法的网络使用可能被标记为风险
- **混淆代码**：无法检测经过混淆或加密的API调用
- **文件类型**：仅支持JavaScript/TypeScript文件分析
- **动态构造**：无法检测运行时动态构造的API调用

## 🤝 贡献指南

1. **Fork** 项目仓库
2. **创建** 功能分支 (`git checkout -b feature/amazing-feature`)
3. **提交** 更改 (`git commit -m '添加某个很棒的功能'`)
4. **推送** 到分支 (`git push origin feature/amazing-feature`)
5. **创建** Pull Request

### 开发建议
- 添加新的API检测规则时，请更新相应的测试用例
- 保持代码风格一致
- 为新功能编写文档

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持

如果您遇到问题或有功能建议，请：
1. 查看现有的 Issues
2. 创建新的 Issue 并提供详细信息
3. 或者直接提交 Pull Request

---

**⚠️ 免责声明**：此工具仅用于安全审计目的。检测结果需要人工验证，工具不能替代专业的安全审查。