stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

release orchestrator v1 draft and build fixes

Browse Source
This commit is contained in:
master
2026-01-12 12:24:17 +02:00
parent f3de858c59
commit 9873f80830
1598 changed files with 240385 additions and 5944 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureMatcher.cs
View File

@@ -17,18 +17,33 @@ public sealed class DeltaSignatureMatcher : IDeltaSignatureMatcher
{
private readonly DisassemblyService _disassemblyService;
private readonly NormalizationService _normalizationService;
private readonly ISymbolChangeTracer _changeTracer;
private readonly ILogger<DeltaSignatureMatcher> _logger;
public DeltaSignatureMatcher(
DisassemblyService disassemblyService,
NormalizationService normalizationService,
ISymbolChangeTracer changeTracer,
ILogger<DeltaSignatureMatcher> logger)
{
_disassemblyService = disassemblyService;
_normalizationService = normalizationService;
_changeTracer = changeTracer;
_logger = logger;
}
/// <summary>
/// Legacy constructor for backward compatibility.
/// Creates an internal SymbolChangeTracer instance.
/// </summary>
public DeltaSignatureMatcher(
DisassemblyService disassemblyService,
NormalizationService normalizationService,
ILogger<DeltaSignatureMatcher> logger)
: this(disassemblyService, normalizationService, new SymbolChangeTracer(), logger)
{
}
/// <inheritdoc />
public async Task<IReadOnlyList<MatchResult>> MatchAsync(
Stream binaryStream,
@@ -329,6 +344,58 @@ public sealed class DeltaSignatureMatcher : IDeltaSignatureMatcher
}
}
/// <inheritdoc />
public Task<DeltaComparisonResult> CompareSignaturesAsync(
DeltaSignature fromSignature,
DeltaSignature toSignature,
CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(fromSignature);
ArgumentNullException.ThrowIfNull(toSignature);
_logger.LogDebug(
"Comparing signatures: {From} ({FromSymbols} symbols) -> {To} ({ToSymbols} symbols)",
fromSignature.SignatureId,
fromSignature.Symbols.Length,
toSignature.SignatureId,
toSignature.Symbols.Length);
var symbolResults = _changeTracer.CompareAllSymbols(fromSignature, toSignature);
var summary = new DeltaComparisonSummary
{
TotalSymbols = symbolResults.Count,
UnchangedSymbols = symbolResults.Count(r => r.ChangeType == SymbolChangeType.Unchanged),
AddedSymbols = symbolResults.Count(r => r.ChangeType == SymbolChangeType.Added),
RemovedSymbols = symbolResults.Count(r => r.ChangeType == SymbolChangeType.Removed),
ModifiedSymbols = symbolResults.Count(r => r.ChangeType == SymbolChangeType.Modified),
PatchedSymbols = symbolResults.Count(r => r.ChangeType == SymbolChangeType.Patched),
AverageConfidence = symbolResults.Count > 0
? symbolResults.Average(r => r.Confidence)
: 0.0,
TotalSizeDelta = symbolResults.Sum(r => r.SizeDelta)
};
_logger.LogInformation(
"Comparison complete: {Total} symbols, {Unchanged} unchanged, {Added} added, {Removed} removed, {Modified} modified, {Patched} patched",
summary.TotalSymbols,
summary.UnchangedSymbols,
summary.AddedSymbols,
summary.RemovedSymbols,
summary.ModifiedSymbols,
summary.PatchedSymbols);
var result = new DeltaComparisonResult
{
FromSignatureId = fromSignature.SignatureId,
ToSignatureId = toSignature.SignatureId,
SymbolResults = [.. symbolResults],
Summary = summary
};
return Task.FromResult(result);
}
private static byte[] GetNormalizedBytes(NormalizedFunction normalized)
{
var totalSize = normalized.Instructions.Sum(i => i.NormalizedBytes.Length);

12
src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/IDeltaSignatureMatcher.cs
View File

@@ -35,4 +35,16 @@ public interface IDeltaSignatureMatcher
string symbolHash,
string symbolName,
IEnumerable<DeltaSignature> signatures);
/// <summary>
/// Compare two delta signatures and return detailed change information.
/// </summary>
/// <param name="fromSignature">The "before" signature.</param>
/// <param name="toSignature">The "after" signature.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>Detailed comparison result with symbol-level changes.</returns>
Task<DeltaComparisonResult> CompareSignaturesAsync(
DeltaSignature fromSignature,
DeltaSignature toSignature,
CancellationToken ct = default);
}

