251 lines
10 KiB
Markdown
251 lines
10 KiB
Markdown
# 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
|
|
```http
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```typescript
|
|
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](02-scan-submission-flow.md) - How scans that feed the dashboard are created
|
|
- [Policy Evaluation Flow](04-policy-evaluation-flow.md) - How policy verdicts are computed
|
|
- [Risk Score Dashboard Flow](18-risk-score-dashboard-flow.md) - Detailed risk scoring
|