timoniersystems/lookout
GitHub: timoniersystems/lookout
一款软件供应链安全漏洞扫描与 SBOM 分析工具，能解析软件物料清单、查询 NVD 的 CVE 详情并通过图数据库追踪依赖路径，帮助开发者理解和修复依赖项中的漏洞。
Stars: 2 | Forks: 0
# Lookout
[](https://github.com/timoniersystems/lookout/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
## 演示
## 什么是 Lookout？
Lookout 帮助你理解和修复软件依赖项中的漏洞。它能回答以下关键问题：
- 📊 **我的软件中存在哪些漏洞？**
- 🔍 **这个有漏洞的包是如何进入我的项目的？**
- 🛠️ **我应该升级哪个直接依赖项来修复它？**
### 主要功能
- **CVE 分析** - 通过限速和重试逻辑从 NVD 获取详细的漏洞数据
- **SBOM 扫描** - 集成 Trivy 扫描软件物料清单
- **依赖路径追踪** - 将存在漏洞的间接依赖项追溯到您的根包
- **多界面** - 用于自动化的 CLI，带有实时进度跟踪的 Web UI
- **图数据库** - 由 Dgraph 驱动的依赖图可视化
- **异步处理** - 带有 SSE 进度更新的后台 SBOM 处理
- **严重性过滤** - 按 CRITICAL、HIGH、MEDIUM、LOW 过滤漏洞
## 快速开始
### CLI 用法
```
# 克隆并构建
git clone https://github.com/timoniersystems/lookout.git
cd lookout
make build && make install
# 获取 CVE 数据
lookout cve CVE-2021-44228
# 扫描 SBOM
lookout sbom examples/cyclonedx-sbom-example.json
# 追踪依赖路径（需要 Dgraph）
make up-standalone
export DGRAPH_HOST=localhost
lookout sbom examples/cyclonedx-sbom-example.json \
--dep-path 'pkg:composer/asm89/stack-cors@1.3.0'
```
### Web UI
```
# 生成 TLS 证书
make certs
# 启动所有服务
make up
# 访问 UI (HTTPS)
open https://localhost:7443
# 访问 Dgraph Ratel
open http://localhost:8000
```
## 安装
### 使用 Docker (推荐)
```
# 生成 TLS 证书
make certs
# 启动所有服务
make up
```
访问地址：
- Lookout Web UI: https://localhost:7443 (HTTPS) 或 http://localhost:7080 (重定向到 HTTPS)
- Dgraph Ratel UI: http://localhost:8000
- Dgraph API: http://localhost:8080
有关详细的设置和配置，请参阅 [Docker Compose 指南](docs/DOCKER_COMPOSE.md)。
### 二进制文件下载
从 [Releases](https://github.com/timoniersystems/lookout/releases) 下载：
```
# Linux
wget https://github.com/timoniersystems/lookout/releases/latest/download/lookout-linux-amd64
chmod +x lookout-linux-amd64
sudo mv lookout-linux-amd64 /usr/local/bin/lookout
# macOS (Apple Silicon)
wget https://github.com/timoniersystems/lookout/releases/latest/download/lookout-darwin-arm64
chmod +x lookout-darwin-arm64
sudo mv lookout-darwin-arm64 /usr/local/bin/lookout
# 验证
lookout version
```
### 从源代码构建
**要求：**
- Go 1.26+
- Docker 和 Docker Compose (用于 UI 和依赖追踪)
- Trivy (可选，用于 SBOM 扫描)
```
git clone https://github.com/timoniersystems/lookout.git
cd lookout
make build
make install
```
## 文档
- 📖 **[使用指南](docs/USAGE.md)** - 包含示例和工作流的完整指南
- 🐳 **[Docker Compose 指南](docs/DOCKER_COMPOSE.md)** - 使用 Docker 运行、服务、端口、故障排除
- ☸️ **[Kubernetes 部署](docs/KUBERNETES_SETUP.md)** - 完整的 K8s 指南：Kind 集群、Gateway API、ArgoCD GitOps、AWS ALB、生产部署
- 🔒 **[TLS 设置指南](docs/TLS_SETUP.md)** - HTTPS 配置和安全最佳实践
- 🏗️ **[架构](docs/ARCHITECTURE.md)** - 系统设计和组件
- 💻 **[贡献指南](CONTRIBUTING.md)** - 开发设置和贡献指南
- 🚀 **[CI/CD 指南](docs/CI_CD.md)** - GitHub Actions 工作流和发布
## 示例：依赖路径追踪
当您在间接依赖项中发现漏洞时，Lookout 会向您显示其路径：
```
lookout sbom mybom.json --dep-path 'pkg:npm/minimist@1.2.5'
```
输出：
```
════════════════════════════════════════════════════════════
DEPENDENCY PATH ANALYSIS
════════════════════════════════════════════════════════════
Searched: pkg:npm/minimist@1.2.5
Depth: 3 level(s)
Dependency Tree:
🏠 pkg:npm/myapp@1.0.0
│
└──> 📦 pkg:npm/mocha@8.4.0
│
└──> 📦 pkg:npm/mkdirp@0.5.1
│
└──> ⚠️ pkg:npm/minimist@1.2.5
════════════════════════════════════════════════════════════
Legend:
🏠 = Root package (your application)
📦 = Intermediate dependency
⚠️ = Vulnerable component
```
**操作：** 升级 `mocha` 以获取已修复的 `minimist`。
## 配置
### NVD API 密钥 (强烈推荐)
使用 API 密钥获取快 10 倍的 CVE 查询速度：
```
# 请求密钥：https://nvd.nist.gov/developers/request-an-api-key
# 设置环境变量
export NVD_API_KEY="your-api-key-here"
# 添加到 shell 配置文件以实现持久化
echo 'export NVD_API_KEY="your-api-key"' >> ~/.zshrc
```
| 模式 | 频率限制 | 速度 |
|------|-----------|-------|
| 无 API 密钥 | 5 req/30s | 6s 延迟 |
| 有 API 密钥 | 50 req/30s | 0.6s 延迟 |
### 环境变量
```
# NVD API
export NVD_API_KEY="your-api-key"
# Dgraph 连接（用于带有 Docker Dgraph 的 CLI）
export DGRAPH_HOST=localhost # Use "alpha" when all in Docker
export DGRAPH_PORT=9080
# Web 服务器
export SERVER_PORT=3000
```
有关所有选项，请参阅[使用指南](docs/USAGE.md#environment-variables)。
## 常见用例
### 1. 安全审计
```
# 扫描你的 SBOM 以查找漏洞
lookout sbom path/to/sbom.json --severity high
```
### 2. 调查特定 CVE
```
# 获取详细的 CVE 信息
lookout cve CVE-2021-44228
```
### 3. 批量 CVE 处理
```
# 处理 CVE 列表
cat cves.txt
CVE-2021-44228
CVE-2022-23305
lookout cve-file cves.txt
```
### 4. 修复间接依赖漏洞
```
# 1. 扫描并识别易受攻击的包
lookout sbom mybom.json
# 2. 追踪依赖路径
lookout sbom mybom.json --dep-path 'pkg:npm/lodash@4.17.20'
# 3. 升级路径中显示的直接依赖
```
## 项目结构
```
lookout/
├── cmd/
│ ├── cli/ # CLI application entry point (Cobra commands)
│ └── ui/ # Web UI application entry point
├── pkg/
│ ├── cli/
│ │ └── cli_processor/ # CVE formatting and output
│ ├── common/
│ │ ├── cyclonedx/ # CycloneDX SBOM parsing
│ │ ├── spdx/ # SPDX SBOM parsing
│ │ ├── fileutil/ # File utilities
│ │ ├── handler/ # HTTP handlers
│ │ ├── nvd/ # NVD API client
│ │ ├── processor/ # File processing
│ │ ├── progress/ # Progress tracking
│ │ └── trivy/ # Trivy integration
│ ├── config/ # Configuration management
│ ├── graph/ # Graph operations and queries
│ ├── interfaces/ # Interface definitions
│ ├── logging/ # Structured logging
│ ├── repository/ # Data access layer
│ ├── service/ # Business logic layer
│ ├── ui/ # UI components
│ │ └── echo/ # Echo server setup
│ └── validation/ # Input validation
├── assets/
│ ├── static/ # CSS, JavaScript
│ └── templates/ # HTML templates
├── nginx/ # Nginx reverse proxy config
├── examples/ # Example SBOM files
└── docs/ # Documentation
```
## 支持的格式
- **SBOMs**: CycloneDX 1.4+ (JSON), SPDX 2.3+ (JSON)
- **CVE 列表**: 纯文本或 Trivy JSON
- **包 URL**: [PURL 规范](https://github.com/package-url/purl-spec)
## 要求
**对于 CLI：**
- Go 1.26+ (仅构建时)
- Trivy (可选，用于 SBOM 扫描)
- Dgraph (可选，用于依赖追踪)
**对于 Web UI：**
- Docker 和 Docker Compose
## 已知限制
1. **频率限制**：NVD API 有严格的频率限制。使用 API 密钥可获得最佳性能。
2. **SBOM 格式**：支持 CycloneDX 1.4+ 和 SPDX 2.3+ (仅限 JSON，尚不支持 XML)。
3. **大型 SBOM**：处理数百个 CVE 可能会很慢。强烈建议使用 NVD API 密钥。
有关解决方案，请参阅[使用指南](docs/USAGE.md#troubleshooting)。
## 验证发布版本
所有发布二进制文件和容器镜像均使用 GitHub 的 OIDC token 进行 [SLSA 构建来源](https://slsa.dev/)签名。您可以验证工件是否由此存储库的 CI 生成且未被篡改。
**容器镜像：**
```
gh attestation verify oci://ghcr.io/timoniersystems/lookout:latest --owner timoniersystems
```
**发布二进制文件** (从 [releases 页面](https://github.com/timoniersystems/lookout/releases)下载后)：
```
gh attestation verify lookout-linux-amd64 --owner timoniersystems
```
需要 [GitHub CLI](https://cli.github.com/) (`gh`)。
## 许可证
MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE)。
## 支持
- 📚 [文档](docs/)
- 🐛 [报告问题](https://github.com/timoniersystems/lookout/issues)
- 💬 [讨论](https://github.com/timoniersystems/lookout/discussions)
**如果您觉得有用，请给本仓库加星标 ⭐！**
▶ 点击观看 CLI 演示
标签：CISA项目, CVE列表处理, CycloneDX, Dgraph图数据库, EVTX分析, Go语言开发, NVD漏洞库, SBOM分析, SPDX, Svelte, TCP SYN 扫描, Trivy集成, Web UI, 严重性过滤, 交互式探索, 依赖关系图分析, 依赖路径追踪, 加密, 命令行工具CLI, 实时进度跟踪, 异步处理, 日志审计, 漏洞扫描器, 请求拦截, 软件供应链安全, 远程方法调用