30
src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/ISymbolChangeTracer.cs Normal file
View File

@@ -0,0 +1,30 @@
// Copyright (c) StellaOps. All rights reserved.
// Licensed under AGPL-3.0-or-later. See LICENSE in the project root.
namespace StellaOps.BinaryIndex.DeltaSig;
/// <summary>
/// Service for detailed symbol comparison between binary versions.
/// </summary>
public interface ISymbolChangeTracer
{
/// <summary>
/// Compare two symbol signatures and compute detailed change metrics.
/// </summary>
/// <param name="fromSymbol">Symbol from the "before" version (null if added).</param>
/// <param name="toSymbol">Symbol from the "after" version (null if removed).</param>
/// <returns>Detailed symbol match result with change tracking.</returns>
SymbolMatchResult CompareSymbols(
SymbolSignature? fromSymbol,
SymbolSignature? toSymbol);
/// <summary>
/// Compare all symbols between two delta signatures.
/// </summary>
/// <param name="fromSignature">The "before" delta signature.</param>
/// <param name="toSignature">The "after" delta signature.</param>
/// <returns>List of symbol comparison results.</returns>
IReadOnlyList<SymbolMatchResult> CompareAllSymbols(
DeltaSignature fromSignature,
DeltaSignature toSignature);
}

150
src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Models.cs
View File

@@ -72,6 +72,11 @@ public sealed record DeltaSignatureRequest
/// </summary>
public sealed record DeltaSignature
{
/// <summary>
/// Unique identifier for this signature.
/// </summary>
public string SignatureId { get; init; } = Guid.NewGuid().ToString("N");
/// <summary>
/// Schema identifier for this signature format.
/// </summary>
@@ -278,6 +283,79 @@ public sealed record SymbolMatchResult
/// Match confidence (0.0 - 1.0).
/// </summary>
public double Confidence { get; init; }
// ====== CHANGE TRACKING FIELDS ======
/// <summary>
/// Type of change detected.
/// </summary>
public SymbolChangeType ChangeType { get; init; } = SymbolChangeType.Unchanged;
/// <summary>
/// Size delta in bytes (positive = larger, negative = smaller).
/// </summary>
public int SizeDelta { get; init; }
/// <summary>
/// CFG basic block count delta (if available).
/// </summary>
public int? CfgBlockDelta { get; init; }
/// <summary>
/// Indices of chunks that matched (for partial match analysis).
/// </summary>
public ImmutableArray<int> MatchedChunkIndices { get; init; } = [];
/// <summary>
/// Human-readable explanation of the change.
/// </summary>
public string? ChangeExplanation { get; init; }
/// <summary>
/// Hash of the "from" version (before change).
/// </summary>
public string? FromHash { get; init; }
/// <summary>
/// Hash of the "to" version (after change).
/// </summary>
public string? ToHash { get; init; }
/// <summary>
/// Method used for matching (CFGHash, InstructionHash, SemanticHash, ChunkHash).
/// </summary>
public string? MatchMethod { get; init; }
}
/// <summary>
/// Type of symbol change detected.
/// </summary>
public enum SymbolChangeType
{
/// <summary>
/// No change detected.
/// </summary>
Unchanged,
/// <summary>
/// Symbol was added (not present in "from" version).
/// </summary>
Added,
/// <summary>
/// Symbol was removed (not present in "to" version).
/// </summary>
Removed,
/// <summary>
/// Symbol was modified (hash changed).
/// </summary>
Modified,
/// <summary>
/// Symbol was patched (security fix applied, verified).
/// </summary>
Patched
}
/// <summary>
@@ -310,3 +388,75 @@ public sealed record AuthoringResult
/// </summary>
public string? Error { get; init; }
}
/// <summary>
/// Result of comparing two delta signatures.
/// </summary>
public sealed record DeltaComparisonResult
{
/// <summary>
/// Identifier for the "from" signature.
/// </summary>
public required string FromSignatureId { get; init; }
/// <summary>
/// Identifier for the "to" signature.
/// </summary>
public required string ToSignatureId { get; init; }
/// <summary>
/// Individual symbol comparison results.
/// </summary>
public ImmutableArray<SymbolMatchResult> SymbolResults { get; init; } = [];
/// <summary>
/// Summary of the comparison.
/// </summary>
public required DeltaComparisonSummary Summary { get; init; }
}
/// <summary>
/// Summary of a delta comparison between two signatures.
/// </summary>
public sealed record DeltaComparisonSummary
{
/// <summary>
/// Total number of symbols compared.
/// </summary>
public int TotalSymbols { get; init; }
/// <summary>
/// Number of unchanged symbols.
/// </summary>
public int UnchangedSymbols { get; init; }
/// <summary>
/// Number of added symbols.
/// </summary>
public int AddedSymbols { get; init; }
/// <summary>
/// Number of removed symbols.
/// </summary>
public int RemovedSymbols { get; init; }
/// <summary>
/// Number of modified symbols.
/// </summary>
public int ModifiedSymbols { get; init; }
/// <summary>
/// Number of patched symbols (security fixes).
/// </summary>
public int PatchedSymbols { get; init; }
/// <summary>
/// Average confidence across all symbol comparisons.
/// </summary>
public double AverageConfidence { get; init; }
/// <summary>
/// Total size delta in bytes.
/// </summary>
public int TotalSizeDelta { get; init; }
}

