git.stella-ops.org/src/Scanner/StellaOps.Scanner.Worker/Orchestration/PoEOrchestrator.cs

// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.

using Microsoft.Extensions.Logging;
using StellaOps.Attestor;
using StellaOps.Scanner.Core.Configuration;
using StellaOps.Scanner.Reachability;
using StellaOps.Signals.Storage;

namespace StellaOps.Scanner.Worker.Orchestration;

/// <summary>
/// Orchestrates Proof of Exposure (PoE) generation and storage during scan workflow.
/// Integrates with ScanOrchestrator to emit PoE artifacts for reachable vulnerabilities.
/// </summary>
public class PoEOrchestrator
{
    private readonly IReachabilityResolver _resolver;
    private readonly IProofEmitter _emitter;
    private readonly IPoECasStore _casStore;
    private readonly ILogger<PoEOrchestrator> _logger;

    public PoEOrchestrator(
        IReachabilityResolver resolver,
        IProofEmitter emitter,
        IPoECasStore casStore,
        ILogger<PoEOrchestrator> logger)
    {
        _resolver = resolver ?? throw new ArgumentNullException(nameof(resolver));
        _emitter = emitter ?? throw new ArgumentNullException(nameof(emitter));
        _casStore = casStore ?? throw new ArgumentNullException(nameof(casStore));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    /// <summary>
    /// Generate PoE artifacts for all reachable vulnerabilities in a scan.
    /// Called after richgraph-v1 emission, before SBOM finalization.
    /// </summary>
    /// <param name="context">Scan context with graph hash, build ID, image digest</param>
    /// <param name="vulnerabilities">Vulnerabilities detected in scan</param>
    /// <param name="configuration">PoE configuration</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>List of generated PoE hashes</returns>
    public async Task<IReadOnlyList<PoEResult>> GeneratePoEArtifactsAsync(
        PoEScanContext context,
        IReadOnlyList<VulnerabilityMatch> vulnerabilities,
        PoEConfiguration configuration,
        CancellationToken cancellationToken = default)
    {
        if (!configuration.Enabled)
        {
            _logger.LogDebug("PoE generation disabled, skipping");
            return Array.Empty<PoEResult>();
        }

        _logger.LogInformation(
            "Generating PoE artifacts for {Count} vulnerabilities (scan: {ScanId}, image: {ImageDigest})",
            vulnerabilities.Count, context.ScanId, context.ImageDigest);

        var results = new List<PoEResult>();

        // Filter to reachable vulnerabilities if configured
        var targetVulns = configuration.EmitOnlyReachable
            ? vulnerabilities.Where(v => v.IsReachable).ToList()
            : vulnerabilities.ToList();

        if (targetVulns.Count == 0)
        {
            _logger.LogInformation("No reachable vulnerabilities found, skipping PoE generation");
            return results;
        }

        _logger.LogInformation(
            "Emitting PoE for {Count} {Type} vulnerabilities",
            targetVulns.Count,
            configuration.EmitOnlyReachable ? "reachable" : "total");

        // Create resolution requests
        var requests = targetVulns.Select(v => new ReachabilityResolutionRequest(
            GraphHash: context.GraphHash,
            BuildId: context.BuildId,
            ComponentRef: v.ComponentRef,
            VulnId: v.VulnId,
            PolicyDigest: context.PolicyDigest,
            Options: CreateResolverOptions(configuration)
        )).ToList();

        // Batch resolve subgraphs
        var subgraphs = await _resolver.ResolveBatchAsync(requests, cancellationToken);

        // Generate PoE artifacts
        foreach (var (vulnId, subgraph) in subgraphs)
        {
            if (subgraph == null)
            {
                _logger.LogDebug("Skipping PoE for {VulnId}: no reachable paths", vulnId);
                continue;
            }

            try
            {
                var poeResult = await GenerateSinglePoEAsync(
                    subgraph,
                    context,
                    configuration,
                    cancellationToken);

                results.Add(poeResult);

                _logger.LogInformation(
                    "Generated PoE for {VulnId}: {Hash} (signed: {IsSigned})",
                    vulnId, poeResult.PoEHash, poeResult.IsSigned);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to generate PoE for {VulnId}", vulnId);
                // Continue with other vulnerabilities
            }
        }

        _logger.LogInformation(
            "PoE generation complete: {SuccessCount}/{TotalCount} artifacts",
            results.Count, targetVulns.Count);

        return results;
    }

    /// <summary>
    /// Generate a single PoE artifact for a subgraph.
    /// </summary>
    private async Task<PoEResult> GenerateSinglePoEAsync(
        PoESubgraph subgraph,
        PoEScanContext context,
        PoEConfiguration configuration,
        CancellationToken cancellationToken)
    {
        // Build metadata
        var metadata = new ProofMetadata(
            GeneratedAt: DateTime.UtcNow,
            Analyzer: new AnalyzerInfo(
                Name: "stellaops-scanner",
                Version: context.ScannerVersion,
                ToolchainDigest: subgraph.ToolchainDigest
            ),
            Policy: new PolicyInfo(
                PolicyId: context.PolicyId,
                PolicyDigest: context.PolicyDigest,
                EvaluatedAt: DateTime.UtcNow
            ),
            ReproSteps: GenerateReproSteps(context, subgraph)
        );

        // Generate canonical PoE JSON
        var poeBytes = await _emitter.EmitPoEAsync(
            subgraph,
            metadata,
            context.GraphHash,
            context.ImageDigest,
            evidenceRefs: null,
            options: null,
            cancellationToken: cancellationToken);

        // Compute PoE hash
        var poeHash = _emitter.ComputePoEHash(poeBytes);

        // Sign with DSSE
        var dsseBytes = await _emitter.SignPoEAsync(
            poeBytes,
            configuration.SigningKeyId,
            cancellationToken);

        // Store in CAS
        var poeRef = await _casStore.StoreAsync(poeBytes, dsseBytes, cancellationToken);

        return new PoEResult(
            VulnId: subgraph.VulnId,
            ComponentRef: subgraph.ComponentRef,
            PoEHash: poeHash,
            PoERef: poeRef,
            IsSigned: dsseBytes != null && dsseBytes.Length > 0,
            PathCount: subgraph.Edges.Count
        );
    }

    private ResolverOptions CreateResolverOptions(PoEConfiguration config)
    {
        var strategy = config.PruneStrategy.ToLowerInvariant() switch
        {
            "shortestwithconfidence" => PathPruneStrategy.ShortestWithConfidence,
            "shortestonly" => PathPruneStrategy.ShortestOnly,
            "confidencefirst" => PathPruneStrategy.ConfidenceFirst,
            "runtimefirst" => PathPruneStrategy.RuntimeFirst,
            _ => PathPruneStrategy.ShortestWithConfidence
        };

        return new ResolverOptions(
            MaxDepth: config.MaxDepth,
            MaxPaths: config.MaxPaths,
            IncludeGuards: config.IncludeGuards,
            RequireRuntimeConfirmation: config.RequireRuntimeConfirmation,
            PruneStrategy: strategy
        );
    }

    private string[] GenerateReproSteps(PoEScanContext context, PoESubgraph subgraph)
    {
        return new[]
        {
            $"1. Build container image: {context.ImageDigest}",
            $"2. Run scanner: stella scan --image {context.ImageDigest} --config {context.ConfigPath ?? "etc/scanner.yaml"}",
            $"3. Extract reachability graph and resolve paths",
            $"4. Resolve {subgraph.VulnId} → {subgraph.ComponentRef} to vulnerable symbols",
            $"5. Compute paths from {subgraph.EntryRefs.Length} entry points to {subgraph.SinkRefs.Length} sinks"
        };
    }
}