up

2025-11-28 09:40:40 +02:00
parent 1c6730a1d2
commit 05da719048
206 changed files with 34741 additions and 1751 deletions
--- a/src/Cli/StellaOps.Cli/Services/BackendOperationsClient.cs
+++ b/src/Cli/StellaOps.Cli/Services/BackendOperationsClient.cs
@@ -18,10 +18,10 @@ using Microsoft.Extensions.Logging;
 using StellaOps.Auth.Abstractions;
 using StellaOps.Auth.Client;
 using StellaOps.Cli.Configuration;
-using StellaOps.Cli.Services.Models;
-using StellaOps.Cli.Services.Models.AdvisoryAi;
-using StellaOps.Cli.Services.Models.Ruby;
-using StellaOps.Cli.Services.Models.Transport;
+using StellaOps.Cli.Services.Models;
+using StellaOps.Cli.Services.Models.AdvisoryAi;
+using StellaOps.Cli.Services.Models.Ruby;
+using StellaOps.Cli.Services.Models.Transport;

 namespace StellaOps.Cli.Services;

@@ -32,12 +32,12 @@ internal sealed class BackendOperationsClient : IBackendOperationsClient
    private static readonly IReadOnlyDictionary<string, object?> EmptyMetadata =
        new ReadOnlyDictionary<string, object?>(new Dictionary<string, object?>(0, StringComparer.OrdinalIgnoreCase));

-    private const string OperatorReasonParameterName = "operator_reason";
-    private const string OperatorTicketParameterName = "operator_ticket";
-    private const string BackfillReasonParameterName = "backfill_reason";
-    private const string BackfillTicketParameterName = "backfill_ticket";
-    private const string AdvisoryScopesHeader = "X-StellaOps-Scopes";
-    private const string AdvisoryRunScope = "advisory:run";
+    private const string OperatorReasonParameterName = "operator_reason";
+    private const string OperatorTicketParameterName = "operator_ticket";
+    private const string BackfillReasonParameterName = "backfill_reason";
+    private const string BackfillTicketParameterName = "backfill_ticket";
+    private const string AdvisoryScopesHeader = "X-StellaOps-Scopes";
+    private const string AdvisoryRunScope = "advisory:run";

    private readonly HttpClient _httpClient;
    private readonly StellaOpsCliOptions _options;
@@ -859,9 +859,9 @@ internal sealed class BackendOperationsClient : IBackendOperationsClient
        return MapPolicyFindingExplain(document);
    }

