LarsLaskowski/DockerUpdateGuard

# DockerUpdateGuard DockerUpdateGuard 是一个 Web 应用程序，用于追踪 Docker 中实际运行的内容，将其与 registry 元数据进行比较，并展示哪些地方需要注意更新、漏洞以及共享的基础镜像依赖。 它是为那些不满足于仅仅知道“存在更新的 tag”的团队而设计的。该应用程序维护一个已观察镜像和运行中容器的清单，将它们与 registry 的 tag 和 digest 相关联，采样 CPU、内存和网络使用情况，并保留扫描历史记录，以便审查更新决策而不是凭猜测。 ## 该应用程序有助于 - 发现已配置的 Docker 实例及其上当前运行的容器 - 检测运行中的容器是最新的、落后于较新版本，还是需要人工审查 - 当 `latest` 等别名 tag 与语义版本 tag 共享相同的 digest 时，将它们解析并匹配 - 随时间追踪 Docker 实例和运行中容器的资源使用情况 - 将运行中的容器与已观察的镜像和共享基础镜像进行关联 - 刷新镜像的漏洞数据 - 保留历史扫描结果以供审计和故障排除 ## 主要 UI 区域 - **Dashboard**：当前清单的汇总视图 - **Observed Images**：从 Docker Hub 账户数据中发现的仓库和 tag - **Runtime Containers**：具有更新和漏洞状态的实时工作负载清单 - **Docker Instances**：已配置的引擎及其使用历史 - **Shared Base Images**：已观察镜像中基础镜像的重用情况 - **Scan History**：近期的后台活动及其结果 ## 运行时要求 DockerUpdateGuard 需要： - 一个 PostgreSQL 数据库 - 访问一个或多个 Docker Engine endpoint - 可选的 Docker Hub 凭据，用于经过身份验证的 registry 访问 - 每个 Docker 实例可选的 Portainer 访问权限 - 用于遥测数据导出的可选 OTLP endpoint - 启用基于 Trivy 的漏洞扫描时，可选的 Trivy 服务器 应用程序在启动时会自动应用 EF Core 迁移。 ## 运行应用程序 ### 本地开发 使用仓库根目录中的解决方案文件： ``` dotnet restore DockerUpdateGuard.slnx reihitsu-format ./ dotnet build DockerUpdateGuard.slnx -c Release --no-restore dotnet test src\Tests\**\*.csproj -c Release --no-build --logger trx --collect:"XPlat Code Coverage" ``` ### Docker 镜像 容器镜像默认监听 `8080` 端口。 在 Linux 上使用本地 Docker socket 的示例： ``` docker run -d \ --name dockerupdateguard \ -p 8080:8080 \ --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \ -v /path/to/appsettings.json:/app/appsettings.json:ro \ networlddev/dockerupdateguard:latest ``` 当 DockerUpdateGuard 在 Linux 容器内运行，并且需要通过 Unix socket 检查宿主机 Docker Engine 时，必须满足两个条件： 1. `/var/run/docker.sock` 必须挂载到容器中 2. 在 appsettings.json 中，相应的 Docker 实例 BaseUrl 必须设置为 `unix:///var/run/docker.sock` 如果缺少这两个设置中的任何一个，应用程序将无法连接到宿主机引擎。 ## 配置模型 DockerUpdateGuard 使用标准的 ASP.NET Core 配置绑定，并在容器部署时优先使用配置文件： - `appsettings.json` - `appsettings.{Environment}.json` - 命令行参数 - ASP.NET Core 支持的密钥存储 例如： - JSON 键：`DockerUpdateGuard:Scanning:RuntimeImageUpdateScanIntervalMinutes` ## 配置参考 ### 连接和主机设置 | 键 | 默认值 | 必需 | 描述 | | --- | --- | --- | --- | | `ConnectionStrings:DockerUpdateGuard` | 无 | 是* | 当未设置 `DockerUpdateGuard:ConnectionString` 时使用的命名 PostgreSQL 连接字符串 | | `DockerUpdateGuard:ConnectionString` | 无 | 是* | 内联 PostgreSQL 连接字符串 | | `DockerUpdateGuard:ConnectionStringName` | `DockerUpdateGuard` | 否 | 要解析的 `ConnectionStrings` 条目名称 | | `DockerUpdateGuard:DisplayVersion` | 程序集版本 | 否 | UI 页脚中显示的版本字符串；Docker 镜像会自动设置此项 | \* 必须至少配置 `DockerUpdateGuard:ConnectionString` 或 `ConnectionStrings:{ConnectionStringName}` 中的一个。 ### `DockerUpdateGuard:DockerHub` | 键 | 默认值 | 必需 | 描述 | | --- | --- | --- | --- | | `Registry` | `docker.io` | 是 | 由 Docker Hub 集成处理的 registry 主机 | | `UserName` | 无 | 否 | 用于经过身份验证的 API 请求的 Docker Hub 用户名 | | `Pat` | 无 | 否 | Docker Hub 个人访问令牌 | | `RequestTimeoutSeconds` | `30` | 否 | 对外 Docker Hub 和 OCI registry 请求的超时时间 | | `MaxParallelRequests` | `4` | 否 | registry 操作的最大逻辑请求并发数 | ### `DockerUpdateGuard:Vulnerabilities` | 键 | 默认值 | 必需 | 描述 | | --- | --- | --- | --- | | `Enabled` | `false` | 否 | 启用漏洞刷新 | | `Provider` | `None` | 启用时必需 | 支持的值：`None`, `DockerScout`, `Trivy` | | `TrivyBaseUrl` | 无 | `Trivy` 必需 | Trivy 服务器的 Base URL | | `RequestTimeoutSeconds` | `30` | 否 | 漏洞提供程序请求的超时时间 | ### `DockerUpdateGuard:Scanning` | 键 | 默认值 | 描述 | | --- | --- | --- | | `DiscoveryIntervalMinutes` | `15` | 已配置 Docker 实例的同步间隔 | | `DockerHubAccountDiscoveryIntervalMinutes` | `60` | 刷新 Docker Hub 账户镜像清单的间隔 | | `OwnImageBaseScanIntervalMinutes` | `60` | 解析已观察镜像基础镜像链的间隔 | | `DockerHubRequestLimitWindowHours` | `6` | 计划内 Docker Hub 刷新的配额窗口大小 | | `DockerHubRequestLimitPerWindow` | `200` | 每个配额窗口计划内的 Docker Hub 请求预算 | | `DockerHubReservedManualRequestsPerWindow` | `40` | 为手动扫描和临时活动保留的请求预算 | | `RuntimeImageUpdateScanIntervalMinutes` | `30` | 刷新运行中容器状态和更新状态的间隔 | | `ResourceStatisticsIntervalMinutes` | `5` | 采样 CPU、内存和网络使用情况的间隔 | | `VulnerabilityRefreshIntervalMinutes` | `180` | 刷新漏洞信息的间隔 | | `CleanupIntervalMinutes` | `720` | 清理旧扫描数据的间隔 | | `RetryCount` | `2` | 瞬时后台故障的重试次数 | | `RetainScanRunsDays` | `30` | 已完成的扫描历史的保留期 | ### `DockerUpdateGuard:DockerInstances[]` 每个条目描述一个 Docker Engine endpoint。 | 键 | 默认值 | 必需 | 描述 | | --- | --- | --- | --- | | `Name` | 无 | 是 | Docker 实例的显示名称 | | `BaseUrl` | 无 | 是 | Docker endpoint URI；验证允许 `http`, `https`, `tcp`, `unix` 和 `npipe` | | `Enabled` | `true` | 否 | 启用或禁用此 Docker 实例 | | `UseTls` | `false` | 否 | 对于 `tcp://` endpoint，将连接升级为 HTTPS | | `SkipCertificateValidation` | `false` | 否 | 跳过 TLS endpoint 的服务器证书验证。**不安全：** 禁用 TLS 身份验证并使连接面临中间人攻击风险；在运行时只要其处于活动状态就会记录警告。仅对带有自签名证书的受信任 endpoint 使用。 | | `CertificatePath` | 无 | 否 | 用于 TLS 安全引擎访问的可选客户端证书路径 | | `RequestTimeoutSeconds` | `15` | 否 | Docker Engine 请求的超时时间 | 推荐的 Linux socket 配置： | 键 | 示例值 | | --- | --- | | `DockerUpdateGuard:DockerInstances[0]:Name` | `Local Docker` | | `DockerUpdateGuard:DockerInstances[0]:BaseUrl` | `unix:///var/run/docker.sock` | | `DockerUpdateGuard:DockerInstances[0]:Enabled` | `true` | ### `DockerUpdateGuard:DockerInstances[].Portainer` Portainer 设置是可选的，仅在需要提供基于 Portainer 的操作时才需要。 | 键 | 默认值 | 必需 | 描述 | | --- | --- | --- | --- | | `Enabled` | `false` | 否 | 为 Docker 实例启用 Portainer 集成 | | `BaseUrl` | 无 | 启用时必需 | 绝对 `https` Portainer URL（强烈建议）；参见 `AllowInsecureHttp` | | `AllowInsecureHttp` | `false` | 否 | 允许为 `BaseUrl` 使用明文 `http`；凭据将以未加密方式传输——仅在 localhost 或受信任的专用网络上使用 | | `Username` | 无 | 条件必需 | Portainer 登录的用户名 | | `Password` | 无 | 条件必需 | Portainer 登录的密码 | | `ApiToken` | 无 | 条件必需 | Portainer API token；优先于用户名/密码 | | `EndpointId` | 无 | 否 | 显式 Portainer endpoint ID；省略时自动发现 | | `RequestTimeoutSeconds` | `15` | 否 | Portainer 请求的超时时间 | 启用 Portainer 时，必须配置以下其中一项： - `ApiToken`，或者 - `Username` 和 `Password` ### 遥测 | 键 | 默认值 | 必需 | 描述 | | --- | --- | --- | --- | | `ServiceName` | `DockerUpdateGuard` | 启用遥测时必需 | 遥测资源中使用的服务名称 | | `OtlpEndpoint` | 无 | 否 | 绝对 `http` 或 `https` OTLP endpoint | | `Instance` | 无 | 否 | 逻辑部署实例名称 | | `EnableLogging` | `true` | 否 | 启用 OpenTelemetry 日志导出 | | `EnableMetrics` | `true` | 否 | 启用 OpenTelemetry 指标导出 | | `EnableTracing` | `true` | 否 | 启用 OpenTelemetry 追踪导出 | 如果所有三个遥测开关均为 `false`，则遥测实际上已被禁用。 ## 配置示例 ### JSON ``` { "ConnectionStrings": { "DockerUpdateGuard": "Host=postgres;Port=5432;Database=dockerupdateguard;Username=dockerupdateguard;Password=change-me" }, "DockerUpdateGuard": { "ConnectionStringName": "DockerUpdateGuard", "DockerHub": { "Registry": "docker.io", "UserName": "dockerupdateguard", "Pat": "change-me", "RequestTimeoutSeconds": 30, "MaxParallelRequests": 4 }, "Vulnerabilities": { "Enabled": true, "Provider": "Trivy", "TrivyBaseUrl": "http://trivy:4954", "RequestTimeoutSeconds": 30 }, "Scanning": { "DiscoveryIntervalMinutes": 5, "DockerHubAccountDiscoveryIntervalMinutes": 15, "OwnImageBaseScanIntervalMinutes": 30, "DockerHubRequestLimitWindowHours": 6, "DockerHubRequestLimitPerWindow": 200, "DockerHubReservedManualRequestsPerWindow": 40, "RuntimeImageUpdateScanIntervalMinutes": 10, "ResourceStatisticsIntervalMinutes": 5, "VulnerabilityRefreshIntervalMinutes": 60, "CleanupIntervalMinutes": 720, "RetryCount": 1, "RetainScanRunsDays": 14 }, "DockerInstances": [ { "Name": "Local Docker", "BaseUrl": "unix:///var/run/docker.sock", "Enabled": true, "UseTls": false, "SkipCertificateValidation": false, "RequestTimeoutSeconds": 15, "Portainer": { "Enabled": false, "BaseUrl": "https://portainer.local", "EndpointId": "1", "RequestTimeoutSeconds": 15 } } ] }, "Telemetry": { "ServiceName": "DockerUpdateGuard", "Instance": "Production", "OtlpEndpoint": "http://otel-collector:4317", "EnableLogging": true, "EnableMetrics": true, "EnableTracing": true } } ``` ### 容器部署配置 建议将 appsettings.json 挂载到容器中，而不是使用环境变量。例如： - 将您的配置文件挂载到容器的内容根目录，例如：`-v /path/to/appsettings.json:/app/appsettings.json:ro` 有关确切的键和结构，请参见上面的 JSON 示例。 ## 基于 Docker 部署的注意事项 - 容器默认监听 8080 端口 - 镜像根据镜像构建参数设置 `DockerUpdateGuard:DisplayVersion` - 对于 Linux 宿主机监控，请绑定挂载 `/var/run/docker.sock` - 对于受 TLS 保护的远程引擎，如果使用了 `CertificatePath`，还需挂载客户端证书文件 - 应用程序需要对已配置的 registry、可选的 Portainer endpoint、可选的 Trivy 服务器和可选的 OTLP collector 进行出站网络访问 ## 许可证 本仓库根据 LICENSE.md 中描述的专有条款进行分发。有关完整的许可证文本，请参见 LICENSE.md。

标签：Docker, 占用监测, 安全防御评估, 测试用例, 用户代理, 请求拦截, 资产管理, 资源监控, 运维监控, 镜像更新