save progress
This commit is contained in:
StellaOps Bot
250
docs/flows/01-dashboard-data-flow.md
Normal file
250
docs/flows/01-dashboard-data-flow.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user