mrepol742/npm-guard
GitHub: mrepol742/npm-guard
NPM Guard 是一个扫描本地 npm 缓存以检测可疑包和已知问题的供应链安全守护进程。
Stars: 1 | Forks: 2
# NPM Guard
NPM Guard 会扫描本地 npm 缓存，以检测可疑包和已知问题。它支持单次扫描、watcher 模式、cron 定时调度，以及同时运行两者的混合模式。
## 要求
- Python 3
- Linux 环境
- npm 缓存目录（默认为 `~/.npm`）
## 安装说明
通过 AUR 安装：
```
yay -S npm-guard
```
或者如果您倾向于手动安装：
克隆仓库并安装依赖：
```
git clone https://github.com/mrepol742/npm-guard.git --depth=1
cd npm-guard
```
创建虚拟环境并安装依赖项：
```
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
## 配置
编辑 `config.yaml` 以适应您的环境和所需的扫描模式。
关键字段：
- `scan_mode`：`manual`、`watcher`、`cron` 或 `hybrid`
- `cron.expression`：在 `cron` 和 `hybrid` 模式中使用的 5 段式 cron 表达式
- `paths.npm_cache`：您的 npm 缓存路径
- `paths.quarantine`：用于隔离文件的目录
- `security.quarantine_enabled`：启用或禁用隔离
- `security.risk_threshold`：触发隔离的最低分数
示例：
```
scan_mode: manual
cron:
expression: "0 */6 * * *"
paths:
npm_cache: "/home/you/.npm"
quarantine: "/home/you/.npm-quarantine"
security:
quarantine_enabled: true
risk_threshold: 50
```
## 运行
入口文件是 `main.py`。它会使用 `config.yaml` 中的 `scan_mode`。
一次性深度扫描：
```
python main.py
```
Watcher 模式（实时监控）：
```
# 设置 scan_mode: watcher
python main.py
```
Cron 模式（定时扫描）：
```
# 设置 scan_mode: cron
python main.py
```
混合模式（watcher + cron）：
```
# 设置 scan_mode: hybrid
python main.py
```
## 统计与维护
显示数据库统计信息：
```
python main.py --stats
```
清空数据库：
```
python main.py --clear
```
## Systemd
您有两种选择。
选项 A：Arch Linux 软件包
使用 `PKGBUILD`。它会安装 /usr/bin/npm-guard 包装器和 systemd 服务。
选项 B：手动安装
```
sudo rsync -av --exclude='.git' --exclude='venv' ./ /opt/npm-guard/
cd /opt/npm-guard
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
sudo tee /usr/bin/npm-guard >/dev/null <<'SCRIPT'
#!/usr/bin/env bash
cd /opt/npm-guard
exec /opt/npm-guard/venv/bin/python3 /opt/npm-guard/main.py
SCRIPT
sudo chmod +x /usr/bin/npm-guard
sudo install -Dm644 systemd/npm-guard.service /etc/systemd/system/npm-guard.service
sudo systemctl daemon-reload
sudo systemctl enable npm-guard.service --now
```
## 注意事项
- 深度扫描和 watcher 模式可以检测 tarball，即使 npm 缓存存储它们时没有 `.tgz` 扩展名，包括 `_cacache/content-v2` 下的条目。
- 大型的 npm 缓存可能需要较长时间来扫描。
- 此项目仅在 Arch Linux 上进行了测试，可能需要针对其他 Linux 发行版进行调整。
## 性能
由于此工具旨在本地 npm 缓存上运行，性能可能会因缓存大小和包的数量而异。
深度扫描模式可能会占用大量资源，特别是对于大型缓存，而 watcher 模式经过优化，能够以最小的开销进行实时监控。
Cron 模式允许在非高峰时段进行定时扫描，以最大限度地减少对系统性能的影响。
现在您明白为什么杀毒软件如此昂贵，以及为什么它需要如此频繁地更新了吧。
## 许可证
本项目采用 MIT 许可证授权。详情请参阅 [LICENSE](LICENSE) 文件。
本项目仅供教育目的使用。使用风险自负。
作者不对本软件造成的任何损害或损失负责。
标签：Cilium, IP 地址批量处理, NPM, Python, 守护进程, 安全扫描, 文档安全, 无后门, 时序注入, 系统服务, 网络信息收集