up

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

@@ -1,26 +1,28 @@
-using System.Collections.Generic;
-using System.Collections.Immutable;
-using System.Collections.ObjectModel;
-using System.Linq;
-using System.Text;
-using System.Text.Json;
-using System.Text.Json.Serialization;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Collections.ObjectModel;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Routing;
 using StellaOps.Policy;
+using StellaOps.Scanner.Surface.Env;
 using StellaOps.Scanner.WebService.Constants;
-using StellaOps.Scanner.WebService.Contracts;
-using StellaOps.Scanner.WebService.Infrastructure;
-using StellaOps.Scanner.WebService.Security;
-using StellaOps.Scanner.WebService.Services;
-using StellaOps.Zastava.Core.Contracts;
-using RuntimePolicyVerdict = StellaOps.Zastava.Core.Contracts.PolicyVerdict;
+using StellaOps.Scanner.WebService.Contracts;
+using StellaOps.Scanner.WebService.Infrastructure;
+using StellaOps.Scanner.WebService.Security;
+using StellaOps.Scanner.WebService.Services;
+using StellaOps.Zastava.Core.Contracts;
+using RuntimePolicyVerdict = StellaOps.Zastava.Core.Contracts.PolicyVerdict;
 
-namespace StellaOps.Scanner.WebService.Endpoints;
-
-#pragma warning disable ASPDEPR002
-
-internal static class PolicyEndpoints
+namespace StellaOps.Scanner.WebService.Endpoints;
+
+#pragma warning disable ASPDEPR002
+
+internal static class PolicyEndpoints
 {
     private static readonly JsonSerializerOptions SerializerOptions = new(JsonSerializerDefaults.Web)
     {
@@ -57,30 +59,42 @@ internal static class PolicyEndpoints
                 return operation;
             });
 
