137 lines
5.3 KiB
Markdown
137 lines
5.3 KiB
Markdown
# Analytics Module
|
|
|
|
The Analytics module provides a star-schema data warehouse layer for SBOM and attestation data, enabling executive reporting, risk dashboards, and ad-hoc analysis.
|
|
|
|
## Overview
|
|
|
|
Stella Ops generates rich data through SBOM ingestion, vulnerability correlation, VEX assessments, and attestations. The Analytics module normalizes this data into a queryable warehouse schema optimized for:
|
|
|
|
- **Executive dashboards**: Risk posture, vulnerability trends, compliance status
|
|
- **Supply chain analysis**: Supplier concentration, license distribution
|
|
- **Security metrics**: CVE exposure, VEX effectiveness, MTTR tracking
|
|
- **Attestation coverage**: SLSA compliance, provenance gaps
|
|
|
|
## Key Capabilities
|
|
|
|
| Capability | Description |
|
|
|------------|-------------|
|
|
| Unified component registry | Canonical component table with normalized suppliers and licenses |
|
|
| Vulnerability correlation | Pre-joined component-vulnerability mapping with EPSS/KEV flags |
|
|
| VEX-adjusted exposure | Vulnerability counts that respect VEX overrides |
|
|
| Attestation tracking | Provenance and SLSA level coverage by environment/team |
|
|
| Time-series rollups | Daily snapshots for trend analysis |
|
|
| Materialized views | Pre-computed aggregations for dashboard performance |
|
|
|
|
## Data Model
|
|
|
|
### Star Schema Overview
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ artifacts │ (dimension)
|
|
│ container/app │
|
|
└────────┬────────┘
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
│ │ │
|
|
┌─────────▼──────┐ ┌─────▼─────┐ ┌──────▼──────┐
|
|
│ artifact_ │ │attestations│ │vex_overrides│
|
|
│ components │ │ (fact) │ │ (fact) │
|
|
│ (bridge) │ └───────────┘ └─────────────┘
|
|
└─────────┬──────┘
|
|
│
|
|
┌─────────▼──────┐
|
|
│ components │ (dimension)
|
|
│ unified │
|
|
│ registry │
|
|
└─────────┬──────┘
|
|
│
|
|
┌─────────▼──────┐
|
|
│ component_ │
|
|
│ vulns │ (fact)
|
|
│ (bridge) │
|
|
└────────────────┘
|
|
```
|
|
|
|
### Core Tables
|
|
|
|
| Table | Type | Purpose |
|
|
|-------|------|---------|
|
|
| `components` | Dimension | Unified component registry with PURL, supplier, license |
|
|
| `artifacts` | Dimension | Container images and applications with SBOM metadata |
|
|
| `artifact_components` | Bridge | Links artifacts to their SBOM components |
|
|
| `component_vulns` | Fact | Component-to-vulnerability mapping |
|
|
| `attestations` | Fact | Attestation metadata (provenance, SBOM, VEX) |
|
|
| `vex_overrides` | Fact | VEX status overrides with justifications |
|
|
| `raw_sboms` | Audit | Raw SBOM payloads for reprocessing |
|
|
| `raw_attestations` | Audit | Raw DSSE envelopes for audit |
|
|
| `daily_vulnerability_counts` | Rollup | Daily vuln aggregations |
|
|
| `daily_component_counts` | Rollup | Daily component aggregations |
|
|
|
|
### Materialized Views
|
|
|
|
| View | Refresh | Purpose |
|
|
|------|---------|---------|
|
|
| `mv_supplier_concentration` | Daily | Top suppliers by component count |
|
|
| `mv_license_distribution` | Daily | License category distribution |
|
|
| `mv_vuln_exposure` | Daily | CVE exposure adjusted by VEX |
|
|
| `mv_attestation_coverage` | Daily | Provenance/SLSA coverage by env/team |
|
|
|
|
## Quick Start
|
|
|
|
### Day-1 Queries
|
|
|
|
**Top supplier concentration (supply chain risk):**
|
|
```sql
|
|
SELECT * FROM analytics.sp_top_suppliers(20);
|
|
```
|
|
|
|
**License risk heatmap:**
|
|
```sql
|
|
SELECT * FROM analytics.sp_license_heatmap();
|
|
```
|
|
|
|
**CVE exposure adjusted by VEX:**
|
|
```sql
|
|
SELECT * FROM analytics.sp_vuln_exposure('prod', 'high');
|
|
```
|
|
|
|
**Fixable vulnerability backlog:**
|
|
```sql
|
|
SELECT * FROM analytics.sp_fixable_backlog('prod');
|
|
```
|
|
|
|
**Attestation coverage gaps:**
|
|
```sql
|
|
SELECT * FROM analytics.sp_attestation_gaps('prod');
|
|
```
|
|
|
|
### API Endpoints
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/api/analytics/suppliers` | GET | Supplier concentration data |
|
|
| `/api/analytics/licenses` | GET | License distribution |
|
|
| `/api/analytics/vulnerabilities` | GET | CVE exposure (VEX-adjusted) |
|
|
| `/api/analytics/backlog` | GET | Fixable vulnerability backlog |
|
|
| `/api/analytics/attestation-coverage` | GET | Attestation gaps |
|
|
| `/api/analytics/trends/vulnerabilities` | GET | Vulnerability time-series |
|
|
| `/api/analytics/trends/components` | GET | Component time-series |
|
|
|
|
## Architecture
|
|
|
|
See [architecture.md](./architecture.md) for detailed design decisions, data flow, and normalization rules.
|
|
|
|
## Schema Reference
|
|
|
|
See [analytics_schema.sql](../../db/analytics_schema.sql) for complete DDL including:
|
|
- Table definitions with indexes
|
|
- Normalization functions
|
|
- Materialized views
|
|
- Stored procedures
|
|
- Refresh procedures
|
|
|
|
## Sprint Reference
|
|
|
|
Implementation tracked in: `docs/implplan/SPRINT_20260120_030_Platform_sbom_analytics_lake.md`
|