SpaceTerran/homelab-vulnerability-scanner

# Homelab 漏洞扫描器 [](https://opensource.org/licenses/MIT) 针对 Homelab Docker 容器的自动化每周漏洞扫描，具备 AI 驱动的风险评估功能。它会发现您所有的容器仓库，使用 [Trivy](https://github.com/aquasecurity/trivy) 扫描每个 Docker 镜像，并将结果结合您的环境上下文发送给 [Claude](https://claude.ai)，从而生成按优先级排序的、可操作的建议——最终以 GitHub Issue 的形式呈现。 ## 工作原理 1. **发现 (Discover)** — 查询 GitHub API 以获取您组织内所有 `*-Containers` 仓库 2. **收集 (Collect)** — 从 docker-compose 文件中提取 `image:` 引用 3. **扫描 (Scan)** — 对每个镜像运行 Trivy HIGH/CRITICAL 级别扫描 4. **分析 (Analyze)** — 将结果和环境上下文提供给 Claude CLI 进行风险评估 5. **报告 (Report)** — 创建一个包含分类结果的 GitHub Issue ``` GitHub API ──> docker-compose files ──> image list │ ▼ Trivy scans (HIGH/CRITICAL) │ ▼ Environment context + findings │ ▼ Claude CLI analysis │ ▼ GitHub Issue (auto-closes previous) ``` ## 前置条件 - 拥有使用 docker-compose 的容器仓库的 **GitHub 组织 (org)** - 具有 Docker 访问权限的 **自托管 GitHub Actions runner** - 带有 OAuth token 的 **Claude CLI**（需要 [Claude Max 订阅](https://claude.ai)） - 具有 `repo` + `workflow` + `write:packages` 权限范围的 **GitHub PAT** ## 快速开始 1. **Fork 本仓库** 到您的 GitHub 组织中 2. **自定义 `context/environment.md`** — 填入您的基础设施详情，这是让 AI 分析有用的关键（例如哪些服务面向互联网，哪些在 SSO 后面等） 3. **更新 `scripts/collect-images.sh`** — 将 `ORG="your-org"` 改为您的 GitHub 组织名称 4. **添加组织级 Secrets：** | Secret | 用途 | |--------|---------| | `PAT_TOKEN` | GitHub API 访问 + GHCR 认证（用于私有镜像） | | `CLAUDE_CODE_OAUTH_TOKEN` | Claude CLI 认证 | 5. **启用工作流** — 每周运行（UTC 时间周日早上 6 点）或通过 Actions 标签页手动触发 ## 配置 ### 环境上下文 (`context/environment.md`) 此文件为 AI 分析师提供您基础设施的相关知识，以便其恰当地评估风险。面向互联网的服务中的 CVE 与仅在局域网（LAN）内且位于 SSO 之后的同名服务中的 CVE，处理方式是不同的。 根据以下内容进行自定义： - 您的网络架构（WAF、反向代理、防火墙区域） - 认证覆盖范围（哪些服务在 SSO 之后） - 服务暴露级别（面向互联网 vs 仅限 LAN） - 容器运行时注意事项（特权容器、socket 挂载） ### 仓库发现 容器仓库通过 GitHub API 动态发现。您组织中任何匹配 `*-Containers` 的非存档仓库都会被自动包含在内——当您添加新的容器仓库时，无需更改配置。 ### 所需 Secrets | Secret | 权限范围 (Scopes) | 用途 | |--------|--------|---------| | `PAT_TOKEN` | `repo`, `workflow`, `write:packages` | GitHub API + GHCR 认证 | | `CLAUDE_CODE_OAUTH_TOKEN` | — | Claude CLI (Max 订阅 OAuth) | ## 项目结构 ``` homelab-vulnerability-scanner/ ├── .github/workflows/ │ └── weekly-audit.yml # Workflow: schedule + orchestration ├── context/ │ └── environment.md # Your infrastructure context for AI ├── scripts/ │ ├── collect-images.sh # Discover repos + extract image refs │ └── generate-report.sh # Trivy scans + Claude analysis + report ├── LICENSE └── README.md ``` ## 输出示例 工作流会创建一个按风险分类显示结果的 GitHub Issue： ### 需要关注 (Needs Attention) 面向互联网的服务中的漏洞，或需要采取行动的关键严重性问题。 ### 信息参考 (Informational) 位于 SSO 之后且仅限 LAN 的服务中的漏洞，或者 Renovate 会自动更新的情况。 ### 干净 (Clean) 没有 HIGH/CRITICAL 发现的镜像。 每项发现均包含：通俗语言的 CVE 描述、修复可用性、基于您环境的风险评估，以及具体的建议操作。 ## 计划 | 触发器 | 时间 | |---------|------| | 定时触发 | UTC 时间每周日凌晨 6:00 | | 手动触发 | 通过 Actions 标签页使用 `workflow_dispatch` | 当创建新报告时，之前的报告会被自动关闭。原始扫描数据保存在 workflow artifacts 中。 ## 博客文章 若要了解关于此项目构建过程的详细演练，请查看博客文章：[Automated Vulnerability Scanning for Your Homelab Containers](https://spaceterran.com/posts/automated-vulnerability-scanning-homelab-containers-ai/) ## 贡献 欢迎贡献！如果您发现错误或有功能请求，请开启一个 issue 或提交 PR。 ## 许可证 [MIT](LICENSE)

标签：AI 风险评估, CI/CD 安全, Claude, CVE检测, CVE 检测, DevSecOps, DLL 劫持, Docker 容器, Docker部署, GitHub Actions, GitHub Issue, Homelab, Web截图, 上游代理, 大语言模型, 安全合规, 容器安全, 应用安全, 持续监控, 数据投毒防御, 结构化查询, 网络代理, 自动化安全, 自动化报告, 自动笔记, 请求拦截