Add experimental-download-offline-databases flag (#1039)

Currently flags `experimental-offline` and `experimental-local-db` are
confusing sometimes.

This PR renames `experimental-local-db` to
`experimental-download-database` to make it more explicit whether to
download the database or not.

For now, `experimental-download-database` only works when
`experimental-offline` is set.

`internal/local` is also modified to reflect the change in the naming
and meaning of this flag.

Author: cuixq

cmd/osv-scanner/__snapshots__/main_test.snap

@@ -1354,6 +1354,24 @@ No issues found
 
 ---
 
+[TestRun_LocalDatabases/#12 - 1]
+
+---
+
+[TestRun_LocalDatabases/#12 - 2]
+databases can only be downloaded when running in offline mode
+
+---
+
+[TestRun_LocalDatabases/#12 - 3]
+
+---
+
+[TestRun_LocalDatabases/#12 - 4]
+databases can only be downloaded when running in offline mode
+
+---
+
 [TestRun_LockfileWithExplicitParseAs/#00 - 1]
 
 ---

cmd/osv-scanner/main_test.go

@@ -480,74 +480,80 @@ func TestRun_LocalDatabases(t *testing.T) {
 		// one specific supported lockfile
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "./fixtures/locks-many/composer.lock"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "./fixtures/locks-many/composer.lock"},
 			exit: 0,
 		},
 		// one specific supported sbom with vulns
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "--config=./fixtures/osv-scanner-empty-config.toml", "./fixtures/sbom-insecure/postgres-stretch.cdx.xml"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "--config=./fixtures/osv-scanner-empty-config.toml", "./fixtures/sbom-insecure/postgres-stretch.cdx.xml"},
 			exit: 1,
 		},
 		// one specific unsupported lockfile
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "./fixtures/locks-many/not-a-lockfile.toml"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "./fixtures/locks-many/not-a-lockfile.toml"},
 			exit: 128,
 		},
 		// all supported lockfiles in the directory should be checked
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "./fixtures/locks-many"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "./fixtures/locks-many"},
 			exit: 0,
 		},
 		// all supported lockfiles in the directory should be checked
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "./fixtures/locks-many-with-invalid"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "./fixtures/locks-many-with-invalid"},
 			exit: 127,
 		},
 		// only the files in the given directories are checked by default (no recursion)
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "./fixtures/locks-one-with-nested"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "./fixtures/locks-one-with-nested"},
 			exit: 0,
 		},
 		// nested directories are checked when `--recursive` is passed
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "--recursive", "./fixtures/locks-one-with-nested"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "--recursive", "./fixtures/locks-one-with-nested"},
 			exit: 0,
 		},
 		// .gitignored files
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "--recursive", "./fixtures/locks-gitignore"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "--recursive", "./fixtures/locks-gitignore"},
 			exit: 0,
 		},
 		// ignoring .gitignore
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "--recursive", "--no-ignore", "./fixtures/locks-gitignore"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "--recursive", "--no-ignore", "./fixtures/locks-gitignore"},
 			exit: 0,
 		},
 		// output with json
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "--json", "./fixtures/locks-many/composer.lock"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "--json", "./fixtures/locks-many/composer.lock"},
 			exit: 0,
 		},
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "--format", "json", "./fixtures/locks-many/composer.lock"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "--format", "json", "./fixtures/locks-many/composer.lock"},
 			exit: 0,
 		},
 		// output format: markdown table
 		{
 			name: "",
-			args: []string{"", "--experimental-local-db", "--format", "markdown", "./fixtures/locks-many/composer.lock"},
+			args: []string{"", "--experimental-offline", "--experimental-download-offline-databases", "--format", "markdown", "./fixtures/locks-many/composer.lock"},
 			exit: 0,
 		},
