Layerleak 是一个只读的 OCI 镜像密钥扫描器。它无需 Docker 守护进程即可解析公共镜像引用，根据 OCI 摘要验证下载的内容，重建层状态，检查已删除的构件和镜像元数据，并返回经过脱敏、带有来源信息的发现结果。
它支持 Docker Hub、GHCR、Quay、GCR、MCR、Amazon ECR Public 以及其他兼容 OCI 的注册表。结果可以保存为 JSON，并持久化到 PostgreSQL 中供捆绑的 API 使用。
此开发树记录了 github.com/brumbelow/layerleak/v3 模块路径上的 3.0.0 系列。下面展示的候选发布命令只有在确切标签发布后才可安装。变更日志和 OpenAPI 文档中的 3.0.0 标签被有意冻结，以便已接受的候选发布版本可以从同一源提交提升。
Layerleak 扫描不受信任的镜像内容，因此其默认设置有意保持有限并采用故障关闭策略：
partial 或 failed，绝不会报告为干净扫描。Layerleak 不验证检测到的凭据是否有效。API 没有授权模型：它默认开放，可选的 LAYERLEAK_API_BEARER_TOKENS 共享令牌检查是针对 /api/ 路径的纵深防御，而非访问控制。无论哪种方式，都只能将其暴露在受信任的网络上或经过身份验证的网关之后。
Layerleak 需要 Go 1.27.1 或更高版本。```bash go install github.com/brumbelow/layerleak/v3@latest layerleak --version layerleak --help
`/v3` 模块路径是规范的安装目标；安装后的二进制文件
仍然命名为 `layerleak`。当可复现性很重要时，请显式固定一个稳定版或候选发布版：```bash
go install github.com/brumbelow/layerleak/[email protected]
go install github.com/brumbelow/layerleak/[email protected]
/v3 路径上的 @latest 会选择已发布的最高 v3 版本。一旦存在稳定版本，Go 就会将预发布版本从 @latest 中排除，因此当仅发布候选版本时，@latest 会解析为最新的候选版本。根路径 github.com/brumbelow/layerleak 不带 /v3 将永远停留在 v1.0.0；请始终包含 /v3。检出构建会报告由 VCS 派生的开发版本，包括脏工作区标记，或在没有 VCS 信息时报告 dev。通过发布安装的二进制文件会通过 layerleak --version 报告解析后的模块版本。
每个发布版本还会附带预构建的 CLI 归档，因此无需 Go 工具链：适用于 linux 和 darwin 上 amd64 和 arm64 的 layerleak_<version>_<os>_<arch>.tar.gz（包含 layerleak、LICENSE 和 THIRD_PARTY_NOTICES.md）以及 layerleak_<version>_windows_amd64.zip（layerleak.exe）。每个发布版本都带有一个由发布工作流以无密钥方式签名的 layerleak_<version>_checksums.txt（layerleak_<version>_checksums.txt.sigstore.json），以及针对每个归档的构建来源证明。运行前请先验证：```bash
version=v3.0.0
archive="layerleak_${version}linux_amd64.tar.gz"
checksums="layerleak${version}_checksums.txt"
base="https://github.com/brumbelow/layerleak/releases/download/${version}"
curl --fail --location --proto '=https' --tlsv1.2 --remote-name-all
"${base}/${archive}" "${base}/${checksums}" "${base}/${checksums}.sigstore.json"
sha256sum --check --ignore-missing "${checksums}"
cosign verify-blob
--bundle "${checksums}.sigstore.json"
--certificate-identity 'https://github.com/Brumbelow/layerleak/.github/workflows/container-release.yml@refs/heads/main'
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com'
"${checksums}"
gh attestation verify "${archive}" --repo Brumbelow/layerleak
--signer-workflow Brumbelow/layerleak/.github/workflows/container-release.yml
--source-ref refs/heads/main --deny-self-hosted-runners
tar -xzf "${archive}" layerleak ./layerleak version
签名证明校验和文件来自该仓库在 `main` 上的发布工作流，校验和将归档文件绑定到该文件，而证明则独立地将归档文件绑定到构建它的工作流运行。发布中的 `release-manifest.json` 列出了每个归档文件及其内部二进制的摘要。稳定版本会使用稳定版本字符串重新构建已接受的候选版本的提交，并且除非重新构建能够逐字节复现候选版本的二进制文件，否则拒绝发布，因此 `layerleak version` 报告的正是你下载的标签。
### GitHub Action
仓库根目录是一个复合 action，它会为 runner 下载归档文件，按上述方式验证它（校验和、校验和文件的 cosign bundle，其中 cosign 版本固定在 `scripts/release-tools.sh` 中，以及归档证明），并运行 `layerleak scan`。将其固定到发布标签；匹配的归档文件将从该发布中下载：```yaml
name: Image secrets
on: { push: { branches: [main] } }
permissions: { contents: read, security-events: write }
jobs:
layerleak:
runs-on: ubuntu-24.04
steps:
- id: scan
uses: brumbelow/[email protected]
with: { image: "ghcr.io/${{ github.repository }}:${{ github.sha }}", fail-on: none }
- uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
if: ${{ always() && steps.scan.outputs.sarif-file != '' }}
with: { sarif_file: "${{ steps.scan.outputs.sarif-file }}" }
| 输入 | 默认值 | 含义 |
|---|---|---|
image | 必填 | 要扫描的镜像引用；私有仓库在步骤的 env 中使用 LAYERLEAK_REGISTRY_USERNAME/LAYERLEAK_REGISTRY_PASSWORD。 |
version | uses: 中的标签 | 下载其归档文件的发布版本；仅当 uses: 指定的是分支或提交时才设置此项。 |
format | sarif | summary、json 或 sarif。 |
fail-on | low | 传递给 --fail-on；none 会报告但不使步骤失败。 |
allow-partial | false | 传递 --allow-partial。 |
platform | 每个 linux 清单 | 传递给 --platform。 |
output-file | $RUNNER_TEMP/layerleak/results.<ext> | 格式化结果的写入位置。 |
extra-args | 空 | 更多 layerleak scan 标志，按空白字符拆分并追加到最后（例如 --all-tags --max-repository-tags 50）。 |
输出：exit-code（CLI 退出码，参见“扫描镜像”下的表格）、
result-file（写入的文件）、sarif-file（当 format
为 sarif 时是同一路径，否则为空）以及 version（已下载
并验证的发布版本）。当 CLI 以非零状态退出时，该步骤恰好失败，
因此在上传步骤上使用 fail-on: none 加上 if: always() 可实现
仅报告扫描。该 action 从不打印发现结果；只有经过脱敏的
summary 格式会回显到日志中，并且扫描以 --no-artifacts 运行。
它需要 curl、tar（在 Windows 上为 unzip/7z）以及 GitHub CLI，这些
都存在于 GitHub 托管的 Linux、macOS 和 Windows runner 上。
从源码构建：```bash git clone https://github.com/brumbelow/layerleak.git cd layerleak go build -o layerleak . ./layerleak --help
支持的发布路径包括上述用于 CLI 的 `/v3` 模块路径，以及用于 API 及其捆绑的迁移、清理和健康检查命令的 `ghcr.io/brumbelow/layerleak:<published-version>`。`cmd/*` 包是用于开发的源码构建目标，并非单独版本化的安装路径。在启动基于 PostgreSQL 的 API 版本之前，请运行与其匹配的 `layerleak-migrate-up` 二进制文件或容器入口点，并等待迁移成功：除非已安装的 schema 恰好是它期望的版本，否则 API 会拒绝启动；启动后，`/readyz` 会在每次探测时重新检查数据库和 schema，以便报告后续的降级情况。
## 平台支持
| 组件 | 平台 | 验证方式 |
| --- | --- | --- |
| `layerleak` CLI | 通过 `go install` 在 amd64 和 arm64 上的 Linux、macOS 和 Windows | 测试在 CI 中的 linux/amd64 上运行；darwin/arm64、darwin/amd64、windows/amd64 和 linux/arm64 在每次变更时都会进行编译和审查。 |
| API 镜像 | `linux/amd64`、`linux/arm64` | 由发布工作流为两个平台构建、冒烟测试、扫描并签名。 |
在 Windows 上，动态进度显示会将控制台切换到虚拟终端模式；拒绝切换的控制台（早于 Windows 10 1511）会回退到普通进度行，`--progress plain` 也是如此。bash、zsh、fish 和 PowerShell 的 shell 补全来自 `layerleak completion <shell>`。
CLI 通过 HTTPS 或 `HTTPS_PROXY` 直接访问注册表（参见[配置](#configuration)）。API 监听纯 HTTP，并期望部署层终止 TLS、对客户端进行身份验证并实施速率限制；参见 [SECURITY.md](https://github.com/brumbelow/layerleak/blob/main/SECURITY.md#security-boundaries)。
## 扫描镜像
裸仓库会扫描其 `latest` 标签。对于不可变目标，请使用显式标签或摘要：```bash
layerleak scan ubuntu
layerleak scan library/nginx:1.29 --format json
layerleak scan alpine@sha256:<digest>
layerleak scan ghcr.io/homebrew/core/hello:latest
layerleak scan quay.io/prometheus/busybox:latest
layerleak scan gcr.io/distroless/static:nonroot
layerleak scan public.ecr.aws/docker/library/alpine:3.20
layerleak scan mcr.microsoft.com/hello-world:latest
从多平台索引中选择平台。如果不使用 --platform，则会扫描每个 linux 清单，其他操作系统的条目会作为 platform_skipped 诊断信息报告，而不是被下载：```bash
layerleak scan alpine:latest --platform linux/arm64
layerleak scan golang:latest --platform linux
扫描每个公共标签是显式操作，因为它可能执行大量工作：```bash
layerleak scan mongo --all-tags
layerleak scan mongo --all-tags \
--tag-page-size 100 \
--max-repository-tags 500 \
--max-repository-targets 200
有用的扫描标志：