feat(cli): explode archive materials in chainloop att add (#3254)

Signed-off-by: Javier Rodriguez <javier@chainloop.dev>

Author: javirln

app/cli/cmd/attestation_add.go

@@ -18,8 +18,10 @@ package cmd
 import (
 	"errors"
 	"fmt"
+	"math"
 	"os"
 
+	"code.cloudfoundry.org/bytefmt"
 	"github.com/jedib0t/go-pretty/v6/table"
 	"github.com/muesli/reflow/wrap"
 	"github.com/spf13/cobra"
@@ -40,6 +42,8 @@ func newAttestationAddCmd() *cobra.Command {
 	var annotationsFlag []string
 	var noStrictValidation bool
 	var policyInputFromFileFlag []string
+	var maxExtractEntries int
+	var maxExtractSize string
 
 	// OCI registry credentials can be passed as flags or environment variables
 	var registryServer, registryUsername, registryPassword string
@@ -79,6 +83,16 @@ func newAttestationAddCmd() *cobra.Command {
     --policy-input-from-file trusted-binaries-signed:ignored_paths=exception.csv:Path \
     --policy-input-from-file trusted-binaries-vendor-keys:third_party_paths=exception.csv:Path`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
+			maxExtractSizeBytes, err := bytefmt.ToBytes(maxExtractSize)
+			if err != nil {
+				return fmt.Errorf("invalid --max-extract-size %q: %w", maxExtractSize, err)
+			}
+			// Guard against the uint64->int64 cast wrapping negative, which would
+			// later surface as a misleading "archive too large" error.
+			if maxExtractSizeBytes > math.MaxInt64 {
+				return fmt.Errorf("--max-extract-size %q is too large", maxExtractSize)
+			}
+
 			a, err := action.NewAttestationAdd(
 				&action.AttestationAddOpts{
 					ActionsOpts:        ActionOpts,
@@ -90,6 +104,8 @@ func newAttestationAddCmd() *cobra.Command {
 					RegistryPassword:   registryPassword,
 					LocalStatePath:     attestationLocalStatePath,
 					NoStrictValidation: noStrictValidation,
+					MaxExtractEntries:  maxExtractEntries,
+					MaxExtractSize:     int64(maxExtractSizeBytes),
 				},
 			)
 			if err != nil {
@@ -127,21 +143,28 @@ func newAttestationAddCmd() *cobra.Command {
 							return fmt.Errorf("loading resource: %w", err)
 						}
 					}
-					// TODO: take the material output and show render it
 					resp, err := a.Run(cmd.Context(), attestationID, name, rawValuePath, kind, annotations, policyInputFiles)
 					if err != nil {
 						return err
 					}
 
-					logger.Info().Msg("material added to attestation")
+					logger.Info().Int("materials", len(resp)).Msg("material(s) added to attestation")
 
 					policies, err := a.GetPolicyEvaluations(cmd.Context(), attestationID)
 					if err != nil {
 						return err
 					}
 
-					return output.EncodeOutput(flagOutputFormat, resp, func(s *action.AttestationStatusMaterial) error {
-						return displayMaterialInfo(s, policies[resp.Name])
+					// The explode path can return several materials. EncodeOutput
+					// renders the whole slice as a single JSON array (a parseable
+					// document) and the table renderer per material.
+					return output.EncodeOutput(flagOutputFormat, resp, func(mats []*action.AttestationStatusMaterial) error {
+						for _, m := range mats {
+							if err := displayMaterialInfo(m, policies[m.Name]); err != nil {
+								return err
+							}
+						}
+						return nil
 					})
 				},
 			)
@@ -171,6 +194,10 @@ func newAttestationAddCmd() *cobra.Command {
 	cmd.Flags().StringVar(&registryUsername, "registry-username", "", fmt.Sprintf("registry username, ($%s)", registryUsernameEnvVarName))
 	cmd.Flags().StringVar(&registryPassword, "registry-password", "", fmt.Sprintf("registry password, ($%s)", registryPasswordEnvVarName))
 
+	// Archive extraction guards
+	cmd.Flags().IntVar(&maxExtractEntries, "max-extract-entries", 10000, "max number of files to extract when --value is an archive")
+	cmd.Flags().StringVar(&maxExtractSize, "max-extract-size", "1GiB", "max total uncompressed size to extract when --value is an archive")
+
 	if registryServer == "" {
 		registryServer = os.Getenv(registryServerEnvVarName)
 	}

app/cli/cmd/output/output.go

@@ -56,6 +56,7 @@ type tabulatedData interface {
 		*action.APITokenItem |
 		[]*action.APITokenItem |
 		*action.AttestationStatusMaterial |
+		[]*action.AttestationStatusMaterial |
 		*action.ListMembershipResult |
 		*action.PolicyLintResult
 }

app/cli/documentation/cli-reference.mdx

@@ -263,6 +263,8 @@ Options
 --attestation-id string                Unique identifier of the in-progress attestation
 -h, --help                                 help for add
 --kind string                          kind of the material to be recorded: ["ARTIFACT" "ASYNCAPI_SPEC" "ATTESTATION" "BLACKDUCK_SCA_JSON" "CERTCC_DRANZER" "CHAINLOOP_AI_AGENT_CONFIG" "CHAINLOOP_AI_CODING_SESSION" "CHAINLOOP_PR_INFO" "CHAINLOOP_RUNNER_CONTEXT" "CONTAINER_IMAGE" "CSAF_INFORMATIONAL_ADVISORY" "CSAF_SECURITY_ADVISORY" "CSAF_SECURITY_INCIDENT_RESPONSE" "CSAF_VEX" "EVIDENCE" "GHAS_CODE_SCAN" "GHAS_DEPENDENCY_SCAN" "GHAS_SECRET_SCAN" "GITLAB_SECURITY_REPORT" "GITLEAKS_JSON" "GRAPHQL_SPEC" "HELM_CHART" "JACOCO_XML" "JUNIT_XML" "OPENAPI_SPEC" "OPENVEX" "OSSF_SCORECARD_JSON" "RADAMSA_CRASHES" "RADAMSA_REPORT" "SARIF" "SBOM_CYCLONEDX_JSON" "SBOM_SPDX_JSON" "SLSA_PROVENANCE" "STRING" "SYSINTERNALS_ACCESSCHK" "SYSINTERNALS_SIGCHECK" "TWISTCLI_SCAN_JSON" "YELP_DETECT_SECRETS_BASELINE" "ZAP_DAST_ZIP"]
+--max-extract-entries int              max number of files to extract when --value is an archive (default 10000)
+--max-extract-size string              max total uncompressed size to extract when --value is an archive (default "1GiB")
 --name string                          name of the material as shown in the contract
 --no-strict-validation                 skip strict schema validation for structured materials (SBOM_CYCLONEDX_JSON, OPENAPI_SPEC, ASYNCAPI_SPEC, OSSF_SCORECARD_JSON)
 --policy-input-from-file stringArray   feed a policy input from a column of a CSV or JSON file, in the format [<policy>:]<input>=<file>[:<column>] (e.g. ignored_paths=exception.csv:Path); an optional <policy>: prefix scopes the input to a single policy (matched by name or ref), otherwise it applies to every declaring policy; <column> is a single top-level column/field name and defaults to the input name; repeatable. The file is also recorded as EVIDENCE.

app/cli/pkg/action/attestation_add.go

@@ -42,6 +42,12 @@ type AttestationAddOpts struct {
 	LocalStatePath                                     string
 	// NoStrictValidation skips strict schema validation
 	NoStrictValidation bool
+	// MaxExtractEntries limits the number of entries extracted from an archive.
+	// Zero defaults to materials.DefaultArchiveLimits().MaxEntries.
+	MaxExtractEntries int
+	// MaxExtractSize limits the total uncompressed bytes extracted from an archive.
+	// Zero defaults to materials.DefaultArchiveLimits().MaxTotalSize.
+	MaxExtractSize int64
 }
 
 type newCrafterOpts struct {
@@ -56,6 +62,8 @@ type AttestationAdd struct {
 	casCAPath          string
 	connectionInsecure bool
 	localStatePath     string
+	maxExtractEntries  int
+	maxExtractSize     int64
 	*newCrafterOpts
 }
 
@@ -69,19 +77,31 @@ func NewAttestationAdd(cfg *AttestationAddOpts) (*AttestationAdd, error) {
 		opts = append(opts, crafter.WithNoStrictValidation(cfg.NoStrictValidation))
 	}
 
+	defaults := materials.DefaultArchiveLimits()
+	maxEntries := cfg.MaxExtractEntries
+	if maxEntries <= 0 {
+		maxEntries = defaults.MaxEntries
+	}
+	maxSize := cfg.MaxExtractSize
+	if maxSize <= 0 {
+		maxSize = defaults.MaxTotalSize
+	}
+
 	return &AttestationAdd{
 		ActionsOpts:        cfg.ActionsOpts,
 		newCrafterOpts:     &newCrafterOpts{cpConnection: cfg.CPConnection, opts: opts},
 		casURI:             cfg.CASURI,
 		casCAPath:          cfg.CASCAPath,
 		connectionInsecure: cfg.ConnectionInsecure,
 		localStatePath:     cfg.LocalStatePath,
+		maxExtractEntries:  maxEntries,
+		maxExtractSize:     maxSize,
 	}, nil
 }
 
 var ErrAttestationNotInitialized = errors.New("attestation not yet initialized")
 
-func (action *AttestationAdd) Run(ctx context.Context, attestationID, materialName, materialValue, materialType string, annotations map[string]string, policyInputFiles []*PolicyInputFromFile) (*AttestationStatusMaterial, error) {
+func (action *AttestationAdd) Run(ctx context.Context, attestationID, materialName, materialValue, materialType string, annotations map[string]string, policyInputFiles []*PolicyInputFromFile) ([]*AttestationStatusMaterial, error) {
 	// initialize the crafter. If attestation-id is provided we assume the attestation is performed using remote state
 	crafter, err := newCrafter(&newCrafterStateOpts{enableRemoteState: (attestationID != ""), localStatePath: action.localStatePath}, action.CPConnection, action.opts...)
 	if err != nil {
@@ -133,6 +153,31 @@ func (action *AttestationAdd) Run(ctx context.Context, attestationID, materialNa
 	// 3. If materialType is not empty, add material contract free with materialType and materialName
 	addOpts := runtimeInputAddOpts(runtimeInputs)
 
+	// Explode path: --kind set, value is a (non-archive-native) archive.
+	format, err := shouldExplode(materialType, materialValue)
+	if err != nil {
+		return nil, fmt.Errorf("detecting archive: %w", err)
+	}
+	if format != materials.ArchiveNone {
+		if len(policyInputFiles) > 0 {
+			action.Logger.Warn().Msg("--policy-input-from-file is ignored when expanding an archive; evidence cross-links are not recorded for exploded materials")
+		}
+		limits := materials.ArchiveLimits{MaxEntries: action.maxExtractEntries, MaxTotalSize: action.maxExtractSize}
+		mts, err := crafter.AddMaterialsFromArchive(ctx, attestationID, materialType, materialName, materialValue, format, casBackend, annotations, limits, addOpts...)
+		if err != nil {
+			return nil, fmt.Errorf("adding materials from archive: %w", err)
+		}
+		results := make([]*AttestationStatusMaterial, 0, len(mts))
+		for _, mt := range mts {
+			r, err := attMaterialToAction(mt)
+			if err != nil {
+				return nil, fmt.Errorf("converting material to action: %w", err)
+			}
+			results = append(results, r)
+		}
+		return results, nil
+	}
+
 	var mt *api.Attestation_Material
 	switch {
 	case materialName == "" && materialType == "":
@@ -176,7 +221,21 @@ func (action *AttestationAdd) Run(ctx context.Context, attestationID, materialNa
 		return nil, fmt.Errorf("converting material to action: %w", err)
 	}
 
-	return materialResult, nil
+	return []*AttestationStatusMaterial{materialResult}, nil
+}
+
+// shouldExplode decides whether an att-add should explode the value into many
+// materials: only when the kind is explodable (SBOM/SARIF) and the value is a
+// supported archive. It returns ArchiveNone for every other kind so a regular
+// zip provided as e.g. ARTIFACT or EVIDENCE is recorded whole.
+func shouldExplode(materialType, value string) (materials.ArchiveFormat, error) {
+	// Only explode kinds that have a meaningful "bundle of the same kind"
+	// archive form (SBOM, SARIF). Any other kind — including ARTIFACT and
+	// EVIDENCE — records the archive whole even when the value is a zip/tar.
+	if !materials.IsExplodableKind(materialType) {
+		return materials.ArchiveNone, nil
+	}
+	return materials.DetectArchive(value)
 }
 
 // runtimeInputAddOpts wraps the runtime inputs as crafter add options, or
@@ -315,29 +374,14 @@ func policyInputEvidenceNames(materialName string, policyInputFiles []*PolicyInp
 	return names
 }
 
-// sanitizeMaterialNamePart lower-cases s and collapses every run of characters
-// outside [a-z0-9] into a single "-", trimming leading/trailing "-", so the
-// result is a valid material-name component. Falls back to "input" if nothing
-// usable remains.
+// sanitizeMaterialNamePart sanitizes s into a valid material-name component via
+// materials.SanitizeMaterialName, falling back to "input" if nothing usable
+// remains.
 func sanitizeMaterialNamePart(s string) string {
-	var b strings.Builder
-	pendingHyphen := false
-	for _, r := range strings.ToLower(s) {
-		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') {
-			if pendingHyphen && b.Len() > 0 {
-				b.WriteByte('-')
-			}
-			b.WriteRune(r)
-			pendingHyphen = false
-		} else {
-			pendingHyphen = true
-		}
-	}
-
-	if b.Len() == 0 {
-		return "input"
+	if name := materials.SanitizeMaterialName(s); name != "" {
+		return name
 	}
-	return b.String()
+	return "input"
 }
 
 // GetPolicyEvaluations is a Wrapper around the getPolicyEvaluations

app/cli/pkg/action/attestation_add_routing_test.go

@@ -0,0 +1,82 @@
+//
+// Copyright 2026 The Chainloop Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package action
+
+import (
+	"archive/zip"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/chainloop-dev/chainloop/pkg/attestation/crafter/materials"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// writeTestZip creates a zip archive at dir/name containing a single file
+// "entry.txt" and returns its path.
+func writeTestZip(t *testing.T, dir, name string) string {
+	t.Helper()
+	path := filepath.Join(dir, name)
+	f, err := os.Create(path)
+	require.NoError(t, err)
+	defer f.Close()
+
+	w := zip.NewWriter(f)
+	entry, err := w.Create("entry.txt")
+	require.NoError(t, err)
+	_, err = entry.Write([]byte("hello"))
+	require.NoError(t, err)
+	require.NoError(t, w.Close())
+	return path
+}
+
+func TestShouldExplode(t *testing.T) {
+	dir := t.TempDir()
+	zipPath := writeTestZip(t, dir, "s.zip")
+
+	// non-archive: a plain temp file with an unrecognised extension
+	plainPath := filepath.Join(dir, "plain.bin")
+	require.NoError(t, os.WriteFile(plainPath, []byte("not an archive"), 0600))
+
+	tests := []struct {
+		name       string
+		kind       string
+		value      string
+		wantFormat materials.ArchiveFormat
+	}{
+		// A non-ArchiveNone format means the value will be exploded. Only
+		// explodable kinds (SBOM, SARIF) explode; everything else is recorded
+		// whole even when the value is an archive.
+		{"explodable SBOM + archive", "SBOM_CYCLONEDX_JSON", zipPath, materials.ArchiveZip},
+		{"explodable SARIF + archive", "SARIF", zipPath, materials.ArchiveZip},
+		{"non-explodable ARTIFACT + archive", "ARTIFACT", zipPath, materials.ArchiveNone},
+		{"non-explodable EVIDENCE + archive", "EVIDENCE", zipPath, materials.ArchiveNone},
+		{"archive-native ZAP + archive", "ZAP_DAST_ZIP", zipPath, materials.ArchiveNone},
+		{"no kind", "", zipPath, materials.ArchiveNone},
+		{"explodable kind + non-archive", "SBOM_CYCLONEDX_JSON", plainPath, materials.ArchiveNone},
+		// Non-file values must never return an error — even for an explodable kind
+		// the value here is not a file path at all.
+		{"explodable kind STRING-like non-file value", "SARIF", "hello world", materials.ArchiveNone},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			format, err := shouldExplode(tc.kind, tc.value)
+			require.NoError(t, err)
+			assert.Equal(t, tc.wantFormat, format)
+		})
+	}
+}