Merge remote-tracking branch 'upstream/main' into add-nested-archive-cataloging

cmd/syft/internal/commands/cataloger_info.go

@@ -349,8 +349,8 @@ func renderCatalogerInfoTable(_ *capabilities.Document, catalogers []capabilitie
 		})),
 		tablewriter.WithConfig(tablewriter.Config{
 			Row: tw.CellConfig{
-				Formatting: tw.CellFormatting{MergeMode: tw.MergeHierarchical},
-				Alignment:  tw.CellAlignment{Global: tw.AlignLeft},
+				Merging:   tw.CellMerging{Mode: tw.MergeHierarchical},
+				Alignment: tw.CellAlignment{Global: tw.AlignLeft},
 			},
 		}),
 	)

cmd/syft/internal/commands/convert.go

@@ -1,24 +1,34 @@
 package commands
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
+	"strings"
 
 	"github.com/spf13/cobra"
 
 	"github.com/anchore/clio"
+	"github.com/anchore/go-homedir"
 	"github.com/anchore/syft/cmd/syft/internal/options"
 	"github.com/anchore/syft/cmd/syft/internal/ui"
 	"github.com/anchore/syft/internal"
+	"github.com/anchore/syft/internal/bus"
 	"github.com/anchore/syft/internal/log"
+	"github.com/anchore/syft/internal/spillbuf"
+	"github.com/anchore/syft/internal/tmpdir"
 	"github.com/anchore/syft/syft/format"
+	"github.com/anchore/syft/syft/format/syftjson"
+	"github.com/anchore/syft/syft/sbom"
 )
 
 const (
 	convertExample = `  {{.appName}} {{.command}} img.syft.json -o spdx-json                      convert a syft SBOM to spdx-json, output goes to stdout
   {{.appName}} {{.command}} img.syft.json -o cyclonedx-json=img.cdx.json    convert a syft SBOM to CycloneDX, output is written to the file "img.cdx.json"
   {{.appName}} {{.command}} - -o spdx-json                                  convert an SBOM from STDIN to spdx-json
+  SYFT_CONVERT_PASSTHROUGH_EXACT_FORMAT=true {{.appName}} {{.command}} img.syft.json -o syft-json=out.syft.json    copy the input to "out.syft.json" unchanged if it is already syft-json at the current schema version
 `
 )
 
