git.stella-ops.org/src/__Libraries/StellaOps.Evidence.Bundle/BinaryDiffEvidence.cs

// <copyright file="BinaryDiffEvidence.cs" company="StellaOps">
// SPDX-License-Identifier: BUSL-1.1
// Sprint: SPRINT_20260112_008_LB_binary_diff_evidence_models (BINDIFF-LB-001)
// </copyright>

using System.Collections.Immutable;
using System.Text.Json.Serialization;

namespace StellaOps.Evidence.Bundle;

/// <summary>
/// Binary diff evidence capturing semantic and structural changes between binary versions.
/// </summary>
public sealed class BinaryDiffEvidence
{
    /// <summary>
    /// Status of the binary diff evidence.
    /// </summary>
    public required EvidenceStatus Status { get; init; }

    /// <summary>
    /// SHA-256 hash of the diff evidence content.
    /// </summary>
    public string? Hash { get; init; }

    /// <summary>
    /// Previous binary artifact digest.
    /// </summary>
    public string? PreviousBinaryDigest { get; init; }

    /// <summary>
    /// Current binary artifact digest.
    /// </summary>
    public string? CurrentBinaryDigest { get; init; }

    /// <summary>
    /// Type of binary diff performed.
    /// </summary>
    public BinaryDiffType DiffType { get; init; }

    /// <summary>
    /// Binary format or ISA (e.g., "elf-x86_64", "pe-amd64", "macho-arm64").
    /// </summary>
    public string? BinaryFormat { get; init; }

    /// <summary>
    /// Tool and version used for diffing.
    /// </summary>
    public string? ToolVersion { get; init; }

    /// <summary>
    /// Overall similarity score (0.0-1.0).
    /// </summary>
    public double? SimilarityScore { get; init; }

    /// <summary>
    /// Function-level changes.
    /// </summary>
    public ImmutableArray<BinaryFunctionDiff> FunctionChanges { get; init; } = [];

    /// <summary>
    /// Symbol-level changes.
    /// </summary>
    public ImmutableArray<BinarySymbolDiff> SymbolChanges { get; init; } = [];

    /// <summary>
    /// Section-level changes.
    /// </summary>
    public ImmutableArray<BinarySectionDiff> SectionChanges { get; init; } = [];

    /// <summary>
    /// Semantic fingerprint changes.
    /// </summary>
    public BinarySemanticDiff? SemanticDiff { get; init; }

    /// <summary>
    /// Security-relevant changes detected.
    /// </summary>
    public ImmutableArray<BinarySecurityChange> SecurityChanges { get; init; } = [];

    /// <summary>
    /// Reason if diff is unavailable.
    /// </summary>
    public string? UnavailableReason { get; init; }

    /// <summary>
    /// Previous scan ID for reference.
    /// </summary>
    public string? PreviousScanId { get; init; }

    /// <summary>
    /// Previous scan time.
    /// </summary>
    public DateTimeOffset? PreviousScanTime { get; init; }

    /// <summary>
    /// When this diff was computed.
    /// </summary>
    public DateTimeOffset? ComputedAt { get; init; }
}

/// <summary>
/// Type of binary diff analysis.
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum BinaryDiffType
{
    /// <summary>Structural diff (sections, symbols).</summary>
    Structural,

    /// <summary>Semantic diff (IR-based).</summary>
    Semantic,

    /// <summary>Combined structural and semantic.</summary>
    Combined,

    /// <summary>Fast hash-only comparison.</summary>
    HashOnly
}

/// <summary>
/// Function-level diff entry.
/// </summary>
public sealed class BinaryFunctionDiff
{
    /// <summary>
    /// Diff operation type.
    /// </summary>
    public required BinaryDiffOperation Operation { get; init; }

    /// <summary>
    /// Function name or symbol.
    /// </summary>
    public required string FunctionName { get; init; }

    /// <summary>
    /// Function address in previous binary.
    /// </summary>
    public ulong? PreviousAddress { get; init; }

    /// <summary>
    /// Function address in current binary.
    /// </summary>
    public ulong? CurrentAddress { get; init; }

    /// <summary>
    /// Previous size in bytes.
    /// </summary>
    public int? PreviousSize { get; init; }

    /// <summary>
    /// Current size in bytes.
    /// </summary>
    public int? CurrentSize { get; init; }

    /// <summary>
    /// Semantic similarity score (0.0-1.0) for modified functions.
    /// </summary>
    public double? Similarity { get; init; }

    /// <summary>
    /// Node hash for the function (for reachability correlation).
    /// </summary>
    public string? NodeHash { get; init; }

