git.stella-ops.org/docs/product-advisories/28-Nov-2025 - Graph Analytics and Dependency Insights.md

Graph Analytics and Dependency Insights

Version: 1.0 Date: 2025-11-29 Status: Canonical

This advisory defines the product rationale, graph model, and implementation strategy for the Graph module, covering dependency analysis, impact visualization, and offline exports.

---

1. Executive Summary

The Graph module provides dependency analysis and impact visualization across the vulnerability landscape. Key capabilities:

• Unified Graph Model - Artifacts, components, advisories, policies linked
• Impact Analysis - Blast radius, affected paths, transitive dependencies
• Policy Overlays - VEX and policy decisions visualized on graph
• Analytics - Clustering, centrality, community detection
• Offline Export - Deterministic graph snapshots for air-gap

---

2. Market Drivers

2.1 Target Segments

Segment	Graph Requirements	Use Case
Security Teams	Impact analysis	Vulnerability prioritization
Developers	Dependency visualization	Upgrade planning
Compliance	Audit trails	Relationship documentation
Management	Risk dashboards	Portfolio risk view

2.2 Competitive Positioning

Most vulnerability tools show flat lists. Stella Ops differentiates with:

• Graph-native architecture linking all entities
• Impact visualization showing blast radius
• Policy overlays embedding decisions in graph
• Offline-compatible exports for air-gap analysis
• Analytics for community detection and centrality

---

3. Graph Model

3.1 Node Types

Node	Description	Key Properties
Artifact	Image/application digest	tenant, environment, labels
Component	Package version	purl, ecosystem, version
File	Source/binary path	hash, mtime
License	License identifier	spdx-id, restrictions
Advisory	Vulnerability record	cve-id, severity, sources
VEXStatement	VEX decision	status, justification
PolicyVersion	Signed policy pack	version, digest

3.2 Edge Types

Edge	From	To	Properties
DEPENDS_ON	Component	Component	scope, optional
BUILT_FROM	Artifact	Component	layer, path
DECLARED_IN	Component	File	sbom-id
AFFECTED_BY	Component	Advisory	version-range
VEX_EXEMPTS	VEXStatement	Advisory	justification
GOVERNS_WITH	PolicyVersion	Artifact	run-id
OBSERVED_RUNTIME	Artifact	Component	zastava-event-id

3.3 Provenance

Every edge carries:

• createdAt - UTC timestamp
• sourceDigest - SRM/SBOM hash
• provenanceRef - Link to source document

---

4. Overlay System

4.1 Overlay Types

Overlay	Purpose	Content
policy.overlay.v1	Policy decisions	verdict, severity, rules
openvex.v1	VEX status	status, justification
reachability.v1	Runtime reachability	state, confidence
clustering.v1	Community detection	cluster-id, modularity
centrality.v1	Node importance	degree, betweenness

4.2 Overlay Structure

{
  "overlayId": "sha256(tenant|nodeId|overlayKind)",
  "overlayKind": "policy.overlay.v1",
  "nodeId": "component:pkg:npm/lodash@4.17.21",
  "tenant": "acme-corp",
  "generatedAt": "2025-11-29T12:00:00Z",
  "content": {
    "verdict": "blocked",
    "severity": "critical",
    "rulesMatched": ["rule-001", "rule-002"],
    "explainTrace": "sampled trace data..."
  }
}

---

5. Query Capabilities

5.1 Search API

POST /graph/search
{
  "tenant": "acme-corp",
  "query": "severity:critical AND ecosystem:npm",
  "nodeTypes": ["Component", "Advisory"],
  "limit": 100
}

5.2 Path Query

POST /graph/paths
{
  "source": "artifact:sha256:abc123...",
  "target": "advisory:CVE-2025-12345",
  "maxDepth": 6,
  "includeOverlays": true
}

Response:

{
  "paths": [
    {
      "nodes": ["artifact:sha256:...", "component:pkg:npm/...", "advisory:CVE-..."],
      "edges": [{"type": "BUILT_FROM"}, {"type": "AFFECTED_BY"}],
      "length": 2
    }
  ],
  "overlays": [
    {"nodeId": "component:...", "overlayKind": "policy.overlay.v1", "content": {...}}
  ]
}