-        policyGroup.MapPost("/preview", HandlePreviewAsync)
-            .WithName("scanner.policy.preview")
-            .Produces<PolicyPreviewResponseDto>(StatusCodes.Status200OK)
-            .Produces(StatusCodes.Status400BadRequest)
-            .RequireAuthorization(ScannerPolicies.Reports)
-            .WithOpenApi(operation =>
-            {
-                operation.Summary = "Preview policy impact against findings.";
-                operation.Description = "Evaluates the supplied findings against the active or proposed policy, returning diffs, quieted verdicts, and actionable validation messages.";
-                return operation;
-            });
-
-        policyGroup.MapPost("/runtime", HandleRuntimePolicyAsync)
-            .WithName("scanner.policy.runtime")
-            .Produces<RuntimePolicyResponseDto>(StatusCodes.Status200OK)
-            .Produces(StatusCodes.Status400BadRequest)
-            .RequireAuthorization(ScannerPolicies.Reports)
-            .WithOpenApi(operation =>
-            {
-                operation.Summary = "Evaluate runtime policy for digests.";
-                operation.Description = "Returns per-image policy verdicts, signature and SBOM metadata, and cache hints for admission controllers.";
-                return operation;
-            });
-    }
+        policyGroup.MapPost("/preview", HandlePreviewAsync)
+            .WithName("scanner.policy.preview")
+            .Produces<PolicyPreviewResponseDto>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status400BadRequest)
+            .RequireAuthorization(ScannerPolicies.Reports)
+            .WithOpenApi(operation =>
+            {
+                operation.Summary = "Preview policy impact against findings.";
+                operation.Description = "Evaluates the supplied findings against the active or proposed policy, returning diffs, quieted verdicts, and actionable validation messages.";
+                return operation;
+            });
+
+        policyGroup.MapPost("/runtime", HandleRuntimePolicyAsync)
+            .WithName("scanner.policy.runtime")
+            .Produces<RuntimePolicyResponseDto>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status400BadRequest)
+            .RequireAuthorization(ScannerPolicies.Reports)
+            .WithOpenApi(operation =>
+            {
+                operation.Summary = "Evaluate runtime policy for digests.";
+                operation.Description = "Returns per-image policy verdicts, signature and SBOM metadata, and cache hints for admission controllers.";
+                return operation;
+            });
+
+        policyGroup.MapPost("/overlay", HandlePolicyOverlayAsync)
+            .WithName("scanner.policy.overlay")
+            .Produces<PolicyOverlayResponseDto>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status400BadRequest)
+            .RequireAuthorization(ScannerPolicies.Reports)
+            .WithOpenApi(operation =>
+            {
+                operation.Summary = "Request policy overlays for graph nodes.";
+                operation.Description = "Returns deterministic policy overlays with runtime evidence for graph nodes (Cartographer integration). Overlay IDs are computed as sha256(tenant|nodeId|overlayKind).";
+                return operation;
+            });
+    }
 
     private static IResult HandleSchemaAsync(HttpContext context)
     {
@@ -170,97 +184,97 @@ internal static class PolicyEndpoints
 
         var domainRequest = PolicyDtoMapper.ToDomain(request);
         var response = await previewService.PreviewAsync(domainRequest, cancellationToken).ConfigureAwait(false);
-        var payload = PolicyDtoMapper.ToDto(response);
-        return Json(payload);
-    }
-
-    private static async Task<IResult> HandleRuntimePolicyAsync(
-        RuntimePolicyRequestDto request,
-        IRuntimePolicyService runtimePolicyService,
-        HttpContext context,
-        CancellationToken cancellationToken)
-    {
-        ArgumentNullException.ThrowIfNull(request);
-        ArgumentNullException.ThrowIfNull(runtimePolicyService);
-
-        if (request.Images is null || request.Images.Count == 0)
-        {
-            return ProblemResultFactory.Create(
-                context,
-                ProblemTypes.Validation,
-                "Invalid runtime policy request",
-                StatusCodes.Status400BadRequest,
-                detail: "images collection must include at least one digest.");
-        }
-
-        var normalizedImages = new List<string>();
-        var seen = new HashSet<string>(StringComparer.Ordinal);
-        foreach (var image in request.Images)
-        {
-            if (string.IsNullOrWhiteSpace(image))
-            {
-                return ProblemResultFactory.Create(
-                    context,
-                    ProblemTypes.Validation,
-                    "Invalid runtime policy request",
-                    StatusCodes.Status400BadRequest,
-                    detail: "Image digests must be non-empty.");
-            }
-
-            var trimmed = image.Trim();
-            if (!trimmed.Contains(':', StringComparison.Ordinal))
-            {
-                return ProblemResultFactory.Create(
-                    context,
-                    ProblemTypes.Validation,
-                    "Invalid runtime policy request",
-                    StatusCodes.Status400BadRequest,
-                    detail: "Image digests must include an algorithm prefix (e.g. sha256:...).");
-            }
-
-            if (seen.Add(trimmed))
-            {
-                normalizedImages.Add(trimmed);
-            }
-        }
-
-        if (normalizedImages.Count == 0)
-        {
-            return ProblemResultFactory.Create(
-                context,
-                ProblemTypes.Validation,
-                "Invalid runtime policy request",
-                StatusCodes.Status400BadRequest,
-                detail: "images collection must include at least one unique digest.");
-        }
-
-        var namespaceValue = string.IsNullOrWhiteSpace(request.Namespace) ? null : request.Namespace.Trim();
-        var normalizedLabels = new Dictionary<string, string>(StringComparer.Ordinal);
-        if (request.Labels is not null)
-        {
-            foreach (var pair in request.Labels)
-            {
-                if (string.IsNullOrWhiteSpace(pair.Key))
-                {
-                    continue;
-                }
-
-                var key = pair.Key.Trim();
-                var value = pair.Value?.Trim() ?? string.Empty;
-                normalizedLabels[key] = value;
-            }
-        }
-
-        var evaluationRequest = new RuntimePolicyEvaluationRequest(
-            namespaceValue,
-            new ReadOnlyDictionary<string, string>(normalizedLabels),
-            normalizedImages);
-
-        var evaluation = await runtimePolicyService.EvaluateAsync(evaluationRequest, cancellationToken).ConfigureAwait(false);
-
-        var resultPayload = MapRuntimePolicyResponse(evaluation);
-        return Json(resultPayload);
-    }
+        var payload = PolicyDtoMapper.ToDto(response);
+        return Json(payload);
+    }
+
+    private static async Task<IResult> HandleRuntimePolicyAsync(
+        RuntimePolicyRequestDto request,
+        IRuntimePolicyService runtimePolicyService,
+        HttpContext context,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentNullException.ThrowIfNull(runtimePolicyService);
+
+        if (request.Images is null || request.Images.Count == 0)
+        {
+            return ProblemResultFactory.Create(
+                context,
+                ProblemTypes.Validation,
+                "Invalid runtime policy request",
+                StatusCodes.Status400BadRequest,
+                detail: "images collection must include at least one digest.");
+        }
+
+        var normalizedImages = new List<string>();
+        var seen = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var image in request.Images)
+        {
+            if (string.IsNullOrWhiteSpace(image))
+            {
+                return ProblemResultFactory.Create(
+                    context,
+                    ProblemTypes.Validation,
+                    "Invalid runtime policy request",
+                    StatusCodes.Status400BadRequest,
+                    detail: "Image digests must be non-empty.");
+            }
+
+            var trimmed = image.Trim();
+            if (!trimmed.Contains(':', StringComparison.Ordinal))
+            {
+                return ProblemResultFactory.Create(
+                    context,
+                    ProblemTypes.Validation,
+                    "Invalid runtime policy request",
+                    StatusCodes.Status400BadRequest,
+                    detail: "Image digests must include an algorithm prefix (e.g. sha256:...).");
+            }
+
+            if (seen.Add(trimmed))
+            {
+                normalizedImages.Add(trimmed);
+            }
+        }
+
+        if (normalizedImages.Count == 0)
+        {
+            return ProblemResultFactory.Create(
+                context,
+                ProblemTypes.Validation,
+                "Invalid runtime policy request",
+                StatusCodes.Status400BadRequest,
+                detail: "images collection must include at least one unique digest.");
+        }
+
+        var namespaceValue = string.IsNullOrWhiteSpace(request.Namespace) ? null : request.Namespace.Trim();
+        var normalizedLabels = new Dictionary<string, string>(StringComparer.Ordinal);
+        if (request.Labels is not null)
+        {
+            foreach (var pair in request.Labels)
+            {
+                if (string.IsNullOrWhiteSpace(pair.Key))
+                {
+                    continue;
+                }
+
+                var key = pair.Key.Trim();
+                var value = pair.Value?.Trim() ?? string.Empty;
+                normalizedLabels[key] = value;
+            }
+        }
+
+        var evaluationRequest = new RuntimePolicyEvaluationRequest(
+            namespaceValue,
+            new ReadOnlyDictionary<string, string>(normalizedLabels),
+            normalizedImages);
+
+        var evaluation = await runtimePolicyService.EvaluateAsync(evaluationRequest, cancellationToken).ConfigureAwait(false);
+
+        var resultPayload = MapRuntimePolicyResponse(evaluation);
+        return Json(resultPayload);
+    }
 
     private static string NormalizeSegment(string segment)
     {
@@ -273,69 +287,198 @@ internal static class PolicyEndpoints
         return "/" + trimmed;
     }
 
