qwexvf/aegis-cli

# aegis [](https://github.com/qwexvf/aegis-cli/actions/workflows/ci.yml) [](https://goreportcard.com/report/github.com/qwexvf/aegis-cli) [](LICENSE) 支持 9 种包生态系统的供应链安全扫描器。无需账号，无需 API 密钥，无需后端。  - **CVE / GHSA 查询** — 针对 [OSV.dev](https://osv.dev) 进行批量查询，一次性覆盖所有 9 种生态系统 - **AST 能力扫描** — tree-sitter 遍历每个包的源码；揭示 `shell-spawn`、`net-egress`、`dynamic-eval`、`fs-write-outside-root` 等，甚至适用于尚未发布安全公告的包 - **行为启发式检测** — 执行 `curl|sh` 的 postinstall 钩子、混淆的 payload、拼写抢注名称（Levenshtein 距离为 2）、维护者劫持模式、补丁版本的能力漂移 - **包含传递性依赖** — 基于 lockfile；每个已解析的包都会被扫描，而不仅是直接依赖 - **多语言 Monorepo** — 查找所有 lockfile，合并为一个 `aegis.lock` - **支持离线** — 设置 `AEGIS_NO_VULN_LOOKUP=1` 可在隔离网络中使用；通过 `AEGIS_OSV_URL` 自行托管 OSV 镜像 ## 生态系统 | 生态系统 | Lockfiles | OSV | AST scan | |---------------|-----------------------------------------------------------------------|-----|---------------| | **npm** | `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` | ✅ | ✅ `jsscan` | | **PyPI** | `poetry.lock`, `uv.lock`, `Pipfile.lock`, `requirements.txt` | ✅ | ✅ `pyscan` | | **RubyGems** | `Gemfile.lock` | ✅ | ✅ `rbscan` | | **crates.io** | `Cargo.lock` | ✅ | ✅ `rsscan` | | **Go** | `go.sum` / `go.mod` | ✅ | ✅ `goscan` | | **Maven** | `pom.xml`, `gradle.lockfile` | ✅ | ✅ `jvscan` | | **Packagist** | `composer.lock` | ✅ | ✅ `phpscan` | | **NuGet** | `packages.lock.json` | ✅ | ✅ `csscan` | | **Gleam** | `manifest.toml` | ✅ | ✅ `gleamscan`| ## 安装 ``` go install github.com/qwexvf/aegis-cli/cmd/aegis@latest ``` 预编译二进制文件（cosign 签名，包含 SLSA provenance）：[Releases](https://github.com/qwexvf/aegis-cli/releases) ``` # 运行前验证 cosign verify-blob \ --certificate-identity-regexp 'https://github.com/qwexvf/aegis-cli/.github/workflows/release.yml.*' \ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ --certificate checksums.txt.pem \ --signature checksums.txt.sig \ checksums.txt sha256sum -c checksums.txt ``` ## 用法 ``` # 快照 lockfile 并扫描 aegis snapshot save # parse lockfile → aegis.lock aegis snapshot enrich # AST scan + CVE lookup aegis snapshot show # direct deps aegis snapshot show --all # + transitive aegis snapshot diff baseline.lock # drift between two snapshots # CI 门禁 — 发现结果 ≥ 阈值时以退出码 1 退出 aegis ci --fail-on=block aegis ci --fail-on=prompt --json # machine-readable output # 临时分析 package（从 registry 获取） aegis analyze lodash@4.17.21 aegis analyze --evidence ua-parser-js@0.7.29 # 分析本地源码树（不从 registry 获取） aegis analyze rubygems/rest-client@1.6.13 \ --local examples/incidents/rubygems/rest-client-1.6.13/ # allowlist aegis allowlist add lodash \ --capability=dynamic-eval \ --version='^4' \ --reason='_.template uses Function() to compile templates' aegis allowlist list aegis allowlist test npm/lodash@4.17.21 aegis allowlist verify # shell 补全 aegis completion bash > /etc/bash_completion.d/aegis aegis completion zsh > "${fpath[1]}/_aegis" aegis completion fish > ~/.config/fish/completions/aegis.fish ``` ## 工作原理 1. **解析** — lockfile → 每个已解析的 `(name, version)`，包括直接和传递性依赖 2. **获取** — 从 registry 下载 tarball；缓存于 `~/.aegis/cache/sources/` 3. **AST 扫描** — tree-sitter 遍历每个文件；输出 `capability:file:line:snippet` 证据 4. **CVE 查询** — 批量 POST 请求至 OSV.dev；严重级别缓存于 `~/.aegis/cache/advisories/` 5. **白名单** — 内置 → `~/.aegis/allowlist.yaml` → `.aegis-allowlist.yaml`；具体规则优先于通配符 6. **裁决** — `max(ast, advisory)` 对比 `--fail-on`；Critical/High → `block`，Medium → `prompt`，Low → `review` ## 白名单 ``` # .aegis-allowlist.yaml — 提交此文件以实现团队共享的抑制规则 version: 1 rules: - ecosystem: npm name: lodash version: "^4" capability: dynamic-eval reason: "_.template uses Function() to compile templates" ``` 分三层，按匹配顺序依次为：内置（约 20 条精选规则） → 用户级（`~/.aegis/allowlist.yaml`） → 项目级（`.aegis-allowlist.yaml`）。 ## CI [`examples/ci/`](examples/ci/) 中提供了适用于 GitHub Actions、GitLab CI 和通用 shell 的开箱即用模板。 | 退出代码 | 含义 | |-----------|---------| | `0` | 干净 — 未发现级别 ≥ `--fail-on` 的问题 | | `1` | 发现级别 ≥ `--fail-on` 的问题 | | `2` | 裁决失败（配置 / 网络错误） | `aegis ci --json` 的输出非常稳定，适合用于工具链集成 — 详见 [`examples/ci/README.md`](examples/ci/README.md)。 ## 文档 完整文档：**[qwexvf.github.io/aegis-cli](https://qwexvf.github.io/aegis-cli/)** - [入门指南](https://qwexvf.github.io/aegis-cli/getting-started/) - [命令参考](https://qwexvf.github.io/aegis-cli/reference/commands/) - [实用手册](https://qwexvf.github.io/aegis-cli/guides/cookbook/) - [架构说明](https://qwexvf.github.io/aegis-cli/contributing/architecture/) - [更新日志](CHANGELOG.md) ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。在进行非平凡的 PR 之前，请先提交 Issue。 漏洞报告：[GitHub 私有漏洞报告](https://github.com/qwexvf/aegis-cli/security/advisories/new) — 请勿使用公开 Issue。 ## 许可证 [Apache-2.0](LICENSE)

标签：AST风险评分, bun, crates.io, CVE查询, DNS 解析, EVTX分析, GHSA查询, Go, Go语言, IP 地址批量处理, npm, OSV.dev, pnpm, PyPI, RubyGems, Ruby工具, tree-sitter, Typosquat检测, yarn, 云安全监控, 代码安全, 传递依赖, 依赖安全, 包管理器, 单体仓库, 后门检测, 安全合规, 安装门禁, 日志审计, 漏洞枚举, 离线支持, 程序破解, 统一API, 网络代理, 网络信息收集, 网络安全, 行为启发式, 跨平台支持, 锁文件快照, 隐私保护, 静态分析