Add inline DSSE provenance documentation and Mongo schema

- Introduced a new document outlining the inline DSSE provenance for SBOM, VEX, scan, and derived events.
- Defined the Mongo schema for event patches, including key fields for provenance and trust verification.
- Documented the write path for ingesting provenance metadata and backfilling historical events.
- Created CI/CD snippets for uploading DSSE attestations and generating provenance metadata.
- Established Mongo indexes for efficient provenance queries and provided query recipes for various use cases.
- Outlined policy gates for managing VEX decisions based on provenance verification.
- Included UI nudges for displaying provenance information and implementation tasks for future enhancements.

---

Implement reachability lattice and scoring model

- Developed a comprehensive document detailing the reachability lattice and scoring model.
- Defined core types for reachability states, evidence, and mitigations with corresponding C# models.
- Established a scoring policy with base score contributions from various evidence classes.
- Mapped reachability states to VEX gates and provided a clear overview of evidence sources.
- Documented the event graph schema for persisting reachability data in MongoDB.
- Outlined the integration of runtime probes for evidence collection and defined a roadmap for future tasks.

---

Introduce uncertainty states and entropy scoring

- Created a draft document for tracking uncertainty states and their impact on risk scoring.
- Defined core uncertainty states with associated entropy values and evidence requirements.
- Established a schema for storing uncertainty states alongside findings.
- Documented the risk score calculation incorporating uncertainty and its effect on final risk assessments.
- Provided policy guidelines for handling uncertainty in decision-making processes.
- Outlined UI guidelines for displaying uncertainty information and suggested remediation actions.

---

Add Ruby package inventory management

- Implemented Ruby package inventory management with corresponding data models and storage mechanisms.
- Created C# records for Ruby package inventory, artifacts, provenance, and runtime details.
- Developed a repository for managing Ruby package inventory documents in MongoDB.
- Implemented a service for storing and retrieving Ruby package inventories.
- Added unit tests for the Ruby package inventory store to ensure functionality and data integrity.

src/Scanner/StellaOps.Scanner.WebService/Contracts/RubyContracts.cs

@@ -0,0 +1,21 @@
+using System.Text.Json.Serialization;
+using StellaOps.Scanner.Core.Contracts;
+
+namespace StellaOps.Scanner.WebService.Contracts;
+
+public sealed record RubyPackagesResponse
+{
+    [JsonPropertyName("scanId")]
+    public string ScanId { get; init; } = string.Empty;
+
+    [JsonPropertyName("imageDigest")]
+    public string ImageDigest { get; init; } = string.Empty;
+
+    [JsonPropertyName("generatedAt")]
+    public DateTimeOffset GeneratedAt { get; init; }
+        = DateTimeOffset.UtcNow;
+
+    [JsonPropertyName("packages")]
+    public IReadOnlyList<RubyPackageArtifact> Packages { get; init; }
+        = Array.Empty<RubyPackageArtifact>();
+}

src/Scanner/StellaOps.Scanner.WebService/Endpoints/ScanEndpoints.cs

@@ -13,6 +13,8 @@ using StellaOps.Scanner.WebService.Domain;
 using StellaOps.Scanner.WebService.Infrastructure;
 using StellaOps.Scanner.WebService.Security;
 using StellaOps.Scanner.WebService.Services;
+using DomainScanProgressEvent = StellaOps.Scanner.WebService.Domain.ScanProgressEvent;
+using StellaOps.Scanner.Core.Contracts;
 using StellaOps.Scanner.EntryTrace;
 
 namespace StellaOps.Scanner.WebService.Endpoints;
@@ -54,6 +56,12 @@ internal static class ScanEndpoints
             .Produces<EntryTraceResponse>(StatusCodes.Status200OK)
             .Produces(StatusCodes.Status404NotFound)
             .RequireAuthorization(ScannerPolicies.ScansRead);
+
+        scans.MapGet("/{scanId}/ruby-packages", HandleRubyPackagesAsync)
+            .WithName("scanner.scans.ruby-packages")
+            .Produces<RubyPackagesResponse>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status404NotFound)
+            .RequireAuthorization(ScannerPolicies.ScansRead);
     }
 
     private static async Task<IResult> HandleSubmitAsync(
@@ -311,6 +319,46 @@ internal static class ScanEndpoints
         return Json(response, StatusCodes.Status200OK);
     }
 
+    private static async Task<IResult> HandleRubyPackagesAsync(
+        string scanId,
+        IRubyPackageInventoryStore inventoryStore,
+        HttpContext context,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(inventoryStore);
+
+        if (!ScanId.TryParse(scanId, out var parsed))
+        {
+            return ProblemResultFactory.Create(
+                context,
+                ProblemTypes.Validation,
+                "Invalid scan identifier",
+                StatusCodes.Status400BadRequest,
+                detail: "Scan identifier is required.");
+        }
+
+        var inventory = await inventoryStore.GetAsync(parsed.Value, cancellationToken).ConfigureAwait(false);
+        if (inventory is null)
+        {
+            return ProblemResultFactory.Create(
+                context,
+                ProblemTypes.NotFound,
+                "Ruby packages not found",
+                StatusCodes.Status404NotFound,
+                detail: "Ruby package inventory is not available for the requested scan.");
+        }
+
+        var response = new RubyPackagesResponse
+        {
+            ScanId = inventory.ScanId,
+            ImageDigest = inventory.ImageDigest,
+            GeneratedAt = inventory.GeneratedAtUtc,
+            Packages = inventory.Packages
+        };
+
+        return Json(response, StatusCodes.Status200OK);
+    }
+
     private static IReadOnlyDictionary<string, string> NormalizeMetadata(IDictionary<string, string> metadata)
     {
         if (metadata is null || metadata.Count == 0)
@@ -342,7 +390,7 @@ internal static class ScanEndpoints
         await writer.WriteAsync(new[] { (byte)'\n' }, cancellationToken).ConfigureAwait(false);
     }
 
-    private static async Task WriteSseAsync(PipeWriter writer, object payload, ScanProgressEvent progressEvent, CancellationToken cancellationToken)
+    private static async Task WriteSseAsync(PipeWriter writer, object payload, DomainScanProgressEvent progressEvent, CancellationToken cancellationToken)
     {
         var json = JsonSerializer.Serialize(payload, SerializerOptions);
         var eventName = progressEvent.State.ToLowerInvariant();

src/Scanner/StellaOps.Scanner.WebService/Program.cs

@@ -19,6 +19,7 @@ using StellaOps.Cryptography.DependencyInjection;
 using StellaOps.Cryptography.Plugin.BouncyCastle;
 using StellaOps.Policy;
 using StellaOps.Scanner.Cache;
+using StellaOps.Scanner.Core.Contracts;
 using StellaOps.Scanner.Surface.Env;
 using StellaOps.Scanner.Surface.FS;
 using StellaOps.Scanner.Surface.Secrets;

src/Scanner/StellaOps.Scanner.WebService/Services/SurfacePointerService.cs

@@ -13,6 +13,7 @@ using StellaOps.Scanner.Storage.Catalog;
 using StellaOps.Scanner.Storage.ObjectStore;
 using StellaOps.Scanner.Storage.Repositories;
 using StellaOps.Scanner.Surface.Env;
+using StellaOps.Scanner.Surface.FS;
 using StellaOps.Scanner.WebService.Contracts;
 using StellaOps.Scanner.WebService.Options;