holbein-io/ephor-scanner

# Ephor Scanner Kubernetes 漏洞扫描代理，用于发现运行中的工作负载，使用 [Trivy](https://github.com/aquasecurity/trivy) 扫描容器镜像，并将结果报告给 [Ephor](https://github.com/holbein-io/ephor) API。 ## 工作原理 扫描器作为 Kubernetes CronJob 运行，每次执行时运行一个无状态的 6 阶段流水线： ``` 1. Load config Read environment variables, initialize logging | 2. Discover workloads Query K8s API for Deployments, StatefulSets, | DaemonSets, and CronJobs across target namespaces | 3. Deduplicate images Extract unique container images across all workloads | 4. Scan images Update Trivy vulnerability DB, then scan all unique | images concurrently (configurable parallelism) | 5. Build payloads Group results by namespace, map to Ephor schema | 6. Deliver POST per-namespace results to /api/v1/scans/ingest ``` 每次运行都会生成一个扫描组 ID (UUID)，用于将所有按命名空间划分的 payload 关联在一起。镜像扫描失败会被记录，但不会阻止成功结果的交付。 ## 快速开始 前置条件：一个已安装 [Helm 3](https://helm.sh/) 的 Kubernetes 集群。 ``` helm install ephor-scanner ./deploy/helm/ephor-scanner \ --set ephor.apiUrl=http://ephor-api:8080 \ --set scan.namespaces=default,production ``` 扫描器将按默认计划运行（每 6 小时一次）。要触发立即扫描： ``` kubectl create job --from=cronjob/ephor-scanner ephor-scanner-manual ``` ## 配置 所有配置均通过环境变量完成。使用 Helm chart 部署时，这些变量通过 `values.yaml` 文件设置。 ### 必需项 | Variable | Description | |---|---| | `EPHOR_API_URL` | Ephor API 的 Base URL（例如 `http://ephor-api:8080`） | | `SCAN_NAMESPACES` | 要扫描的 Kubernetes 命名空间的逗号分隔列表 | ### 可选项 | Variable | Default | Description | |---|---|---| | `SCAN_CONCURRENCY` | `3` | 并行镜像扫描的数量 | | `SCAN_SEVERITY` | `CRITICAL,HIGH,MEDIUM,LOW` | 要包含的严重性级别 | | `SCAN_WORKLOAD_TYPES` | `Deployment,StatefulSet,DaemonSet,CronJob` | 要发现的工作负载类型 | | `EPHOR_AUTH_HEADER` | _(none)_ | 自定义认证 header 名称 | | `EPHOR_AUTH_VALUE` | _(none)_ | 认证 header 值 | | `TRIVY_BINARY` | `trivy` | Trivy 可执行文件的路径 | | `TRIVY_CACHE_DIR` | `/tmp/trivy-cache` | Trivy 缓存目录 | | `TRIVY_TIMEOUT` | `300` | 单个镜像扫描超时时间（秒） | | `TRIVY_DB_UPDATE_TIMEOUT` | `60` | 漏洞数据库更新超时时间（秒） | | `TRIVY_DB_REPO` | _(none)_ | Trivy DB 的自定义 OCI 仓库（离线环境） | | `TRIVY_SKIP_DB_UPDATE` | `false` | 如果缓存已预填充，则跳过 DB 更新 | | `LOG_LEVEL` | `info` | 日志级别（`debug`, `info`, `warn`, `error`） | | `LOG_FORMAT` | `json` | 日志格式（`json` 或 `text`） | ## Helm Values 位于 `deploy/helm/ephor-scanner/` 的 Helm chart 关键值： | Value | Default | Description | |---|---|---| | `schedule` | `0 */6 * * *` | CronJob 调度计划 | | `ephor.apiUrl` | `""` | Ephor API URL（必需） | | `scan.namespaces` | `""` | 目标命名空间（必需） | | `scan.concurrency` | `3` | 并行镜像扫描数 | | `cache.enabled` | `true` | 通过 PVC 在多次运行间持久化 Trivy DB | | `cache.size` | `1Gi` | PVC 存储大小 | | `activeDeadlineSeconds` | `3600` | 最大作业运行时间 | | `resources.requests.memory` | `128Mi` | 内存请求 | | `resources.limits.memory` | `512Mi` | 内存限制 | 有关可配置值的完整列表，请参阅 `deploy/helm/ephor-scanner/values.yaml`。 ## 开发 前置条件：Go 1.25+, Make。 ``` # 构建 make build # 运行单元测试 make test # 运行集成测试（需要 Trivy 二进制文件和网络访问） make test-integration # Lint make lint # 格式化 make fmt ``` 二进制文件构建到 `bin/ephor-scanner`。版本号从 git 标签自动检测。 ### Docker ``` docker build -t ephor-scanner . ``` 该镜像为多阶段构建：从源代码编译的 Go 二进制文件，从 `aquasec/trivy:0.69.3` 复制的 Trivy 二进制文件，两者都放置在 Alpine 3.21 基础镜像上。以非 root 用户 (uid 10001) 运行。 ## 架构 ``` ephor-scanner/ cmd/scanner/ Entry point (6-phase orchestration) config/ Environment variable loading internal/ api/ HTTP client for Ephor API delivery discovery/ Kubernetes workload discovery (client-go) models/ Data structures matching Ephor API schema processor/ Image deduplication, concurrent scanning, payload building scanner/ Trivy CLI wrapper (os/exec) deploy/helm/ Helm chart (CronJob, RBAC, ConfigMap, Secret, PVC) tests/integration/ Integration tests docs/adr/ Architecture Decision Records ``` 设计决策记录在 `docs/adr/` 中。关键选择： - **Trivy 作为 CLI wrapper** (ADR-001) -- 通过稳定的 JSON 接口将扫描器版本与 Trivy 版本解耦 - **无状态架构** (ADR-002) -- 无本地状态，所有持久化由 Ephor API 处理 - **直接 K8s API 发现** (ADR-003) -- 使用 client-go 进行细粒度的工作负载控制 - **CronJob 部署模型** (ADR-004) -- 资源高效的批处理执行 - **持久化 Trivy 缓存** (ADR-009) -- PVC 避免每次运行时重新下载漏洞 DB ## 兼容性 Ephor 组件独立版本化。请查看 [兼容性矩阵](https://docs.holbein.io/reference/compatibility) 以确保您的扫描器、API 和 Trivy 版本能够协同工作。 ## 贡献 欢迎贡献。请阅读我们的[贡献指南](CONTRIBUTING.md)以了解开发工作流程、提交约定和 pull request 流程的详细信息。 所有贡献者在第一个 pull request 被接受之前必须签署我们的[贡献者许可协议](CLA.md)。GitHub Action 将自动引导您完成该流程。 ## 许可证 本项目采用 [GNU Affero General Public License v3.0](LICENSE) 许可。

标签：Anthropic, CIS基准, Claude, CronJob, CVE检测, DevSecOps, Docker, Ephor, EVTX分析, Go, Helm Chart, Ruby工具, SBOM, TLS, Web截图, 上游代理, 子域名突变, 安全代理, 安全合规, 安全防御评估, 容器安全, 工作负载发现, 日志审计, 活动识别, 硬件无关, 网络代理, 请求响应过滤, 请求拦截, 镜像扫描, 镜像漏洞, 防御工具