5.3 Diff Query

POST /graph/diff
{
  "snapshotA": "snapshot-2025-11-28",
  "snapshotB": "snapshot-2025-11-29",
  "includeOverlays": true
}

---

6. Analytics Pipeline

6.1 Clustering

• Algorithm: Louvain community detection
• Output: Cluster IDs per node, modularity score
• Use Case: Identify tightly coupled component groups

6.2 Centrality

• Degree centrality: Most connected nodes
• Betweenness centrality: Critical path nodes
• Use Case: Identify high-impact components

6.3 Background Processing

analytics:
  enabled: true
  schedule: "0 */6 * * *"  # Every 6 hours
  algorithms:
    - clustering
    - centrality
  snapshotRetention: 30

---

7. Implementation Strategy

7.1 Phase 1: Core Model (Complete)

• Node/edge schema
• SBOM ingestion pipeline
• Advisory/VEX linking
• Basic search API

7.2 Phase 2: Overlays (In Progress)

• Policy overlay generation
• VEX overlay generation
• Reachability overlay (GRAPH-REACH-50-001)
• Inline overlay in query responses (GRAPH-QUERY-51-001)

7.3 Phase 3: Analytics (Planned)

• Clustering algorithm
• Centrality calculations
• Background worker
• Analytics overlays export

7.4 Phase 4: Visualization (Planned)

• Console graph viewer
• Impact tree visualization
• Diff visualization

---

8. API Surface

8.1 Core APIs

Endpoint	Method	Scope	Description
/graph/search	POST	graph:read	Search nodes
/graph/query	POST	graph:read	Complex queries
/graph/paths	POST	graph:read	Path finding
/graph/diff	POST	graph:read	Snapshot diff
/graph/nodes/{id}	GET	graph:read	Node detail

8.2 Export APIs

Endpoint	Method	Scope	Description
/graph/export	POST	graph:export	Start export job
/graph/export/{jobId}	GET	graph:read	Job status
/graph/export/{jobId}/download	GET	graph:export	Download bundle

---

9. Storage Model

9.1 Collections

Collection	Purpose	Key Indexes
graph_nodes	Node records	{tenant, nodeType, nodeId}
graph_edges	Edge records	{tenant, fromId, toId, edgeType}
graph_overlays	Overlay data	{tenant, nodeId, overlayKind}
graph_snapshots	Point-in-time snapshots	{tenant, snapshotId}

9.2 Export Format

graph-export/
├── nodes.jsonl          # Sorted by nodeId
├── edges.jsonl          # Sorted by (from, to, type)
├── overlays/
│   ├── policy.jsonl
│   ├── openvex.jsonl
│   └── manifest.json
└── manifest.json

---

10. Observability

10.1 Metrics

• graph_ingest_lag_seconds
• graph_nodes_total{nodeType}
• graph_edges_total{edgeType}
• graph_query_latency_seconds{queryType}
• graph_analytics_runs_total
• graph_analytics_clusters_total

10.2 Offline Support

• Graph snapshots packaged for Offline Kit
• Deterministic NDJSON exports
• Overlay manifests with digests

---

11. Related Documentation

Resource	Location
Graph architecture	docs/modules/graph/architecture.md
Query language	docs/modules/graph/query-language.md
Overlay specification	docs/modules/graph/overlays.md

---

12. Sprint Mapping

• Primary Sprint: SPRINT_0141_0001_0001_graph_indexer.md
• Related Sprints:
  • SPRINT_0401_0001_0001_reachability_evidence_chain.md
  • SPRINT_0140_0001_0001_runtime_signals.md

Key Task IDs:

• GRAPH-CORE-40-001 - Core model (DONE)
• GRAPH-INGEST-41-001 - SBOM ingestion (DONE)
• GRAPH-REACH-50-001 - Reachability overlay (IN PROGRESS)
• GRAPH-ANALYTICS-55-001 - Clustering (TODO)
• GRAPH-VIZ-60-001 - Visualization (FUTURE)

---

13. Success Metrics

Metric	Target
Query latency	< 500ms p95
Ingestion lag	< 5 minutes
Path query depth	Up to 6 hops
Export reproducibility	100% deterministic
Analytics freshness	< 6 hours

---

Last updated: 2025-11-29