feat: add support for registry mirrors

docs/docs/configuration/others.md

@@ -117,3 +117,23 @@ The following example will fail when a critical vulnerability is found or the OS
 ```
 $ trivy image --exit-code 1 --exit-on-eol 1 --severity CRITICAL alpine:3.16.3
 ```
+
+## Mirrors support
+
+!!! warning "EXPERIMENTAL"
+    This feature might change without preserving backwards compatibility.
+
+Trivy supports mirrors for [remote container images](../target/container_image.md#container-registry) and [databases](./db.md).
+
+To configure them, add a list of mirrors along with the host to the [trivy config file](../references/configuration/config-file.md#registry-options).
+
+!!! note
+    Use the `index.docker.io` host for images from `Docker Hub`, even if you don't use that prefix.
+
+Example for `index.docker.io`:
+```yaml
+registry:
+  mirrors:
+    index.docker.io:
+     - mirror.gcr.io
+```

docs/docs/references/configuration/config-file.md

@@ -461,6 +461,11 @@ pkg:
 
 ```yaml
 registry:
+  mirrors:
+    index.docker.io:
+     - harbor.example.com/docker.io
+     - mirror.gcr.io
+
   # Same as '--password'
   password: []
 

magefiles/docs.go

@@ -127,7 +127,7 @@ func writeFlags(group flag.FlagGroup, w *os.File) {
 			}
 			w.WriteString(ind + parts[i] + ":")
 			if isLastPart {
-				writeFlagValue(flg.GetDefaultValue(), ind, w)
+				writeFlagValue(value(flg), ind, w)
 			}
 			w.WriteString("\n")
 		}
@@ -147,9 +147,31 @@ func writeFlagValue(val any, ind string, w *os.File) {
 		} else {
 			w.WriteString(" []\n")
 		}
+	case map[string][]string:
+		w.WriteString("\n")
+		for k, vv := range v {
+			fmt.Fprintf(w, "%s  %s:\n", ind, k)
+			for _, vvv := range vv {
+				fmt.Fprintf(w, "  %s - %s\n", ind, vvv)
+			}
+		}
 	case string:
 		fmt.Fprintf(w, " %q\n", v)
 	default:
 		fmt.Fprintf(w, " %v\n", v)
 	}
 }
+
+var registryMirrorsExample = map[string][]string{
+	"index.docker.io": {
+		"harbor.example.com/docker.io",
+		"mirror.gcr.io",
+	},
+}
+
+func value(flg flag.Flagger) any {
+	if flg.GetConfigName() == flag.RegistryMirrorsFlag.ConfigName {
+		return registryMirrorsExample
+	}
+	return flg.GetDefaultValue()
+}

pkg/fanal/types/image.go

@@ -81,6 +81,9 @@ type RegistryOptions struct {
 	// RegistryToken is a bearer token to be sent to a registry
 	RegistryToken string
 
+	// RegistryMirrors is a map of hosts with mirrors for them
+	RegistryMirrors map[string][]string
+
 	// SSL/TLS
 	Insecure bool
 

pkg/flag/options.go

@@ -30,7 +30,7 @@ import (
 )
 
 type FlagType interface {
-	int | string | []string | bool | time.Duration | float64
+	int | string | []string | bool | time.Duration | float64 | map[string][]string
 }
 
 type Flag[T FlagType] struct {
@@ -161,6 +161,8 @@ func (f *Flag[T]) cast(val any) any {
 		return cast.ToFloat64(val)
 	case time.Duration:
 		return cast.ToDuration(val)
+	case map[string][]string:
+		return cast.ToStringMapStringSlice(val)
 	case []string:
 		if s, ok := val.(string); ok && strings.Contains(s, ",") {
 			// Split environmental variables by comma as it is not done by viper.
@@ -467,11 +469,12 @@ func (o *Options) ScanOpts() types.ScanOptions {
 // RegistryOpts returns options for OCI registries
 func (o *Options) RegistryOpts() ftypes.RegistryOptions {
 	return ftypes.RegistryOptions{
-		Credentials:   o.Credentials,
-		RegistryToken: o.RegistryToken,
-		Insecure:      o.Insecure,
-		Platform:      o.Platform,
-		AWSRegion:     o.AWSOptions.Region,
+		Credentials:     o.Credentials,
+		RegistryToken:   o.RegistryToken,
+		Insecure:        o.Insecure,
+		Platform:        o.Platform,
+		AWSRegion:       o.AWSOptions.Region,
+		RegistryMirrors: o.RegistryMirrors,
 	}
 }
 

pkg/flag/registry_flags.go

@@ -31,26 +31,33 @@ var (
 		ConfigName: "registry.token",
 		Usage:      "registry token",
 	}
+	RegistryMirrorsFlag = Flag[map[string][]string]{
+		ConfigName: "registry.mirrors",
+		Usage:      "map of hosts and registries for them.",
+	}
 )
 
 type RegistryFlagGroup struct {
-	Username      *Flag[[]string]
-	Password      *Flag[[]string]
-	PasswordStdin *Flag[bool]
-	RegistryToken *Flag[string]
+	Username        *Flag[[]string]
+	Password        *Flag[[]string]
+	PasswordStdin   *Flag[bool]
+	RegistryToken   *Flag[string]
+	RegistryMirrors *Flag[map[string][]string]
 }
 
 type RegistryOptions struct {
-	Credentials   []types.Credential
-	RegistryToken string
+	Credentials     []types.Credential
+	RegistryToken   string
+	RegistryMirrors map[string][]string
 }
 
 func NewRegistryFlagGroup() *RegistryFlagGroup {
 	return &RegistryFlagGroup{
-		Username:      UsernameFlag.Clone(),
-		Password:      PasswordFlag.Clone(),
-		PasswordStdin: PasswordStdinFlag.Clone(),
-		RegistryToken: RegistryTokenFlag.Clone(),
+		Username:        UsernameFlag.Clone(),
+		Password:        PasswordFlag.Clone(),
+		PasswordStdin:   PasswordStdinFlag.Clone(),
+		RegistryToken:   RegistryTokenFlag.Clone(),
+		RegistryMirrors: RegistryMirrorsFlag.Clone(),
 	}
 }
 
@@ -64,6 +71,7 @@ func (f *RegistryFlagGroup) Flags() []Flagger {
 		f.Password,
 		f.PasswordStdin,
 		f.RegistryToken,
+		f.RegistryMirrors,
 	}
 }
 
@@ -97,7 +105,8 @@ func (f *RegistryFlagGroup) ToOptions() (RegistryOptions, error) {
 	}
 
 	return RegistryOptions{
-		Credentials:   credentials,
-		RegistryToken: f.RegistryToken.Value(),
+		Credentials:     credentials,
+		RegistryToken:   f.RegistryToken.Value(),
+		RegistryMirrors: f.RegistryMirrors.Value(),
 	}, nil
 }

pkg/remote/remote.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/google/go-containerregistry/pkg/authn"
@@ -36,39 +37,46 @@ func Get(ctx context.Context, ref name.Reference, option types.RegistryOptions)
 	}
 
 	var errs error
-	// Try each authentication method until it succeeds
-	for _, authOpt := range authOptions(ctx, ref, option) {
-		remoteOpts := []remote.Option{
-			remote.WithTransport(tr),
-			authOpt,
-		}
-
-		if option.Platform.Platform != nil {
-			p, err := resolvePlatform(ref, option.Platform, remoteOpts)
-			if err != nil {
-				return nil, xerrors.Errorf("platform error: %w", err)
+	// Try each mirrors/host until it succeeds
+	for _, r := range append(registryMirrors(ref, option), ref) {
+		// Try each authentication method until it succeeds
+		for _, authOpt := range authOptions(ctx, r, option) {
+			remoteOpts := []remote.Option{
+				remote.WithTransport(tr),
+				authOpt,
 			}
-			// Don't pass platform when the specified image is single-arch.
-			if p.Platform != nil {
-				remoteOpts = append(remoteOpts, remote.WithPlatform(*p.Platform))
+
+			if option.Platform.Platform != nil {
+				p, err := resolvePlatform(r, option.Platform, remoteOpts)
+				if err != nil {
+					return nil, xerrors.Errorf("platform error: %w", err)
+				}
+				// Don't pass platform when the specified image is single-arch.
+				if p.Platform != nil {
+					remoteOpts = append(remoteOpts, remote.WithPlatform(*p.Platform))
+				}
 			}
-		}
 
-		desc, err := remote.Get(ref, remoteOpts...)
-		if err != nil {
-			errs = multierror.Append(errs, err)
-			continue
-		}
+			var desc *remote.Descriptor
+			desc, err = remote.Get(r, remoteOpts...)
+			if err != nil {
+				errs = multierror.Append(errs, err)
+				continue
+			}
 
-		if option.Platform.Force {
-			if err = satisfyPlatform(desc, lo.FromPtr(option.Platform.Platform)); err != nil {
-				return nil, err
+			if option.Platform.Force {
+				if err = satisfyPlatform(desc, lo.FromPtr(option.Platform.Platform)); err != nil {
+					return nil, err
+				}
 			}
+			if ref.Context().RegistryStr() != r.Context().RegistryStr() {
+				log.WithPrefix("remote").Info("Mirror was used to get remote image", log.String("image", ref.String()), log.String("mirror", r.Context().RegistryStr()))
+			}
+			return desc, nil
 		}
-		return desc, nil
 	}
 
-	// No authentication succeeded
+	// No authentication for mirrors/host succeeded
 	return nil, errs
 }
 
@@ -81,21 +89,28 @@ func Image(ctx context.Context, ref name.Reference, option types.RegistryOptions
 	}
 
 	var errs error
-	// Try each authentication method until it succeeds
-	for _, authOpt := range authOptions(ctx, ref, option) {
-		remoteOpts := []remote.Option{
-			remote.WithTransport(tr),
-			authOpt,
-		}
-		index, err := remote.Image(ref, remoteOpts...)
-		if err != nil {
-			errs = multierror.Append(errs, err)
-			continue
+	// Try each mirrors/host until it succeeds
+	for _, r := range append(registryMirrors(ref, option), ref) {
+		// Try each authentication method until it succeeds
+		for _, authOpt := range authOptions(ctx, r, option) {
+			remoteOpts := []remote.Option{
+				remote.WithTransport(tr),
+				authOpt,
+			}
+			index, err := remote.Image(r, remoteOpts...)
+			if err != nil {
+				errs = multierror.Append(errs, err)
+				continue
+			}
+
+			if ref.Context().RegistryStr() != r.Context().RegistryStr() {
+				log.WithPrefix("remote").Info("Mirror was used to get remote image", log.String("image", ref.String()), log.String("mirror", r.Context().RegistryStr()))
+			}
+			return index, nil
 		}
-		return index, nil
 	}
 
-	// No authentication succeeded
+	// No authentication for mirrors/host succeeded
 	return nil, errs
 }
 
@@ -126,6 +141,29 @@ func Referrers(ctx context.Context, d name.Digest, option types.RegistryOptions)
 	return nil, errs
 }
 
+func registryMirrors(hostRef name.Reference, option types.RegistryOptions) []name.Reference {
+	var mirrors []name.Reference
+
+	ctx := hostRef.Context()
+	reg := ctx.RegistryStr()
+	if ms, ok := option.RegistryMirrors[reg]; ok {
+		for _, m := range ms {
+			var nameOpts []name.Option
+			if option.Insecure {
+				nameOpts = append(nameOpts, name.Insecure)
+			}
+			mirrorImageName := strings.Replace(hostRef.Name(), reg, m, 1)
+			ref, err := name.ParseReference(mirrorImageName, nameOpts...)
+			if err != nil {
+				log.WithPrefix("remote").Warn("Unable to parse mirror of image", log.String("mirror", mirrorImageName))
+				continue
+			}
+			mirrors = append(mirrors, ref)
+		}
+	}
+	return mirrors
+}
+
 func httpTransport(option types.RegistryOptions) (http.RoundTripper, error) {
 	d := &net.Dialer{
 		Timeout: 10 * time.Minute,