+		// database should be downloaded only when offline is set
+		{
+			name: "",
+			args: []string{"", "--experimental-download-offline-databases", "./fixtures/locks-many"},
+			exit: 127,
+		},
 	}
 
 	for _, tt := range tests {

cmd/osv-scanner/scan/main.go

@@ -101,14 +101,14 @@ func Command(stdout, stderr io.Writer, r *reporter.Reporter) *cli.Command {
 				Usage: "specify the level of information that should be provided during runtime; value can be: " + strings.Join(reporter.VerbosityLevels(), ", "),
 				Value: "info",
 			},
-			&cli.BoolFlag{
-				Name:  "experimental-local-db",
-				Usage: "checks for vulnerabilities using local databases",
-			},
 			&cli.BoolFlag{
 				Name:  "experimental-offline",
 				Usage: "checks for vulnerabilities using local databases that are already cached",
 			},
+			&cli.BoolFlag{
+				Name:  "experimental-download-offline-databases",
+				Usage: "downloads vulnerability databases for offline comparison",
+			},
 			&cli.StringFlag{
 				Name:   "experimental-local-db-path",
 				Usage:  "sets the path that local databases should be stored",
@@ -210,9 +210,9 @@ func action(context *cli.Context, stdout, stderr io.Writer) (reporter.Reporter,
 		DirectoryPaths:       context.Args().Slice(),
 		CallAnalysisStates:   callAnalysisStates,
 		ExperimentalScannerActions: osvscanner.ExperimentalScannerActions{
-			LocalDBPath:    context.String("experimental-local-db-path"),
-			CompareLocally: context.Bool("experimental-local-db"),
-			CompareOffline: context.Bool("experimental-offline"),
+			LocalDBPath:       context.String("experimental-local-db-path"),
+			DownloadDatabases: context.Bool("experimental-download-offline-databases"),
+			CompareOffline:    context.Bool("experimental-offline"),
 			// License summary mode causes all
 			// packages to appear in the json as
 			// every package has a license - even

docs/offline-mode.md

@@ -49,7 +49,7 @@ If the `OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY` environment variable is _not_ set,
 1. The location returned by [`os.UserCacheDir`](https://pkg.go.dev/os#UserCacheDir)
 2. The location returned by [`os.TempDir`](https://pkg.go.dev/os#TempDir)
 
-The database can be [downloaded manually](./experimental.md#manual-database-download) or by using the [`--experimental-local-db` flag](./experimental.md#local-database-option).
+The database can be [downloaded manually](./experimental.md#manual-database-download) or by using the [`--experimental-download-offline-databases` flag](./experimental.md#download-databases-option).
 
 ## Offline option
 
@@ -59,17 +59,17 @@ The offline database flag `--experimental-offline` causes OSV-Scanner to scan yo
 osv-scanner --experimental-offline ./path/to/your/dir
 ```
 
-## Local database option
+## Download offline databases option
 
-The local database flag `--experimental-local-db` causes OSV-Scanner to download or update your local database and then scan your project against it.
+The download offline databases flag `--experimental-download-offline-databases` allows OSV-Scanner to download or update your local database when running in offline mode, to make it easier to get started. This option only works when you also set the offline flag.
 
 ```bash
-osv-scanner --experimental-local-db ./path/to/your/dir
+osv-scanner --experimental-offline --experimental-download-offline-databases ./path/to/your/dir
 ```
 
 ## Manual database download
 
-Instead of using the `--experimental-local-db` flag to download the database, it is possible to manually download the database.
+Instead of using the `--experimental-download-offline-databases` flag to download the database, it is possible to manually download the database.
 
 A downloadable copy of the OSV database is stored in a GCS bucket maintained by OSV:
 [`gs://osv-vulnerabilities`](https://osv-vulnerabilities.storage.googleapis.com)

pkg/osvscanner/osvscanner.go

@@ -47,8 +47,8 @@ type ScannerActions struct {
 }
 
 type ExperimentalScannerActions struct {
-	CompareLocally        bool
 	CompareOffline        bool
+	DownloadDatabases     bool
 	ShowAllPackages       bool
 	ScanLicensesSummary   bool
 	ScanLicensesAllowlist []string
@@ -753,17 +753,17 @@ func DoScan(actions ScannerActions, r reporter.Reporter) (models.VulnerabilityRe
 	}
 
 	if actions.CompareOffline {
-		actions.CompareLocally = true
-	}
-
-	if actions.CompareLocally {
 		actions.SkipGit = true
 
 		if len(actions.ScanLicensesAllowlist) > 0 || actions.ScanLicensesSummary {
 			return models.VulnerabilityResults{}, errors.New("cannot retrieve licenses locally")
 		}
 	}
 
+	if !actions.CompareOffline && actions.DownloadDatabases {
+		return models.VulnerabilityResults{}, errors.New("databases can only be downloaded when running in offline mode")
+	}
+
 	configManager := config.ConfigManager{
 		DefaultConfig: config.Config{},
 		ConfigMap:     make(map[string]config.Config),
@@ -847,7 +847,7 @@ func DoScan(actions ScannerActions, r reporter.Reporter) (models.VulnerabilityRe
 
 	overrideGoVersion(r, filteredScannedPackages, &configManager)
 
-	vulnsResp, err := makeRequest(r, filteredScannedPackages, actions.CompareLocally, actions.CompareOffline, actions.LocalDBPath)
+	vulnsResp, err := makeRequest(r, filteredScannedPackages, actions.CompareOffline, actions.DownloadDatabases, actions.LocalDBPath)
 	if err != nil {
 		return models.VulnerabilityResults{}, err
 	}
@@ -950,8 +950,8 @@ func patchPackageForRequest(pkg scannedPackage) scannedPackage {
 func makeRequest(
 	r reporter.Reporter,
 	packages []scannedPackage,
-	compareLocally bool,
 	compareOffline bool,
+	downloadDBs bool,
 	localDBPath string) (*osv.HydratedBatchedResponse, error) {
 	// Make OSV queries from the packages.
 	var query osv.BatchedQuery
@@ -974,8 +974,9 @@ func makeRequest(
 		}
 	}
 
-	if compareLocally {
-		hydratedResp, err := local.MakeRequest(r, query, compareOffline, localDBPath)
+	if compareOffline {
+		// Downloading databases requires network access.
+		hydratedResp, err := local.MakeRequest(r, query, !downloadDBs, localDBPath)
 		if err != nil {
 			return &osv.HydratedBatchedResponse{}, fmt.Errorf("local comparison failed %w", err)
 		}