Robust Base-Image Extraction from Container History Layers
We describe a robust signal for the base image of an official container: the first history-layer's ADD of a minirootfs tarball. Naïve FROM regex is unreliable because (a) official images do not set org.opencontainers.image.base.name, (b) they build FROM scratch, and (c) the literal string FROM may appear inside RUN-command shell text. We report on the implementation in TOME and a quantitative evaluation on a curated set of 34 official Docker Hub images.
1. Introduction
Container supply-chain security requires lineage: an image's dependencies, its base, and the artifacts that depend on it. The first link is the base image. Without a reliable base signal, the chain is rooted in folklore. Most tooling parses the FROM line; for official Docker Hub images this fails on three counts.
2. Background
The OCI image specification (OCI, 2017) defines the image manifest, config, and layer formats. The config includes a history array. Software supply-chain security is surveyed by Zhao et al. (2023); Torres-Arias et al. (2019) introduce in-toto.
3. Method
3.1 The Signal
For official base images, the first non-empty history layer is ADD alpine-minirootfs-3.19.4-x86_64.tar.gz / # buildkit or ADD minirootfs.tar.xz / # buildkit. The base-name string and version are recoverable from this line with a small per-distribution parser. The ADD instruction is structural, not lexical.
3.2 The Implementation
extractBaseImage(configBlob) walks the image config's history array, finds the first ADD.*minirootfs.*#buildkit/ entry, parses the tarball filename for distribution and version. No FROM-regex fallback.
3.3 Why Not FROM Regex
Three failure modes: no base label; FROM scratch; shell text in RUN commands.
4. Results
Ran on 34 official Docker Hub images:
| Source | Correct base | Wrong base | No signal |
|---|---|---|---|
| FROM regex | 6 / 34 | 17 / 34 | 11 / 34 |
| Minirootfs ADD | 32 / 34 | 0 / 34 | 2 / 34 |
5. Discussion
The signal is robust for the official-image set. Third-party images with COPY from a previous stage or with custom layer ordering may not expose the minirootfs ADD.
6. Conclusion
A robust base-image extractor for official Docker Hub images, based on the first history-layer's ADD of a minirootfs tarball. Structural (immune to shell-text false matches), handles FROM scratch, no false positives on 32/34 images.
References
OCI (2017). OCI image format specification. / Torres-Arias et al. (2019). USENIX Security. / Zhao, X. et al. (2023). ACM Computing Surveys.