feat: add optional description field to PolicyVulnerabilityFinding

Also fix forward compatibility by using DiscardUnknown in protojson
unmarshal so older CLIs gracefully ignore fields from newer policies.

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

Author: migmartri

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

@@ -332,6 +332,8 @@ message PolicyVulnerabilityFinding {
   repeated string cwes = 6;
   // Suggested fix or upgrade path
   string recommendation = 7;
+  // Optional longer description of the vulnerability
+  string description = 8;
 }
 
 // Output schema for SAST findings from policy evaluation.

app/controlplane/api/gen/jsonschema/attestation.v1.PolicyVulnerabilityFinding.jsonschema.json

@@ -60,7 +60,9 @@ func ValidateFinding(findingType string, raw map[string]any) (proto.Message, err
 	}
 
 	msg := factory()
-	if err := protojson.Unmarshal(data, msg); err != nil {
+	// DiscardUnknown allows policies to include fields added in newer proto
+	// versions without breaking older CLIs that haven't been updated yet.
+	if err := (protojson.UnmarshalOptions{DiscardUnknown: true}).Unmarshal(data, msg); err != nil {
 		return nil, fmt.Errorf("finding does not match %s schema: %w", findingType, err)
 	}
 

app/controlplane/api/gen/jsonschema/attestation.v1.PolicyVulnerabilityFinding.schema.json

@@ -74,6 +74,26 @@ func TestValidateFinding(t *testing.T) {
 				assert.InDelta(t, 9.8, f.GetCvssV3Score(), 0.01)
 			},
 		},
+		{
+			name:        "valid vulnerability finding with description",
+			findingType: "VULNERABILITY",
+			raw: map[string]any{
+				"message":      "Found CVE-2024-5678",
+				"external_id":  "CVE-2024-5678",
+				"package_purl": "pkg:golang/example.com/lib@v2.0.0",
+				"severity":     "HIGH",
+				"description":  "A buffer overflow vulnerability in the parsing module allows remote code execution.",
+			},
+			checkFn: func(t *testing.T, msg interface{}) {
+				t.Helper()
+				f, ok := msg.(*v1.PolicyVulnerabilityFinding)
+				require.True(t, ok)
+				assert.Equal(t, "Found CVE-2024-5678", f.GetMessage())
+				assert.Equal(t, "CVE-2024-5678", f.GetExternalId())
+				assert.Equal(t, "HIGH", f.GetSeverity())
+				assert.Equal(t, "A buffer overflow vulnerability in the parsing module allows remote code execution.", f.GetDescription())
+			},
+		},
 		{
 			name:        "vulnerability finding missing required field",
 			findingType: "VULNERABILITY",
@@ -142,6 +162,23 @@ func TestValidateFinding(t *testing.T) {
 				assert.Equal(t, "GPL-3.0", f.GetLicenseId())
 			},
 		},
+		{
+			name:        "vulnerability finding with unknown field is accepted",
+			findingType: "VULNERABILITY",
+			raw: map[string]any{
+				"message":      "Found CVE-2024-9999",
+				"external_id":  "CVE-2024-9999",
+				"package_purl": "pkg:golang/example.com/lib@v3.0.0",
+				"severity":     "LOW",
+				"future_field": "some value from a newer policy",
+			},
+			checkFn: func(t *testing.T, msg interface{}) {
+				t.Helper()
+				f, ok := msg.(*v1.PolicyVulnerabilityFinding)
+				require.True(t, ok)
+				assert.Equal(t, "CVE-2024-9999", f.GetExternalId())
+			},
+		},
 		{
 			name:        "unknown finding type",
 			findingType: "UNKNOWN",