feat(rate-limiting): Implement core rate limiting functionality with configuration, decision-making, metrics, middleware, and service registration

- 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.
2025-12-17 18:02:37 +02:00
parent 394b57f6bf
commit 8bbfe4d2d2
211 changed files with 47179 additions and 1590 deletions
--- a/docs/benchmarks/smart-diff-wii.md
+++ b/docs/benchmarks/smart-diff-wii.md
@@ -0,0 +1,150 @@
+# 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)