1
src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/ServiceCollectionExtensions.cs
View File

@@ -43,6 +43,7 @@ public static class ServiceCollectionExtensions
logger);
});
services.AddSingleton<ISymbolChangeTracer, SymbolChangeTracer>();
services.AddSingleton<IDeltaSignatureMatcher, DeltaSignatureMatcher>();
return services;

237
src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/SymbolChangeTracer.cs Normal file
View File

@@ -0,0 +1,237 @@
// Copyright (c) StellaOps. All rights reserved.
// Licensed under AGPL-3.0-or-later. See LICENSE in the project root.
using System.Collections.Immutable;
using System.Globalization;
namespace StellaOps.BinaryIndex.DeltaSig;
/// <summary>
/// Service for detailed symbol comparison between binary versions.
/// Determines change type, similarity, and generates explanations.
/// </summary>
public sealed class SymbolChangeTracer : ISymbolChangeTracer
{
/// <inheritdoc />
public SymbolMatchResult CompareSymbols(
SymbolSignature? fromSymbol,
SymbolSignature? toSymbol)
{
// Case 1: Symbol added
if (fromSymbol is null && toSymbol is not null)
{
return new SymbolMatchResult
{
SymbolName = toSymbol.Name,
ExactMatch = false,
Confidence = 1.0,
ChangeType = SymbolChangeType.Added,
SizeDelta = toSymbol.SizeBytes,
ToHash = toSymbol.HashHex,
ChangeExplanation = "Symbol added in new version"
};
}
// Case 2: Symbol removed
if (fromSymbol is not null && toSymbol is null)
{
return new SymbolMatchResult
{
SymbolName = fromSymbol.Name,
ExactMatch = false,
Confidence = 1.0,
ChangeType = SymbolChangeType.Removed,
SizeDelta = -fromSymbol.SizeBytes,
FromHash = fromSymbol.HashHex,
ChangeExplanation = "Symbol removed in new version"
};
}
// Case 3: Both exist - compare
if (fromSymbol is not null && toSymbol is not null)
{
return CompareExistingSymbols(fromSymbol, toSymbol);
}
// Case 4: Both null (shouldn't happen)
throw new ArgumentException("Both symbols cannot be null");
}
/// <inheritdoc />
public IReadOnlyList<SymbolMatchResult> CompareAllSymbols(
DeltaSignature fromSignature,
DeltaSignature toSignature)
{
ArgumentNullException.ThrowIfNull(fromSignature);
ArgumentNullException.ThrowIfNull(toSignature);
var fromSymbols = fromSignature.Symbols
.ToDictionary(s => s.Name, StringComparer.Ordinal);
var toSymbols = toSignature.Symbols
.ToDictionary(s => s.Name, StringComparer.Ordinal);
var allNames = fromSymbols.Keys
.Union(toSymbols.Keys, StringComparer.Ordinal)
.OrderBy(n => n, StringComparer.Ordinal);
var results = new List<SymbolMatchResult>();
foreach (var name in allNames)
{
fromSymbols.TryGetValue(name, out var fromSymbol);
toSymbols.TryGetValue(name, out var toSymbol);
var result = CompareSymbols(fromSymbol, toSymbol);
results.Add(result);
}
return results;
}
private static SymbolMatchResult CompareExistingSymbols(
SymbolSignature from,
SymbolSignature to)
{
var exactMatch = string.Equals(from.HashHex, to.HashHex, StringComparison.OrdinalIgnoreCase);
var sizeDelta = to.SizeBytes - from.SizeBytes;
var cfgDelta = (from.CfgBbCount.HasValue && to.CfgBbCount.HasValue)
? to.CfgBbCount.Value - from.CfgBbCount.Value
: (int?)null;
if (exactMatch)
{
return new SymbolMatchResult
{
SymbolName = from.Name,
ExactMatch = true,
Confidence = 1.0,
ChangeType = SymbolChangeType.Unchanged,
SizeDelta = 0,
FromHash = from.HashHex,
ToHash = to.HashHex,
MatchMethod = "ExactHash",
ChangeExplanation = "No change detected"
};
}
// Compute chunk matches
var fromChunks = from.Chunks ?? [];
var toChunks = to.Chunks ?? [];
var (chunksMatched, matchedIndices) = CompareChunks(fromChunks, toChunks);
var chunkSimilarity = fromChunks.Length > 0
? (double)chunksMatched / fromChunks.Length
: 0.0;
// Determine change type and confidence
var (changeType, confidence, explanation, method) = DetermineChange(
from, to, chunkSimilarity, cfgDelta);
return new SymbolMatchResult
{
SymbolName = from.Name,
ExactMatch = false,
ChunksMatched = chunksMatched,
ChunksTotal = Math.Max(fromChunks.Length, toChunks.Length),
Confidence = confidence,
ChangeType = changeType,
SizeDelta = sizeDelta,
CfgBlockDelta = cfgDelta,
MatchedChunkIndices = matchedIndices,
FromHash = from.HashHex,
ToHash = to.HashHex,
MatchMethod = method,
ChangeExplanation = explanation
};
}
private static (int matched, ImmutableArray<int> indices) CompareChunks(
ImmutableArray<ChunkHash> fromChunks,
ImmutableArray<ChunkHash> toChunks)
{
if (fromChunks.Length == 0 || toChunks.Length == 0)
{
return (0, []);
}
var toChunkSet = toChunks
.Select(c => c.HashHex)
.ToHashSet(StringComparer.OrdinalIgnoreCase);
var matchedIndices = new List<int>();
var matched = 0;
for (var i = 0; i < fromChunks.Length; i++)
{
if (toChunkSet.Contains(fromChunks[i].HashHex))
{
matched++;
matchedIndices.Add(i);
}
}
return (matched, matchedIndices.ToImmutableArray());
}
private static (SymbolChangeType type, double confidence, string explanation, string method)
DetermineChange(
SymbolSignature from,
SymbolSignature to,
double chunkSimilarity,
int? cfgDelta)
{
// High chunk similarity with CFG change = likely patch
if (chunkSimilarity >= 0.85 && cfgDelta.HasValue && Math.Abs(cfgDelta.Value) <= 5)
{
return (
SymbolChangeType.Patched,
Math.Min(0.95, chunkSimilarity),
string.Format(
CultureInfo.InvariantCulture,
"Function patched: {0} basic blocks changed",
Math.Abs(cfgDelta.Value)),
"CFGHash+ChunkMatch"
);
}
// High chunk similarity = minor modification
if (chunkSimilarity >= 0.7)
{
return (
SymbolChangeType.Modified,
chunkSimilarity,
string.Format(
CultureInfo.InvariantCulture,
"Function modified: {0:P0} of code changed",
1 - chunkSimilarity),
"ChunkMatch"
);
}
// Semantic match check (if available)
if (!string.IsNullOrEmpty(from.SemanticHashHex) &&
!string.IsNullOrEmpty(to.SemanticHashHex))
{
var semanticMatch = string.Equals(
from.SemanticHashHex, to.SemanticHashHex,
StringComparison.OrdinalIgnoreCase);
if (semanticMatch)
{
return (
SymbolChangeType.Modified,
0.80,
"Function semantically equivalent (compiler variation)",
"SemanticHash"
);
}
}
// Low similarity = significant modification
return (
SymbolChangeType.Modified,
Math.Max(0.4, chunkSimilarity),
"Function significantly modified",
"ChunkMatch"
);
}
}