-    private static IResult Json<T>(T value)
-    {
-        var payload = JsonSerializer.Serialize(value, SerializerOptions);
-        return Results.Content(payload, "application/json", Encoding.UTF8);
-    }
-
-    private static RuntimePolicyResponseDto MapRuntimePolicyResponse(RuntimePolicyEvaluationResult evaluation)
-    {
-        var results = new Dictionary<string, RuntimePolicyImageResponseDto>(evaluation.Results.Count, StringComparer.Ordinal);
-        foreach (var pair in evaluation.Results)
-        {
-            var decision = pair.Value;
-            RuntimePolicyRekorDto? rekor = null;
-            if (decision.Rekor is not null)
-            {
-                rekor = new RuntimePolicyRekorDto
-                {
-                    Uuid = decision.Rekor.Uuid,
-                    Url = decision.Rekor.Url,
-                    Verified = decision.Rekor.Verified
-                };
-            }
-
-            string? metadata = null;
-            if (decision.Metadata is not null && decision.Metadata.Count > 0)
-            {
-                metadata = JsonSerializer.Serialize(decision.Metadata, SerializerOptions);
-            }
-
-            results[pair.Key] = new RuntimePolicyImageResponseDto
-            {
-                PolicyVerdict = ToCamelCase(decision.PolicyVerdict),
-                Signed = decision.Signed,
-                HasSbomReferrers = decision.HasSbomReferrers,
-                HasSbomLegacy = decision.HasSbomReferrers,
-                Reasons = decision.Reasons.ToArray(),
-                Rekor = rekor,
-                Confidence = Math.Round(decision.Confidence, 6, MidpointRounding.AwayFromZero),
-                Quieted = decision.Quieted,
-                QuietedBy = decision.QuietedBy,
-                Metadata = metadata,
-                BuildIds = decision.BuildIds is { Count: > 0 } ? decision.BuildIds.ToArray() : null
-            };
-        }
-
-        return new RuntimePolicyResponseDto
-        {
-            TtlSeconds = evaluation.TtlSeconds,
-            ExpiresAtUtc = evaluation.ExpiresAtUtc,
-            PolicyRevision = evaluation.PolicyRevision,
-            Results = results
-        };
-    }
-
-    private static string ToCamelCase(RuntimePolicyVerdict verdict)
-        => verdict switch
-        {
-            RuntimePolicyVerdict.Pass => "pass",
-            RuntimePolicyVerdict.Warn => "warn",
-            RuntimePolicyVerdict.Fail => "fail",
-            RuntimePolicyVerdict.Error => "error",
-            _ => "unknown"
-        };
-}
-
-#pragma warning restore ASPDEPR002
+    private static IResult Json<T>(T value)
+    {
+        var payload = JsonSerializer.Serialize(value, SerializerOptions);
+        return Results.Content(payload, "application/json", Encoding.UTF8);
+    }
+
+    private static RuntimePolicyResponseDto MapRuntimePolicyResponse(RuntimePolicyEvaluationResult evaluation)
+    {
+        var results = new Dictionary<string, RuntimePolicyImageResponseDto>(evaluation.Results.Count, StringComparer.Ordinal);
+        foreach (var pair in evaluation.Results)
+        {
+            var decision = pair.Value;
+            RuntimePolicyRekorDto? rekor = null;
+            if (decision.Rekor is not null)
+            {
+                rekor = new RuntimePolicyRekorDto
+                {
+                    Uuid = decision.Rekor.Uuid,
+                    Url = decision.Rekor.Url,
+                    Verified = decision.Rekor.Verified
+                };
+            }
+
+            string? metadata = null;
+            if (decision.Metadata is not null && decision.Metadata.Count > 0)
+            {
+                metadata = JsonSerializer.Serialize(decision.Metadata, SerializerOptions);
+            }
+
+            results[pair.Key] = new RuntimePolicyImageResponseDto
+            {
+                PolicyVerdict = ToCamelCase(decision.PolicyVerdict),
+                Signed = decision.Signed,
+                HasSbomReferrers = decision.HasSbomReferrers,
+                HasSbomLegacy = decision.HasSbomReferrers,
+                Reasons = decision.Reasons.ToArray(),
+                Rekor = rekor,
+                Confidence = Math.Round(decision.Confidence, 6, MidpointRounding.AwayFromZero),
+                Quieted = decision.Quieted,
+                QuietedBy = decision.QuietedBy,
+                Metadata = metadata,
+                BuildIds = decision.BuildIds is { Count: > 0 } ? decision.BuildIds.ToArray() : null
+            };
+        }
+
+        return new RuntimePolicyResponseDto
+        {
+            TtlSeconds = evaluation.TtlSeconds,
+            ExpiresAtUtc = evaluation.ExpiresAtUtc,
+            PolicyRevision = evaluation.PolicyRevision,
+            Results = results
+        };
+    }
+
+    private static string ToCamelCase(RuntimePolicyVerdict verdict)
+        => verdict switch
+        {
+            RuntimePolicyVerdict.Pass => "pass",
+            RuntimePolicyVerdict.Warn => "warn",
+            RuntimePolicyVerdict.Fail => "fail",
+            RuntimePolicyVerdict.Error => "error",
+            _ => "unknown"
+        };
+
+    private static async Task<IResult> HandlePolicyOverlayAsync(
+        PolicyOverlayRequestDto request,
+        IRuntimePolicyService runtimePolicyService,
+        ISurfaceEnvironment surfaceEnvironment,
+        TimeProvider timeProvider,
+        HttpContext context,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentNullException.ThrowIfNull(runtimePolicyService);
+        ArgumentNullException.ThrowIfNull(surfaceEnvironment);
+        ArgumentNullException.ThrowIfNull(timeProvider);
+
+        if (request.Nodes is null || request.Nodes.Count == 0)
+        {
+            return ProblemResultFactory.Create(
+                context,
+                ProblemTypes.Validation,
+                "Invalid policy overlay request",
+                StatusCodes.Status400BadRequest,
+                detail: "nodes collection must include at least one node.");
+        }
+
+        var tenant = !string.IsNullOrWhiteSpace(request.Tenant)
+            ? request.Tenant.Trim()
+            : surfaceEnvironment.Settings.Tenant;
+
+        var overlayKind = !string.IsNullOrWhiteSpace(request.OverlayKind)
+            ? request.OverlayKind.Trim()
+            : "policy.overlay.v1";
+
+        var imageDigests = request.Nodes
+            .Where(n => !string.IsNullOrWhiteSpace(n.ImageDigest))
+            .Select(n => n.ImageDigest!.Trim())
+            .Distinct(StringComparer.Ordinal)
+            .ToList();
+
+        RuntimePolicyEvaluationResult? evaluation = null;
+        if (imageDigests.Count > 0)
+        {
+            var evalRequest = new RuntimePolicyEvaluationRequest(
+                null,
+                new ReadOnlyDictionary<string, string>(new Dictionary<string, string>(StringComparer.Ordinal)),
+                imageDigests);
+            evaluation = await runtimePolicyService.EvaluateAsync(evalRequest, cancellationToken).ConfigureAwait(false);
+        }
+
+        var overlays = new List<PolicyOverlayDto>(request.Nodes.Count);
+        foreach (var node in request.Nodes)
+        {
+            if (string.IsNullOrWhiteSpace(node.NodeId))
+            {
+                continue;
+            }
+
+            var nodeId = node.NodeId.Trim();
+            var overlayId = ComputeOverlayId(tenant, nodeId, overlayKind);
+
+            string verdict = "unknown";
+            IReadOnlyList<string> reasons = Array.Empty<string>();
+            double? confidence = null;
+            bool? quieted = null;
+            PolicyOverlayEvidenceDto? evidence = null;
+
+            if (!string.IsNullOrWhiteSpace(node.ImageDigest) &&
+                evaluation?.Results.TryGetValue(node.ImageDigest.Trim(), out var decision) == true)
+            {
+                verdict = ToCamelCase(decision.PolicyVerdict);
+                reasons = decision.Reasons.ToArray();
+                confidence = Math.Round(decision.Confidence, 6, MidpointRounding.AwayFromZero);
+                quieted = decision.Quieted;
+
+                if (request.IncludeEvidence)
+                {
+                    RuntimePolicyRekorDto? rekor = null;
+                    if (decision.Rekor is not null)
+                    {
+                        rekor = new RuntimePolicyRekorDto
+                        {
+                            Uuid = decision.Rekor.Uuid,
+                            Url = decision.Rekor.Url,
+                            Verified = decision.Rekor.Verified
+                        };
+                    }
+
+                    evidence = new PolicyOverlayEvidenceDto
+                    {
+                        Signed = decision.Signed,
+                        HasSbomReferrers = decision.HasSbomReferrers,
+                        Rekor = rekor,
+                        BuildIds = decision.BuildIds is { Count: > 0 } ? decision.BuildIds.ToArray() : null,
+                        Metadata = decision.Metadata is { Count: > 0 }
+                            ? new ReadOnlyDictionary<string, string>(decision.Metadata.ToDictionary(kv => kv.Key, kv => kv.Value, StringComparer.Ordinal))
+                            : null
+                    };
+                }
+            }
+
+            overlays.Add(new PolicyOverlayDto
+            {
+                OverlayId = overlayId,
+                NodeId = nodeId,
+                OverlayKind = overlayKind,
+                Verdict = verdict,
+                Reasons = reasons,
+                Confidence = confidence,
+                Quieted = quieted,
+                Evidence = evidence
+            });
+        }
+
+        var response = new PolicyOverlayResponseDto
+        {
+            Tenant = tenant,
+            GeneratedAt = timeProvider.GetUtcNow(),
+            PolicyRevision = evaluation?.PolicyRevision,
+            Overlays = overlays.OrderBy(o => o.NodeId, StringComparer.Ordinal).ToArray()
+        };
+
+        return Json(response);
+    }
+
+    private static string ComputeOverlayId(string tenant, string nodeId, string overlayKind)
+    {
+        var input = $"{tenant}|{nodeId}|{overlayKind}";
+        var hash = SHA256.HashData(Encoding.UTF8.GetBytes(input));
+        return $"sha256:{Convert.ToHexString(hash).ToLowerInvariant()}";
+    }
+}
+
+#pragma warning restore ASPDEPR002