ariary/soa
GitHub: ariary/soa
soa 是一个依赖防火墙 CLI，用于在下载前拦截供应链攻击。
Stars: 0 | Forks: 0
# soa 与 tonga
*Tonga soa* — 马达加斯加语中的“欢迎”。🇲🇬
您的软件包现在要经过海关检查了。
## 核心机制
两个二进制文件，一个任务：在恶意依赖到达您的机器之前将其拦截。
- **`soa`** — 客户端。它封装了您的包管理器命令，并通过本地代理拦截每一个依赖下载。在任何存档到达您的机器之前，它都会根据安全策略服务器进行检查。如果软件包太新、太可疑或分析失败，它将在边境被拦截。
- **`tonga`** — 后端。运行检查服务器和告警信息源。
想象一下[供应链攻击](https://github.com/ariary/malicious-go-package)：一个您从未听说过的依赖项潜入您的构建过程，并在安装时运行任意代码。`soa` 会在它到达您的机器之前将其捕获。
## 操作演示
终端 1，启动检查服务器：
```
tonga serve
```
终端 2，在任何命令前加上 `soa` 前缀：
```
soa make build
```
就是这样。`soa` 不关心您运行什么。它会设置一个本地代理，重新配置相关的环境变量，并在每一个依赖下载落地之前进行检查。工作时您会看到如下内容：
```
[soa] ⠋ scanning github.com/gin-gonic/gin@v1.9.1
[soa] ✓ github.com/gin-gonic/gin@v1.9.1 allowed
```
如果有东西被拦截：
```
[soa] ✗ github.com/sketchy/lib@v0.0.1 blocked: published 2 days ago
```
`soa` 可以封装任何东西：您的工具链、您的别名、您的脚本：
```
soa go test ./...
soa npm install express
soa pip install requests
soa bundle install
soa ./scripts/deps.sh # anything that pulls packages
```
## 支持的生态系统
| 生态系统 | 被劫持的环境变量 |
|---|---|
| Go | `GOPROXY` |
| npm | `npm_config_registry` |
| pip | `PIP_INDEX_URL` |
| RubyGems | `GEM_HOST` |
默认情况下，所有生态系统都是启用的。可以通过以下命令为单次运行禁用某个生态系统：
```
soa --go=false npm install # only intercept npm, leave Go alone
```
每个生态系统都是一个 `Manager`，一个接口实现。添加新的支持很简单。
## 获取
```
go install github.com/ariary/soa/cmd/soa@latest
go install github.com/ariary/soa/cmd/tonga@latest
```
## 底层原理
```
you ─► soa ─► local proxy ─► tonga serve ─► allow/block
│ │
│ if allowed │
▼ │
upstream registry ◄────────────────┘
```
1. `soa` 检测活动的生态系统并读取其上游注册表（例如 Go 的 `GOPROXY`，npm 的 `npm_config_registry`）
2. 启动一个本地 HTTP 代理，并覆盖相关环境变量使其指向该代理
3. 使用修改后的环境启动您的命令
4. 对于每一个源码存档的下载，都会询问检查服务器 (`tonga serve`)
5. 元数据请求直接通过（查找操作无延迟）
6. 完成后，代理关闭，`soa` 以您的命令的退出码退出
## 规则
检查服务器 (`tonga serve`) 按顺序强制执行规则。一个软件包必须通过所有启用的规则才能被放行。
**已知恶意软件**：首先检查该软件包是否在已知恶意软件包数据库中。如果软件包+版本是已知的供应链攻击，它将被立即拦截。始终开启，无需配置。
- [osv.dev](https://osv.dev) MAL-* 告警 ([OpenSSF](https://github.com/ossf/malicious-packages)) — 始终激活，涵盖所有 GHSA MALWARE 条目以及来自其他检测源的约 19 万多个条目
- [GitHub Advisory Database](https://github.com/advisories) MALWARE 分类 — 可选，当设置了 `GITHUB_TOKEN` 时启用。仅当到 osv.dev 的约 10 分钟传播延迟对您的威胁模型有影响时才有用
**最大存在时间**：该软件包版本必须至少已发布 N 天。用于在新的恶意版本获得信任之前将其捕获。默认启用，为 7 天。
**最低版本数**：该软件包必须至少有 N 个已发布版本。只有一个版本且没有历史记录的软件包是可疑的。默认启用，最少 2 个版本。
**分析**：将软件包发送给 LLM 进行恶意软件检测。代码分析和发布元数据检查并行运行。如果任一方标记了该软件包，它将被立即拦截。默认关闭。设置详情请参阅 [docs/malware-analysis.md](docs/malware-analysis.md)。
## 信息源
`tonga feed` 监控新的恶意软件包告警，并实时打印到您的终端：
```
tonga feed
```
```
[tonga] feed started (polling every 5m, sources: osv.dev + GHSA)
[MAL-2025-49286] npm / gunpowder-ghost@209.0.0, 217.0.0, 213.0.0, 212.0.0, 211.0.0, 225.0.0
Malicious code in gunpowder-ghost (npm)
2026-04-30 https://osv.dev/vulnerability/MAL-2025-49286
---
[GHSA-5w4c-85pv-cwhv] npm / tanstack@2.0.7
Malware in tanstack
2026-04-29 https://github.com/advisories/GHSA-5w4c-85pv-cwhv
---
```
按生态系统筛选并调整间隔：
```
tonga feed --ecosystem npm,pypi --interval 1m
```
两个信息源，已去重（完整比较请参阅 [docs/osv-vs-ghsa.md](docs/osv-vs-ghsa.md)）：
- **osv.dev MAL-*** ([OpenSSF Malicious Packages](https://github.com/ossf/malicious-packages)) — 始终开启，无需令牌。这是 GHSA MALWARE 的超集。
- **GitHub Advisory Database** (GHSA `MALWARE` 分类) — 可选，当设置了 `GITHUB_TOKEN` 时启用。仅对 GHSA 来源的告警提供约 10 分钟的提前通知。
状态在重启后会持久化 — 您不会看到同一条告警两次。
## 可调参数
配置文件位于 `~/.config/soa/config.yaml`：
```
check_url: "http://localhost:9090"
proxy:
port: 8080
poll_interval: "500ms"
check_timeout: "30s"
server:
port: 9090
cache_path: "~/.config/soa/approved.json"
rules:
max_age:
enabled: true
min_days: 7
min_versions:
enabled: true
count: 2
analysis:
enabled: false
provider: "ollama"
model: "llama3"
```
每个值都可以通过环境变量覆盖：
| 配置项 | 环境变量 | 默认值 |
|---|---|---|
| `check_url` | `SOA_CHECK_URL` | `http://localhost:9090` |
| `proxy.port` | `SOA_PROXY_PORT` | `8080` |
| `check_timeout` | `SOA_CHECK_TIMEOUT` | `30s` |
| `server.port` | `SOA_SERVER_PORT` | `9090` |
| `server.cache_path` | `SOA_SERVER_CACHE_PATH` | `~/.config/soa/approved.json` |
| `rules.max_age.enabled` | `SOA_RULE_MAX_AGE_ENABLED` | `true` |
| `rules.max_age.min_days` | `SOA_RULE_MAX_AGE_MIN_DAYS` | `7` |
| `rules.min_versions.enabled` | `SOA_RULE_MIN_VERSIONS_ENABLED` | `true` |
| `rules.min_versions.count` | `SOA_RULE_MIN_VERSIONS_COUNT` | `2` |
| `rules.analysis.enabled` | `SOA_RULE_ANALYSIS_ENABLED` | `false` |
| `rules.analysis.provider` | `SOA_ANALYSIS_PROVIDER` | `ollama` |
| `rules.analysis.model` | `SOA_ANALYSIS_MODEL` | `llama3` |
完整的分析配置参考请参阅 [docs/malware-analysis.md](docs/malware-analysis.md)。
## 常见问题
**如果检查服务器宕机了怎么办？**
所有软件包都会被拦截。`soa` 采用“失败即关闭”策略。没有免检通行证。
**这会减慢速度吗？**
只有源码存档的下载会经过检查。元数据请求直接通过。如果软件包在已批准缓存中，检查是瞬间完成的。
**`tonga feed` 的附加价值是什么？**
使用 `soa`+`tonga serve` 在*导入的那一刻*保护您，而 tonga feed 则在代码存放在您环境中的整个期间保护您（帮助检测那些已经在已批准缓存中的恶意依赖）。这就像在门口检查证件和拥有一个系统来标记该人员“许可”后来是否被撤销之间的区别。
**我可以使用自己的检查服务器吗？**
可以。将 `check_url` 指向任何实现了[检查 API](pkg/checkapi/checkapi.go) 的服务器。`tonga serve` 只是一个参考实现。
**"tonga soa" 是什么意思？**
马达加斯加语中的“欢迎”。🇲🇬
标签：CI/CD安全, EVTX分析, Go语言, Llama, TLS抓取, 供应链攻击防护, 依赖管理, 包管理器, 安全策略, 恶意包检测, 恶意软件防护, 提示词设计, 日志审计, 构建过程保护, 环境变量, 程序破解, 统一API, 网络安全, 自定义DNS解析器, 软件安全, 软件构建安全, 隐私保护