10 KiB
10 KiB
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-Idheader - 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 |
Related Flows
- Scan Submission Flow - How scans that feed the dashboard are created
- Policy Evaluation Flow - How policy verdicts are computed
- Risk Score Dashboard Flow - Detailed risk scoring