8bbfe4d2d2
- Add RateLimitConfig for configuration management with YAML binding support. - Introduce RateLimitDecision to encapsulate the result of rate limit checks. - Implement RateLimitMetrics for OpenTelemetry metrics tracking. - Create RateLimitMiddleware for enforcing rate limits on incoming requests. - Develop RateLimitService to orchestrate instance and environment rate limit checks. - Add RateLimitServiceCollectionExtensions for dependency injection registration.
151 lines
4.0 KiB
Markdown
151 lines
4.0 KiB
Markdown
# Smart-Diff Weighted Impact Index (WII)
|
||
|
||
**Source Advisory:** `docs/product-advisories/unprocessed/16-Dec-2025 - Smart‑Diff Meets Call‑Stack Reachability.md`
|
||
**Status:** Processed 2025-12-17
|
||
|
||
## Overview
|
||
|
||
The Weighted Impact Index (WII) is a composite score (0-100) that combines Smart-Diff semantic analysis with call-stack reachability to measure the runtime risk of code changes. It proves not just "what changed" but "how risky the change is in reachable code."
|
||
|
||
## Core Concepts
|
||
|
||
### Inputs
|
||
|
||
1. **Smart-Diff Output** - Semantic differences between artifact states
|
||
2. **Call Graph** - Symbol nodes with call edges
|
||
3. **Entrypoints** - HTTP routes, jobs, message handlers
|
||
4. **Runtime Heat** - pprof, APM, or eBPF execution frequency data
|
||
5. **Advisory Data** - CVSS v4, EPSS v4 scores
|
||
|
||
### WII Scoring Model
|
||
|
||
The WII uses 8 weighted features per diff unit:
|
||
|
||
| Feature | Weight | Description |
|
||
|---------|--------|-------------|
|
||
| `Δreach_len` | 0.25 | Change in shortest reachable path length |
|
||
| `Δlib_depth` | 0.10 | Change in library call depth |
|
||
| `exposure` | 0.15 | Public/external-facing API |
|
||
| `privilege` | 0.15 | Path crosses privileged sinks |
|
||
| `hot_path` | 0.15 | Frequently executed (runtime evidence) |
|
||
| `cvss_v4` | 0.10 | Normalized CVSS v4 severity |
|
||
| `epss_v4` | 0.10 | Exploit probability |
|
||
| `guard_coverage` | -0.10 | Sanitizers/validations reduce score |
|
||
|
||
### Determinism Bonus
|
||
|
||
When `reachability == true` AND (`cvss_v4 > 0.7` OR `epss_v4 > 0.5`), add +5 bonus for "evidence-linked determinism."
|
||
|
||
### Formula
|
||
|
||
```
|
||
WII = clamp(0, 1, Σ(w_i × feature_i_normalized)) × 100
|
||
```
|
||
|
||
## Data Structures
|
||
|
||
### DiffUnit
|
||
|
||
```json
|
||
{
|
||
"unitId": "pkg:npm/lodash@4.17.21#function:merge",
|
||
"change": "modified",
|
||
"before": {"hash": "sha256:abc...", "attrs": {}},
|
||
"after": {"hash": "sha256:def...", "attrs": {}},
|
||
"features": {
|
||
"reachable": true,
|
||
"reachLen": 3,
|
||
"libDepth": 2,
|
||
"exposure": true,
|
||
"privilege": false,
|
||
"hotPath": true,
|
||
"cvssV4": 0.75,
|
||
"epssV4": 0.45,
|
||
"guardCoverage": false
|
||
},
|
||
"wii": 68
|
||
}
|
||
```
|
||
|
||
### Artifact-Level WII
|
||
|
||
Two metrics for artifact-level impact:
|
||
- `max(WII_unit)` - Spike impact (single highest risk change)
|
||
- `p95(WII_unit)` - Broad impact (distribution of risk)
|
||
|
||
## DSSE Attestation
|
||
|
||
The WII is emitted as a DSSE-signed attestation:
|
||
|
||
```json
|
||
{
|
||
"_type": "https://in-toto.io/Statement/v1",
|
||
"subject": [{"name": "ghcr.io/acme/app:1.9.3", "digest": {"sha256": "..."}}],
|
||
"predicateType": "https://stella-ops.org/attestations/smart-diff-wii@v1",
|
||
"predicate": {
|
||
"artifactBefore": {"digest": {"sha256": "..."}},
|
||
"artifactAfter": {"digest": {"sha256": "..."}},
|
||
"evidence": {
|
||
"sbomBefore": {"digest": {"sha256": "..."}},
|
||
"sbomAfter": {"digest": {"sha256": "..."}},
|
||
"callGraph": {"digest": {"sha256": "..."}},
|
||
"runtimeHeat": {"optional": true, "digest": {"sha256": "..."}}
|
||
},
|
||
"units": [...],
|
||
"aggregateWII": {
|
||
"max": 85,
|
||
"p95": 62,
|
||
"mean": 45
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Pipeline Integration
|
||
|
||
1. **Collect** - Build call graph, import SBOMs, CVE/EPSS data
|
||
2. **Diff** - Run Smart-Diff to generate `DiffUnit[]`
|
||
3. **Enrich** - Query reachability engine per unit
|
||
4. **Score** - Compute per-unit and aggregate WII
|
||
5. **Attest** - Emit DSSE statement with evidence URIs
|
||
6. **Store** - Proof-Market Ledger (Rekor) + PostgreSQL
|
||
|
||
## Use Cases
|
||
|
||
### CI/CD Gates
|
||
|
||
```yaml
|
||
# .github/workflows/security.yml
|
||
- name: Smart-Diff WII Check
|
||
run: |
|
||
stellaops smart-diff \
|
||
--base ${{ env.BASE_IMAGE }} \
|
||
--target ${{ env.TARGET_IMAGE }} \
|
||
--wii-threshold 70 \
|
||
--fail-on-threshold
|
||
```
|
||
|
||
### Risk Prioritization
|
||
|
||
Sort changes by WII for review prioritization:
|
||
|
||
```bash
|
||
stellaops smart-diff show \
|
||
--sort wii \
|
||
--format table
|
||
```
|
||
|
||
### Attestation Verification
|
||
|
||
```bash
|
||
stellaops verify-attestation \
|
||
--input smart-diff-wii.json \
|
||
--predicate-type smart-diff-wii@v1
|
||
```
|
||
|
||
## Related Documentation
|
||
|
||
- [Smart-Diff CLI Reference](../cli/smart-diff-cli.md)
|
||
- [Reachability Analysis](./reachability-analysis.md)
|
||
- [DSSE Attestation Format](../api/dsse-format.md)
|