@@ -26,6 +36,7 @@ type ConvertOptions struct {
 	options.Config      `yaml:",inline" mapstructure:",squash"`
 	options.Output      `yaml:",inline" mapstructure:",squash"`
 	options.UpdateCheck `yaml:",inline" mapstructure:",squash"`
+	Convert             options.Convert `yaml:"convert" json:"convert" mapstructure:"convert"`
 }
 
 func Convert(app clio.Application) *cobra.Command {
@@ -34,6 +45,7 @@ func Convert(app clio.Application) *cobra.Command {
 	opts := &ConvertOptions{
 		UpdateCheck: options.DefaultUpdateCheck(),
 		Output:      options.DefaultOutput(),
+		Convert:     options.DefaultConvert(),
 	}
 
 	return app.SetupCommand(&cobra.Command{
@@ -46,11 +58,11 @@ func Convert(app clio.Application) *cobra.Command {
 		}),
 		Args:    validateConvertArgs,
 		PreRunE: applicationUpdateCheck(id, &opts.UpdateCheck),
-		RunE: func(_ *cobra.Command, args []string) error {
+		RunE: func(cmd *cobra.Command, args []string) error {
 			restoreStdout := ui.CaptureStdoutToTraceLog()
 			defer restoreStdout()
 
-			return RunConvert(opts, args[0])
+			return RunConvert(cmd.Context(), opts, args[0])
 		},
 	}, opts)
 }
@@ -59,30 +71,63 @@ func validateConvertArgs(cmd *cobra.Command, args []string) error {
 	return validateArgs(cmd, args, "an SBOM argument is required")
 }
 
-func RunConvert(opts *ConvertOptions, userInput string) error {
+func RunConvert(ctx context.Context, opts *ConvertOptions, userInput string) error {
 	log.Warn("convert is an experimental feature, run `syft convert -h` for help")
 
-	writer, err := opts.SBOMWriter()
+	// a temp dir is only needed when STDIN is a pipe and has to be spilled to disk; it is created lazily on
+	// first use (under the user's TMPDIR), so a file input never touches it. Mirrors syft.CreateSBOM, which
+	// also honors a TempDir already attached to the context.
+	td := tmpdir.FromContext(ctx)
+	if td == nil {
+		_, td = tmpdir.Root(ctx, "syft-convert")
+		defer func() {
+			_ = td.Cleanup()
+		}()
+	}
+
+	reader, inputInfo, err := openConvertInput(userInput, td)
 	if err != nil {
 		return err
 	}
+	defer func() {
+		_ = reader.Close()
+	}()
 
-	var reader io.ReadSeekCloser
+	outputs := opts.Outputs
+	var unchanged []string
+	if opts.Convert.PassthroughExactFormat {
+		log.Warn("convert.passthrough-exact-format is enabled: syft-json input that already exactly matches a requested output format and schema version will be copied to that output unchanged (this does not apply to any other input format)")
 
-	if userInput == "-" {
-		// though os.Stdin is an os.File, it does not support seeking
-		// you will get errors such as "seek /dev/stdin: illegal seek".
-		// We need to buffer what we read.
-		reader = internal.NewBufferedSeeker(os.Stdin)
-	} else {
-		f, err := os.Open(userInput)
+		unchanged, outputs, err = partitionOutputsBySourceFormat(opts.Output, reader)
 		if err != nil {
-			return fmt.Errorf("failed to open SBOM file: %w", err)
+			return err
 		}
-		defer func() {
-			_ = f.Close()
-		}()
-		reader = f
+	}
+
+	// resolve (and validate) every output that needs converting before writing anything, so that
+	// a bad -o value fails the command without leaving partial results behind
+	var writer sbom.Writer
+	if len(outputs) > 0 {
+		outputOpts := opts.Output
+		outputOpts.Outputs = outputs
+		writer, err = outputOpts.SBOMWriter()
+		if err != nil {
+			return err
+		}
+	}
+
+	for _, output := range unchanged {
+		if err := writeUnchanged(output, opts.LegacyFile, inputInfo, reader); err != nil {
+			return err
+		}
+	}
+
+	if writer == nil {
+		return nil
+	}
+
+	if _, err := reader.Seek(0, io.SeekStart); err != nil {
+		return fmt.Errorf("unable to seek to start of SBOM: %w", err)
 	}
 
 	s, _, _, err := format.Decode(reader)
@@ -100,3 +145,171 @@ func RunConvert(opts *ConvertOptions, userInput string) error {
 
 	return nil
 }
+
+// openConvertInput opens the SBOM document at the given path, or STDIN when "-". The returned reader is seekable so
+// the document can be identified, copied, and decoded in turn without being loaded into memory. The returned
+// os.FileInfo describes the file the document is being read from, so that writing back over it can be recognized;
+// it is nil when the input is not a file (a pipe or a terminal on STDIN).
+func openConvertInput(userInput string, td *tmpdir.TempDir) (io.ReadSeekCloser, os.FileInfo, error) {
+	if userInput == "-" {
+		return openStdin(td)
+	}
+
+	f, err := os.Open(userInput)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to open SBOM file: %w", err)
+	}
+
+	info, err := f.Stat()
+	if err != nil {
+		// the document is readable, we just cannot recognize it as an output destination
+		log.WithFields("error", err, "path", userInput).Debug("unable to stat SBOM file")
+	}
+	return f, info, nil
+}
+
+// openStdin returns a seekable view of STDIN. When STDIN is a regular file (such as a shell redirect) it is read in
+// place. A pipe or terminal cannot seek (you will get errors such as "seek /dev/stdin: illegal seek"), so its
+// contents are drained into a spill buffer: a small head stays in memory and everything beyond it goes to a temp
+// file under td, so an arbitrarily large piped SBOM never has to be held in memory to be made seekable.
+func openStdin(td *tmpdir.TempDir) (io.ReadSeekCloser, os.FileInfo, error) {
+	if info, err := os.Stdin.Stat(); err == nil && info.Mode().IsRegular() {
+		if start, err := os.Stdin.Seek(0, io.SeekCurrent); err == nil {
+			// a redirect reads the file in place, so it is just as much an input file as a path argument is
+			return readSeekNopCloser{io.NewSectionReader(os.Stdin, start, info.Size()-start)}, info, nil
+		}
+	}
+
+	buf := spillbuf.New(td)
+	if _, err := io.Copy(io.NewOffsetWriter(buf, 0), os.Stdin); err != nil {
+		_ = buf.Close()
+		return nil, nil, fmt.Errorf("failed to read SBOM from STDIN: %w", err)
+	}
+
+	return &spilledReader{
+		SectionReader: io.NewSectionReader(buf, 0, buf.Size()),
+		buf:           buf,
+	}, nil, nil
+}
+
+type readSeekNopCloser struct {
+	io.ReadSeeker
+}
+
+func (readSeekNopCloser) Close() error {
+	return nil
+}
+
+// spilledReader is a seekable view over a spill buffer; closing it releases the buffer's memory and spill file.
+type spilledReader struct {
+	*io.SectionReader
+	buf *spillbuf.Buffer
+}
+
+func (r *spilledReader) Close() error {
+	return r.buf.Close()
+}
+
+// partitionOutputsBySourceFormat splits the requested outputs (in "<format>[@<version>][=<path>]" form) into those
+// that exactly match the format and schema version of a syft-json input document (which can be written out
+// unchanged) and those that still require conversion. Input in any other format is always converted. Outputs that
+// cannot be resolved to an encoder are left for the writer to report on.
+func partitionOutputsBySourceFormat(output options.Output, reader io.ReadSeeker) (unchanged []string, toConvert []string, err error) {
+	if _, err := reader.Seek(0, io.SeekStart); err != nil {
+		return nil, nil, fmt.Errorf("unable to seek to start of SBOM: %w", err)
+	}
+
+	id, version := format.Identify(reader)
+	if id == "" || version == "" {
+		// let decoding surface the appropriate error
+		return nil, output.Outputs, nil
+	}
+
+	if id != syftjson.ID {
+		log.WithFields("format", id, "version", version).Debug("input is not syft-json, passthrough does not apply")
+		return nil, output.Outputs, nil
+	}
+
+	encoders, err := output.Encoders()
+	if err != nil {
+		return nil, nil, err
+	}
+	collection := format.NewEncoderCollection(encoders...)
+
+	for _, out := range output.Outputs {
+		name, _, _ := strings.Cut(strings.TrimSpace(out), "=")
+		enc := collection.GetByString(name)
+		if enc != nil && enc.ID() == id && enc.Version() == version {
+			log.WithFields("format", id, "version", version, "output", out).Warn("input already exactly matches the requested output format and schema version, copying it unchanged instead of converting it")
+			unchanged = append(unchanged, out)
+			continue
+		}
+		toConvert = append(toConvert, out)
+	}
+
+	return unchanged, toConvert, nil
+}
+
+// writeUnchanged copies the SBOM document as-is to the destination described by the given "<format>[=<path>]"
+// output value, falling back to the (deprecated) --file path, and finally to the report bus (STDOUT). When the
+// destination is the input file itself there is nothing to do.
+func writeUnchanged(output string, defaultFile string, inputInfo os.FileInfo, reader io.ReadSeeker) error {
+	if _, err := reader.Seek(0, io.SeekStart); err != nil {
+		return fmt.Errorf("unable to seek to start of SBOM: %w", err)
+	}
+
+	_, path, _ := strings.Cut(strings.TrimSpace(output), "=")
+	if path == "" {
+		path = defaultFile
+	}
+
+	if path == "" {
+		// the report bus only carries strings, so STDOUT output must be materialized in memory
+		content, err := io.ReadAll(reader) //nolint:gocritic // the whole SBOM is the report; there is no meaningful bound
+		if err != nil {
+			return fmt.Errorf("unable to read SBOM: %w", err)
+		}
+		bus.Report(string(content))
+		return nil
+	}
+
+	expandedPath, err := homedir.Expand(path)
+	if err != nil {
+		log.Warnf("could not expand given writer output path=%q: %w", path, err)
+		expandedPath = path
+	}
+
+	if isSameFile(inputInfo, expandedPath) {
+		log.WithFields("path", expandedPath).Info("output is the input file, leaving it as-is")
+		return nil
+	}
+
+	if err := os.MkdirAll(filepath.Dir(expandedPath), 0755); err != nil {
+		return fmt.Errorf("unable to create report directory: %w", err)
+	}
+
+	f, err := os.OpenFile(expandedPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0644)
+	if err != nil {
+		return fmt.Errorf("unable to create report file: %w", err)
+	}
+
+	if _, err := io.Copy(f, reader); err != nil {
+		_ = f.Close()
+		return fmt.Errorf("unable to write report file: %w", err)
+	}
+
+	return f.Close()
+}
+
+// isSameFile reports whether the given path names the file the input is being read from. Comparing the input's
+// os.FileInfo rather than its path covers a shell redirect onto STDIN, which has no path to compare.
+func isSameFile(inputInfo os.FileInfo, path string) bool {
+	if inputInfo == nil {
+		return false
+	}
+	pathInfo, err := os.Stat(path)
+	if err != nil {
+		return false
+	}
+	return os.SameFile(inputInfo, pathInfo)
+}

cmd/syft/internal/commands/convert_test.go

@@ -0,0 +1,448 @@
+package commands
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/wagoodman/go-partybus"
+
+	"github.com/anchore/syft/cmd/syft/internal/options"
+	"github.com/anchore/syft/internal/bus"
+	"github.com/anchore/syft/internal/spillbuf"
+	"github.com/anchore/syft/syft/event"
+	"github.com/anchore/syft/syft/file"
+	"github.com/anchore/syft/syft/format"
+	"github.com/anchore/syft/syft/format/cyclonedxjson"
+	"github.com/anchore/syft/syft/format/spdxjson"
+	"github.com/anchore/syft/syft/format/syftjson"
+	"github.com/anchore/syft/syft/pkg"
+	"github.com/anchore/syft/syft/sbom"
+	"github.com/anchore/syft/syft/source"
+)
+
+func convertTestSBOM() sbom.SBOM {
+	catalog := pkg.NewCollection()
+	catalog.Add(pkg.Package{
+		Name:    "musl-utils",
+		Version: "1.2.3-r4",
+		Type:    pkg.ApkPkg,
+		FoundBy: "apk-db-cataloger",
+		Locations: file.NewLocationSet(
+			file.NewLocation("/lib/apk/db/installed"),
+		),
+		PURL: "pkg:apk/alpine/musl-utils@1.2.3-r4",
+	})
+
+	return sbom.SBOM{
+		Artifacts: sbom.Artifacts{
+			Packages: catalog,
+		},
+		Source: source.Description{
+			ID:      "some-id",
+			Name:    "some-dir",
+			Version: "latest",
+			Metadata: source.DirectoryMetadata{
+				Path: "/some/path",
+			},
+		},
+		Descriptor: sbom.Descriptor{
+			Name:    "syft",
+			Version: "v0.0.0-test",
+		},
+	}
+}
+
+func mustConvertEncoder(enc sbom.FormatEncoder, err error) sbom.FormatEncoder {
+	if err != nil {
+		panic(err)
+	}
+	return enc
+}
+
+func encodeConvertTestSBOM(t *testing.T, enc sbom.FormatEncoder) []byte {
+	buf := &bytes.Buffer{}
+	require.NoError(t, enc.Encode(buf, convertTestSBOM()))
+	return buf.Bytes()
+}
+
+// prettySyftJSON returns the test SBOM as pretty-printed syft-json. Pretty input makes a verbatim copy
+// distinguishable from a re-encode, since re-encoding always produces compact output here.
+func prettySyftJSON(t *testing.T) []byte {
+	cfg := syftjson.DefaultEncoderConfig()
+	cfg.Pretty = true
+	return encodeConvertTestSBOM(t, mustConvertEncoder(syftjson.NewFormatEncoderWithConfig(cfg)))
+}
+
+func Test_partitionOutputsBySourceFormat(t *testing.T) {
+	syftEncoder := mustConvertEncoder(syftjson.NewFormatEncoderWithConfig(syftjson.DefaultEncoderConfig()))
+	syftVersion := syftEncoder.Version()
+	syftContent := encodeConvertTestSBOM(t, syftEncoder)
+
+	// the same document claiming an older schema version
+	olderSyftContent := bytes.ReplaceAll(syftContent, []byte(`"version":"`+syftVersion+`"`), []byte(`"version":"16.0.0"`))
+	require.NotEqual(t, syftContent, olderSyftContent)
+
+	cdxContent := encodeConvertTestSBOM(t, mustConvertEncoder(cyclonedxjson.NewFormatEncoderWithConfig(cyclonedxjson.DefaultEncoderConfig())))
+
+	tests := []struct {
+		name          string
+		content       []byte
+		outputs       []string
+		wantUnchanged []string
+		wantToConvert []string
+	}{
+		{
+			name:          "syft-json matches the bare format name",
+			content:       syftContent,
+			outputs:       []string{"syft-json"},
+			wantUnchanged: []string{"syft-json"},
+		},
+		{
+			name:          "syft-json matches its alias",
+			content:       syftContent,
+			outputs:       []string{"json"},
+			wantUnchanged: []string{"json"},
+		},
+		{
+			name:          "syft-json matches an explicit version and file path",
+			content:       syftContent,
+			outputs:       []string{"syft-json@" + syftVersion + "=out/some.syft.json"},
+			wantUnchanged: []string{"syft-json@" + syftVersion + "=out/some.syft.json"},
+		},
+		{
+			name:          "syft-json at an older schema version requires conversion",
+			content:       olderSyftContent,
+			outputs:       []string{"syft-json"},
+			wantToConvert: []string{"syft-json"},
+		},
+		{
+			name:          "a different output format requires conversion",
+			content:       syftContent,
+			outputs:       []string{"spdx-json"},
+			wantToConvert: []string{"spdx-json"},
+		},
+		{
+			name:          "mixed outputs are partitioned",
+			content:       syftContent,
+			outputs:       []string{"syft-json=a.json", "spdx-json=b.json", "cyclonedx-xml"},
+			wantUnchanged: []string{"syft-json=a.json"},
+			wantToConvert: []string{"spdx-json=b.json", "cyclonedx-xml"},
+		},
+		{
+			name:          "unknown format is left for the writer to report",
+			content:       syftContent,
+			outputs:       []string{"bogus"},
+			wantToConvert: []string{"bogus"},
+		},
+		{
+			name:          "non syft-json input is always converted, even when it matches the output",
+			content:       cdxContent,
+			outputs:       []string{"cyclonedx-json"},
+			wantToConvert: []string{"cyclonedx-json"},
+		},
+		{
+			name:          "unidentifiable content is left for the decoder to report",
+			content:       []byte("definitely not an sbom"),
+			outputs:       []string{"syft-json"},
+			wantToConvert: []string{"syft-json"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			output := options.DefaultOutput()
+			output.Outputs = tt.outputs
+
+			unchanged, toConvert, err := partitionOutputsBySourceFormat(output, bytes.NewReader(tt.content))
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantUnchanged, unchanged)
+			assert.Equal(t, tt.wantToConvert, toConvert)
+		})
+	}
+}
+
+func Test_RunConvert_passthroughExactFormat(t *testing.T) {
+	syftContent := prettySyftJSON(t)
+
+	newOpts := func(passthrough bool, outputs ...string) *ConvertOptions {
+		opts := &ConvertOptions{
+			Output: options.DefaultOutput(),
+			Convert: options.Convert{
+				PassthroughExactFormat: passthrough,
+			},
+		}
+		opts.Outputs = outputs
+		return opts
+	}
+
+	writeInput := func(t *testing.T, content []byte) string {
+		input := filepath.Join(t.TempDir(), "input.json")
+		require.NoError(t, os.WriteFile(input, content, 0600))
+		return input
+	}
+
+	t.Run("matching output is copied unchanged while others are converted", func(t *testing.T) {
+		dir := t.TempDir()
+		syftOut := filepath.Join(dir, "out.syft.json")
+		spdxOut := filepath.Join(dir, "out.spdx.json")
+
+		opts := newOpts(true, "syft-json="+syftOut, "spdx-json="+spdxOut)
+		require.NoError(t, RunConvert(context.Background(), opts, writeInput(t, syftContent)))
+
+		got, err := os.ReadFile(syftOut)
+		require.NoError(t, err)
+		assert.Equal(t, syftContent, got)
+
+		spdx, err := os.ReadFile(spdxOut)
+		require.NoError(t, err)
+		id, _ := format.Identify(bytes.NewReader(spdx))
+		assert.Equal(t, spdxjson.ID, id)
+	})
+
+	t.Run("STDIN input is copied unchanged while others are converted", func(t *testing.T) {
+		dir := t.TempDir()
+		syftOut := filepath.Join(dir, "out.syft.json")
+		spdxOut := filepath.Join(dir, "out.spdx.json")
+
+		stdin, err := os.Open(writeInput(t, syftContent))
+		require.NoError(t, err)
+		defer stdin.Close()
+
+		originalStdin := os.Stdin
+		os.Stdin = stdin
+		t.Cleanup(func() { os.Stdin = originalStdin })
+
+		opts := newOpts(true, "syft-json="+syftOut, "spdx-json="+spdxOut)
+		require.NoError(t, RunConvert(context.Background(), opts, "-"))
+
+		got, err := os.ReadFile(syftOut)
+		require.NoError(t, err)
+		assert.Equal(t, syftContent, got)
+
+		spdx, err := os.ReadFile(spdxOut)
+		require.NoError(t, err)
+		id, _ := format.Identify(bytes.NewReader(spdx))
+		assert.Equal(t, spdxjson.ID, id)
+	})
+
+	t.Run("piped STDIN input is copied unchanged while others are converted", func(t *testing.T) {
+		dir := t.TempDir()
+		syftOut := filepath.Join(dir, "out.syft.json")
+		spdxOut := filepath.Join(dir, "out.spdx.json")
+
+		pipeReader, pipeWriter, err := os.Pipe()
+		require.NoError(t, err)
+		defer pipeReader.Close()
+		go func() {
+			defer pipeWriter.Close()
+			_, _ = pipeWriter.Write(syftContent)
+		}()
+
+		originalStdin := os.Stdin
+		os.Stdin = pipeReader
+		t.Cleanup(func() { os.Stdin = originalStdin })
+
+		opts := newOpts(true, "syft-json="+syftOut, "spdx-json="+spdxOut)
+		require.NoError(t, RunConvert(context.Background(), opts, "-"))
+
+		got, err := os.ReadFile(syftOut)
+		require.NoError(t, err)
+		assert.Equal(t, syftContent, got)
+
+		spdx, err := os.ReadFile(spdxOut)
+		require.NoError(t, err)
+		id, _ := format.Identify(bytes.NewReader(spdx))
+		assert.Equal(t, spdxjson.ID, id)
+	})
+
+	t.Run("without the option the matching output is re-encoded", func(t *testing.T) {
+		syftOut := filepath.Join(t.TempDir(), "out.syft.json")
+
+		opts := newOpts(false, "syft-json="+syftOut)
+		require.NoError(t, RunConvert(context.Background(), opts, writeInput(t, syftContent)))
+
+		got, err := os.ReadFile(syftOut)
+		require.NoError(t, err)
+		id, _ := format.Identify(bytes.NewReader(got))
+		assert.Equal(t, syftjson.ID, id)
+		// the input was pretty-printed and the encoder is not configured to be, so a re-encode cannot reproduce it
+		assert.NotEqual(t, syftContent, got)
+	})
+
+	t.Run("non syft-json input is re-encoded even when it matches the output", func(t *testing.T) {
+		cdxContent := encodeConvertTestSBOM(t, mustConvertEncoder(cyclonedxjson.NewFormatEncoderWithConfig(cyclonedxjson.DefaultEncoderConfig())))
+		cdxOut := filepath.Join(t.TempDir(), "out.cdx.json")
+
+		opts := newOpts(true, "cyclonedx-json="+cdxOut)
+		require.NoError(t, RunConvert(context.Background(), opts, writeInput(t, cdxContent)))
+
+		got, err := os.ReadFile(cdxOut)
+		require.NoError(t, err)
+		id, _ := format.Identify(bytes.NewReader(got))
+		assert.Equal(t, cyclonedxjson.ID, id)
+		// a fresh serial number is minted on every encode, so a round trip never reproduces the input
+		assert.NotEqual(t, cdxContent, got)
+	})
+
+	t.Run("the deprecated --file path is honored", func(t *testing.T) {
+		syftOut := filepath.Join(t.TempDir(), "out.syft.json")
+
+		opts := newOpts(true, "syft-json")
+		opts.LegacyFile = syftOut
+		require.NoError(t, RunConvert(context.Background(), opts, writeInput(t, syftContent)))
+
+		got, err := os.ReadFile(syftOut)
+		require.NoError(t, err)
+		assert.Equal(t, syftContent, got)
+	})
+
+	t.Run("writing over the input file leaves it intact", func(t *testing.T) {
+		input := writeInput(t, syftContent)
+
+		opts := newOpts(true, "syft-json="+input)
+		require.NoError(t, RunConvert(context.Background(), opts, input))
+
+		got, err := os.ReadFile(input)
+		require.NoError(t, err)
+		assert.Equal(t, syftContent, got)
+	})
+
+	t.Run("writing over a redirected STDIN input leaves it intact", func(t *testing.T) {
+		input := writeInput(t, syftContent)
+
+		stdin, err := os.Open(input)
+		require.NoError(t, err)
+		defer stdin.Close()
+
+		originalStdin := os.Stdin
+		os.Stdin = stdin
+		t.Cleanup(func() { os.Stdin = originalStdin })
+
+		opts := newOpts(true, "syft-json="+input)
+		require.NoError(t, RunConvert(context.Background(), opts, "-"))
+
+		got, err := os.ReadFile(input)
+		require.NoError(t, err)
+		assert.Equal(t, syftContent, got)
+	})
+
+	t.Run("an invalid output fails before anything is written", func(t *testing.T) {
+		syftOut := filepath.Join(t.TempDir(), "out.syft.json")
+
+		opts := newOpts(true, "syft-json="+syftOut, "bogus")
+		require.Error(t, RunConvert(context.Background(), opts, writeInput(t, syftContent)))
+
+		assert.NoFileExists(t, syftOut)
+	})
+
+	t.Run("a missing input file is reported", func(t *testing.T) {
+		syftOut := filepath.Join(t.TempDir(), "out.syft.json")
+
+		opts := newOpts(true, "syft-json="+syftOut)
+		err := RunConvert(context.Background(), opts, filepath.Join(t.TempDir(), "does-not-exist.json"))
+		require.ErrorContains(t, err, "failed to open SBOM file")
+
+		assert.NoFileExists(t, syftOut)
+	})
+
+	t.Run("unrecognized input is left to the decoder to reject", func(t *testing.T) {
+		syftOut := filepath.Join(t.TempDir(), "out.syft.json")
+
+		opts := newOpts(true, "syft-json="+syftOut)
+		err := RunConvert(context.Background(), opts, writeInput(t, []byte("definitely not an sbom")))
+		require.ErrorContains(t, err, "failed to decode SBOM")
+	})
+}
+
+// largeSyftJSON returns a pretty-printed syft-json document of at least minBytes, built from many small packages.
+func largeSyftJSON(t *testing.T, minBytes int64) []byte {
+	catalog := pkg.NewCollection()
+	for i := 0; i < int(minBytes/100); i++ {
+		catalog.Add(pkg.Package{
+			Name:    fmt.Sprintf("pkg-%d", i),
+			Version: "1.0.0",
+			Type:    pkg.ApkPkg,
+			PURL:    fmt.Sprintf("pkg:apk/alpine/pkg-%d@1.0.0", i),
+		})
+	}
+	s := convertTestSBOM()
+	s.Artifacts.Packages = catalog
+
+	cfg := syftjson.DefaultEncoderConfig()
+	cfg.Pretty = true
+	enc := mustConvertEncoder(syftjson.NewFormatEncoderWithConfig(cfg))
+
+	buf := &bytes.Buffer{}
+	require.NoError(t, enc.Encode(buf, s))
+	require.Greater(t, int64(buf.Len()), minBytes)
+	return buf.Bytes()
+}
+
+func Test_RunConvert_pipedInputLargerThanMemoryLimitSpillsToDisk(t *testing.T) {
+	// a piped document bigger than the spill buffer's in-memory tier is written to a temp file under TMPDIR;
+	// the conversion must identify, copy and clean up from there rather than holding the document in memory
+	dir := t.TempDir()
+	syftOut := filepath.Join(dir, "out.syft.json")
+	spillRoot := filepath.Join(dir, "spill")
+	require.NoError(t, os.Mkdir(spillRoot, 0o755))
+	t.Setenv("TMPDIR", spillRoot)
+
+	content := largeSyftJSON(t, 2*spillbuf.DefaultMemLimit)
+
+	pipeReader, pipeWriter, err := os.Pipe()
+	require.NoError(t, err)
+	defer pipeReader.Close()
+	go func() {
+		defer pipeWriter.Close()
+		_, _ = pipeWriter.Write(content)
+	}()
+
+	originalStdin := os.Stdin
+	os.Stdin = pipeReader
+	t.Cleanup(func() { os.Stdin = originalStdin })
+
+	opts := &ConvertOptions{
+		Output: options.DefaultOutput(),
+		Convert: options.Convert{
+			PassthroughExactFormat: true,
+		},
+	}
+	opts.Outputs = []string{"syft-json=" + syftOut}
+	require.NoError(t, RunConvert(context.Background(), opts, "-"))
+
+	got, err := os.ReadFile(syftOut)
+	require.NoError(t, err)
+	assert.Equal(t, content, got)
+
+	entries, err := os.ReadDir(spillRoot)
+	require.NoError(t, err)
+	assert.Empty(t, entries, "the spill directory must be removed once the conversion finishes")
+}
+
+func Test_writeUnchanged_stdout(t *testing.T) {
+	// with no output path the document is published on the report bus, which is how the CLI writes to STDOUT
+	b := partybus.NewBus()
+	subscription := b.Subscribe()
+	bus.Set(b)
+	t.Cleanup(func() {
+		bus.Set(nil)
+	})
+
+	content := []byte(`{"some":"document"}`)
+	require.NoError(t, writeUnchanged("syft-json", "", nil, bytes.NewReader(content)))
+
+	select {
+	case e := <-subscription.Events():
+		assert.Equal(t, event.CLIReport, e.Type)
+		assert.Equal(t, string(content), e.Value)
+	case <-time.After(time.Second):
+		t.Fatal("no report was published")
+	}
+}

cmd/syft/internal/options/convert.go

@@ -0,0 +1,27 @@
+package options
+
+import (
+	"github.com/anchore/clio"
+)
+
+var _ clio.FieldDescriber = (*Convert)(nil)
+
+// Convert holds the options specific to the convert command. These are deliberately configuration-only (config file
+// or environment) rather than flags: they change how the command behaves for every invocation in a pipeline and are
+// not expected to vary from one call to the next.
+type Convert struct {
+	PassthroughExactFormat bool `yaml:"passthrough-exact-format" json:"passthrough-exact-format" mapstructure:"passthrough-exact-format"`
+}
+
+func DefaultConvert() Convert {
+	return Convert{
+		PassthroughExactFormat: false,
+	}
+}
+
+func (o *Convert) DescribeFields(descriptions clio.FieldDescriptionSet) {
+	descriptions.Add(&o.PassthroughExactFormat, `when a syft-json input SBOM already exactly matches the requested output format and schema version, copy it to that output unchanged instead of decoding and re-encoding it.
+Note: this only applies to syft-json input, and only when the document's schema version is identical to the schema version this version of syft produces. Any other input is always converted.
+Note: output written this way is a byte-for-byte copy of the input, so format options (such as 'format.pretty' or 'format.json.legacy') are not applied to it.
+Note: to keep memory use minimal on large documents, give the input as a file path (or a shell redirect) and write the output with '-o <format>=<path>'. Piped input, or output to STDOUT, requires the whole document to be held in memory.`)
+}

cmd/syft/internal/test/integration/multiplatform_oci_test.go

@@ -60,6 +60,8 @@ func TestMultiPlatformOCIImageSelection(t *testing.T) {
 
 					// The raw config of the selected image must match the requested platform...
 					assertConfigPlatform(t, meta.RawConfig, "linux", arch)
+					assert.Equal(t, "linux", meta.OS)
+					assert.Equal(t, arch, meta.Architecture)
 					// ...and it must be the exact per-platform image from the multi-platform index.
 					assert.Equal(t, expectedDigest[arch], meta.ID)
 				})
