image

Documentation

Overview

Package image pulls a container image and finds the CA bundle inside it, without running the image.

Not running it is the point. The images most worth checking are the ones that cannot run anything: a FROM scratch image has no shell, and an image built for linux/s390x will not start on the machine doing the checking. Reading the layers works on any image, from any machine, in any CI job that can reach the registry.

Index

• Variables
• type Options
• type Pool
  • func Pull(ref string, opts Options) (*Pool, error)
  • func (p *Pool) Bytes() []byte
• type Source

Variables

var ErrNoBundle = errors.New("image contains no CA bundle at any path Go reads")

ErrNoBundle means the image ships nothing at any path or directory Go reads.

For an image that never speaks TLS this is correct and intended. For one that does, it is a runtime failure waiting on the first outbound request.

var SearchDirs = []string{
	"/etc/ssl/certs",
	"/etc/pki/tls/certs",
}

SearchDirs is the list of directories Go reads IN ADDITION to the file it picks from SearchPaths, from certDirectories in crypto/x509/root_unix.go.

This is the part that is easy to miss, and missing it makes a trust store check worse than none. loadSystemRoots reads the first file that exists and breaks, and then walks these directories and appends EVERY file in them. So a single extra .pem dropped in /etc/ssl/certs is a root the process trusts and a file-only check never sees.

var SearchPaths = []string{
	"/etc/ssl/certs/ca-certificates.crt",
	"/etc/pki/tls/certs/ca-bundle.crt",
	"/etc/ssl/ca-bundle.pem",
	"/etc/pki/tls/cacert.pem",
	"/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",
	"/etc/ssl/cert.pem",
}

SearchPaths is the list Go's crypto/x509 consults on Linux, in the order it consults them, from crypto/x509/root_linux.go. Go stops at the first file that exists, so the order is not cosmetic: a file at the first path shadows a bundle at the fifth, which is exactly how an image can ship two trust stores and silently use the older one.

Types

type Options

type Options struct {
	Platform string // "linux/amd64"; empty means the registry's default
	Insecure bool   // allow plain HTTP, for a local registry
}

Options controls how an image is fetched.

type Pool

type Pool struct {
	Sources  []Source // in the order Go reads them; excludes shadowed entries
	Shadowed []Source // present at a SearchPaths path Go never reaches
	// CertFileEnv and CertDirEnv hold SSL_CERT_FILE and SSL_CERT_DIR if the
	// image sets them, because they override everything above and silently make
	// the rest of this analysis wrong.
	CertFileEnv string
	CertDirEnv  string
}

Pool is everything Go's x509.SystemCertPool would load from an image.

func Pull

func Pull(ref string, opts Options) (*Pool, error)

Pull fetches an image and returns everything Go would load into the system certificate pool, in the order it loads it.

func (*Pool) Bytes

func (p *Pool) Bytes() []byte

Bytes returns every source concatenated, in read order, which is the input Go's AppendCertsFromPEM sees across the whole load.

type Source

type Source struct {
	Path string
	Data []byte
	// Via records the file the path resolved through, when it is a symlink.
	Via string
	// FromDir is true when Go reads this because it walks a directory, rather
	// than because the path is in SearchPaths.
	FromDir bool
	// Shadowed is true for a file in SearchPaths that Go never opens, because an
	// earlier path in the list exists. Shadowed files are reported and NOT read.
	Shadowed bool
}

Source is one file Go would read into the system pool.