cybershaykh/npxconfuse
GitHub: cybershaykh/npxconfuse
npxconfuse 是一款 npm 供应链安全扫描器，用于检测项目脚本和依赖中引用了未被声明注册的包名，从而防止攻击者通过抢注同名包实现远程代码执行。
Stars: 11 | Forks: 2
# npxconfuse
` 调用指向了 npm 上**未被声明**的包。攻击者可以注册该名称，并在运行你脚本的每个开发者和 CI pipeline 上实现 RCE。 |
| 🔴 | **Bin 不匹配** | `CRITICAL` | 带有 scope 的包（`@scope/pkg`）暴露了一个**不同的、无 scope 且未被声明的**二进制名称。由于 npm 二进制文件不能包含 `/`，这种不匹配是 scoped 包固有的。 |
| 🟡 | **依赖混淆** | `HIGH` | 私有/内部包名（企业级 scoped 包、`file:` 引用）在公共 npm registry 上**未注册**。攻击者可以发布同名包并劫持安装。 |
| 🟠 | **名称冲突** | `MEDIUM` | 已使用的包名存在于公共 registry 中，但**属于不同的实体** —— 这可能是值得调查的 typo-squatting（域名/包名抢注）或 namespace 碰撞。 |
### 30 秒了解攻击原理
```
# 你的 package.json 脚本：
"scripts": {
"dev": "npx my-internal-tool --watch" # ← name is UNCLAIMED on npm
}
# 攻击者：
npm publish my-internal-tool # ← now every `npm run dev` runs attacker code
```
`npxconfuse` 可以自动发现你整个代码库、GitHub 组织以及面向公众的网络资产中这些未被声明的名称。
## 安装说明
**环境要求：** Node.js >= 18
```
# 直接运行（无需安装）
npx npxconfuse scan ./my-project
# 全局安装
npm install -g npxconfuse
# 作为 dev dependency 本地安装
npm install --save-dev npxconfuse
```
## 快速入门
```
# 1. 扫描你当前的项目
npxconfuse scan . # basic: package.json files
npxconfuse scan . --deep # thorough: also scans JS bundles
# 2. 输出 JSON 结果扫描（用于 CI/CD pipelines）
npxconfuse scan . -o json
# 3. 扫描并保存结果
npxconfuse scan . --save findings.json
# 4. 直接检查一系列 package 名称
npxconfuse check names.txt
```
## 使用方法
### `scan` — 扫描本地目录
```
npxconfuse scan [options]
# 项目基础扫描
npxconfuse scan ./my-project
# 深度扫描 — 同时解析 JS bundles 中的 imports/requires
npxconfuse scan ./my-project --deep
# JSON 输出到 stdout
npxconfuse scan ./my-project -o json
# 保存到文件
npxconfuse scan ./my-project --save results.csv
```
**扫描内容：**
- `package.json` — 脚本（npx 调用）、bin 字段、依赖项
**使用 `--deep` 时：**
- JS bundle（`*.js`, `*.mjs`, `*.cjs`）— 解析 `require()`、`import` 以及内嵌的 `package.json` 块
**跳过内容：**
- `node_modules/`、`.git/`、`dist/`、`build/`、`.next/`、`coverage/`
### `github` — 扫描 GitHub 组织
```
npxconfuse github [options]
# 扫描一个 org（需要 GITHUB_TOKEN）
export GITHUB_TOKEN=ghp_your_token_here
npxconfuse github my-company
# 限制为 100 个 repos
npxconfuse github my-company --max-repos 100
# GitHub Enterprise
npxconfuse github my-company --github-enterprise https://github.internal.example.com
```
**Token 要求：**
- 在 [github.com/settings/tokens](https://github.com/settings/tokens) 创建 token
- Scope：`repo`（私有仓库）或 `public_repo`（仅限公共仓库）
### `web` — 扫描网络域名
```
npxconfuse web
# domains.txt — 每行一个 domain/URL：
# example.com
# https://app.example.com
# api.example.org
npxconfuse web domains.txt
```
探测每个域名的：
- 暴露的 `/package.json`、`/package-lock.json`
- `
npx 混淆漏洞扫描器
在攻击者之前，找出你的供应链中未被声明的 npm 包名。