@@ -125,6 +127,8 @@ func TestMultiPlatformOCIImageSelection_DefaultPlatform(t *testing.T) {
 
 			// The raw config of the selected image must match the current platform
 			assertConfigPlatform(t, meta.RawConfig, "linux", runtime.GOARCH)
+			assert.Equal(t, "linux", meta.OS)
+			assert.Equal(t, runtime.GOARCH, meta.Architecture)
 		})
 	}
 }

cmd/syft/internal/test/integration/single_platform_oci_test.go

@@ -0,0 +1,64 @@
+package integration
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/anchore/stereoscope/pkg/image"
+	"github.com/anchore/stereoscope/pkg/imagetest"
+	"github.com/anchore/syft/syft"
+	"github.com/anchore/syft/syft/source"
+)
+
+// TestSinglePlatformOCIImage covers the single-image (non-index) OCI layouts, where syft used to report
+// empty os/architecture metadata and silently accept any --platform. Both now come from the image config.
+func TestSinglePlatformOCIImage(t *testing.T) {
+	// a platform this fixture is never built for, so the mismatch is not host dependent
+	unavailablePlatform, err := image.NewPlatform("linux/ppc64le")
+	require.NoError(t, err)
+
+	sources := map[string]image.Source{
+		"oci-dir":     image.OciDirectorySource,
+		"oci-archive": image.OciTarballSource,
+	}
+
+	for from, imageSource := range sources {
+		t.Run(from, func(t *testing.T) {
+			localPath := strings.TrimPrefix(imagetest.PrepareFixtureImage(t, imageSource, "image-distro-id"), string(imageSource)+":")
+
+			t.Run("reports the platform from the image config", func(t *testing.T) {
+				src, err := syft.GetSource(
+					context.Background(),
+					localPath,
+					syft.DefaultGetSourceConfig().WithSources(from),
+				)
+				require.NoError(t, err)
+				t.Cleanup(func() {
+					require.NoError(t, src.Close())
+				})
+
+				meta, ok := src.Describe().Metadata.(source.ImageMetadata)
+				require.True(t, ok, "expected image metadata, got %T", src.Describe().Metadata)
+
+				// the fixture is built for whatever the local docker daemon runs, so assert against the
+				// config rather than a fixed platform
+				assert.NotEmpty(t, meta.OS)
+				assert.NotEmpty(t, meta.Architecture)
+				assertConfigPlatform(t, meta.RawConfig, meta.OS, meta.Architecture)
+			})
+
+			t.Run("rejects a platform the image does not match", func(t *testing.T) {
+				_, err := syft.GetSource(
+					context.Background(),
+					localPath,
+					syft.DefaultGetSourceConfig().WithSources(from).WithPlatform(unavailablePlatform),
+				)
+				require.ErrorContains(t, err, "linux/ppc64le")
+			})
+		})
+	}
+}

