Dashboard Data Flow

Overview

The Dashboard Data Flow describes how StellaOps aggregates security posture data from multiple sources and presents it to users through the Console UI. The dashboard provides real-time visibility into vulnerability counts, policy compliance, scan status, and risk trends across all managed assets.

Business Value: Operators gain immediate visibility into their security posture without querying multiple systems.

Actors

Actor Type Role
Operator Human Views dashboard, triggers actions
Console (Web UI) System Renders dashboard components
Gateway Service Routes and authenticates requests
Platform Service Service Aggregates data from modules
Scanner Service Provides scan results and SBOM data
Policy Engine Service Provides policy verdicts
Concelier Service Provides advisory data
VexLens Service Provides VEX consensus data

Prerequisites

  • User authenticated via Authority (OAuth/OIDC)
  • Tenant context established via X-Tenant-Id header
  • At least one scan completed for data to display

Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           Dashboard Data Flow                                    │
└─────────────────────────────────────────────────────────────────────────────────┘

┌────────┐      ┌─────────┐      ┌─────────┐      ┌──────────┐
│Operator│      │ Console │      │ Gateway │      │ Platform │
└───┬────┘      └────┬────┘      └────┬────┘      └────┬─────┘
    │                │                │                │
    │  Open Dashboard│                │                │
    │───────────────>│                │                │
    │                │                │                │
    │                │ GET /api/v1/dashboard          │
    │                │ Authorization: Bearer {jwt}    │
    │                │ X-Tenant-Id: {tenant}          │
    │                │───────────────>│                │
    │                │                │                │
    │                │                │ Validate JWT   │
    │                │                │ Extract claims │
    │                │                │───────┐        │
    │                │                │       │        │
    │                │                │<──────┘        │
    │                │                │                │
    │                │                │ Forward with   │
    │                │                │ X-User-Id      │
    │                │                │───────────────>│
    │                │                │                │
    │                │                │                │  ┌─────────┐
    │                │                │                │  │ Scanner │
    │                │                │                │  └────┬────┘
    │                │                │                │       │
    │                │                │                │ Query scan stats
    │                │                │                │──────>│
    │                │                │                │       │
    │                │                │                │<──────│
    │                │                │                │       │
    │                │                │                │  ┌────────┐
    │                │                │                │  │ Policy │
    │                │                │                │  └───┬────┘
    │                │                │                │      │
    │                │                │                │ Query verdicts
    │                │                │                │─────>│
    │                │                │                │      │
    │                │                │                │<─────│
    │                │                │                │      │
    │                │                │                │  ┌──────────┐
    │                │                │                │  │ Concelier│
    │                │                │                │  └────┬─────┘
    │                │                │                │       │
    │                │                │                │ Query advisories
    │                │                │                │──────>│
    │                │                │                │       │
    │                │                │                │<──────│
    │                │                │                │
    │                │                │ Aggregated     │
    │                │                │ Dashboard DTO  │
    │                │                │<───────────────│
    │                │                │                │
    │                │ 200 OK         │                │
    │                │ {dashboard}    │                │
    │                │<───────────────│                │
    │                │                │                │
    │ Render widgets │                │                │
    │<───────────────│                │                │
    │                │                │                │

Step-by-Step

1. User Opens Dashboard

  • Operator navigates to Console dashboard
  • Browser loads Angular SPA from CDN/static files

2. Authentication Check

  • Console checks for valid JWT in local storage
  • If expired, redirects to Authority login flow
  • If valid, proceeds with API calls

3. Dashboard API Request

GET /api/v1/dashboard HTTP/1.1
Host: gateway.stellaops.local
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
X-Tenant-Id: acme-corp
Accept: application/json

4. Gateway Processing

  • Validates JWT signature against Authority JWKS
  • Extracts tenant from claims or header
  • Applies rate limiting and ABAC rules
  • Adds internal headers: X-User-Id, X-User-Email

5. Platform Service Aggregation

Platform Service fans out to multiple modules in parallel:

Query Module Endpoint
Scan statistics Scanner GET /internal/stats?tenant={id}
Policy verdicts Policy GET /internal/verdicts/summary?tenant={id}
Advisory counts Concelier GET /internal/advisories/counts?tenant={id}
VEX coverage VexLens GET /internal/vex/coverage?tenant={id}

6. Data Aggregation

Platform Service combines responses into dashboard DTO:

{
  "summary": {
    "total_images": 1247,
    "images_scanned_24h": 89,
    "critical_vulns": 12,
    "high_vulns": 145,
    "policy_violations": 3
  },
  "trends": {
    "vuln_trend_7d": [-5, -2, 0, +3, -1, -4, -2],
    "scan_volume_7d": [78, 92, 85, 89, 76, 81, 89]
  },
  "top_vulns": [
    {"cve": "CVE-2024-1234", "severity": "critical", "affected_images": 8}
  ],
  "policy_status": {
    "compliant": 1198,
    "non_compliant": 49,
    "pending": 0
  }
}

7. Response Delivery

  • Platform returns aggregated DTO
  • Gateway forwards to Console
  • Console renders dashboard widgets

Data Contracts

Request Headers

Header Required Description
Authorization Yes Bearer JWT token
X-Tenant-Id Yes Tenant identifier
Accept No application/json (default)

Response Schema

interface DashboardResponse {
  summary: {
    total_images: number;
    images_scanned_24h: number;
    critical_vulns: number;
    high_vulns: number;
    medium_vulns: number;
    low_vulns: number;
    policy_violations: number;
  };
  trends: {
    vuln_trend_7d: number[];
    scan_volume_7d: number[];
  };
  top_vulns: Array<{
    cve: string;
    severity: 'critical' | 'high' | 'medium' | 'low';
    affected_images: number;
  }>;
  policy_status: {
    compliant: number;
    non_compliant: number;
    pending: number;
  };
  last_updated: string; // ISO-8601
}

Error Handling

Error HTTP Status Recovery
Invalid JWT 401 Redirect to login
Tenant not found 404 Show tenant selection
Module timeout 504 Partial dashboard with stale data indicator
Rate limited 429 Exponential backoff retry

Observability

Metrics

Metric Type Labels
dashboard_request_total Counter tenant, status
dashboard_latency_seconds Histogram tenant
dashboard_module_latency_seconds Histogram module

Trace Context

dashboard-request
├── gateway-auth-check
├── platform-aggregate
│   ├── scanner-stats-query
│   ├── policy-verdicts-query
│   ├── concelier-advisories-query
│   └── vexlens-coverage-query
└── response-serialize

Key Log Events

Event Level Fields
dashboard.request INFO tenant_id, user_id
dashboard.module_timeout WARN module, timeout_ms
dashboard.complete INFO tenant_id, latency_ms