feat(policies): suppress hint on Violation skips the gate while keeping CAS data

Adds `bool suppress` on PolicyEvaluation.Violation. Policies opt in by
emitting `"suppress": true` on a structured finding (typically derived
from `assessment.effective_status == NOT_AFFECTED`). The engine reads
the bool generically; the gate filter excludes suppressed entries from
the count while the full violations list still flows to CAS and
ingestion (last_seen_at refreshes, audit trail preserved).

Touches: proto field, engine extraction in engineEvaluationsToAPIViolations,
gate filter in validatePolicyEnforcement, action-layer round-trip on
attestation_status, tests for all three.

Assisted-by: Claude Code
Signed-off-by: Miguel Martinez Trivino <miguel@chainloop.dev>

Author: migmartri

app/cli/cmd/attestation_push.go

@@ -186,11 +186,25 @@ func (e *GateError) Error() string {
 	return fmt.Sprintf("the policy %q is configured as a gate and has violations", e.PolicyName)
 }
 
+// hasGatingViolation reports whether any of the supplied violations should
+// count toward the policy gate. Entries flagged Suppress (typically because
+// an assessment renders the finding NOT_AFFECTED) are excluded.
+func hasGatingViolation(violations []*action.PolicyViolation) bool {
+	for _, v := range violations {
+		if !v.Suppress {
+			return true
+		}
+	}
+	return false
+}
+
 func validatePolicyEnforcement(status *action.AttestationStatusResult, bypassPolicyCheck bool) error {
-	// Block if any of the policies has been configured as a gate.
+	// Block if any of the policies has been configured as a gate. Entries
+	// flagged Suppress are excluded from the gate count but remain in
+	// eval.Violations for CAS storage and ingestion (audit trail preserved).
 	for _, evaluations := range status.PolicyEvaluations {
 		for _, eval := range evaluations {
-			if len(eval.Violations) > 0 && eval.Gate {
+			if eval.Gate && hasGatingViolation(eval.Violations) {
 				if bypassPolicyCheck {
 					logger.Warn().Msg(exceptionBypassPolicyCheck)
 					continue

app/cli/cmd/attestation_push_test.go

@@ -88,4 +88,51 @@ func TestValidatePolicyEnforcement(t *testing.T) {
 		err := validatePolicyEnforcement(status, false)
 		require.NoError(t, err)
 	})
+
+	t.Run("does not block when every violation on a gated policy is suppressed", func(t *testing.T) {
+		status := &action.AttestationStatusResult{
+			PolicyEvaluations: map[string][]*action.PolicyEvaluation{
+				"materials": {
+					{
+						Name: "cdx-fresh",
+						Gate: true,
+						Violations: []*action.PolicyViolation{
+							{Message: "CVE-2024-1 NOT_AFFECTED", Suppress: true},
+							{Message: "CVE-2024-2 NOT_AFFECTED", Suppress: true},
+						},
+					},
+				},
+			},
+			HasPolicyViolations:         true,
+			MustBlockOnPolicyViolations: false,
+		}
+
+		err := validatePolicyEnforcement(status, false)
+		require.NoError(t, err)
+	})
+
+	t.Run("blocks when at least one violation on a gated policy is not suppressed", func(t *testing.T) {
+		status := &action.AttestationStatusResult{
+			PolicyEvaluations: map[string][]*action.PolicyEvaluation{
+				"materials": {
+					{
+						Name: "cdx-fresh",
+						Gate: true,
+						Violations: []*action.PolicyViolation{
+							{Message: "CVE-2024-1 NOT_AFFECTED", Suppress: true},
+							{Message: "CVE-2024-2 active", Suppress: false},
+						},
+					},
+				},
+			},
+			HasPolicyViolations:         true,
+			MustBlockOnPolicyViolations: false,
+		}
+
+		err := validatePolicyEnforcement(status, false)
+		require.Error(t, err)
+		var gateErr *GateError
+		require.ErrorAs(t, err, &gateErr)
+		require.Equal(t, "cdx-fresh", gateErr.PolicyName)
+	})
 }

app/cli/pkg/action/attestation_status.go

@@ -367,8 +367,9 @@ func policyEvaluationStateToActionForStatus(in *v1.PolicyEvaluation) *PolicyEval
 	violations := make([]*PolicyViolation, 0, len(in.Violations))
 	for _, v := range in.Violations {
 		violations = append(violations, &PolicyViolation{
-			Subject: v.Subject,
-			Message: v.Message,
+			Subject:  v.Subject,
+			Message:  v.Message,
+			Suppress: v.GetSuppress(),
 		})
 	}
 

app/cli/pkg/action/workflow_run_describe.go

@@ -115,6 +115,10 @@ type PolicyEvaluation struct {
 type PolicyViolation struct {
 	Subject string `json:"subject"`
 	Message string `json:"message"`
+	// Suppress, when true, excludes this entry from the gate count while
+	// keeping it in the CAS-stored bundle (audit trail preserved). Set by
+	// the policy author via the rego "suppress" key.
+	Suppress bool `json:"suppress,omitempty"`
 }
 
 type PolicyReference struct {

app/controlplane/api/gen/frontend/attestation/v1/crafting_state.ts

@@ -284,6 +284,13 @@ message PolicyEvaluation {
       PolicySASTFinding sast = 4;
       PolicyLicenseViolationFinding license_violation = 5;
     }
+
+    // Suppression hint set by the policy. When true the gate count
+    // excludes this entry, but it is still stored in CAS and ingested
+    // (audit trail preserved). Set by the policy author (typically based
+    // on `assessment.effective_status`) — the engine reads the bool
+    // without interpreting why.
+    bool suppress = 6;
   }
 
   message Reference {

app/controlplane/api/gen/jsonschema/attestation.v1.PolicyEvaluation.Violation.jsonschema.json

@@ -787,6 +787,16 @@ func splitArgs(s string) []string {
 	return result
 }
 
+// extractSuppress pulls the optional "suppress" boolean from a structured
+// rego finding. Returns false for plain-string violations or when absent.
+func extractSuppress(raw map[string]any) bool {
+	if raw == nil {
+		return false
+	}
+	v, _ := raw["suppress"].(bool)
+	return v
+}
+
 func engineEvaluationsToAPIViolations(results []*engine.EvaluationResult, findingType string) ([]*v12.PolicyEvaluation_Violation, []string, error) {
 	res := make([]*v12.PolicyEvaluation_Violation, 0)
 	var warnings []string
@@ -796,8 +806,9 @@ func engineEvaluationsToAPIViolations(results []*engine.EvaluationResult, findin
 	for _, r := range results {
 		for _, v := range r.Violations {
 			apiV := &v12.PolicyEvaluation_Violation{
-				Subject: v.Subject,
-				Message: v.Violation,
+				Subject:  v.Subject,
+				Message:  v.Violation,
+				Suppress: extractSuppress(v.RawFinding),
 			}
 
 			hasStructuredData := v.RawFinding != nil