cmd/syft/internal/test/integration/testdata/image-java-no-main-package/Dockerfile

@@ -8,8 +8,6 @@ RUN mkdir tmp
 
 WORKDIR /usr/share/jenkins/tmp
 
-RUN apt-get update 2>&1 > /dev/null && apt-get install -y less zip 2>&1 > /dev/null
-
 RUN unzip ../jenkins.war 2>&1 > /dev/null
 
 RUN rm -rf ./META-INF/MANIFEST.MF ./WEB-INF ./jsbundles ./scripts ./css
@@ -18,7 +16,8 @@ WORKDIR /usr/share/jenkins
 
 RUN rm -rf jenkins.war
 
-RUN cd ./tmp && zip -r ../jenkins.war . && cd ..
+# use jar (from the JDK in the base image) to rezip -- M keeps it manifest-less, which is the point of this fixture
+RUN cd ./tmp && jar cfM ../jenkins.war . && cd ..
 
 RUN rm -rf ./tmp
 

cmd/syft/internal/test/integration/testdata/image-pkg-coverage/Dockerfile

@@ -16,7 +16,7 @@ RUN unxz /lib/modules/6.0.7-301.fc37.x86_64/kernel/drivers/tty/ttynull.ko.xz
 # dotnet pkg coverage
 # https://nuget.info/packages/DocuSign.eSign.dll/6.8.0
 # https://github.com/docusign/docusign-esign-csharp-client/blob/master/LICENSE
-RUN curl -LO https://www.nuget.org/api/v2/package/DocuSign.eSign.dll/6.8.0
+RUN curl -fLO https://www.nuget.org/api/v2/package/DocuSign.eSign.dll/6.8.0
 RUN unzip 6.8.0
 RUN chmod 600 lib/net462/DocuSign.eSign.dll
 RUN rm 6.8.0