CVE-Todo/CVETodo-agent
GitHub: CVE-Todo/CVETodo-agent
一款跨平台的系统软件包漏洞扫描代理，持续监控已安装依赖并对接 CVETodo 平台进行 CVE 告警与跟踪管理。
Stars: 1 | Forks: 0
# CVETodo Agent
CVETodo Agent 是一款跨平台的扫描程序，用于监控系统中已安装的软件包，并将结果上报至 https://cvetodo.com 的仪表板。随后，CVETodo 系统会持续监控与该清单相关的任何 CVE，并在发现漏洞时立即向您发送警报，同时将其添加到您仪表板的待办事项列表中。
该 Agent 的源代码在 Github 上向所有人公开，以确保其执行活动的透明度。
## 功能特性
- **多平台软件包扫描**：支持 Windows、Debian/Ubuntu (dpkg)、RedHat/CentOS/SUSE (rpm)、Python (pip) 和 Node.js (npm) 软件包
- **持续监控**：作为服务运行，持续监控新的漏洞
- **灵活的配置**：支持环境变量的 YAML 配置
- **结构化日志**：具有可配置级别的 JSON 和文本格式日志
- **离线功能**：在 API 不可用时将扫描结果存储在本地
- **跨平台**：支持在 Linux、Windows 和 macOS 上运行
- **团队集成**：与 CVETodo 团队管理和 API 密钥集成
## 安装说明
### 快速安装（推荐）
安装脚本会下载最新版本，设置您的配置，并将 Agent 注册为**每天一次**扫描系统的后台服务。
#### Windows
在具有管理员权限的 PowerShell 提示符下运行：
```
irm https://raw.githubusercontent.com/CVE-Todo/CVETodo-agent/main/install.ps1 | iex
```
非交互式安装：
```
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/CVE-Todo/CVETodo-agent/main/install.ps1))) -ApiKey "your-key" -TeamId "your-team"
```
#### Linux / macOS
```
curl -fsSL https://raw.githubusercontent.com/CVE-Todo/CVETodo-agent/main/install.sh | sudo bash
```
非交互式安装：
```
curl -fsSL https://raw.githubusercontent.com/CVE-Todo/CVETodo-agent/main/install.sh | sudo CVETODO_API_KEY=your-key CVETODO_TEAM_ID=your-team bash
```
### 关闭 Agent
默认情况下，Agent 每天扫描一次。您可以随时将其关闭：
- **CLI**：`cvetodo-agent service stop`（直到下次重启）或 `cvetodo-agent service uninstall`（完全移除）
- **配置文件**：在配置文件中设置 `agent.enabled: false` —— 服务保持安装状态，但不执行任何扫描
- **GUI/系统工具**：在 `services.msc` (Windows) 中停止或禁用“CVETodo Agent”服务，或在 Linux 中使用 `systemctl stop cvetodo-agent` / `systemctl disable cvetodo-agent`
### 手动安装（预编译二进制文件）
从[发布页面](https://github.com/CVE-Todo/CVETodo-agent/releases)下载适合您平台的最新版本
（资产命名为 `cvetodo-agent---amd64.tar.gz`，在 Windows 上为 `.zip`），解压该二进制文件并将其放置在您的 PATH 中。然后运行 `cvetodo-agent config init`，接着运行 `cvetodo-agent service install`。
### 验证版本
快速安装脚本会自动根据随每个版本发布的 `SHA256SUMS` 文件验证下载内容。如果您手动下载二进制文件，也可以进行同样的操作：
```
sha256sum -c --ignore-missing SHA256SUMS
```
版本产物还带有[构建来源证明](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)，以证明它们是由此仓库在 GitHub Actions 上的发布工作流构建的。
使用 [GitHub CLI](https://cli.github.com/) 进行验证：
```
gh attestation verify cvetodo-agent--linux-amd64.tar.gz --repo CVE-Todo/CVETodo-agent
```
### 从源码构建
#### 前置条件
- Go 1.21 或更高版本
- Make（可选，用于构建自动化）
#### 构建步骤
```
git clone https://github.com/CVE-Todo/CVETodo-agent.git
cd CVETodo-agent
# 为当前平台构建
make build
# 或为所有平台构建
make build-all
# 本地安装
make install
```
## 配置说明
### 交互式设置
```
cvetodo-agent config init
```
这将引导您完成交互式设置过程：
```
CVETodo Agent Configuration Setup
=================================
To obtain your API key and team ID:
1. Log into your CVETodo account
2. Navigate to your team settings
3. Go to the 'Agent Keys' section
4. Generate a new API key for this agent
Enter your CVETodo team API key: your-actual-api-key
Enter your CVETodo team ID: your-actual-team-id
Configuration file created at: /home/user/.cvetodo-agent.yaml
You can now run 'cvetodo-agent scan' to perform your first vulnerability scan.
```
如果配置文件已存在，系统将提示您是否替换：
```
cvetodo-agent config init
# 配置文件已存在于：/home/user/.cvetodo-agent.yaml
# 你想替换它吗？ (y/N): y
# 正在替换现有配置...
```
强制覆盖且不提示：
```
cvetodo-agent config init --force
```
该命令会在 `~/.cvetodo-agent.yaml` 创建一个包含您实际凭证的配置文件。
### 检查配置状态
```
cvetodo-agent config status
```
此命令可帮助您排查配置问题：
```
Configuration Status
===================
✓ Config file exists: /home/user/.cvetodo-agent.yaml
✓ Configuration is valid
- API Base URL: https://api.cvetodo.com
- Team ID: team_12345
- API Key: sk12****5678 (hidden)
- Agent Name: my-server
- Scan Interval: 24h0m0s
- Enabled Scanners: [dpkg rpm pip npm]
```
### 获取 API 密钥
要获取您的 API 密钥和团队 ID：
1. 登录您的 CVETodo 账户
2. 导航至您的团队设置
3. 进入“Agent Keys”部分
4. 为 Agent 生成新的 API 密钥
5. 在 `config init` 提示时复制 API 密钥和团队 ID
### 配置文件
运行 `config init` 后，您的配置文件将如下所示：
```
# CVETodo Agent 配置
api:
base_url: "https://cvetodo.com"
api_key: "your-actual-api-key"
team_id: "your-actual-team-id"
timeout: "30s"
agent:
enabled: true # set to false to disable all scanning without uninstalling
name: "my-server"
scan_interval: "24h"
report_interval: "24h"
data_dir: "/home/user/.cvetodo-agent/data"
log_level: "info"
log_format: "text"
scanner:
enabled_scanners:
- "dpkg" # Debian/Ubuntu packages
- "rpm" # RedHat/CentOS/SUSE packages
- "pip" # Python packages
- "npm" # Node.js packages
```
### 环境变量
所有配置选项都可以使用 `CVETODO_` 前缀的环境变量进行覆盖：
```
export CVETODO_API_API_KEY="your-api-key"
export CVETODO_API_TEAM_ID="your-team-id"
export CVETODO_LOG_LEVEL="debug"
```
## 用法
### 一次性扫描
```
# 执行单次漏洞扫描
cvetodo-agent scan
# 启用 debug 日志进行扫描
cvetodo-agent scan --log-level debug
```
### 持续监控
```
# 以持续监控模式运行 agent
cvetodo-agent run
# 使用自定义配置文件运行
cvetodo-agent run --config /path/to/config.yaml
```
### 命令行选项
```
# 全局 flags
-c, --config string config file (default is $HOME/.cvetodo-agent.yaml)
-l, --log-level string log level (debug, info, warn, error) (default "info")
--log-format string log format (text, json) (default "text")
# 可用命令
run Start the CVETodo agent in continuous monitoring mode (foreground)
scan Perform a one-time system scan
config init Initialize configuration file (--force to overwrite)
config status Check configuration status and validate settings
service install Install and start the background service (daily scans)
service uninstall Stop and remove the background service
service start Start the background service
service stop Stop the background service
service status Show background service status
version Show version information
help Show help for any command
# Config 初始化特定 flags
--force Force overwrite existing configuration file
```
## 软件包扫描器
该 Agent 包含适用于各种包管理器的扫描器：
### 支持的包管理器
- **dpkg**: Debian/Ubuntu 软件包 (`.deb`)
- **rpm**: RedHat/CentOS/SUSE 软件包 (`.rpm`)
- **pip**: Python 软件包
- **npm**: Node.js 软件包（全局安装）
### 扫描器要求
- **dpkg**: 需要 `dpkg-query` 命令
- **rpm**: 需要 `rpm` 命令
- **pip**: 需要 `pip` 或 `pip3` 命令
- **npm**: 需要 `npm` 命令
扫描器会根据所需命令的可用性自动启用。
## 系统服务
该 Agent 内置了对 Windows (SCM)、Linux (systemd) 和 macOS (launchd) 的服务支持 —— 无需外部工具。快速安装脚本会自动完成此设置；若要手动操作：
```
# 需要管理员/root 权限
sudo cvetodo-agent service install # registers the service and starts it (auto-starts on boot)
sudo cvetodo-agent service status
sudo cvetodo-agent service stop
sudo cvetodo-agent service uninstall
```
默认情况下，该服务每天扫描一次 (`agent.scan_interval: 24h`)。在配置文件中设置 `agent.enabled: false` 可在不卸载服务的情况下暂停扫描。
关于服务的注意事项：配置文件需从系统级位置读取，以便服务账户能够找到它 —— Windows 上为 `C:\ProgramData\cvetodo-agent\.cvetodo-agent.yaml`，Linux/macOS 上为 `/etc/cvetodo-agent/.cvetodo-agent.yaml`。
### Docker
```
FROM alpine:latest
RUN apk --no-cache add ca-certificates
COPY cvetodo-agent /usr/local/bin/
COPY config.yaml /etc/cvetodo-agent/
CMD ["cvetodo-agent", "run", "--config", "/etc/cvetodo-agent/config.yaml"]
```
## 开发
### 前置条件
- Go 1.21+
- Make
### 开发环境设置
```
git clone https://github.com/CVE-Todo/CVETodo-agent.git
cd CVETodo-agent
# 设置开发环境
make dev-setup
# 运行测试
make test
# 运行 coverage
make test-coverage
# 格式化代码
make fmt
# 运行 linting
make lint
```
### 项目结构
```
CVETodo-agent/
├── cmd/agent/ # Main application entry point
├── internal/
│ ├── agent/ # Core agent logic
│ ├── api/ # CVETodo API client
│ ├── config/ # Configuration management
│ ├── logger/ # Logging utilities
│ └── scanner/ # Package scanners
├── build/ # Build artifacts
├── dist/ # Distribution packages
├── Makefile # Build automation
├── go.mod # Go module definition
└── README.md # This file
```
### 构建系统
本项目使用 Make 进行构建自动化：
```
make help # Show all available targets
make build # Build for current platform (creates .exe on Windows)
make build-all # Build for all platforms
make build-windows # Build Windows .exe specifically
make test # Run tests
make clean # Clean build artifacts
make package # Create release packages
```
**特定平台的输出：**
- **Windows**: `build/cvetodo-agent.exe`
- **Linux/macOS**: `build/cvetodo-agent`
**跨平台构建：**
- Windows: `dist/windows-amd64/cvetodo-agent.exe`
- Linux: `dist/linux-amd64/cvetodo-agent`
- macOS: `dist/darwin-amd64/cvetodo-agent`
**无 Make 的 Windows 环境：**
如果您在 Windows 上没有安装 Make，请使用提供的批处理脚本：
```
build.bat
```
这会创建可以直接使用的 `build/cvetodo-agent.exe`。
## 安全性
### API 密钥管理
- 安全地存储 API 密钥
- 在生产环境中使用环境变量
- 定期轮换密钥
- 将密钥权限限制为所需的最低限度
### 网络安全
- Agent 通过 HTTPS 进行通信
- 验证 SSL 证书
- 考虑使用私有网络进行 API 通信
### 文件权限
- 配置文件应具有限制权限 (600)
- 数据目录应仅允许 Agent 用户访问
- 日志文件可能包含敏感信息
## 常见问题排查
### 常见问题
1. **找不到配置或配置无效**
# 检查配置状态
cvetodo-agent config status
# 如果配置不存在，请创建它
cvetodo-agent config init
# 替代方案：使用环境变量
export CVETODO_API_API_KEY="your-api-key"
export CVETODO_API_TEAM_ID="your-team-id"
2. **API 密钥验证失败**
- 在 CVETodo 团队设置中验证 API 密钥
- 确保 API 密钥具有适当的权限
- 检查团队 ID 是否与您的 CVETodo 账户匹配
3. **软件包扫描权限被拒绝**
- 确保 Agent 以适当的权限运行
- 某些包管理器需要提升的权限
4. **API 连接失败**
- 检查网络连接
- 验证 API endpoint 和凭证
- 检查防火墙设置
5. **找不到扫描器**
- 安装所需的包管理器工具
- 检查 PATH 环境变量
### 配置排查
检查您的配置状态：
```
cvetodo-agent config status
```
正常运行时的预期输出：
```
Configuration Status
===================
✓ Config file exists: /home/user/.cvetodo-agent.yaml
✓ Configuration is valid
- API Base URL: https://api.cvetodo.com
- Team ID: team_12345
- API Key: sk12****5678 (hidden)
- Agent Name: my-server
- Scan Interval: 24h0m0s
- Enabled Scanners: [dpkg rpm pip npm]
```
如果配置缺失或无效：
```
Configuration Status
===================
✗ Config file not found: /home/user/.cvetodo-agent.yaml
To create a configuration file, run:
cvetodo-agent config init
```
### 调试模式
```
cvetodo-agent scan --log-level debug --log-format json
```
### 日志分析
- 检查结构化日志以获取错误详情
- 监控性能指标
- 审查安全事件
## 贡献
1. Fork 该仓库
2. 创建一个功能分支
3. 进行您的更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交 pull request
## 许可证
本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。
## 支持
- GitHub Issues：[报告 Bug 和功能请求](https://github.com/CVE-Todo/CVETodo-agent/issues)
- 文档：[Wiki](https://github.com/CVE-Todo/CVETodo-agent/wiki)
- CVETodo 支持：[联系支持团队](https://cvetodo.com/support)
标签：Agent, EVTX分析, PB级数据处理, 安全运维, 日志审计, 漏洞追踪, 系统扫描, 请求拦截