-    public async Task<EntryTraceResponseModel?> GetEntryTraceAsync(string scanId, CancellationToken cancellationToken)
-    {
-        EnsureBackendConfigured();
+    public async Task<EntryTraceResponseModel?> GetEntryTraceAsync(string scanId, CancellationToken cancellationToken)
+    {
+        EnsureBackendConfigured();

        if (string.IsNullOrWhiteSpace(scanId))
        {
@@ -883,174 +883,174 @@ internal sealed class BackendOperationsClient : IBackendOperationsClient
            throw new InvalidOperationException(failure);
        }

-        var result = await response.Content.ReadFromJsonAsync<EntryTraceResponseModel>(SerializerOptions, cancellationToken).ConfigureAwait(false);
-        if (result is null)
-        {
-            throw new InvalidOperationException("EntryTrace response payload was empty.");
-        }
-
-        return result;
-    }
-
-    public async Task<RubyPackageInventoryModel?> GetRubyPackagesAsync(string scanId, CancellationToken cancellationToken)
-    {
-        EnsureBackendConfigured();
-
-        if (string.IsNullOrWhiteSpace(scanId))
-        {
-            throw new ArgumentException("Scan identifier is required.", nameof(scanId));
-        }
-
-        var encodedScanId = Uri.EscapeDataString(scanId);
-        using var request = CreateRequest(HttpMethod.Get, $"api/scans/{encodedScanId}/ruby-packages");
-        await AuthorizeRequestAsync(request, cancellationToken).ConfigureAwait(false);
-
-        using var response = await _httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
-        if (response.StatusCode == HttpStatusCode.NotFound)
-        {
-            return null;
-        }
-
-        if (!response.IsSuccessStatusCode)
-        {
-            var failure = await CreateFailureMessageAsync(response, cancellationToken).ConfigureAwait(false);
-            throw new InvalidOperationException(failure);
-        }
-
-        var inventory = await response.Content
-            .ReadFromJsonAsync<RubyPackageInventoryModel>(SerializerOptions, cancellationToken)
-            .ConfigureAwait(false);
-
-        if (inventory is null)
-        {
-            throw new InvalidOperationException("Ruby package response payload was empty.");
-        }
-
-        var normalizedScanId = string.IsNullOrWhiteSpace(inventory.ScanId) ? scanId : inventory.ScanId;
-        var normalizedDigest = inventory.ImageDigest ?? string.Empty;
-        var packages = inventory.Packages ?? Array.Empty<RubyPackageArtifactModel>();
-
-        return inventory with
-        {
-            ScanId = normalizedScanId,
-            ImageDigest = normalizedDigest,
-            Packages = packages
-        };
-    }
-
-    public async Task<AdvisoryPipelinePlanResponseModel> CreateAdvisoryPipelinePlanAsync(
-        AdvisoryAiTaskType taskType,
-        AdvisoryPipelinePlanRequestModel request,
-        CancellationToken cancellationToken)
-    {
-        ArgumentNullException.ThrowIfNull(request);
-
-        var taskSegment = taskType.ToString().ToLowerInvariant();
-        var relative = $"v1/advisory-ai/pipeline/{taskSegment}";
-
-        var payload = new AdvisoryPipelinePlanRequestModel
-        {
-            TaskType = taskType,
-            AdvisoryKey = string.IsNullOrWhiteSpace(request.AdvisoryKey) ? string.Empty : request.AdvisoryKey.Trim(),
-            ArtifactId = string.IsNullOrWhiteSpace(request.ArtifactId) ? null : request.ArtifactId!.Trim(),
-            ArtifactPurl = string.IsNullOrWhiteSpace(request.ArtifactPurl) ? null : request.ArtifactPurl!.Trim(),
-            PolicyVersion = string.IsNullOrWhiteSpace(request.PolicyVersion) ? null : request.PolicyVersion!.Trim(),
-            Profile = string.IsNullOrWhiteSpace(request.Profile) ? "default" : request.Profile!.Trim(),
-            PreferredSections = request.PreferredSections is null
-                ? null
-                : request.PreferredSections
-                    .Where(static section => !string.IsNullOrWhiteSpace(section))
-                    .Select(static section => section.Trim())
-                    .ToArray(),
-            ForceRefresh = request.ForceRefresh
-        };
-
-        using var httpRequest = CreateRequest(HttpMethod.Post, relative);
-        ApplyAdvisoryAiEndpoint(httpRequest, taskType);
-        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
-        httpRequest.Content = JsonContent.Create(payload, options: SerializerOptions);
-
-        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
-        if (!response.IsSuccessStatusCode)
-        {
-            var failure = await CreateFailureMessageAsync(response, cancellationToken).ConfigureAwait(false);
-            throw new InvalidOperationException(failure);
-        }
-
-        try
-        {
-            var plan = await response.Content.ReadFromJsonAsync<AdvisoryPipelinePlanResponseModel>(SerializerOptions, cancellationToken).ConfigureAwait(false);
-            if (plan is null)
-            {
-                throw new InvalidOperationException("Advisory AI plan response was empty.");
-            }
-
-            return plan;
-        }
-        catch (JsonException ex)
-        {
-            var raw = response.Content is null
-                ? string.Empty
-                : await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
-            throw new InvalidOperationException($"Failed to parse advisory plan response. {ex.Message}", ex)
-            {
-                Data = { ["payload"] = raw }
-            };
-        }
-    }
-
-    public async Task<AdvisoryPipelineOutputModel?> TryGetAdvisoryPipelineOutputAsync(
-        string cacheKey,
-        AdvisoryAiTaskType taskType,
-        string profile,
-        CancellationToken cancellationToken)
-    {
-        if (string.IsNullOrWhiteSpace(cacheKey))
-        {
-            throw new ArgumentException("Cache key is required.", nameof(cacheKey));
-        }
-
-        var encodedKey = Uri.EscapeDataString(cacheKey);
-        var taskSegment = Uri.EscapeDataString(taskType.ToString().ToLowerInvariant());
-        var resolvedProfile = string.IsNullOrWhiteSpace(profile) ? "default" : profile.Trim();
-        var relative = $"v1/advisory-ai/outputs/{encodedKey}?taskType={taskSegment}&profile={Uri.EscapeDataString(resolvedProfile)}";
-
-        using var request = CreateRequest(HttpMethod.Get, relative);
-        ApplyAdvisoryAiEndpoint(request, taskType);
-        await AuthorizeRequestAsync(request, cancellationToken).ConfigureAwait(false);
-
-        using var response = await _httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
-        if (response.StatusCode == HttpStatusCode.NotFound)
-        {
-            return null;
-        }
-
-        if (!response.IsSuccessStatusCode)
-        {
-            var failure = await CreateFailureMessageAsync(response, cancellationToken).ConfigureAwait(false);
-            throw new InvalidOperationException(failure);
-        }
-
-        try
-        {
-            return await response.Content.ReadFromJsonAsync<AdvisoryPipelineOutputModel>(SerializerOptions, cancellationToken).ConfigureAwait(false);
-        }
-        catch (JsonException ex)
-        {
-            var raw = response.Content is null
-                ? string.Empty
-                : await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
-            throw new InvalidOperationException($"Failed to parse advisory output response. {ex.Message}", ex)
-            {
-                Data = { ["payload"] = raw }
-            };
-        }
-    }
-
-    public async Task<IReadOnlyList<ExcititorProviderSummary>> GetExcititorProvidersAsync(bool includeDisabled, CancellationToken cancellationToken)
-    {
-        EnsureBackendConfigured();
-
+        var result = await response.Content.ReadFromJsonAsync<EntryTraceResponseModel>(SerializerOptions, cancellationToken).ConfigureAwait(false);
+        if (result is null)
+        {
+            throw new InvalidOperationException("EntryTrace response payload was empty.");
+        }
+
+        return result;
+    }
+
+    public async Task<RubyPackageInventoryModel?> GetRubyPackagesAsync(string scanId, CancellationToken cancellationToken)
+    {
+        EnsureBackendConfigured();
+
+        if (string.IsNullOrWhiteSpace(scanId))
+        {
+            throw new ArgumentException("Scan identifier is required.", nameof(scanId));
+        }
+
+        var encodedScanId = Uri.EscapeDataString(scanId);
+        using var request = CreateRequest(HttpMethod.Get, $"api/scans/{encodedScanId}/ruby-packages");
+        await AuthorizeRequestAsync(request, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
+        if (response.StatusCode == HttpStatusCode.NotFound)
+        {
+            return null;
+        }
+
+        if (!response.IsSuccessStatusCode)
+        {
+            var failure = await CreateFailureMessageAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException(failure);
+        }
+
+        var inventory = await response.Content
+            .ReadFromJsonAsync<RubyPackageInventoryModel>(SerializerOptions, cancellationToken)
+            .ConfigureAwait(false);
+
+        if (inventory is null)
+        {
+            throw new InvalidOperationException("Ruby package response payload was empty.");
+        }
+
+        var normalizedScanId = string.IsNullOrWhiteSpace(inventory.ScanId) ? scanId : inventory.ScanId;
+        var normalizedDigest = inventory.ImageDigest ?? string.Empty;
+        var packages = inventory.Packages ?? Array.Empty<RubyPackageArtifactModel>();
+
+        return inventory with
+        {
+            ScanId = normalizedScanId,
+            ImageDigest = normalizedDigest,
+            Packages = packages
+        };
+    }
+
+    public async Task<AdvisoryPipelinePlanResponseModel> CreateAdvisoryPipelinePlanAsync(
+        AdvisoryAiTaskType taskType,
+        AdvisoryPipelinePlanRequestModel request,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        var taskSegment = taskType.ToString().ToLowerInvariant();
+        var relative = $"v1/advisory-ai/pipeline/{taskSegment}";
+
+        var payload = new AdvisoryPipelinePlanRequestModel
+        {
+            TaskType = taskType,
+            AdvisoryKey = string.IsNullOrWhiteSpace(request.AdvisoryKey) ? string.Empty : request.AdvisoryKey.Trim(),
+            ArtifactId = string.IsNullOrWhiteSpace(request.ArtifactId) ? null : request.ArtifactId!.Trim(),
+            ArtifactPurl = string.IsNullOrWhiteSpace(request.ArtifactPurl) ? null : request.ArtifactPurl!.Trim(),
+            PolicyVersion = string.IsNullOrWhiteSpace(request.PolicyVersion) ? null : request.PolicyVersion!.Trim(),
+            Profile = string.IsNullOrWhiteSpace(request.Profile) ? "default" : request.Profile!.Trim(),
+            PreferredSections = request.PreferredSections is null
+                ? null
+                : request.PreferredSections
+                    .Where(static section => !string.IsNullOrWhiteSpace(section))
+                    .Select(static section => section.Trim())
+                    .ToArray(),
+            ForceRefresh = request.ForceRefresh
+        };
+
+        using var httpRequest = CreateRequest(HttpMethod.Post, relative);
+        ApplyAdvisoryAiEndpoint(httpRequest, taskType);
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        httpRequest.Content = JsonContent.Create(payload, options: SerializerOptions);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var failure = await CreateFailureMessageAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException(failure);
+        }
+
+        try
+        {
+            var plan = await response.Content.ReadFromJsonAsync<AdvisoryPipelinePlanResponseModel>(SerializerOptions, cancellationToken).ConfigureAwait(false);
+            if (plan is null)
+            {
+                throw new InvalidOperationException("Advisory AI plan response was empty.");
+            }
+
+            return plan;
+        }
+        catch (JsonException ex)
+        {
+            var raw = response.Content is null
+                ? string.Empty
+                : await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to parse advisory plan response. {ex.Message}", ex)
+            {
+                Data = { ["payload"] = raw }
+            };
+        }
+    }
+
+    public async Task<AdvisoryPipelineOutputModel?> TryGetAdvisoryPipelineOutputAsync(
+        string cacheKey,
+        AdvisoryAiTaskType taskType,
+        string profile,
+        CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(cacheKey))
+        {
+            throw new ArgumentException("Cache key is required.", nameof(cacheKey));
+        }
+
+        var encodedKey = Uri.EscapeDataString(cacheKey);
+        var taskSegment = Uri.EscapeDataString(taskType.ToString().ToLowerInvariant());
+        var resolvedProfile = string.IsNullOrWhiteSpace(profile) ? "default" : profile.Trim();
+        var relative = $"v1/advisory-ai/outputs/{encodedKey}?taskType={taskSegment}&profile={Uri.EscapeDataString(resolvedProfile)}";
+
+        using var request = CreateRequest(HttpMethod.Get, relative);
+        ApplyAdvisoryAiEndpoint(request, taskType);
+        await AuthorizeRequestAsync(request, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
+        if (response.StatusCode == HttpStatusCode.NotFound)
+        {
+            return null;
+        }
+
+        if (!response.IsSuccessStatusCode)
+        {
+            var failure = await CreateFailureMessageAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException(failure);
+        }
+
+        try
+        {
+            return await response.Content.ReadFromJsonAsync<AdvisoryPipelineOutputModel>(SerializerOptions, cancellationToken).ConfigureAwait(false);
+        }
+        catch (JsonException ex)
+        {
+            var raw = response.Content is null
+                ? string.Empty
+                : await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to parse advisory output response. {ex.Message}", ex)
+            {
+                Data = { ["payload"] = raw }
+            };
+        }
+    }
+
+    public async Task<IReadOnlyList<ExcititorProviderSummary>> GetExcititorProvidersAsync(bool includeDisabled, CancellationToken cancellationToken)
+    {
+        EnsureBackendConfigured();
+
        var query = includeDisabled ? "?includeDisabled=true" : string.Empty;
        using var request = CreateRequest(HttpMethod.Get, $"excititor/providers{query}");
        await AuthorizeRequestAsync(request, cancellationToken).ConfigureAwait(false);
@@ -1937,44 +1937,44 @@ internal sealed class BackendOperationsClient : IBackendOperationsClient
        return string.IsNullOrWhiteSpace(value) ? null : value.Trim();
    }

-    private void ApplyAdvisoryAiEndpoint(HttpRequestMessage request, AdvisoryAiTaskType taskType)
-    {
-        if (request is null)
-        {
-            throw new ArgumentNullException(nameof(request));
-        }
-
-        var requestUri = request.RequestUri ?? throw new InvalidOperationException("Request URI was not initialized.");
-
-        if (!string.IsNullOrWhiteSpace(_options.AdvisoryAiUrl) &&
-            Uri.TryCreate(_options.AdvisoryAiUrl, UriKind.Absolute, out var advisoryBase))
-        {
-            if (!requestUri.IsAbsoluteUri)
-            {
-                request.RequestUri = new Uri(advisoryBase, requestUri.ToString());
-            }
-        }
-        else if (!string.IsNullOrWhiteSpace(_options.AdvisoryAiUrl))
-        {
-            throw new InvalidOperationException($"Advisory AI URL '{_options.AdvisoryAiUrl}' is not a valid absolute URI.");
-        }
-        else
-        {
-            EnsureBackendConfigured();
-        }
-
-        var taskScope = $"advisory:{taskType.ToString().ToLowerInvariant()}";
-        var combined = $"{AdvisoryRunScope} {taskScope}";
-
-        if (request.Headers.Contains(AdvisoryScopesHeader))
-        {
-            request.Headers.Remove(AdvisoryScopesHeader);
-        }
-
-        request.Headers.TryAddWithoutValidation(AdvisoryScopesHeader, combined);
-    }
-
-    private HttpRequestMessage CreateRequest(HttpMethod method, string relativeUri)
+    private void ApplyAdvisoryAiEndpoint(HttpRequestMessage request, AdvisoryAiTaskType taskType)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        var requestUri = request.RequestUri ?? throw new InvalidOperationException("Request URI was not initialized.");
+
+        if (!string.IsNullOrWhiteSpace(_options.AdvisoryAiUrl) &&
+            Uri.TryCreate(_options.AdvisoryAiUrl, UriKind.Absolute, out var advisoryBase))
+        {
+            if (!requestUri.IsAbsoluteUri)
+            {
+                request.RequestUri = new Uri(advisoryBase, requestUri.ToString());
+            }
+        }
+        else if (!string.IsNullOrWhiteSpace(_options.AdvisoryAiUrl))
+        {
+            throw new InvalidOperationException($"Advisory AI URL '{_options.AdvisoryAiUrl}' is not a valid absolute URI.");
+        }
+        else
+        {
+            EnsureBackendConfigured();
+        }
+
+        var taskScope = $"advisory:{taskType.ToString().ToLowerInvariant()}";
+        var combined = $"{AdvisoryRunScope} {taskScope}";
+
+        if (request.Headers.Contains(AdvisoryScopesHeader))
+        {
+            request.Headers.Remove(AdvisoryScopesHeader);
+        }
+
+        request.Headers.TryAddWithoutValidation(AdvisoryScopesHeader, combined);
+    }
+
+    private HttpRequestMessage CreateRequest(HttpMethod method, string relativeUri)
    {
        if (!Uri.TryCreate(relativeUri, UriKind.RelativeOrAbsolute, out var requestUri))
        {
@@ -2857,4 +2857,469 @@ internal sealed class BackendOperationsClient : IBackendOperationsClient
        var fallbackSeconds = Math.Min(60, Math.Pow(2, attempt));
        return TimeSpan.FromSeconds(fallbackSeconds);
    }
+
+    // CLI-VEX-30-001: VEX consensus list
+    public async Task<VexConsensusListResponse> ListVexConsensusAsync(VexConsensusListRequest request, string? tenant, CancellationToken cancellationToken)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        EnsureBackendConfigured();
+
+        var queryParams = new List<string>();
+        if (!string.IsNullOrWhiteSpace(request.VulnerabilityId))
+            queryParams.Add($"vulnerabilityId={Uri.EscapeDataString(request.VulnerabilityId)}");
+        if (!string.IsNullOrWhiteSpace(request.ProductKey))
+            queryParams.Add($"productKey={Uri.EscapeDataString(request.ProductKey)}");
+        if (!string.IsNullOrWhiteSpace(request.Purl))
+            queryParams.Add($"purl={Uri.EscapeDataString(request.Purl)}");
+        if (!string.IsNullOrWhiteSpace(request.Status))
+            queryParams.Add($"status={Uri.EscapeDataString(request.Status)}");
+        if (!string.IsNullOrWhiteSpace(request.PolicyVersion))
+            queryParams.Add($"policyVersion={Uri.EscapeDataString(request.PolicyVersion)}");
+        if (request.Limit.HasValue)
+            queryParams.Add($"limit={request.Limit.Value}");
+        if (request.Offset.HasValue)
+            queryParams.Add($"offset={request.Offset.Value}");
+
+        var queryString = queryParams.Count > 0 ? "?" + string.Join("&", queryParams) : string.Empty;
+        var relative = $"api/vex/consensus{queryString}";
+
+        using var httpRequest = CreateRequest(HttpMethod.Get, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"VEX consensus list failed: {message}");
+        }
+
+        VexConsensusListResponse? result;
+        try
+        {
+            result = await response.Content.ReadFromJsonAsync<VexConsensusListResponse>(SerializerOptions, cancellationToken).ConfigureAwait(false);
+        }
+        catch (JsonException ex)
+        {
+            var raw = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to parse VEX consensus list response: {ex.Message}", ex)
+            {
+                Data = { ["payload"] = raw }
+            };
+        }
+
+        if (result is null)
+        {
+            throw new InvalidOperationException("VEX consensus list response was empty.");
+        }
+
+        return result;
+    }
+
+    // CLI-VEX-30-002: VEX consensus detail
+    public async Task<VexConsensusDetailResponse?> GetVexConsensusAsync(string vulnerabilityId, string productKey, string? tenant, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(vulnerabilityId))
+        {
+            throw new ArgumentException("Vulnerability ID must be provided.", nameof(vulnerabilityId));
+        }
+
+        if (string.IsNullOrWhiteSpace(productKey))
+        {
+            throw new ArgumentException("Product key must be provided.", nameof(productKey));
+        }
+
+        EnsureBackendConfigured();
+
+        var encodedVulnId = Uri.EscapeDataString(vulnerabilityId.Trim());
+        var encodedProductKey = Uri.EscapeDataString(productKey.Trim());
+        var relative = $"api/vex/consensus/{encodedVulnId}/{encodedProductKey}";
+
+        using var httpRequest = CreateRequest(HttpMethod.Get, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (response.StatusCode == HttpStatusCode.NotFound)
+        {
+            return null;
+        }
+
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"VEX consensus get failed: {message}");
+        }
+
+        VexConsensusDetailResponse? result;
+        try
+        {
+            result = await response.Content.ReadFromJsonAsync<VexConsensusDetailResponse>(SerializerOptions, cancellationToken).ConfigureAwait(false);
+        }
+        catch (JsonException ex)
+        {
+            var raw = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to parse VEX consensus detail response: {ex.Message}", ex)
+            {
+                Data = { ["payload"] = raw }
+            };
+        }
+
+        return result;
+    }
+
+    // CLI-VEX-30-003: VEX simulation
+    public async Task<VexSimulationResponse> SimulateVexConsensusAsync(VexSimulationRequest request, string? tenant, CancellationToken cancellationToken)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        EnsureBackendConfigured();
+
+        var relative = "api/vex/consensus/simulate";
+
+        using var httpRequest = CreateRequest(HttpMethod.Post, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        var jsonContent = JsonSerializer.Serialize(request, SerializerOptions);
+        httpRequest.Content = new StringContent(jsonContent, Encoding.UTF8, "application/json");
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"VEX consensus simulation failed: {message}");
+        }
+
+        VexSimulationResponse? result;
+        try
+        {
+            result = await response.Content.ReadFromJsonAsync<VexSimulationResponse>(SerializerOptions, cancellationToken).ConfigureAwait(false);
+        }
+        catch (JsonException ex)
+        {
+            var raw = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to parse VEX simulation response: {ex.Message}", ex)
+            {
+                Data = { ["payload"] = raw }
+            };
+        }
+
+        if (result is null)
+        {
+            throw new InvalidOperationException("VEX simulation response was empty.");
+        }
+
+        return result;
+    }
+
+    // CLI-VEX-30-004: VEX export
+    public async Task<VexExportResponse> ExportVexConsensusAsync(VexExportRequest request, string? tenant, CancellationToken cancellationToken)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        EnsureBackendConfigured();
+
+        var relative = "api/vex/consensus/export";
+
+        using var httpRequest = CreateRequest(HttpMethod.Post, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        var jsonContent = JsonSerializer.Serialize(request, SerializerOptions);
+        httpRequest.Content = new StringContent(jsonContent, Encoding.UTF8, "application/json");
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"VEX consensus export failed: {message}");
+        }
+
+        VexExportResponse? result;
+        try
+        {
+            result = await response.Content.ReadFromJsonAsync<VexExportResponse>(SerializerOptions, cancellationToken).ConfigureAwait(false);
+        }
+        catch (JsonException ex)
+        {
+            var raw = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to parse VEX export response: {ex.Message}", ex)
+            {
+                Data = { ["payload"] = raw }
+            };
+        }
+
+        if (result is null)
+        {
+            throw new InvalidOperationException("VEX export response was empty.");
+        }
+
+        return result;
+    }
+
+    public async Task<Stream> DownloadVexExportAsync(string exportId, string? tenant, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(exportId))
+        {
+            throw new ArgumentException("Export ID must be provided.", nameof(exportId));
+        }
+
+        EnsureBackendConfigured();
+
+        var encodedExportId = Uri.EscapeDataString(exportId.Trim());
+        var relative = $"api/vex/consensus/export/{encodedExportId}/download";
+
+        using var httpRequest = CreateRequest(HttpMethod.Get, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        var response = await _httpClient.SendAsync(httpRequest, HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"VEX export download failed: {message}");
+        }
+
+        return await response.Content.ReadAsStreamAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    // CLI-VULN-29-001: Vulnerability explorer list
+    public async Task<VulnListResponse> ListVulnerabilitiesAsync(VulnListRequest request, string? tenant, CancellationToken cancellationToken)
+    {
+        EnsureBackendConfigured();
+
+        var queryParams = new List<string>();
+        if (!string.IsNullOrWhiteSpace(request.VulnerabilityId))
+            queryParams.Add($"vulnerabilityId={Uri.EscapeDataString(request.VulnerabilityId)}");
+        if (!string.IsNullOrWhiteSpace(request.Severity))
+            queryParams.Add($"severity={Uri.EscapeDataString(request.Severity)}");
+        if (!string.IsNullOrWhiteSpace(request.Status))
+            queryParams.Add($"status={Uri.EscapeDataString(request.Status)}");
+        if (!string.IsNullOrWhiteSpace(request.Purl))
+            queryParams.Add($"purl={Uri.EscapeDataString(request.Purl)}");
+        if (!string.IsNullOrWhiteSpace(request.Cpe))
+            queryParams.Add($"cpe={Uri.EscapeDataString(request.Cpe)}");
+        if (!string.IsNullOrWhiteSpace(request.SbomId))
+            queryParams.Add($"sbomId={Uri.EscapeDataString(request.SbomId)}");
+        if (!string.IsNullOrWhiteSpace(request.PolicyId))
+            queryParams.Add($"policyId={Uri.EscapeDataString(request.PolicyId)}");
+        if (request.PolicyVersion.HasValue)
+            queryParams.Add($"policyVersion={request.PolicyVersion.Value}");
+        if (!string.IsNullOrWhiteSpace(request.GroupBy))
+            queryParams.Add($"groupBy={Uri.EscapeDataString(request.GroupBy)}");
+        if (request.Limit.HasValue)
+            queryParams.Add($"limit={request.Limit.Value}");
+        if (request.Offset.HasValue)
+            queryParams.Add($"offset={request.Offset.Value}");
+        if (!string.IsNullOrWhiteSpace(request.Cursor))
+            queryParams.Add($"cursor={Uri.EscapeDataString(request.Cursor)}");
+
+        var relative = "api/vuln";
+        if (queryParams.Count > 0)
+            relative += "?" + string.Join("&", queryParams);
+
+        using var httpRequest = CreateRequest(HttpMethod.Get, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to list vulnerabilities: {message}");
+        }
+
+        var json = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        var result = JsonSerializer.Deserialize<VulnListResponse>(json, SerializerOptions);
+        return result ?? new VulnListResponse(Array.Empty<VulnItem>(), 0, 0, 0, false);
+    }
+
+    // CLI-VULN-29-002: Vulnerability detail
+    public async Task<VulnDetailResponse?> GetVulnerabilityAsync(string vulnerabilityId, string? tenant, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(vulnerabilityId))
+        {
+            throw new ArgumentException("Vulnerability ID must be provided.", nameof(vulnerabilityId));
+        }
+
+        EnsureBackendConfigured();
+
+        var encodedVulnId = Uri.EscapeDataString(vulnerabilityId.Trim());
+        var relative = $"api/vuln/{encodedVulnId}";
+
+        using var httpRequest = CreateRequest(HttpMethod.Get, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
+        {
+            return null;
+        }
+
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Failed to get vulnerability details: {message}");
+        }
+
+        var json = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        return JsonSerializer.Deserialize<VulnDetailResponse>(json, SerializerOptions);
+    }
+
+    // CLI-VULN-29-003: Vulnerability workflow operations
+    public async Task<VulnWorkflowResponse> ExecuteVulnWorkflowAsync(VulnWorkflowRequest request, string? tenant, CancellationToken cancellationToken)
+    {
+        EnsureBackendConfigured();
+
+        var relative = "api/vuln/workflow";
+        var jsonPayload = JsonSerializer.Serialize(request, SerializerOptions);
+
+        using var httpRequest = CreateRequest(HttpMethod.Post, relative);
+        httpRequest.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Workflow operation failed: {message}");
+        }
+
+        var json = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        var result = JsonSerializer.Deserialize<VulnWorkflowResponse>(json, SerializerOptions);
+        return result ?? new VulnWorkflowResponse(false, request.Action, 0);
+    }
+
+    // CLI-VULN-29-004: Vulnerability simulation
+    public async Task<VulnSimulationResponse> SimulateVulnerabilitiesAsync(VulnSimulationRequest request, string? tenant, CancellationToken cancellationToken)
+    {
+        EnsureBackendConfigured();
+
+        var relative = "api/vuln/simulate";
+        var jsonPayload = JsonSerializer.Serialize(request, SerializerOptions);
+
+        using var httpRequest = CreateRequest(HttpMethod.Post, relative);
+        httpRequest.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Vulnerability simulation failed: {message}");
+        }
+
+        var json = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        var result = JsonSerializer.Deserialize<VulnSimulationResponse>(json, SerializerOptions);
+        return result ?? new VulnSimulationResponse(Array.Empty<VulnSimulationDelta>(), new VulnSimulationSummary(0, 0, 0, 0, 0));
+    }
+
+    // CLI-VULN-29-005: Vulnerability export
+    public async Task<VulnExportResponse> ExportVulnerabilitiesAsync(VulnExportRequest request, string? tenant, CancellationToken cancellationToken)
+    {
+        EnsureBackendConfigured();
+
+        var relative = "api/vuln/export";
+        var jsonPayload = JsonSerializer.Serialize(request, SerializerOptions);
+
+        using var httpRequest = CreateRequest(HttpMethod.Post, relative);
+        httpRequest.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Vulnerability export failed: {message}");
+        }
+
+        var json = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        var result = JsonSerializer.Deserialize<VulnExportResponse>(json, SerializerOptions);
+        return result ?? throw new InvalidOperationException("Failed to parse export response.");
+    }
+
+    public async Task<Stream> DownloadVulnExportAsync(string exportId, string? tenant, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(exportId))
+        {
+            throw new ArgumentException("Export ID must be provided.", nameof(exportId));
+        }
+
+        EnsureBackendConfigured();
+
+        var encodedExportId = Uri.EscapeDataString(exportId.Trim());
+        var relative = $"api/vuln/export/{encodedExportId}/download";
+
+        using var httpRequest = CreateRequest(HttpMethod.Get, relative);
+        if (!string.IsNullOrWhiteSpace(tenant))
+        {
+            httpRequest.Headers.TryAddWithoutValidation("X-Tenant-Id", tenant.Trim());
+        }
+
+        await AuthorizeRequestAsync(httpRequest, cancellationToken).ConfigureAwait(false);
+
+        var response = await _httpClient.SendAsync(httpRequest, HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            var (message, _) = await CreateFailureDetailsAsync(response, cancellationToken).ConfigureAwait(false);
+            throw new InvalidOperationException($"Vulnerability export download failed: {message}");
+        }
+
+        return await response.Content.ReadAsStreamAsync(cancellationToken).ConfigureAwait(false);
+    }
 }