Add image-mapper

This example matches non-Chainguard image references to images in the
Chainguard catalog by leveraging the alias metadata in combination with
a few simple heuristics.

Author: ribbybibby

image-mapper/.gitignore

@@ -0,0 +1,2 @@
+image-mapper
+images.txt

image-mapper/Dockerfile

@@ -0,0 +1,18 @@
+FROM cgr.dev/chainguard/go:latest AS builder
+
+WORKDIR /app
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY main.go main.go
+COPY internal internal
+COPY cmd cmd
+
+RUN CGO_ENABLED=0 go build -o image-mapper .
+
+FROM cgr.dev/chainguard/static:latest
+
+COPY --from=builder /app/image-mapper /usr/local/bin/image-mapper
+
+ENTRYPOINT ["/usr/local/bin/image-mapper"]

image-mapper/README.md

@@ -0,0 +1,80 @@
+# image-mapper
+
+An example of matching non-Chainguard images to their Chainguard equivalents.
+
+## Usage
+
+Build the tool.
+
+```
+$ go build -o image-mapper .
+```
+
+Then, provide the images to map on the command line.
+
+```
+$ ./image-mapper ghcr.io/stakater/reloader:v1.4.1 registry.k8s.io/sig-storage/livenessprobe:v2.13.1
+ghcr.io/stakater/reloader:v1.4.1 -> stakater-reloader
+ghcr.io/stakater/reloader:v1.4.1 -> stakater-reloader-fips
+registry.k8s.io/sig-storage/livenessprobe:v2.13.1 -> kubernetes-csi-livenessprobe
+```
+
+You can provide a list of images (one image per line) via stdin when the first
+argument is `-`.
+
+```
+$ cat ./images.txt | ./image-mapper -
+```
+
+Configure the output format with the `-o` flag. Supported formats are: `csv`,
+`json` and `text`.
+
+```
+$ ./image-mapper ghcr.io/stakater/reloader:v1.4.1 registry.k8s.io/sig-storage/livenessprobe:v2.13.1 -o json | jq -r .
+[
+  {
+    "image": "ghcr.io/stakater/reloader:v1.4.1",
+    "results": [
+      "stakater-reloader",
+      "stakater-reloader-fips"
+    ]
+  },
+  {
+    "image": "registry.k8s.io/sig-storage/livenessprobe:v2.13.1",
+    "results": [
+      "kubernetes-csi-livenessprobe"
+    ]
+  }
+]
+```
+
+```
+$ ./image-mapper ghcr.io/stakater/reloader:v1.4.1 bitnami/postgresql -o csv
+ghcr.io/stakater/reloader:v1.4.1,[stakater-reloader stakater-reloader-fips]
+registry.k8s.io/sig-storage/livenessprobe:v2.13.1,[kubernetes-csi-livenessprobe]
+```
+
+The output will map both FIPS and non-FIPS variants. You can exclude FIPS with
+the `--ignore-tiers` flag.
+
+```
+$ ./image-mapper prom/prometheus
+prom/prometheus -> prometheus-fips
+prom/prometheus -> prometheus
+
+$ ./image-mapper prom/prometheus --ignore-tiers=FIPS
+prom/prometheus -> prometheus
+```
+
+## Docker
+
+```
+# Build the image
+docker build -t image-mapper .
+
+# Run for an individual image
+docker run -it --rm image-mapper ghcr.io/stakater/reloader:v1.4.1
+
+# Or, pass a list of images from a text file
+docker run -i --rm image-mapper -- - < images.txt
+```

image-mapper/cmd/root.go

