Add CLI support to scan container image tarball with layer data.

PiperOrigin-RevId: 748018415

Author: alowayed

README.md

@@ -64,6 +64,13 @@ Add the `--remote-image` flag to scan a remote container image. Example:
 scalibr --result=result.textproto --remote-image=alpine@sha256:0a4eaa0eecf5f8c050e5bba433f58c052be7587ee8af3e8b3910ef9ab5fbe9f5
 ```
 
+Or the `--image-tarball` flag to scan a locally saved image tarball like ones
+produced with `docker save my-image > my-image.tar`. Example:
+
+```
+scalibr --result=result.textproto --image-tarball=my-image.tar
+```
+
 ### SPDX generation
 
 OSV-SCALIBR supports generating the result of inventory extraction as an SPDX

binary/cli/cli.go

@@ -130,6 +130,7 @@ type Flags struct {
 	MaxFileSize                int
 	UseGitignore               bool
 	RemoteImage                string
+	ImageTarball               string
 	ImagePlatform              string
 	GoBinaryVersionFromContent bool
 	GovulncheckDBPath          string
@@ -162,6 +163,12 @@ func ValidateFlags(flags *Flags) error {
 	if flags.ImagePlatform != "" && len(flags.RemoteImage) == 0 {
 		return errors.New("--image-platform cannot be used without --remote-image")
 	}
+	if flags.ImageTarball != "" && flags.RemoteImage != "" {
+		return errors.New("--image-tarball cannot be used with --remote-image")
+	}
+	if flags.ImageTarball != "" && flags.ImagePlatform != "" {
+		return errors.New("--image-tarball cannot be used with --image-platform")
+	}
 	if err := validateResultPath(flags.ResultFile); err != nil {
 		return fmt.Errorf("--result %w", err)
 	}
@@ -489,6 +496,12 @@ func (f *Flags) scanRoots() ([]*scalibrfs.ScanRoot, error) {
 		return scalibrfs.RealFSScanRoots(f.Root), nil
 	}
 
+	// If ImageTarball is set, do not set the root.
+	// It is computed later on by ScanContainer(...) when the tarball is read.
+	if f.ImageTarball != "" {
+		return nil, nil
+	}
+
 	// Compute the default scan roots.
 	var scanRoots []*scalibrfs.ScanRoot
 	var scanRootPaths []string

binary/cli/cli_test.go

@@ -194,6 +194,15 @@ func TestValidateFlags(t *testing.T) {
 			},
 			wantErr: nil,
 		},
+		{
+			desc: "Remoe Image with Image Tarball",
+			flags: &cli.Flags{
+				RemoteImage:  "docker",
+				ImageTarball: "image.tar",
+				ResultFile:   "result.textproto",
+			},
+			wantErr: cmpopts.AnyError,
+		},
 	} {
 		t.Run(tc.desc, func(t *testing.T) {
 			err := cli.ValidateFlags(tc.flags)
@@ -236,6 +245,19 @@ func TestGetScanConfig_ScanRoots(t *testing.T) {
 				"windows": {"C:\\myroot"},
 			},
 		},
+		{
+			desc: "Scan root is null if image tarball is provided",
+			flags: map[string]*cli.Flags{
+				"darwin":  {ImageTarball: "image.tar"},
+				"linux":   {ImageTarball: "image.tar"},
+				"windows": {ImageTarball: "image.tar"},
+			},
+			wantScanRoots: map[string][]string{
+				"darwin":  nil,
+				"linux":   nil,
+				"windows": nil,
+			},
+		},
 	} {
 		t.Run(tc.desc, func(t *testing.T) {
 			wantScanRoots, ok := tc.wantScanRoots[runtime.GOOS]
@@ -252,7 +274,7 @@ func TestGetScanConfig_ScanRoots(t *testing.T) {
 			if err != nil {
 				t.Errorf("%v.GetScanConfig(): %v", flags, err)
 			}
-			gotScanRoots := []string{}
+			var gotScanRoots []string
 			for _, r := range cfg.ScanRoots {
 				gotScanRoots = append(gotScanRoots, r.Path)
 			}

binary/scalibr/scalibr.go

@@ -71,6 +71,7 @@ func parseFlags(args []string) (*cli.Flags, error) {
 	maxFileSize := fs.Int("max-file-size", 0, "Files larger than this size in bytes are skipped. If 0, no limit is applied.")
 	useGitignore := fs.Bool("use-gitignore", false, "Skip files declared in .gitignore files in source repos.")
 	remoteImage := fs.String("remote-image", "", "The remote image to scan. If specified, SCALIBR pulls and scans this image instead of the local filesystem.")
+	imageTarball := fs.String("image-tarball", "", "The path to a tarball containing a container image. These are commonly procuded using `docker save`. If specified, SCALIBR scans this image instead of the local filesystem.")
 	imagePlatform := fs.String("image-platform", "", "The platform of the remote image to scan. If not specified, the platform of the client is used. Format is os/arch (e.g. linux/arm64)")
 	goBinaryVersionFromContent := fs.Bool("gobinary-version-from-content", false, "Parse the main module version from the binary content. Off by default because this drastically increases latency (~10x).")
 	govulncheckDBPath := fs.String("govulncheck-db", "", "Path to the offline DB for the govulncheck detectors to use. Leave empty to run the detectors in online mode.")
@@ -105,6 +106,7 @@ func parseFlags(args []string) (*cli.Flags, error) {
 		MaxFileSize:                *maxFileSize,
 		UseGitignore:               *useGitignore,
 		RemoteImage:                *remoteImage,
+		ImageTarball:               *imageTarball,
 		ImagePlatform:              *imagePlatform,
 		GoBinaryVersionFromContent: *goBinaryVersionFromContent,
 		GovulncheckDBPath:          *govulncheckDBPath,

binary/scanrunner/scanrunner.go

@@ -19,6 +19,7 @@ import (
 	"context"
 
 	scalibr "github.com/google/osv-scalibr"
+	scalibrlayerimage "github.com/google/osv-scalibr/artifact/image/layerscanning/image"
 	"github.com/google/osv-scalibr/binary/cli"
 	"github.com/google/osv-scalibr/log"
 	"github.com/google/osv-scalibr/plugin"
@@ -41,11 +42,28 @@ func RunScan(flags *cli.Flags) int {
 		"Running scan with %d extractors and %d detectors",
 		len(cfg.FilesystemExtractors)+len(cfg.StandaloneExtractors), len(cfg.Detectors),
 	)
-	log.Infof("Scan roots: %s", cfg.ScanRoots)
 	if len(cfg.PathsToExtract) > 0 {
 		log.Infof("Paths to extract: %s", cfg.PathsToExtract)
 	}
-	result := scalibr.New().Scan(context.Background(), cfg)
+
+	var result *scalibr.ScanResult
+	if flags.ImageTarball != "" {
+		layerCfg := scalibrlayerimage.DefaultConfig()
+		log.Infof("Scanning image tarball: %s", flags.ImageTarball)
+		img, err := scalibrlayerimage.FromTarball(flags.ImageTarball, layerCfg)
+		if err != nil {
+			log.Errorf("Failed to create image from tarball: %v", err)
+			return 1
+		}
+		result, err = scalibr.New().ScanContainer(context.Background(), img, cfg)
+		if err != nil {
+			log.Errorf("Failed to scan container: %v", err)
+			return 1
+		}
+	} else {
+		log.Infof("Scan roots: %s", cfg.ScanRoots)
+		result = scalibr.New().Scan(context.Background(), cfg)
+	}
 
 	log.Infof("Scan status: %v", result.Status)
 	log.Infof("Found %d software packages, %d security findings", len(result.Inventory.Packages), len(result.Inventory.Findings))

binary/scanrunner/scanrunner_test.go

@@ -15,13 +15,21 @@
 package scanrunner_test
 
 import (
+	"bytes"
+	"errors"
+	"io"
 	"os"
 	"path/filepath"
 	"runtime"
 	"slices"
 	"testing"
 
+	"archive/tar"
+
 	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-containerregistry/pkg/v1/empty"
+	"github.com/google/go-containerregistry/pkg/v1/mutate"
+	"github.com/google/go-containerregistry/pkg/v1/tarball"
 	"github.com/google/osv-scalibr/binary/cli"
 	"github.com/google/osv-scalibr/binary/scanrunner"
 	"google.golang.org/protobuf/encoding/prototext"
@@ -75,11 +83,72 @@ func createFailingDetectorTestFiles(t *testing.T) string {
 	return dir
 }
 
+func createImageTarball(t *testing.T) string {
+	t.Helper()
+
+	var buf bytes.Buffer
+	w := tar.NewWriter(&buf)
+	requirements := `
+nltk==3.2.2
+tabulate==0.7.7
+	`
+	files := []struct {
+		name, contents string
+	}{
+		{"requirements.txt", requirements},
+	}
+	for _, file := range files {
+		hdr := &tar.Header{
+			Name:     file.name,
+			Mode:     0600,
+			Size:     int64(len(file.contents)),
+			Typeflag: tar.TypeReg,
+		}
+		if err := w.WriteHeader(hdr); err != nil {
+			t.Fatalf("couldn't write header for %s: %v", file.name, err)
+		}
+		if _, err := w.Write([]byte(file.contents)); err != nil {
+			t.Fatalf("couldn't write %s: %v", file.name, err)
+		}
+	}
+	w.Close()
+	layer, err := tarball.LayerFromOpener(func() (io.ReadCloser, error) {
+		return io.NopCloser(bytes.NewBuffer(buf.Bytes())), nil
+	})
+	if err != nil {
+		t.Fatalf("unable to create layer: %v", err)
+	}
+	image, err := mutate.AppendLayers(empty.Image, layer)
+	if err != nil {
+		t.Fatalf("unable to create image: %v", err)
+	}
+
+	dir := t.TempDir()
+	tarPath := filepath.Join(dir, "image.tar")
+	if err := tarball.WriteToFile(tarPath, nil, image); err != nil {
+		t.Fatalf("unable to write tarball: %v", err)
+	}
+
+	return dir
+}
+
+func createBadImageTarball(t *testing.T) string {
+	t.Helper()
+
+	dir := t.TempDir()
+	tarPath := filepath.Join(dir, "image.tar")
+	if err := os.WriteFile(tarPath, []byte("bad tarball"), 0600); err != nil {
+		t.Fatalf("unable to write tarball: %v", err)
+	}
+	return dir
+}
+
 func TestRunScan(t *testing.T) {
 	testCases := []struct {
 		desc              string
 		setupFunc         func(t *testing.T) string
 		flags             *cli.Flags
+		wantExit          int
 		wantPluginStatus  []spb.ScanStatus_ScanStatusEnum
 		wantPackagesCount int
 		wantFindingCount  int
@@ -103,6 +172,29 @@ func TestRunScan(t *testing.T) {
 			wantPackagesCount: 1,
 			wantFindingCount:  0,
 		},
+		{
+			desc:      "Successful image extractor run",
+			setupFunc: createImageTarball,
+			flags: &cli.Flags{
+				ImageTarball:    "image.tar",
+				ExtractorsToRun: []string{"python/requirements"},
+			},
+			wantPluginStatus:  []spb.ScanStatus_ScanStatusEnum{spb.ScanStatus_SUCCEEDED},
+			wantPackagesCount: 2,
+			wantFindingCount:  0,
+		},
+		{
+			desc:      "Failure to read image tarball",
+			setupFunc: createBadImageTarball,
+			flags: &cli.Flags{
+				ImageTarball:    "image.tar",
+				ExtractorsToRun: []string{"python/requirements"},
+			},
+			wantExit:          1,
+			wantPluginStatus:  []spb.ScanStatus_ScanStatusEnum{spb.ScanStatus_FAILED},
+			wantPackagesCount: 0,
+			wantFindingCount:  0,
+		},
 		{
 			desc:              "Unsuccessful plugin run",
 			setupFunc:         createFailingDetectorTestFiles,
@@ -123,11 +215,25 @@ func TestRunScan(t *testing.T) {
 
 			dir := tc.setupFunc(t)
 			resultFile := filepath.Join(dir, "result.textproto")
-			tc.flags.Root = dir
 			tc.flags.ResultFile = resultFile
 
-			if gotExit := scanrunner.RunScan(tc.flags); gotExit != 0 {
-				t.Errorf("result.RunScan(%v) returned unexpected exit code, want 0 got %d", tc.flags, gotExit)
+			if tc.flags.ImageTarball != "" {
+				tc.flags.ImageTarball = filepath.Join(dir, tc.flags.ImageTarball)
+			} else {
+				tc.flags.Root = dir
+			}
+
+			gotExit := scanrunner.RunScan(tc.flags)
+			if gotExit != tc.wantExit {
+				t.Fatalf("result.RunScan(%v) = %d, want %d", tc.flags, gotExit, tc.wantExit)
+			}
+			_, err := os.Stat(resultFile)
+			if gotExit == 0 && errors.Is(err, os.ErrNotExist) {
+				t.Fatalf("Scan returned successful exit code 0 but no result file was created")
+			}
+			if gotExit != 0 && errors.Is(err, os.ErrNotExist) {
+				// It is expected that no results are created if the scan fails. Nothing else to check.
+				return
 			}
 
 			output, err := os.ReadFile(resultFile)