    /// <summary>
    /// Whether this function is security-sensitive.
    /// </summary>
    public bool SecuritySensitive { get; init; }

    /// <summary>
    /// Brief description of the change.
    /// </summary>
    public string? ChangeDescription { get; init; }
}

/// <summary>
/// Symbol-level diff entry.
/// </summary>
public sealed class BinarySymbolDiff
{
    /// <summary>
    /// Diff operation type.
    /// </summary>
    public required BinaryDiffOperation Operation { get; init; }

    /// <summary>
    /// Symbol name.
    /// </summary>
    public required string SymbolName { get; init; }

    /// <summary>
    /// Symbol type (function, object, etc.).
    /// </summary>
    public string? SymbolType { get; init; }

    /// <summary>
    /// Section containing the symbol.
    /// </summary>
    public string? Section { get; init; }

    /// <summary>
    /// Symbol visibility.
    /// </summary>
    public string? Visibility { get; init; }
}

/// <summary>
/// Section-level diff entry.
/// </summary>
public sealed class BinarySectionDiff
{
    /// <summary>
    /// Diff operation type.
    /// </summary>
    public required BinaryDiffOperation Operation { get; init; }

    /// <summary>
    /// Section name.
    /// </summary>
    public required string SectionName { get; init; }

    /// <summary>
    /// Previous section size.
    /// </summary>
    public long? PreviousSize { get; init; }

    /// <summary>
    /// Current section size.
    /// </summary>
    public long? CurrentSize { get; init; }

    /// <summary>
    /// Size delta.
    /// </summary>
    public long? SizeDelta { get; init; }

    /// <summary>
    /// Section permissions/flags.
    /// </summary>
    public string? Permissions { get; init; }
}

/// <summary>
/// Semantic diff summary.
/// </summary>
public sealed class BinarySemanticDiff
{
    /// <summary>
    /// Previous semantic fingerprint hash.
    /// </summary>
    public string? PreviousFingerprint { get; init; }

    /// <summary>
    /// Current semantic fingerprint hash.
    /// </summary>
    public string? CurrentFingerprint { get; init; }

    /// <summary>
    /// Overall semantic similarity (0.0-1.0).
    /// </summary>
    public double Similarity { get; init; }

    /// <summary>
    /// Number of semantically identical functions.
    /// </summary>
    public int IdenticalFunctions { get; init; }

    /// <summary>
    /// Number of semantically similar functions.
    /// </summary>
    public int SimilarFunctions { get; init; }

    /// <summary>
    /// Number of semantically different functions.
    /// </summary>
    public int DifferentFunctions { get; init; }

    /// <summary>
    /// IR normalization recipe version used.
    /// </summary>
    public string? NormalizationRecipe { get; init; }
}

/// <summary>
/// Security-relevant change in binary.
/// </summary>
public sealed class BinarySecurityChange
{
    /// <summary>
    /// Type of security change.
    /// </summary>
    public required BinarySecurityChangeType ChangeType { get; init; }

    /// <summary>
    /// Severity of the change (low, medium, high, critical).
    /// </summary>
    public required string Severity { get; init; }

    /// <summary>
    /// Description of the change.
    /// </summary>
    public required string Description { get; init; }

    /// <summary>
    /// Affected function or symbol.
    /// </summary>
    public string? AffectedSymbol { get; init; }

    /// <summary>
    /// CVE IDs potentially related to this change.
    /// </summary>
    public ImmutableArray<string> RelatedCves { get; init; } = [];
}

/// <summary>
/// Type of security-relevant change.
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum BinarySecurityChangeType
{
    /// <summary>New security-sensitive function added.</summary>
    SecurityFunctionAdded,

    /// <summary>Security-sensitive function removed.</summary>
    SecurityFunctionRemoved,

    /// <summary>Security-sensitive function modified.</summary>
    SecurityFunctionModified,

    /// <summary>Crypto function changed.</summary>
    CryptoChange,

    /// <summary>Memory safety function changed.</summary>
    MemorySafetyChange,

    /// <summary>Authentication/authorization function changed.</summary>
    AuthChange,

    /// <summary>Input validation function changed.</summary>
    InputValidationChange,

    /// <summary>Hardening feature added or removed.</summary>
    HardeningChange
}

/// <summary>
/// Binary diff operation types.
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum BinaryDiffOperation
{
    /// <summary>Element was added.</summary>
    Added,

    /// <summary>Element was removed.</summary>
    Removed,

    /// <summary>Element was modified.</summary>
    Modified,

    /// <summary>Element was renamed.</summary>
    Renamed,

    /// <summary>Element was moved to different location.</summary>
    Moved
}