@@ -0,0 +1,59 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/chainguard-dev/customer-success/scripts/image-mapper/internal/mapper"
+	"github.com/spf13/cobra"
+)
+
+var (
+	outputFormat string
+	ignoreTiers  []string
+)
+
+var rootCmd = &cobra.Command{
+	Use:   "image-mapper",
+	Short: "Map upstream image references to Chainguard images.",
+	Args:  cobra.MinimumNArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		ctx := context.Background()
+
+		output, err := mapper.NewOutput(outputFormat)
+		if err != nil {
+			return fmt.Errorf("constructing output: %w", err)
+		}
+
+		var opts []mapper.Option
+		if len(ignoreTiers) > 0 {
+			opts = append(opts, mapper.WithoutTiers(ignoreTiers))
+		}
+		m, err := mapper.NewMapper(ctx, opts...)
+		if err != nil {
+			return fmt.Errorf("creating mapper: %w", err)
+		}
+
+		it := mapper.NewArgsIterator(args)
+		if args[0] == "-" {
+			it = mapper.NewReaderIterator(os.Stdin)
+		}
+
+		mappings, err := m.MapAll(it)
+		if err != nil {
+			return fmt.Errorf("mapping images: %w", err)
+		}
+
+		return output(os.Stdout, mappings)
+	},
+}
+
+func init() {
+	rootCmd.Flags().StringVarP(&outputFormat, "output", "o", "text", "Output format (csv, json, text, customer-yaml)")
+	rootCmd.Flags().StringSliceVar(&ignoreTiers, "ignore-tiers", []string{}, "Ignore Chainguard repos of specific tiers (PREMIUM, APPLICATION, BASE, FIPS, AI)")
+}
+
+func Execute() error {
+	return rootCmd.Execute()
+}

image-mapper/go.mod

@@ -0,0 +1,15 @@
+module github.com/chainguard-dev/customer-success/scripts/image-mapper
+
+go 1.24.5
+
+require (
+	github.com/google/go-cmp v0.7.0
+	github.com/google/go-containerregistry v0.20.6
+	github.com/spf13/cobra v1.9.1
+)
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/spf13/pflag v1.0.6 // indirect
+)

image-mapper/go.sum

@@ -0,0 +1,16 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/go-containerregistry v0.20.6 h1:cvWX87UxxLgaH76b4hIvya6Dzz9qHB31qAwjAohdSTU=
+github.com/google/go-containerregistry v0.20.6/go.mod h1:T0x8MuoAoKX/873bkeSfLD2FAkwCDf9/HZgsFJ02E2Y=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
+github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
+github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
+github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

image-mapper/internal/mapper/iterator.go

@@ -0,0 +1,71 @@
+package mapper
+
+import (
+	"bufio"
+	"errors"
+	"io"
+)
+
+// ErrIteratorDone indicates when an iterator is finished
+var ErrIteratorDone = errors.New("done")
+
+// Iterator iterates over images
+type Iterator interface {
+	Next() (string, error)
+}
+
+type readerIterator struct {
+	scanner *bufio.Scanner
+}
+
+// NewReaderIterator iterates over images in the given reader. It expects an
+// image per line.
+func NewReaderIterator(r io.Reader) Iterator {
+	return &readerIterator{
+		scanner: bufio.NewScanner(r),
+	}
+}
+
+// Next returns the next line
+func (it *readerIterator) Next() (string, error) {
+	if !it.scanner.Scan() {
+		if it.scanner.Err() != nil {
+			return "", it.scanner.Err()
+		}
+
+		return "", ErrIteratorDone
+	}
+
+	txt := it.scanner.Text()
+
+	// If the line is empty, skip to the next one
+	if txt == "" {
+		return it.Next()
+	}
+
+	return txt, nil
+}
+
+type argsIterator struct {
+	args  []string
+	index int
+}
+
+// NewArgsIterator iterates over a list of images
+func NewArgsIterator(args []string) Iterator {
+	return &argsIterator{
+		args: args,
+	}
+}
+
+// Next returns the next image
+func (it *argsIterator) Next() (string, error) {
+	if it.index >= len(it.args) {
+		return "", ErrIteratorDone
+	}
+
+	arg := it.args[it.index]
+	it.index++
+
+	return arg, nil
+}