hkolvenbach/oci-explorer

# OCI Image Explorer 一款本地 Go 应用程序，用于可视化 OCI 容器镜像结构，包括层、manifest、referrers、SBOM、attestation 和其他供应链制品。      ## 功能特性 - **多平台镜像索引** - 可视化包含所有架构变体（linux/amd64、linux/arm64 等）的 fat manifest。按平台过滤整个 UI，以查看特定于平台的层、配置和 referrers。镜像摘要一目了然地显示总大小、层数和平台数量。 - **层检查** - 查看每一层的 digest、压缩大小、媒体类型和注释。层按照与镜像文件系统匹配的堆栈顺序列出。 - **配置详情** - 完整的运行时配置：架构、操作系统、entrypoint、cmd、环境变量、暴露端口、工作目录、用户和标签。构建历史追踪创建层的每一条 Dockerfile 指令，包括来自 `ENV` 和 `LABEL` 命令的空层。 - **Referrers (OCI 1.1)** - 发现并检查通过 OCI Referrers API 附加的供应链制品： - **签名** (Notary, Cosign)，包含 Sigstore 证书身份、OIDC 签发者和签名 digest - **SBOM** (CycloneDX, SPDX)，支持一键下载完整的 SBOM 文档 - **Attestation** (SLSA Provenance, In-Toto)，支持内联查看 attestation payload - **VEX** (OpenVEX)，包含解析后的语句，显示漏洞状态、理由和受影响的产品 - **Cosign 标签发现** — 除了 Referrers API 外，还会查找 `.sig` 和 `.att` cosign 风格的标签 - **漏洞扫描 ([Trivy](https://trivy.dev))** - 按需进行 CVE 扫描，提供丰富的详细信息： - 来自多个来源（NVD、Red Hat 等）的 CVSS 评分，针对每个漏洞显示，并在展开的详情视图中展示 - 按严重性分组的可折叠部分（CRITICAL、HIGH、MEDIUM、LOW、UNKNOWN），并显示每组的数量 - 两级过滤：跨所有组的全局状态过滤器（头部芯片），以及针对每个部分的过滤器覆盖 - 可修复/不可修复/VEXed 状态芯片，在扫描头部和每个严重性组别都显示计数 - 可展开的 CVE 详情，包含包元数据、已安装和修复版本，以及保留格式的完整描述 - 指向 NVD、Red Hat、Debian、Ubuntu、GitHub Advisories、Aqua 和其他漏洞数据库的参考链接 - 自动 VEX 交叉引用：如果镜像具有 OpenVEX referrers，扫描结果会标注 VEX 状态（未受影响、已修复、调查中） - 对跨多个目标的相同 CVE 进行去重（例如，在许多二进制文件中发现的 Go stdlib 漏洞会合并为一个条目） - **匹配标签** - 发现仓库中指向同一 digest 的标签。对于 Docker Hub 和 GCR/Artifact Registry，显示所有别名（例如 `alpine:latest` → 还有 `3.23.3`、`3.23`、`3`），并高亮显示当前标签。不支持的注册表会显示说明注释。 - **标签列表** - 浏览仓库中的所有标签，支持点击导航以检查任何标签。 - **供应链安全评分** - 一目了然的 0–10 分评分，带有动画环形图和字母等级。评估供应链制品的存在：签名、SBOM、attestation、VEX 文档、最小化基础镜像特征（层少、体积小、非 root 用户、无 shell entrypoint）。可展开的详情面板显示每个标准及其通过/失败状态。 - **图形视图** - 交互式有向图，支持平移、缩放和自适应视图控件。显示完整的镜像结构：镜像索引、平台 manifest、配置、层和所有 referrer 制品（SBOM、VEX、attestation、签名），带有颜色编码的节点和关系边。 - **可复制 Digest** - 点击 UI 中的任何 SHA-256 digest 即可将完整值复制到剪贴板。 - **移动端响应式** - 自适应布局，在小屏幕上堆叠列，在桌面上并排显示面板。 - **身份验证** - 使用 Docker 凭证助手（`~/.docker/config.json`）访问私有注册表。支持 Docker Hub、GHCR、GCR、ECR 以及任何配置了凭证助手的注册表。 ## 快速开始 ### 前置条件 - Go 1.25 或更高版本 - Node.js 22+（用于构建 Svelte 前端） - Make（可选，用于构建自动化） - [Trivy](https://trivy.dev) v0.69+（可选，用于漏洞扫描） ### 构建与运行 ``` # 克隆或下载此项目 git clone https://github.com/hkolvenbach/oci-explorer.git cd oci-explorer # 下载依赖项 go mod tidy # 构建并运行 (Docker — 包含 Trivy) make run # 或手动运行 (需要先构建 frontend) cd web && npm ci && npm run build && cd .. go build -o build/oci-explorer . ./build/oci-explorer ``` 应用程序在 http://localhost:8080 启动 Web 服务器 ## 截图 ### CLI 启动 ``` ┌─────────────────────────────────────────────────┐ │ 🐳 OCI Image Explorer │ ├─────────────────────────────────────────────────┤ │ URL: http://localhost:8080 │ │ Platform: darwin/arm64 │ │ Version: 0.5.0 │ │ Press Ctrl+C to stop │ └─────────────────────────────────────────────────┘ ``` ### 主页  ### 详情视图 检查 `ghcr.io/hkolvenbach/oci-explorer:latest` — 一目了然地显示供应链安全评分、平台、层、配置和 referrers：  ### Referrers 视图 通过 OCI Referrers API 发现的供应链制品：SBOM (CycloneDX)、带有 Sigstore 身份的 cosign 签名、attestation (SLSA Provenance) 和 VEX 文档：  ### 漏洞扫描 对 `golang:1.21` 进行按需 Trivy 扫描 — 跨 5 个严重性级别的 4,088 个去重漏洞。头部芯片显示可修复/不可修复的总数；每个严重性组别都有自己的过滤器覆盖。展开 CVE 会显示按来源（NVD、Red Hat 等）分类的 CVSS 评分、包元数据、描述和指向漏洞数据库的参考链接。如果镜像带有 OpenVEX referrers，受影响的 CVE 会自动标注 VEX 状态：  ### 图形视图 包含 SBOM、VEX、attestation 和签名的完整镜像结构的交互式图形可视化：  ### 命令行参数 | 参数 | 短参数 | 默认值 | 描述 | |------|-------|---------|-------------| | `--port` | | `8080` | HTTP 服务器端口 | | `--verbose` | `-v` | `false` | 启用详细日志 | ``` # 在不同端口运行 ./build/oci-explorer --port 3000 # 启用详细日志运行 ./build/oci-explorer -v ``` ### 环境变量 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `PORT` | `8080` | HTTP 服务器端口 | ## 为多平台构建 为所有支持的平台构建二进制文件： ``` make build-all ``` 这将在 `build/` 目录中为以下平台创建二进制文件： - Linux (amd64, arm64) - macOS (amd64, arm64) 创建发布归档： ``` make release ``` ## API 端点 ### GET /api/inspect 检查 OCI 镜像并返回其完整结构。 **查询参数：** - `image` (必需) - 镜像引用（例如 `nginx:latest`、`ghcr.io/org/repo:tag`） **响应：** ``` { "success": true, "data": { "repository": "library/nginx", "tag": "latest", "digest": "sha256:abc123...", "imageIndex": { ... }, "manifest": { ... }, "config": { ... }, "tags": ["latest", "1.25", "1.25.3"], "referrers": [ ... ] } } ``` ### GET /api/tags 列出仓库的所有标签。 **查询参数：** - `repository` (必需) - 仓库名称（例如 `nginx`、`ghcr.io/org/repo`） ### GET /api/matching-tags 查找仓库中解析为与给定镜像相同 digest 的所有标签。 **查询参数：** - `image` (必需) - 镜像引用（例如 `alpine:latest`、`gcr.io/google-containers/pause:3.2`） **注册表支持：** | 注册表 | 策略 | |---|---| | Docker Hub | 分页 Hub API，客户端匹配 digest | | GCR / Artifact Registry | 扩展 `tags/list` 与 manifest 映射（1 次请求） | | 其他 (GHCR, Quay, ECR) | 返回空列表 + 说明注释 | **响应：** ``` { "success": true, "data": { "repository": "index.docker.io/library/alpine", "digest": "sha256:25109184c71b...", "tags": ["latest", "3.23.3", "3.23", "3"] } } ``` ### GET /api/sbom 从 attestation manifest 下载 SBOM 内容。 **查询参数：** - `repository` (必需) - 完整仓库名称 - `digest` (必需) - 包含 SBOM 的 attestation manifest 的 digest **响应：** 原始 SBOM 内容（SPDX 或 CycloneDX JSON），带 `Content-Disposition: attachment` ### GET /api/vex 从 attestation 获取并解析 VEX (Vulnerability Exploitability eXchange) 文档。 **查询参数：** - `repository` (必需) - 完整仓库名称 - `digest` (必需) - 包含 VEX 文档的 attestation manifest 的 digest **响应：** 解析后的 OpenVEX 文档，包含语句、状态、理由和产品标识符。 ### GET /api/scan 使用 Trivy 扫描容器镜像的漏洞（必须在本地安装）。 **查询参数：** - `image` (必需) - 镜像引用（例如 `nginx:latest`） **响应：** 按严重性分组的漏洞，包含 CVE 详情、受影响的包和修复版本。 ### GET /api/health 健康检查端点。 ## 使用示例 ### 检查公共镜像 ``` # Docker Hub curl "http://localhost:8080/api/inspect?image=nginx:latest" curl "http://localhost:8080/api/inspect?image=alpine:3.19" # GitHub Container Registry curl "http://localhost:8080/api/inspect?image=ghcr.io/sigstore/cosign/cosign:latest" # Google Container Registry curl "http://localhost:8080/api/inspect?image=gcr.io/distroless/static:latest" ``` ### 查找匹配标签 **支持的注册表** (Docker Hub) — 显示共享同一 digest 的所有标签，查询的标签标记为 "current"：  **不支持的注册表** (GHCR) — 显示解释限制的警告：  ``` # Docker Hub — 发现 alpine:latest 也标记为 3.23.3, 3.23, 3 curl "http://localhost:8080/api/matching-tags?image=alpine:latest" # GCR — 通过 extended tags/list 进行单次请求查询 curl "http://localhost:8080/api/matching-tags?image=gcr.io/google-containers/pause:3.2" # GHCR — 返回提示 (不支持的 Registry) curl "http://localhost:8080/api/matching-tags?image=ghcr.io/hkolvenbach/oci-explorer:0.2.2" ``` ### 检查私有镜像 应用程序使用 Docker 的凭证助手。首先登录： ``` # Docker Hub docker login # GitHub Container Registry docker login ghcr.io # AWS ECR aws ecr get-login-password | docker login --username AWS --password-stdin .dkr.ecr..amazonaws.com ``` 然后检查： ``` curl "http://localhost:8080/api/inspect?image=ghcr.io/myorg/private-image:v1" ``` ## 供应链安全 所有发布制品都已签名并经过证明，用于端到端供应链验证。 | 制品 | 保护措施 | |----------|-----------| | Docker 镜像 | Cosign 无密钥签名 (Sigstore OIDC) | | Docker 镜像 | SLSA Build Provenance attestation | | Docker 镜像 | 嵌入式 SBOM (BuildKit) | | Docker 镜像 | OpenVEX attestation (基于 govulncheck) | | 发布二进制文件 | GitHub Artifact Attestation (SLSA provenance) | | 运行时基础镜像 | `gcr.io/distroless/static-debian12`（零 CVE，无 shell） | ### 验证镜像签名 ``` cosign verify \ --certificate-identity-regexp="https://github.com/hkolvenbach/oci-explorer" \ --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \ ghcr.io/hkolvenbach/oci-explorer:latest ``` ### 验证 SLSA provenance ``` cosign verify-attestation \ --type slsaprovenance1 \ --certificate-identity-regexp="https://github.com/hkolvenbach/oci-explorer" \ --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \ ghcr.io/hkolvenbach/oci-explorer:latest ``` ### 验证 OpenVEX attestation ``` cosign verify-attestation \ --type openvex \ --certificate-identity-regexp="https://github.com/hkolvenbach/oci-explorer" \ --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \ ghcr.io/hkolvenbach/oci-explorer:latest ``` ### 验证二进制文件 provenance (GitHub Artifact Attestation) ``` gh release download v0.2.2 --repo hkolvenbach/oci-explorer \ --pattern 'oci-explorer-*-linux-amd64.tar.gz' gh attestation verify oci-explorer-0.2.2-linux-amd64.tar.gz \ --repo hkolvenbach/oci-explorer ``` ### 检查嵌入式 SBOM ``` docker buildx imagetools inspect ghcr.io/hkolvenbach/oci-explorer:latest \ --format '{{ json .SBOM }}' ``` ### 使用 OCI Image Explorer 探索 你也可以让 OCI Image Explorer 指向其自身的镜像，以可视化方式检查所有这些供应链制品 —— 签名、SBOM、attestation 和 provenance： ``` http://localhost:8080/?image=ghcr.io/hkolvenbach/oci-explorer:latest ``` ## 项目结构 ``` oci-explorer/ ├── adrs/ # Architecture decision records ├── docs/ │ ├── api.md # API reference (served at /docs/) │ ├── openapi.yaml # OpenAPI specification (served at /api/openapi.yaml) │ └── screenshots/ # Browser screenshots for README ├── docshandler/ # Documentation HTTP handlers (extracted from main.go) │ ├── docshandler.go # ServeDocs, ServeOpenAPISpec, markdownToHTML │ └── docshandler_test.go ├── registry/ │ ├── client.go # OCI registry client using go-containerregistry │ ├── client_test.go # Registry client tests │ └── testdata/ # Test fixtures (Alpine, Kairos, VEX sample data) ├── scanner/ │ ├── scanner.go # Trivy vulnerability scanner (subprocess-based) │ └── scanner_test.go # Scanner unit tests ├── tools/ │ ├── download-alpine/ # Alpine test data downloader │ └── sbom-extractor/ # Reference SBOM extraction tool ├── web/ # Svelte 5 + TypeScript frontend (Vite) │ ├── src/ │ │ ├── components/ # Svelte components │ │ ├── lib/ # API client, types, state, utilities │ │ ├── App.svelte # Root component │ │ └── main.ts # Entry point │ └── package.json ├── Dockerfile # Container build ├── fly.toml # Fly.io deployment config ├── main.go # HTTP server and handlers ├── Makefile # Build automation ├── go.mod # Go module definition ├── go.sum # Dependency checksums ├── LICENSE # Apache 2.0 ├── README.md # This file └── REFERENCES.md # OCI and SBOM specification references ``` ## 依赖项 ### 后端 - [google/go-containerregistry](https://github.com/google/go-containerregistry) - OCI 注册表客户端 - [gorilla/mux](https://github.com/gorilla/mux) - HTTP 路由器 - [Trivy](https://github.com/aquasecurity/trivy) - 漏洞扫描器（Apache 2.0 许可证，捆绑在 Docker 镜像中） ### 前端 - [Svelte 5](https://svelte.dev) - 响应式 UI 框架 - [Tailwind CSS 4](https://tailwindcss.com) - 实用优先的 CSS - [Vite 6](https://vite.dev) - 构建工具 ## OCI 规范支持 此工具支持 OCI Image Spec 1.1 功能，包括： - **镜像索引** (fat manifest) 用于多平台镜像 - **镜像 Manifest** 包含配置和层描述符 - **镜像配置** 包含运行时设置和构建历史 - **Referrers API** 用于附加的制品（签名、SBOM、attestation） - **注释** 适用于所有描述符类型 ## 许可证 Apache License 2.0

标签：Cosign, CVE, CycloneDX, DevSecOps, Docker, EVTX分析, EVTX分析, Go, Manifest, Mutation, Notary, Ruby工具, SBOM, SBOM分析, SLSA, SPDX, Svelte, VEX, 上游代理, 单文件二进制, 可视化, 多平台镜像, 安全防御评估, 容器, 数字签名, 日志审计, 硬件无关, 签名验证, 证明, 跌倒检测, 软件物料清单, 镜像内部结构, 镜像分析, 镜像层级, 镜像配置