license switch agpl -> busl1, sprints work, new product advisories

2026-01-20 15:32:20 +02:00
parent 4903395618
commit c32fff8f86
1835 changed files with 38630 additions and 4359 deletions
--- a/docs/modules/analytics/README.md
+++ b/docs/modules/analytics/README.md
@@ -0,0 +1,136 @@
+# 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`