feat: add QEMU_ADDITIONAL_PACKAGES environment variable (#2266)

* feat: add QEMU_ADDITIONAL_PACKAGES environment variable

Add support for QEMU_ADDITIONAL_PACKAGES environment variable that allows
users to specify additional packages to install in the QEMU microVM during
initialization.

The variable accepts a comma-separated list of package names (e.g.,
"hello-wolfi,nginx-stable,strace") and passes them to microvm-init via
the kernel command line as melange.additional_packages=<list>.

Input validation prevents injection attacks by only allowing alphanumeric
characters, hyphens, underscores, commas, and dots. Invalid input is
rejected with a warning.

Usage:
  QEMU_ADDITIONAL_PACKAGES=hello-wolfi,strace melange build mypackage.yaml

Note: This requires a corresponding update to microvm-init package to
read and process the melange.additional_packages kernel parameter.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

* fix: use strings.SplitSeq for modernization linter

Update to use strings.SplitSeq() instead of strings.Split() for better
efficiency with the iterator pattern in Go 1.24+.

Addresses golangci-lint modernize check.

* refactor: extract testable functions and add tests for QEMU_ADDITIONAL_PACKAGES

Addresses PR feedback from @egibs and @89luca89:
- Extract getAdditionalPackages() function for parsing env var
- Extract getPackageCacheSuffix() function for cache key generation
- Use SHA256 hash instead of truncation to avoid collisions
- Add comprehensive test coverage for both functions
- Fix variable shadowing issue

Tests verify:
- Package parsing and validation
- Security (injection prevention)
- Cache suffix generation with SHA256
- Hash determinism and collision prevention

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

* Apply suggestion from @egibs

Co-authored-by: Evan Gibler <[email protected]>
Signed-off-by: antitree <[email protected]>

* Retrieve additional packages from context

Signed-off-by: antitree <[email protected]>

* refactoring egibs changes

* fix: remove duplicate getAdditionalPackages call that shadows parameter

The merge introduced a bug where additionalPkgs parameter was being
shadowed by a local variable that called getAdditionalPackages again.
This defeats the purpose of passing the parameter and causes the
function to be called twice unnecessarily.

Remove the duplicate call to use the passed parameter correctly.

---------

Signed-off-by: antitree <[email protected]>
Co-authored-by: Claude Sonnet 4.5 <[email protected]>
Co-authored-by: Evan Gibler <[email protected]>

Author: 3 people

pkg/container/qemu_runner.go

@@ -23,6 +23,7 @@ import (
 	"crypto/ed25519"
 	"crypto/elliptic"
 	"crypto/rand"
+	"crypto/sha256"
 	_ "embed"
 	"encoding/base64"
 	"encoding/pem"
@@ -35,6 +36,7 @@ import (
 	"os/signal"
 	"os/user"
 	"path/filepath"
+	"regexp"
 	"runtime"
 	"strconv"
 	"strings"
@@ -1762,16 +1764,20 @@ func generateCpio(ctx context.Context, cfg *Config) (string, error) {
 
 	cacheDir = filepath.Join(cacheDir, "melange-cpio")
 
+	// Include additional packages in cache filename to invalidate cache when they change
+	additionalPkgs := getAdditionalPackages(ctx)
+	cacheSuffix := getPackageCacheSuffix(additionalPkgs)
+
 	baseInitramfs := filepath.Join(
 		cacheDir,
-		"melange-guest.initramfs.cpio")
+		fmt.Sprintf("melange-guest%s.initramfs.cpio", cacheSuffix))
 	initramfsInfo, err := os.Stat(baseInitramfs)
 
 	// Check if we can use the cached base initramfs (less than 24h old)
 	useCache := err == nil && time.Since(initramfsInfo.ModTime()) < 24*time.Hour
 
 	if !useCache {
-		err = generateBaseInitramfs(ctx, cfg, baseInitramfs, cacheDir)
+		err = generateBaseInitramfs(ctx, cfg, baseInitramfs, cacheDir, additionalPkgs)
 		if err != nil {
 			return "", err
 		}
@@ -1782,22 +1788,24 @@ func generateCpio(ctx context.Context, cfg *Config) (string, error) {
 
 // generateBaseInitramfs creates the base initramfs with microvm-init.
 // This is cached for performance as it doesn't change often.
-func generateBaseInitramfs(ctx context.Context, cfg *Config, initramfsPath, cacheDir string) error {
+func generateBaseInitramfs(ctx context.Context, cfg *Config, initramfsPath, cacheDir string, additionalPkgs []string) error {
 	clog.FromContext(ctx).Info("qemu: generating base initramfs")
 
 	err := os.MkdirAll(cacheDir, 0o755)
 	if err != nil {
 		return fmt.Errorf("unable to create dest directory: %w", err)
 	}
 
+	// Start with base packages and add any additional packages from environment
+	packages := []string{"microvm-init"}
+	packages = append(packages, additionalPkgs...)
+
 	spec := apko_types.ImageConfiguration{
 		Contents: apko_types.ImageContents{
 			BuildRepositories: []string{
 				"https://apk.cgr.dev/chainguard",
 			},
-			Packages: []string{
-				"microvm-init",
-			},
+			Packages: packages,
 		},
 	}
 	opts := []apko_build.Option{
@@ -1857,6 +1865,53 @@ func generateBaseInitramfs(ctx context.Context, cfg *Config, initramfsPath, cach
 	return nil
 }
 
+// getAdditionalPackages parses and validates the QEMU_ADDITIONAL_PACKAGES environment variable.
+// Returns a list of package names to add to the initramfs, or empty slice if none/invalid.
+func getAdditionalPackages(ctx context.Context) []string {
+	pkgEnv := os.Getenv("QEMU_ADDITIONAL_PACKAGES")
+	if pkgEnv == "" {
+		return nil
+	}
+
+	// Basic validation: check for suspicious characters that could cause injection
+	// Allow: alphanumeric, hyphens, underscores, commas, dots
+	if matched, _ := regexp.MatchString(`^[a-zA-Z0-9_,.-]+$`, pkgEnv); !matched {
+		clog.FromContext(ctx).Warnf("qemu: QEMU_ADDITIONAL_PACKAGES contains invalid characters, ignoring: %s", pkgEnv)
+		return nil
+	}
+
+	clog.FromContext(ctx).Infof("qemu: QEMU_ADDITIONAL_PACKAGES env set to %s, adding to initramfs", pkgEnv)
+
+	// Split comma-separated list and filter empty entries
+	var packages []string
+	for pkg := range strings.SplitSeq(pkgEnv, ",") {
+		pkg = strings.TrimSpace(pkg)
+		if pkg != "" {
+			packages = append(packages, pkg)
+		}
+	}
+
+	return packages
+}
+
+// getPackageCacheSuffix generates a deterministic cache suffix based on the package list.
+// Uses SHA256 hash (first 12 chars) to avoid collisions and keep filenames reasonable.
+// Returns empty string if packages list is empty.
+func getPackageCacheSuffix(packages []string) string {
+	if len(packages) == 0 {
+		return ""
+	}
+
+	// Join packages with commas to create a stable input string
+	pkgString := strings.Join(packages, ",")
+
+	// Generate SHA256 hash
+	hash := sha256.Sum256([]byte(pkgString))
+
+	// Use first 12 characters of hex encoding (like git short SHA)
+	return fmt.Sprintf("-%x", hash[:6])
+}
+
 // injectHostKeyIntoCpio creates a new initramfs by concatenating the base
 // initramfs with a secondary cpio containing the VM's SSH host key.
 // This allows us to use cached base initramfs while injecting fresh keys each time.

pkg/container/qemu_runner_test.go

@@ -15,8 +15,13 @@
 package container
 
 import (
+	"context"
+	"os"
 	"runtime"
 	"testing"
+
+	"github.com/chainguard-dev/clog"
+	"github.com/chainguard-dev/clog/slogtest"
 )
 
 func TestGetAvailableMemoryKB(t *testing.T) {
@@ -106,3 +111,183 @@ func TestGetAvailableMemoryKB_Fallback(t *testing.T) {
 		t.Errorf("Fallback value %d KB seems too low", expectedFallback)
 	}
 }
+
+func TestGetAdditionalPackages(t *testing.T) {
+	ctx := clog.WithLogger(context.Background(), slogtest.TestLogger(t))
+
+	tests := []struct {
+		name     string
+		envValue string
+		expected []string
+	}{
+		{
+			name:     "empty environment variable",
+			envValue: "",
+			expected: nil,
+		},
+		{
+			name:     "single package",
+			envValue: "hello-wolfi",
+			expected: []string{"hello-wolfi"},
+		},
+		{
+			name:     "multiple packages",
+			envValue: "hello-wolfi,nginx-stable,strace",
+			expected: []string{"hello-wolfi", "nginx-stable", "strace"},
+		},
+		{
+			name:     "packages with spaces around commas rejected",
+			envValue: "hello-wolfi, nginx-stable , strace",
+			expected: nil,
+		},
+		{
+			name:     "packages with dots and underscores",
+			envValue: "python-3.11,gcc_musl,nginx-1.25.0",
+			expected: []string{"python-3.11", "gcc_musl", "nginx-1.25.0"},
+		},
+		{
+			name:     "empty entries filtered out",
+			envValue: "hello-wolfi,,nginx-stable",
+			expected: []string{"hello-wolfi", "nginx-stable"},
+		},
+		{
+			name:     "invalid characters rejected",
+			envValue: "hello-wolfi;rm -rf /",
+			expected: nil,
+		},
+		{
+			name:     "shell injection attempt",
+			envValue: "package$(evil_command)",
+			expected: nil,
+		},
+		{
+			name:     "quotes rejected",
+			envValue: "\"hello-wolfi\"",
+			expected: nil,
+		},
+		{
+			name:     "spaces in package name rejected",
+			envValue: "hello wolfi",
+			expected: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Set environment variable
+			if tt.envValue == "" {
+				os.Unsetenv("QEMU_ADDITIONAL_PACKAGES")
+			} else {
+				os.Setenv("QEMU_ADDITIONAL_PACKAGES", tt.envValue)
+			}
+			defer os.Unsetenv("QEMU_ADDITIONAL_PACKAGES")
+
+			result := getAdditionalPackages(ctx)
+
+			// Compare results
+			if len(result) != len(tt.expected) {
+				t.Errorf("getAdditionalPackages() returned %d packages, expected %d: got %v, want %v",
+					len(result), len(tt.expected), result, tt.expected)
+				return
+			}
+
+			for i, pkg := range result {
+				if pkg != tt.expected[i] {
+					t.Errorf("getAdditionalPackages()[%d] = %q, expected %q", i, pkg, tt.expected[i])
+				}
+			}
+		})
+	}
+}
+
+func TestGetPackageCacheSuffix(t *testing.T) {
+	tests := []struct {
+		name     string
+		packages []string
+		expected string
+	}{
+		{
+			name:     "empty package list",
+			packages: []string{},
+			expected: "",
+		},
+		{
+			name:     "nil package list",
+			packages: nil,
+			expected: "",
+		},
+		{
+			name:     "single package",
+			packages: []string{"hello-wolfi"},
+			expected: "-f5c4369d6487",
+		},
+		{
+			name:     "multiple packages deterministic",
+			packages: []string{"hello-wolfi", "nginx-stable", "strace"},
+			expected: "-8315f3ef029a",
+		},
+		{
+			name:     "same packages different order produces different hash",
+			packages: []string{"strace", "hello-wolfi", "nginx-stable"},
+			expected: "-5236a484f919",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := getPackageCacheSuffix(tt.packages)
+
+			if result != tt.expected {
+				t.Errorf("getPackageCacheSuffix(%v) = %q, expected %q", tt.packages, result, tt.expected)
+			}
+
+			// Additional validation: check format
+			if len(tt.packages) > 0 {
+				// Should start with dash and have 12 hex characters
+				if len(result) != 13 { // "-" + 12 hex chars
+					t.Errorf("getPackageCacheSuffix(%v) = %q, expected 13 characters (dash + 12 hex)", tt.packages, result)
+				}
+				if result[0] != '-' {
+					t.Errorf("getPackageCacheSuffix(%v) = %q, expected to start with '-'", tt.packages, result)
+				}
+			}
+		})
+	}
+}
+
+func TestGetPackageCacheSuffix_Deterministic(t *testing.T) {
+	// Test that the same packages always produce the same hash
+	packages := []string{"hello-wolfi", "nginx-stable", "strace"}
+
+	result1 := getPackageCacheSuffix(packages)
+	result2 := getPackageCacheSuffix(packages)
+
+	if result1 != result2 {
+		t.Errorf("getPackageCacheSuffix is not deterministic: first call returned %q, second call returned %q", result1, result2)
+	}
+}
+
+func TestGetPackageCacheSuffix_NoCollisions(t *testing.T) {
+	// Test that different package lists produce different hashes
+	testCases := [][]string{
+		{"package-a", "package-b", "package-c", "package-d", "package-e"},
+		{"package-a", "package-b", "package-c", "package-d", "package-f"},
+		{"hello-wolfi"},
+		{"hello-wolfi", "nginx-stable"},
+		{"nginx-stable", "hello-wolfi"}, // Order matters
+	}
+
+	hashes := make(map[string][]string)
+	for _, packages := range testCases {
+		hash := getPackageCacheSuffix(packages)
+		hashes[hash] = packages
+	}
+
+	// Should have unique hashes for each unique package list
+	if len(hashes) != len(testCases) {
+		t.Errorf("getPackageCacheSuffix produced collisions: %d unique hashes for %d test cases", len(hashes), len(testCases))
+		for hash, packages := range hashes {
+			t.Logf("Hash %q: %v", hash, packages)
+		}
+	}
+}