save progress

src/Scanner/__Libraries/StellaOps.Scanner.Evidence/Models/DeltaSignatureEvidence.cs

@@ -0,0 +1,303 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Sprint: SPRINT_20260102_001_BE
+// Task: DS-041 - VEX evidence emission for backport detection
+
+using System.Collections.Immutable;
+using System.Text.Json.Serialization;
+
+namespace StellaOps.Scanner.Evidence.Models;
+
+/// <summary>
+/// Evidence from binary delta signature analysis.
+/// Provides cryptographic proof of backport status by comparing
+/// normalized binary code against known patched/vulnerable signatures.
+/// </summary>
+public sealed record DeltaSignatureEvidence
+{
+    /// <summary>
+    /// Schema version for this evidence type.
+    /// </summary>
+    [JsonPropertyName("schema")]
+    public string Schema { get; init; } = "stellaops.evidence.deltasig.v1";
+
+    /// <summary>
+    /// Overall result: patched, vulnerable, inconclusive.
+    /// </summary>
+    [JsonPropertyName("result")]
+    public required DeltaSigResult Result { get; init; }
+
+    /// <summary>
+    /// CVE identifier(s) that were evaluated.
+    /// </summary>
+    [JsonPropertyName("cveIds")]
+    public required ImmutableArray<string> CveIds { get; init; }
+
+    /// <summary>
+    /// Package reference (PURL) being analyzed.
+    /// </summary>
+    [JsonPropertyName("packagePurl")]
+    public required string PackagePurl { get; init; }
+
+    /// <summary>
+    /// Binary identifier (path or Build-ID).
+    /// </summary>
+    [JsonPropertyName("binaryId")]
+    public required string BinaryId { get; init; }
+
+    /// <summary>
+    /// Target architecture (x86_64, aarch64, etc.).
+    /// </summary>
+    [JsonPropertyName("architecture")]
+    public required string Architecture { get; init; }
+
+    /// <summary>
+    /// Symbol-level match results.
+    /// </summary>
+    [JsonPropertyName("symbolMatches")]
+    public required ImmutableArray<SymbolMatchEvidence> SymbolMatches { get; init; }
+
+    /// <summary>
+    /// Confidence score [0, 1] of the overall determination.
+    /// </summary>
+    [JsonPropertyName("confidence")]
+    public required decimal Confidence { get; init; }
+
+    /// <summary>
+    /// Normalization recipe used for comparison.
+    /// </summary>
+    [JsonPropertyName("normalizationRecipe")]
+    public required NormalizationRecipeRef NormalizationRecipe { get; init; }
+
+    /// <summary>
+    /// When this evidence was generated.
+    /// </summary>
+    [JsonPropertyName("generatedAt")]
+    public required DateTimeOffset GeneratedAt { get; init; }
+
+    /// <summary>
+    /// Human-readable summary of the determination.
+    /// </summary>
+    [JsonPropertyName("summary")]
+    public required string Summary { get; init; }
+
+    /// <summary>
+    /// Optional DSSE envelope URI containing the signed attestation.
+    /// </summary>
+    [JsonPropertyName("attestationUri")]
+    public string? AttestationUri { get; init; }
+
+    /// <summary>
+    /// Creates evidence for a patched binary.
+    /// </summary>
+    public static DeltaSignatureEvidence CreatePatched(
+        ImmutableArray<string> cveIds,
+        string packagePurl,
+        string binaryId,
+        string architecture,
+        ImmutableArray<SymbolMatchEvidence> symbolMatches,
+        decimal confidence,
+        NormalizationRecipeRef recipe,
+        TimeProvider? timeProvider = null)
+    {
+        var matchSummary = symbolMatches.IsDefaultOrEmpty
+            ? "No symbols analyzed"
+            : $"{symbolMatches.Count(m => m.State == SignatureState.Patched)} patched, " +
+              $"{symbolMatches.Count(m => m.State == SignatureState.Vulnerable)} vulnerable";
+
+        return new DeltaSignatureEvidence
+        {
+            Result = DeltaSigResult.Patched,
+            CveIds = cveIds,
+            PackagePurl = packagePurl,
+            BinaryId = binaryId,
+            Architecture = architecture,
+            SymbolMatches = symbolMatches,
+            Confidence = confidence,
+            NormalizationRecipe = recipe,
+            GeneratedAt = (timeProvider ?? TimeProvider.System).GetUtcNow(),
+            Summary = $"Binary confirmed PATCHED with {confidence:P0} confidence. {matchSummary}."
+        };
+    }
+
+    /// <summary>
+    /// Creates evidence for a vulnerable binary.
+    /// </summary>
+    public static DeltaSignatureEvidence CreateVulnerable(
+        ImmutableArray<string> cveIds,
+        string packagePurl,
+        string binaryId,
+        string architecture,
+        ImmutableArray<SymbolMatchEvidence> symbolMatches,
+        decimal confidence,
+        NormalizationRecipeRef recipe,
+        TimeProvider? timeProvider = null)
+    {
+        var matchSummary = symbolMatches.IsDefaultOrEmpty
+            ? "No symbols analyzed"
+            : $"{symbolMatches.Count(m => m.State == SignatureState.Vulnerable)} vulnerable symbols matched";
+
+        return new DeltaSignatureEvidence
+        {
+            Result = DeltaSigResult.Vulnerable,
+            CveIds = cveIds,
+            PackagePurl = packagePurl,
+            BinaryId = binaryId,
+            Architecture = architecture,
+            SymbolMatches = symbolMatches,
+            Confidence = confidence,
+            NormalizationRecipe = recipe,
+            GeneratedAt = (timeProvider ?? TimeProvider.System).GetUtcNow(),
+            Summary = $"Binary confirmed VULNERABLE with {confidence:P0} confidence. {matchSummary}."
+        };
+    }
+
+    /// <summary>
+    /// Creates evidence for an inconclusive analysis.
+    /// </summary>
+    public static DeltaSignatureEvidence CreateInconclusive(
+        ImmutableArray<string> cveIds,
+        string packagePurl,
+        string binaryId,
+        string architecture,
+        string reason,
+        ImmutableArray<SymbolMatchEvidence> symbolMatches,
+        NormalizationRecipeRef recipe,
+        TimeProvider? timeProvider = null)
+    {
+        return new DeltaSignatureEvidence
+        {
+            Result = DeltaSigResult.Inconclusive,
+            CveIds = cveIds,
+            PackagePurl = packagePurl,
+            BinaryId = binaryId,
+            Architecture = architecture,
+            SymbolMatches = symbolMatches,
+            Confidence = 0m,
+            NormalizationRecipe = recipe,
+            GeneratedAt = (timeProvider ?? TimeProvider.System).GetUtcNow(),
+            Summary = $"Analysis INCONCLUSIVE: {reason}"
+        };
+    }
+}
+
+/// <summary>
+/// Result of delta signature analysis.
+/// </summary>
+[JsonConverter(typeof(JsonStringEnumConverter<DeltaSigResult>))]
+public enum DeltaSigResult
+{
+    /// <summary>
+    /// Binary contains patched code - security fix is applied.
+    /// </summary>
+    [JsonStringEnumMemberName("patched")]
+    Patched,
+
+    /// <summary>
+    /// Binary contains vulnerable code - security fix is NOT applied.
+    /// </summary>
+    [JsonStringEnumMemberName("vulnerable")]
+    Vulnerable,
+
+    /// <summary>
+    /// Unable to determine patch status (symbols not found, LTO obfuscation, etc.).
+    /// </summary>
+    [JsonStringEnumMemberName("inconclusive")]
+    Inconclusive
+}
+
+/// <summary>
+/// Evidence for a single symbol match.
+/// </summary>
+public sealed record SymbolMatchEvidence
+{
+    /// <summary>
+    /// Symbol/function name.
+    /// </summary>
+    [JsonPropertyName("symbolName")]
+    public required string SymbolName { get; init; }
+
+    /// <summary>
+    /// Normalized hash of the symbol (SHA-256).
+    /// </summary>
+    [JsonPropertyName("hashHex")]
+    public required string HashHex { get; init; }
+
+    /// <summary>
+    /// Matched signature state (patched or vulnerable).
+    /// </summary>
+    [JsonPropertyName("state")]
+    public required SignatureState State { get; init; }
+
+    /// <summary>
+    /// Match confidence [0, 1].
+    /// </summary>
+    [JsonPropertyName("confidence")]
+    public required decimal Confidence { get; init; }
+
+    /// <summary>
+    /// Whether this was an exact full-hash match.
+    /// </summary>
+    [JsonPropertyName("exactMatch")]
+    public required bool ExactMatch { get; init; }
+
+    /// <summary>
+    /// Number of chunks matched (for partial matching).
+    /// </summary>
+    [JsonPropertyName("chunksMatched")]
+    public int? ChunksMatched { get; init; }
+
+    /// <summary>
+    /// Total chunks in signature.
+    /// </summary>
+    [JsonPropertyName("chunksTotal")]
+    public int? ChunksTotal { get; init; }
+
+    /// <summary>
+    /// Reference to the matched signature (PURL of the signature source package).
+    /// </summary>
+    [JsonPropertyName("signatureSourcePurl")]
+    public string? SignatureSourcePurl { get; init; }
+}
+
+/// <summary>
+/// State of a signature: vulnerable or patched.
+/// </summary>
+[JsonConverter(typeof(JsonStringEnumConverter<SignatureState>))]
+public enum SignatureState
+{
+    /// <summary>
+    /// Signature represents vulnerable code (before fix).
+    /// </summary>
+    [JsonStringEnumMemberName("vulnerable")]
+    Vulnerable,
+
+    /// <summary>
+    /// Signature represents patched code (after fix).
+    /// </summary>
+    [JsonStringEnumMemberName("patched")]
+    Patched
+}
+
+/// <summary>
+/// Reference to the normalization recipe used.
+/// </summary>
+public sealed record NormalizationRecipeRef
+{
+    /// <summary>
+    /// Recipe identifier (e.g., "stellaops.normalize.x64.v1").
+    /// </summary>
+    [JsonPropertyName("recipeId")]
+    public required string RecipeId { get; init; }
+
+    /// <summary>
+    /// Recipe version.
+    /// </summary>
+    [JsonPropertyName("version")]
+    public required string Version { get; init; }
+
+    /// <summary>
+    /// Normalization steps applied.
+    /// </summary>
+    [JsonPropertyName("steps")]
+    public ImmutableArray<string> Steps { get; init; } = [];
+}