up
This commit is contained in:
StellaOps Bot
@@ -96,7 +96,7 @@ The next implementation pass must cover the following documents/files (create th
|
||||
|
||||
API contracts to amend:
|
||||
|
||||
- `POST /signals/callgraphs` response should include `graphHash` (BLAKE3) once `GRAPH-CAS-401-001` lands.
|
||||
- `POST /signals/callgraphs` response includes `graphHash` (sha256) for the normalized callgraph; richgraph-v1 uses BLAKE3 for graph CAS hashes.
|
||||
- `POST /signals/runtime-facts` request body schema (NDJSON) with `symbol_id`, `code_id`, `hit_count`, `loader_base`.
|
||||
- `GET /policy/findings` payload must surface `reachability.evidence[]` objects.
|
||||
|
||||
|
||||
337
docs/reachability/ground-truth-schema.md
Normal file
337
docs/reachability/ground-truth-schema.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# Ground Truth Schema for Reachability Datasets
|
||||
|
||||
> **Status:** Design v1 (Sprint 0401)
|
||||
> **Owners:** Scanner Guild, Signals Guild, Quality Guild
|
||||
|
||||
This document defines the ground truth schema for test datasets used to validate reachability analysis. Ground truth samples provide known-correct answers for benchmarking lattice state calculations, path discovery, and policy gate decisions.
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Ground truth datasets enable:
|
||||
|
||||
1. **Regression testing:** Detect regressions in reachability analysis accuracy
|
||||
2. **Benchmark scoring:** Measure precision, recall, F1 for path discovery
|
||||
3. **Lattice validation:** Verify join/meet operations produce expected states
|
||||
4. **Policy gate testing:** Ensure gates block/allow correct VEX transitions
|
||||
|
||||
---
|
||||
|
||||
## 2. Dataset Structure
|
||||
|
||||
### 2.1 Directory Layout
|
||||
|
||||
```
|
||||
datasets/reachability/
|
||||
├── samples/
|
||||
│ ├── java/
|
||||
│ │ ├── vulnerable-log4j/
|
||||
│ │ │ ├── manifest.json # Sample metadata
|
||||
│ │ │ ├── richgraph-v1.json # Input callgraph
|
||||
│ │ │ ├── ground-truth.json # Expected outcomes
|
||||
│ │ │ └── artifacts/ # Source binaries/SBOMs
|
||||
│ │ └── safe-spring-boot/
|
||||
│ │ └── ...
|
||||
│ ├── native/
|
||||
│ │ ├── stripped-elf/
|
||||
│ │ └── openssl-vuln/
|
||||
│ └── polyglot/
|
||||
│ └── node-native-addon/
|
||||
├── corpus/
|
||||
│ ├── positive/ # Known reachable samples
|
||||
│ ├── negative/ # Known unreachable samples
|
||||
│ └── contested/ # Known conflict samples
|
||||
└── schema/
|
||||
├── manifest.schema.json
|
||||
└── ground-truth.schema.json
|
||||
```
|
||||
|
||||
### 2.2 Sample Manifest (`manifest.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"sampleId": "sample:java:vulnerable-log4j:001",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2025-12-13T10:00:00Z",
|
||||
"language": "java",
|
||||
"category": "positive",
|
||||
"description": "Log4Shell CVE-2021-44228 reachable via JNDI lookup in logging path",
|
||||
"source": {
|
||||
"repository": "https://github.com/example/vuln-app",
|
||||
"commit": "abc123...",
|
||||
"buildToolchain": "maven:3.9.0,jdk:17"
|
||||
},
|
||||
"vulnerabilities": [
|
||||
{
|
||||
"vulnId": "CVE-2021-44228",
|
||||
"purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1",
|
||||
"affectedSymbol": "org.apache.logging.log4j.core.lookup.JndiLookup.lookup"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"path": "artifacts/app.jar",
|
||||
"hash": "sha256:...",
|
||||
"type": "application/java-archive"
|
||||
},
|
||||
{
|
||||
"path": "artifacts/sbom.cdx.json",
|
||||
"hash": "sha256:...",
|
||||
"type": "application/vnd.cyclonedx+json"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 Ground Truth Document (`ground-truth.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ground-truth-v1",
|
||||
"sampleId": "sample:java:vulnerable-log4j:001",
|
||||
"generatedAt": "2025-12-13T10:00:00Z",
|
||||
"generator": {
|
||||
"name": "manual-annotation",
|
||||
"version": "1.0.0",
|
||||
"annotator": "security-team"
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"symbolId": "sym:java:...",
|
||||
"display": "org.apache.logging.log4j.core.lookup.JndiLookup.lookup",
|
||||
"purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1",
|
||||
"expected": {
|
||||
"latticeState": "CR",
|
||||
"bucket": "direct",
|
||||
"reachable": true,
|
||||
"confidence": 0.95,
|
||||
"pathLength": 3,
|
||||
"path": [
|
||||
"sym:java:...main",
|
||||
"sym:java:...logInfo",
|
||||
"sym:java:...JndiLookup.lookup"
|
||||
]
|
||||
},
|
||||
"reasoning": "Direct call path from main() through logging framework to vulnerable lookup method"
|
||||
},
|
||||
{
|
||||
"symbolId": "sym:java:...",
|
||||
"display": "org.apache.logging.log4j.core.net.JndiManager.lookup",
|
||||
"purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1",
|
||||
"expected": {
|
||||
"latticeState": "CU",
|
||||
"bucket": "unreachable",
|
||||
"reachable": false,
|
||||
"confidence": 0.90,
|
||||
"pathLength": null,
|
||||
"path": null
|
||||
},
|
||||
"reasoning": "JndiManager.lookup is present but not called from any reachable entry point"
|
||||
}
|
||||
],
|
||||
"entryPoints": [
|
||||
{
|
||||
"symbolId": "sym:java:...",
|
||||
"display": "com.example.app.Main.main",
|
||||
"phase": "runtime",
|
||||
"source": "manifest"
|
||||
}
|
||||
],
|
||||
"expectedUncertainty": {
|
||||
"states": [],
|
||||
"aggregateTier": "T4",
|
||||
"riskScore": 0.0
|
||||
},
|
||||
"expectedGateDecisions": [
|
||||
{
|
||||
"vulnId": "CVE-2021-44228",
|
||||
"targetSymbol": "sym:java:...JndiLookup.lookup",
|
||||
"requestedStatus": "not_affected",
|
||||
"expectedDecision": "block",
|
||||
"expectedBlockedBy": "LatticeState",
|
||||
"expectedReason": "CR state incompatible with not_affected"
|
||||
},
|
||||
{
|
||||
"vulnId": "CVE-2021-44228",
|
||||
"targetSymbol": "sym:java:...JndiLookup.lookup",
|
||||
"requestedStatus": "affected",
|
||||
"expectedDecision": "allow"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Schema Definitions
|
||||
|
||||
### 3.1 Ground Truth Target
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `symbolId` | string | Yes | Canonical SymbolID (`sym:{lang}:{hash}`) |
|
||||
| `display` | string | No | Human-readable symbol name |
|
||||
| `purl` | string | No | Package URL of containing package |
|
||||
| `expected.latticeState` | enum | Yes | Expected v1 lattice state: `U`, `SR`, `SU`, `RO`, `RU`, `CR`, `CU`, `X` |
|
||||
| `expected.bucket` | enum | Yes | Expected v0 bucket (backward compat) |
|
||||
| `expected.reachable` | boolean | Yes | True if symbol is reachable from any entry point |
|
||||
| `expected.confidence` | number | Yes | Expected confidence score [0.0-1.0] |
|
||||
| `expected.pathLength` | number | No | Expected path length (null if unreachable) |
|
||||
| `expected.path` | string[] | No | Expected path (sorted, deterministic) |
|
||||
| `reasoning` | string | Yes | Human explanation of expected outcome |
|
||||
|
||||
### 3.2 Expected Gate Decision
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `vulnId` | string | Yes | Vulnerability identifier |
|
||||
| `targetSymbol` | string | Yes | Target SymbolID |
|
||||
| `requestedStatus` | enum | Yes | VEX status: `affected`, `not_affected`, `under_investigation`, `fixed` |
|
||||
| `expectedDecision` | enum | Yes | Gate outcome: `allow`, `block`, `warn` |
|
||||
| `expectedBlockedBy` | string | No | Gate name if blocked |
|
||||
| `expectedReason` | string | No | Expected reason message |
|
||||
|
||||
---
|
||||
|
||||
## 4. Sample Categories
|
||||
|
||||
### 4.1 Positive Samples (Reachable)
|
||||
|
||||
Known-reachable cases where vulnerable code is called:
|
||||
|
||||
- **direct-call:** Vulnerable function called directly from entry point
|
||||
- **transitive:** Multi-hop path from entry point to vulnerable function
|
||||
- **runtime-observed:** Confirmed reachable via runtime probe
|
||||
- **init-array:** Reachable via load-time constructor
|
||||
|
||||
### 4.2 Negative Samples (Unreachable)
|
||||
|
||||
Known-unreachable cases where vulnerable code exists but isn't called:
|
||||
|
||||
- **dead-code:** Function present but never invoked
|
||||
- **conditional-unreachable:** Function behind impossible condition
|
||||
- **test-only:** Function only reachable from test entry points
|
||||
- **deprecated-api:** Old API present but replaced by new implementation
|
||||
|
||||
### 4.3 Contested Samples
|
||||
|
||||
Cases where static and runtime evidence conflict:
|
||||
|
||||
- **static-reach-runtime-miss:** Static analysis finds path, runtime never observes
|
||||
- **static-miss-runtime-hit:** Static analysis misses path, runtime observes execution
|
||||
- **version-mismatch:** Analysis version differs from runtime version
|
||||
|
||||
---
|
||||
|
||||
## 5. Benchmark Metrics
|
||||
|
||||
### 5.1 Path Discovery Metrics
|
||||
|
||||
```
|
||||
Precision = TruePositive / (TruePositive + FalsePositive)
|
||||
Recall = TruePositive / (TruePositive + FalseNegative)
|
||||
F1 = 2 * (Precision * Recall) / (Precision + Recall)
|
||||
```
|
||||
|
||||
### 5.2 Lattice State Accuracy
|
||||
|
||||
```
|
||||
StateAccuracy = CorrectStates / TotalTargets
|
||||
BucketAccuracy = CorrectBuckets / TotalTargets (v0 compatibility)
|
||||
```
|
||||
|
||||
### 5.3 Gate Decision Accuracy
|
||||
|
||||
```
|
||||
GateAccuracy = CorrectDecisions / TotalGateTests
|
||||
FalseAllow = AllowedWhenShouldBlock / TotalBlocks (critical metric)
|
||||
FalseBlock = BlockedWhenShouldAllow / TotalAllows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Test Harness Integration
|
||||
|
||||
### 6.1 xUnit Test Pattern
|
||||
|
||||
```csharp
|
||||
[Theory]
|
||||
[MemberData(nameof(GetGroundTruthSamples))]
|
||||
public async Task ReachabilityAnalysis_MatchesGroundTruth(GroundTruthSample sample)
|
||||
{
|
||||
// Arrange
|
||||
var graph = await LoadRichGraphAsync(sample.GraphPath);
|
||||
var scorer = _serviceProvider.GetRequiredService<ReachabilityScoringService>();
|
||||
|
||||
// Act
|
||||
var result = await scorer.ComputeAsync(graph, sample.EntryPoints);
|
||||
|
||||
// Assert
|
||||
foreach (var target in sample.Targets)
|
||||
{
|
||||
var actual = result.States.First(s => s.SymbolId == target.SymbolId);
|
||||
Assert.Equal(target.Expected.LatticeState, actual.LatticeState);
|
||||
Assert.Equal(target.Expected.Reachable, actual.Reachable);
|
||||
Assert.InRange(actual.Confidence,
|
||||
target.Expected.Confidence - 0.05,
|
||||
target.Expected.Confidence + 0.05);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Benchmark Runner
|
||||
|
||||
```bash
|
||||
# Run reachability benchmarks
|
||||
dotnet run --project src/Scanner/__Tests/StellaOps.Scanner.Reachability.Benchmarks \
|
||||
--dataset datasets/reachability/samples \
|
||||
--output benchmark-results.json \
|
||||
--threshold-f1 0.95 \
|
||||
--threshold-gate-accuracy 0.99
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Sample Contribution Guidelines
|
||||
|
||||
### 7.1 Adding New Samples
|
||||
|
||||
1. Create directory under `datasets/reachability/samples/{language}/{sample-name}/`
|
||||
2. Add `manifest.json` with sample metadata
|
||||
3. Add `richgraph-v1.json` (run scanner on artifacts)
|
||||
4. Create `ground-truth.json` with manual annotations
|
||||
5. Include reasoning for each expected outcome
|
||||
6. Run validation: `dotnet test --filter "GroundTruth"`
|
||||
|
||||
### 7.2 Ground Truth Validation
|
||||
|
||||
Ground truth files must pass schema validation:
|
||||
|
||||
```bash
|
||||
npx ajv validate -s docs/reachability/ground-truth.schema.json \
|
||||
-d datasets/reachability/samples/**/ground-truth.json
|
||||
```
|
||||
|
||||
### 7.3 Review Requirements
|
||||
|
||||
- All samples require two independent annotators
|
||||
- Contested samples require security team review
|
||||
- Changes to existing samples require regression test pass
|
||||
|
||||
---
|
||||
|
||||
## 8. Related Documents
|
||||
|
||||
- [Lattice Model](./lattice.md) — v1 formal 7-state lattice
|
||||
- [Policy Gates](./policy-gate.md) — Gate rules for VEX decisions
|
||||
- [Evidence Schema](./evidence-schema.md) — richgraph-v1 schema
|
||||
- [richgraph-v1 Contract](../contracts/richgraph-v1.md) — Full schema specification
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 1.0.0 | 2025-12-13 | Scanner Guild | Initial design from Sprint 0401 |
|
||||
@@ -1,215 +1,254 @@
|
||||
# Reachability Lattice & Scoring Model
|
||||
|
||||
> **Status:** Draft – mirrors the December 2025 advisory on confidence-based reachability.
|
||||
> **Owners:** Scanner Guild · Policy Guild · Signals Guild.
|
||||
> **Status:** Implemented v0 in Signals; this document describes the current deterministic bucket model and its policy-facing implications.
|
||||
> **Owners:** Scanner Guild · Signals Guild · Policy Guild.
|
||||
|
||||
> Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation.
|
||||
|
||||
This document defines the confidence lattice, evidence types, mitigation scoring, and policy gates used to turn static/runtime signals into reproducible reachability decisions and VEX statuses.
|
||||
StellaOps models reachability as a deterministic, evidence-linked outcome that can safely represent "unknown" without silently producing false safety. Signals produces a `ReachabilityFactDocument` with per-target `states[]` and a top-level `score` that is stable under replays.
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
## 1. Current model (Signals v0)
|
||||
|
||||
<!-- TODO: Review for separate approval - updated lattice overview -->
|
||||
**Key differentiator:** Unlike simplistic yes/no reachability approaches, the Stella Ops lattice model explicitly handles an **"Unknown"** (under_investigation) state, ensuring incomplete data doesn't lead to false safety. Every VEX decision is evidence-linked with proof pointers to the underlying reachability evidence.
|
||||
Signals scoring (`src/Signals/StellaOps.Signals/Services/ReachabilityScoringService.cs`) computes, for each `target` symbol:
|
||||
|
||||
Classic "reachable: true/false" answers are too brittle. Stella Ops models reachability as an **ordered lattice** with explicit states and scores. Each analyzer/runtime probe emits `Evidence` documents; mitigations add `Mitigation` entries. The lattice engine joins both inputs into a `ReachDecision`:
|
||||
- `reachable`: whether there exists a path from the selected `entryPoints[]` to `target`.
|
||||
- `bucket`: a coarse classification of *why* the target is/was reachable.
|
||||
- `confidence` (0..1): a bounded confidence value.
|
||||
- `weight` (0..1): bucket multiplier.
|
||||
- `score` (0..1): `confidence * weight`.
|
||||
- `path[]`: the discovered path (if reachable), deterministically ordered.
|
||||
- `evidence.runtimeHits[]`: runtime hit symbols that appear on the chosen path.
|
||||
|
||||
The fact-level `score` is the average of per-target scores, penalized by unknowns pressure (see §4).
|
||||
|
||||
---
|
||||
|
||||
## 2. Buckets & default weights
|
||||
|
||||
Bucket assignment is deterministic and uses this precedence:
|
||||
|
||||
1. `unreachable` — no path exists.
|
||||
2. `entrypoint` — the `target` itself is an entrypoint.
|
||||
3. `runtime` — at least one runtime hit overlaps the discovered path.
|
||||
4. `direct` — reachable and the discovered path is length ≤ 2.
|
||||
5. `unknown` — reachable but none of the above classifications apply.
|
||||
|
||||
Default weights (configurable via `SignalsOptions:Scoring:ReachabilityBuckets`):
|
||||
|
||||
| Bucket | Default weight |
|
||||
|--------|----------------|
|
||||
| `entrypoint` | `1.0` |
|
||||
| `direct` | `0.85` |
|
||||
| `runtime` | `0.45` |
|
||||
| `unknown` | `0.5` |
|
||||
| `unreachable` | `0.0` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Confidence (reachable vs unreachable)
|
||||
|
||||
Default confidence values (configurable via `SignalsOptions:Scoring:*`):
|
||||
|
||||
| Input | Default |
|
||||
|-------|---------|
|
||||
| `reachableConfidence` | `0.75` |
|
||||
| `unreachableConfidence` | `0.25` |
|
||||
| `runtimeBonus` | `0.15` |
|
||||
| `minConfidence` | `0.05` |
|
||||
| `maxConfidence` | `0.99` |
|
||||
|
||||
Rules:
|
||||
|
||||
- Base confidence is `reachableConfidence` when `reachable=true`, otherwise `unreachableConfidence`.
|
||||
- When `reachable=true` and runtime evidence overlaps the selected path, add `runtimeBonus` (bounded by `maxConfidence`).
|
||||
- The final confidence is clamped to `[minConfidence, maxConfidence]`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Unknowns pressure (missing/ambiguous evidence)
|
||||
|
||||
Signals tracks unresolved symbols/edges as **Unknowns** (see `docs/signals/unknowns-registry.md`). The number of unknowns for a subject influences the final score:
|
||||
|
||||
```
|
||||
UNOBSERVED (0–9)
|
||||
< POSSIBLE (10–29)
|
||||
< STATIC_PATH (30–59)
|
||||
< DYNAMIC_SEEN (60–79)
|
||||
< DYNAMIC_USER_TAINTED (80–99)
|
||||
< EXPLOIT_CONSTRAINTS_REMOVED (100)
|
||||
unknownsPressure = unknownsCount / (targetsCount + unknownsCount)
|
||||
pressurePenalty = min(unknownsPenaltyCeiling, unknownsPressure)
|
||||
fact.score = avg(states[i].score) * (1 - pressurePenalty)
|
||||
```
|
||||
|
||||
Each state corresponds to increasing confidence that a vulnerability can execute. Mitigations reduce scores; policy gates map scores to VEX statuses (`not_affected`, `under_investigation`, `affected`).
|
||||
Default `unknownsPenaltyCeiling` is `0.35` (configurable).
|
||||
|
||||
This keeps the system deterministic while preventing unknown-heavy subjects from appearing "safe" by omission.
|
||||
|
||||
---
|
||||
|
||||
## 2. Core types
|
||||
## 5. Evidence references & determinism anchors
|
||||
|
||||
```csharp
|
||||
public enum ReachState { Unobserved, Possible, StaticPath, DynamicSeen, DynamicUserTainted, ExploitConstraintsRemoved }
|
||||
Signals produces stable references intended for downstream evidence chains:
|
||||
|
||||
public enum EvidenceKind {
|
||||
StaticCallEdge, StaticEntryPointProximity, StaticPackageDeclaredOnly,
|
||||
RuntimeMethodHit, RuntimeStackSample, RuntimeHttpRouteHit,
|
||||
UserInputSource, DataTaintFlow, ConfigFlagOn, ConfigFlagOff,
|
||||
ContainerNetworkRestricted, ContainerNetworkOpen,
|
||||
WafRulePresent, PatchLevel, VendorVexNotAffected, VendorVexAffected,
|
||||
ManualOverride
|
||||
}
|
||||
- `metadata.fact.digest` — canonical digest of the reachability fact (`sha256:<hex>`).
|
||||
- `metadata.fact.version` — monotonically increasing integer for the same `subjectKey`.
|
||||
- Callgraph ingestion returns a deterministic `graphHash` (sha256) for the normalized callgraph.
|
||||
|
||||
public sealed record Evidence(
|
||||
string Id,
|
||||
EvidenceKind Kind,
|
||||
double Weight,
|
||||
string Source,
|
||||
DateTimeOffset Timestamp,
|
||||
string? ArtifactRef,
|
||||
string? Details);
|
||||
|
||||
public enum MitigationKind { WafRule, FeatureFlagDisabled, AuthZEnforced, InputValidation, PatchedVersion, ContainerNetworkIsolation, RuntimeGuard, KillSwitch, Other }
|
||||
|
||||
public sealed record Mitigation(
|
||||
string Id,
|
||||
MitigationKind Kind,
|
||||
double Strength,
|
||||
string Source,
|
||||
DateTimeOffset Timestamp,
|
||||
string? ConfigHash,
|
||||
string? Details);
|
||||
|
||||
public sealed record ReachDecision(
|
||||
string VulnerabilityId,
|
||||
string ComponentPurl,
|
||||
ReachState State,
|
||||
int Score,
|
||||
string PolicyVersion,
|
||||
IReadOnlyList<Evidence> Evidence,
|
||||
IReadOnlyList<Mitigation> Mitigations,
|
||||
IReadOnlyDictionary<string,string> Metadata);
|
||||
```
|
||||
Downstream services (Policy, UI/CLI explainers, replay tooling) should use these fields as stable evidence references.
|
||||
|
||||
---
|
||||
|
||||
## 3. Scoring policy (default)
|
||||
## 6. Policy-facing guidance (avoid false "not affected")
|
||||
|
||||
| Evidence class | Base score contribution |
|
||||
|--------------------------|-------------------------|
|
||||
| Static path (call graph) | ≥ 30 |
|
||||
| Runtime hit | ≥ 60 |
|
||||
| User-tainted flow | ≥ 80 |
|
||||
| "Constraints removed" | = 100 |
|
||||
| Lockfile-only evidence | 10 (if no other signals)|
|
||||
Policy should treat `unreachable` (or low fact score) as **insufficient** to claim "not affected" unless:
|
||||
|
||||
Mitigations subtract up to 40 points (configurable):
|
||||
- the reachability evidence is present and referenced (`metadata.fact.digest`), and
|
||||
- confidence is above a high-confidence threshold.
|
||||
|
||||
When evidence is missing or confidence is low, the correct output is **under investigation** rather than "not affected".
|
||||
|
||||
---
|
||||
|
||||
## 7. Signals API pointers
|
||||
|
||||
- `docs/api/signals/reachability-contract.md`
|
||||
- `docs/api/signals/samples/facts-sample.json`
|
||||
|
||||
---
|
||||
|
||||
## 8. Roadmap (tracked in Sprint 0401)
|
||||
|
||||
- Introduce first-class uncertainty state lists + entropy-derived `riskScore` (see `docs/uncertainty/README.md`).
|
||||
- Extend evidence refs to include CAS/DSSE pointers for graph-level and edge-bundle attestations.
|
||||
|
||||
---
|
||||
|
||||
## 9. Formal Lattice Model v1 (design — Sprint 0401)
|
||||
|
||||
The v0 bucket model provides coarse classification. The v1 lattice model introduces a formal 7-state lattice with algebraic join/meet operations for monotonic, deterministic reachability analysis across evidence types.
|
||||
|
||||
### 9.1 State Definitions
|
||||
|
||||
| State | Code | Ordering | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `Unknown` | `U` | ⊥ (bottom) | No evidence available; default state |
|
||||
| `StaticallyReachable` | `SR` | 1 | Static analysis suggests path exists |
|
||||
| `StaticallyUnreachable` | `SU` | 1 | Static analysis finds no path |
|
||||
| `RuntimeObserved` | `RO` | 2 | Runtime probe/hit confirms execution |
|
||||
| `RuntimeUnobserved` | `RU` | 2 | Runtime probe active but no hit observed |
|
||||
| `ConfirmedReachable` | `CR` | 3 | Both static + runtime agree reachable |
|
||||
| `ConfirmedUnreachable` | `CU` | 3 | Both static + runtime agree unreachable |
|
||||
| `Contested` | `X` | ⊤ (top) | Static and runtime evidence conflict |
|
||||
|
||||
### 9.2 Lattice Ordering (Hasse Diagram)
|
||||
|
||||
```
|
||||
effectiveScore = baseScore - min(sum(m.Strength), 1.0) * MaxMitigationDelta
|
||||
Contested (X)
|
||||
/ | \
|
||||
/ | \
|
||||
ConfirmedReachable | ConfirmedUnreachable
|
||||
(CR) | (CU)
|
||||
| \ / / |
|
||||
| \ / / |
|
||||
| \ / / |
|
||||
RuntimeObserved RuntimeUnobserved
|
||||
(RO) (RU)
|
||||
| |
|
||||
| |
|
||||
StaticallyReachable StaticallyUnreachable
|
||||
(SR) (SU)
|
||||
\ /
|
||||
\ /
|
||||
Unknown (U)
|
||||
```
|
||||
|
||||
Clamp final scores to 0–100.
|
||||
### 9.3 Join Rules (⊔ — least upper bound)
|
||||
|
||||
---
|
||||
When combining evidence from multiple sources, use the join operation:
|
||||
|
||||
## 4. State & VEX gates
|
||||
```
|
||||
U ⊔ S = S (any evidence beats unknown)
|
||||
SR ⊔ RO = CR (static reachable + runtime hit = confirmed)
|
||||
SU ⊔ RU = CU (static unreachable + runtime miss = confirmed)
|
||||
SR ⊔ RU = X (static reachable but runtime miss = contested)
|
||||
SU ⊔ RO = X (static unreachable but runtime hit = contested)
|
||||
CR ⊔ CU = X (conflicting confirmations = contested)
|
||||
X ⊔ * = X (contested absorbs all)
|
||||
```
|
||||
|
||||
Default thresholds (edit in `reachability.policy.yml`):
|
||||
**Full join table:**
|
||||
|
||||
| State | Score range |
|
||||
|----------------------------|-------------|
|
||||
| UNOBSERVED | 0–9 |
|
||||
| POSSIBLE | 10–29 |
|
||||
| STATIC_PATH | 30–59 |
|
||||
| DYNAMIC_SEEN | 60–79 |
|
||||
| DYNAMIC_USER_TAINTED | 80–99 |
|
||||
| EXPLOIT_CONSTRAINTS_REMOVED| 100 |
|
||||
| ⊔ | U | SR | SU | RO | RU | CR | CU | X |
|
||||
|---|---|----|----|----|----|----|----|---|
|
||||
| **U** | U | SR | SU | RO | RU | CR | CU | X |
|
||||
| **SR** | SR | SR | X | CR | X | CR | X | X |
|
||||
| **SU** | SU | X | SU | X | CU | X | CU | X |
|
||||
| **RO** | RO | CR | X | RO | X | CR | X | X |
|
||||
| **RU** | RU | X | CU | X | RU | X | CU | X |
|
||||
| **CR** | CR | CR | X | CR | X | CR | X | X |
|
||||
| **CU** | CU | X | CU | X | CU | X | CU | X |
|
||||
| **X** | X | X | X | X | X | X | X | X |
|
||||
|
||||
VEX mapping:
|
||||
### 9.4 Meet Rules (⊓ — greatest lower bound)
|
||||
|
||||
* **not_affected**: score ≤ 25 or mitigations dominate (score reduced below threshold).
|
||||
* **affected**: score ≥ 60 (dynamic evidence without sufficient mitigation).
|
||||
* **under_investigation**: everything between. **This explicit "Unknown" state is a key differentiator**—incomplete data never leads to false safety.
|
||||
Used for conservative intersection (e.g., multi-entry-point consensus):
|
||||
|
||||
Each decision records `reachability.policy.version`, analyzer versions, policy hash, and config snapshot so downstream verifiers can replay the exact logic. All decisions are sealed in Decision Capsules for audit-grade reproducibility.
|
||||
```
|
||||
U ⊓ * = U (unknown is bottom)
|
||||
CR ⊓ CR = CR (agreement preserved)
|
||||
X ⊓ S = S (drop contested to either side)
|
||||
```
|
||||
|
||||
---
|
||||
### 9.5 Monotonicity Properties
|
||||
|
||||
## 5. Evidence sources
|
||||
1. **Evidence accumulation is monotonic:** Once state rises in the lattice, it cannot descend without explicit revocation.
|
||||
2. **Revocation resets to Unknown:** When evidence is invalidated (e.g., graph invalidation), state resets to `U`.
|
||||
3. **Contested states require human triage:** `X` state triggers policy flags and UI attention.
|
||||
|
||||
| Signal group | Producers | EvidenceKind |
|
||||
|--------------|-----------|--------------|
|
||||
| Static call graph | Roslyn/IL walkers, ASP.NET routing models, JVM/JIT analyzers | `StaticCallEdge`, `StaticEntryPointProximity`, `StaticFrameworkRouteEdge` |
|
||||
| Runtime sampling | .NET EventPipe, JFR, Node inspector, Go/Rust probes | `RuntimeMethodHit`, `RuntimeStackSample`, `RuntimeHttpRouteHit` |
|
||||
| Data/taint | Taint analyzers, user-input detectors | `UserInputSource`, `DataTaintFlow` |
|
||||
| Environment | Config snapshot, container args, network policy | `ConfigFlagOn/Off`, `ContainerNetworkRestricted/Open` |
|
||||
| Mitigations | WAF connectors, patch diff, kill switches | `MitigationKind.*` via `Mitigation` records |
|
||||
| Trust | Vendor VEX statements, manual overrides | `VendorVexNotAffected/Affected`, `ManualOverride` |
|
||||
### 9.6 Mapping v0 Buckets to v1 States
|
||||
|
||||
Each evidence object **must** log `Source`, timestamps, and references (function IDs, config hashes) so auditors can trace it in the event graph. This enables **evidence-linked VEX decisions** where every assertion includes pointers to the underlying proof.
|
||||
| v0 Bucket | v1 State(s) | Notes |
|
||||
|-----------|-------------|-------|
|
||||
| `unreachable` | `SU`, `CU` | Depends on runtime evidence availability |
|
||||
| `entrypoint` | `CR` | Entry points are by definition reachable |
|
||||
| `runtime` | `RO`, `CR` | Depends on static analysis agreement |
|
||||
| `direct` | `SR`, `CR` | Direct paths with/without runtime confirmation |
|
||||
| `unknown` | `U` | No evidence available |
|
||||
|
||||
---
|
||||
### 9.7 Policy Decision Matrix
|
||||
|
||||
## 6. Event graph schema
|
||||
| v1 State | VEX "not_affected" | VEX "affected" | VEX "under_investigation" |
|
||||
|----------|-------------------|----------------|---------------------------|
|
||||
| `U` | ❌ blocked | ⚠️ needs evidence | ✅ default |
|
||||
| `SR` | ❌ blocked | ✅ allowed | ✅ allowed |
|
||||
| `SU` | ⚠️ low confidence | ❌ contested | ✅ allowed |
|
||||
| `RO` | ❌ blocked | ✅ allowed | ✅ allowed |
|
||||
| `RU` | ⚠️ medium confidence | ❌ contested | ✅ allowed |
|
||||
| `CR` | ❌ blocked | ✅ required | ❌ invalid |
|
||||
| `CU` | ✅ allowed | ❌ blocked | ❌ invalid |
|
||||
| `X` | ❌ blocked | ❌ blocked | ✅ required |
|
||||
|
||||
Persist function-level edges and evidence in Mongo (or your event store) under:
|
||||
### 9.8 Implementation Notes
|
||||
|
||||
* `reach_functions` – documents keyed by `FunctionId`.
|
||||
* `reach_call_sites` – `CallSite` edges (`caller`, `callee`, `frameworkEdge`).
|
||||
* `reach_evidence` – array of `Evidence` per `(scanId, vulnId, component)`.
|
||||
* `reach_mitigations` – array of `Mitigation` entries with config hashes.
|
||||
* `reach_decisions` – final `ReachDecision` document; references above IDs.
|
||||
- **State storage:** `ReachabilityFactDocument.states[].latticeState` field (enum)
|
||||
- **Join implementation:** `ReachabilityLattice.Join(a, b)` in `src/Signals/StellaOps.Signals/Services/`
|
||||
- **Backward compatibility:** v0 bucket computed from v1 state for API consumers
|
||||
|
||||
All collections are tenant-scoped and include analyzer/policy version metadata.
|
||||
### 9.9 Evidence Chain Requirements
|
||||
|
||||
---
|
||||
|
||||
## 7. Policy gates → VEX decisions
|
||||
|
||||
VEXer consumes `ReachDecision` and `reachability.policy.yml` to emit:
|
||||
Each lattice state transition must be accompanied by evidence references:
|
||||
|
||||
```json
|
||||
{
|
||||
"vulnerability": "CVE-2025-1234",
|
||||
"products": ["pkg:nuget/Example@1.2.3"],
|
||||
"status": "not_affected|under_investigation|affected",
|
||||
"status_notes": "Reachability score 22 (Possible) with WAF rule mitigation.",
|
||||
"justification": "component_not_present|vulnerable_code_not_present|... or custom reason",
|
||||
"action_statement": "Monitor config ABC",
|
||||
"impact_statement": "Runtime probes observed 0 hits; static call graph absent.",
|
||||
"timestamp": "...",
|
||||
"custom": {
|
||||
"reachability": {
|
||||
"state": "POSSIBLE",
|
||||
"score": 22,
|
||||
"policyVersion": "reach-1",
|
||||
"evidenceRefs": ["evidence:123", "mitigation:456"]
|
||||
"symbol": "sym:java:...",
|
||||
"latticeState": "CR",
|
||||
"previousState": "SR",
|
||||
"evidence": {
|
||||
"static": {
|
||||
"graphHash": "blake3:...",
|
||||
"pathLength": 3,
|
||||
"confidence": 0.92
|
||||
},
|
||||
"runtime": {
|
||||
"probeId": "probe:...",
|
||||
"hitCount": 47,
|
||||
"observedAt": "2025-12-13T10:00:00Z"
|
||||
}
|
||||
}
|
||||
},
|
||||
"transitionAt": "2025-12-13T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Justifications cite specific evidence/mitigation IDs so replay bundles (`docs/replay/DETERMINISTIC_REPLAY.md`) can prove the decision.
|
||||
|
||||
---
|
||||
|
||||
## 8. Runtime probes (overview)
|
||||
|
||||
* .NET: EventPipe session watching `Microsoft-Windows-DotNETRuntime/Loader,JIT` → `RuntimeMethodHit`.
|
||||
* JVM: JFR recording with `MethodProfilingSample` events.
|
||||
* Node/TS: Inspector or `--trace-event-categories node.async_hooks,node.perf` sample.
|
||||
* Go/Rust: `pprof`/probe instrumentation.
|
||||
|
||||
All runtime probes write evidence via `IRuntimeEvidenceSink`, which deduplicates hits, enriches them with `FunctionId`, and stores them in `reach_evidence`.
|
||||
|
||||
See `src/Scanner/StellaOps.Scanner.WebService/Reachability/Runtime/DotNetRuntimeProbe.cs` (once implemented) for reference.
|
||||
|
||||
---
|
||||
|
||||
## 9. Hybrid Reachability
|
||||
|
||||
<!-- TODO: Review for separate approval - added hybrid reachability section -->
|
||||
Stella Ops combines **static call-graph analysis** with **runtime process tracing** for true hybrid reachability:
|
||||
|
||||
- **Static analysis** provides call-graph edges from IL/bytecode analysis, framework routing models, and entry-point proximity calculations.
|
||||
- **Runtime analysis** provides observed method hits, stack samples, and HTTP route hits from live or shadow traffic.
|
||||
- **Hybrid reconciliation** merges both signal types, with each edge type attestable via DSSE. See `docs/reachability/hybrid-attestation.md` for the attestation model.
|
||||
|
||||
This hybrid approach ensures that both build-time and run-time context contribute to the same verdict, avoiding the blind spots of purely static or purely runtime analysis.
|
||||
|
||||
---
|
||||
|
||||
## 10. Roadmap
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
| `REACH-LATTICE-401-023` | Initial lattice types + scoring engine + event graph schema. |
|
||||
| `REACH-RUNTIME-402-024` | Productionize runtime probes (EventPipe/JFR) with opt-in config and telemetry. |
|
||||
| `REACH-VEX-402-025` | Wire `ReachDecision` into VEX generator; ensure OpenVEX/CSAF cite reachability evidence. |
|
||||
| `REACH-POLICY-402-026` | Expose reachability gates in Policy DSL & CLI (edit/lint/test). |
|
||||
|
||||
Keep this doc updated as the lattice evolves or new signals/mitigations are added.
|
||||
|
||||
269
docs/reachability/policy-gate.md
Normal file
269
docs/reachability/policy-gate.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# Reachability Evidence Policy Gates
|
||||
|
||||
> **Status:** Design v1 (Sprint 0401)
|
||||
> **Owners:** Policy Guild, Signals Guild, VEX Guild
|
||||
|
||||
This document defines the policy gates that enforce reachability evidence requirements for VEX decisions. Gates prevent unsafe "not_affected" claims when evidence is insufficient.
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
Policy gates act as checkpoints between evidence (reachability lattice state, uncertainty tier) and VEX status transitions. They ensure that:
|
||||
|
||||
1. **No false safety:** "not_affected" requires strong evidence of unreachability
|
||||
2. **Explicit uncertainty:** Missing evidence triggers "under_investigation" rather than silence
|
||||
3. **Audit trail:** All gate decisions are logged with evidence references
|
||||
|
||||
---
|
||||
|
||||
## 2. Gate Types
|
||||
|
||||
### 2.1 Lattice State Gate
|
||||
|
||||
Guards VEX status transitions based on the v1 lattice state (see `docs/reachability/lattice.md` §9).
|
||||
|
||||
| Requested VEX Status | Required Lattice State | Gate Action |
|
||||
|---------------------|------------------------|-------------|
|
||||
| `not_affected` | `CU` (ConfirmedUnreachable) | ✅ Allow |
|
||||
| `not_affected` | `SU` (StaticallyUnreachable) | ⚠️ Allow with warning, requires `justification` |
|
||||
| `not_affected` | `RU` (RuntimeUnobserved) | ⚠️ Allow with warning, requires `justification` |
|
||||
| `not_affected` | `U`, `SR`, `RO`, `CR`, `X` | ❌ Block |
|
||||
| `affected` | `CR` (ConfirmedReachable) | ✅ Allow |
|
||||
| `affected` | `SR`, `RO` | ✅ Allow |
|
||||
| `affected` | `U`, `SU`, `RU`, `CU`, `X` | ⚠️ Warn (potential false positive) |
|
||||
| `under_investigation` | Any | ✅ Allow (safe default) |
|
||||
| `fixed` | Any | ✅ Allow (remediation action) |
|
||||
|
||||
### 2.2 Uncertainty Tier Gate
|
||||
|
||||
Guards VEX status transitions based on the uncertainty tier (see `docs/uncertainty/README.md` §1.1).
|
||||
|
||||
| Requested VEX Status | Uncertainty Tier | Gate Action |
|
||||
|---------------------|------------------|-------------|
|
||||
| `not_affected` | T1 (High) | ❌ Block |
|
||||
| `not_affected` | T2 (Medium) | ⚠️ Warn, require explicit override |
|
||||
| `not_affected` | T3 (Low) | ⚠️ Allow with advisory note |
|
||||
| `not_affected` | T4 (Negligible) | ✅ Allow |
|
||||
| `affected` | T1 (High) | ⚠️ Review required (may be false positive) |
|
||||
| `affected` | T2-T4 | ✅ Allow |
|
||||
|
||||
### 2.3 Evidence Completeness Gate
|
||||
|
||||
Guards based on the presence of required evidence artifacts.
|
||||
|
||||
| VEX Status | Required Evidence | Gate Action if Missing |
|
||||
|------------|-------------------|----------------------|
|
||||
| `not_affected` | `graphHash` (DSSE-attested) | ❌ Block |
|
||||
| `not_affected` | `pathAnalysis.pathLength >= 0` | ❌ Block |
|
||||
| `not_affected` | `confidence >= 0.8` | ⚠️ Warn if < 0.8 |
|
||||
| `affected` | `graphHash` OR `runtimeProbe` | ⚠️ Warn if neither |
|
||||
| `under_investigation` | None required | ✅ Allow |
|
||||
|
||||
---
|
||||
|
||||
## 3. Gate Evaluation Order
|
||||
|
||||
Gates are evaluated in this order; first blocking gate stops evaluation:
|
||||
|
||||
```
|
||||
1. Evidence Completeness Gate → Block if required evidence missing
|
||||
2. Lattice State Gate → Block if state incompatible with status
|
||||
3. Uncertainty Tier Gate → Block/warn based on tier
|
||||
4. Confidence Threshold Gate → Warn if confidence below threshold
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Gate Decision Document
|
||||
|
||||
Each gate evaluation produces a decision document:
|
||||
|
||||
```json
|
||||
{
|
||||
"gateId": "gate:vex:not_affected:2025-12-13T10:00:00Z",
|
||||
"requestedStatus": "not_affected",
|
||||
"subject": {
|
||||
"vulnId": "CVE-2025-12345",
|
||||
"purl": "pkg:maven/com.example/foo@1.0.0",
|
||||
"symbolId": "sym:java:..."
|
||||
},
|
||||
"evidence": {
|
||||
"latticeState": "CU",
|
||||
"uncertaintyTier": "T3",
|
||||
"graphHash": "blake3:...",
|
||||
"riskScore": 0.25,
|
||||
"confidence": 0.92
|
||||
},
|
||||
"gates": [
|
||||
{
|
||||
"name": "EvidenceCompleteness",
|
||||
"result": "pass",
|
||||
"reason": "graphHash present"
|
||||
},
|
||||
{
|
||||
"name": "LatticeState",
|
||||
"result": "pass",
|
||||
"reason": "CU allows not_affected"
|
||||
},
|
||||
{
|
||||
"name": "UncertaintyTier",
|
||||
"result": "pass_with_note",
|
||||
"reason": "T3 allows with advisory note",
|
||||
"note": "MissingPurl uncertainty at 35% entropy"
|
||||
}
|
||||
],
|
||||
"decision": "allow",
|
||||
"advisory": "VEX status allowed with note: T3 uncertainty from MissingPurl",
|
||||
"decidedAt": "2025-12-13T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Contested State Handling
|
||||
|
||||
When lattice state is `X` (Contested):
|
||||
|
||||
1. **Block all definitive statuses:** Neither "not_affected" nor "affected" allowed
|
||||
2. **Force "under_investigation":** Auto-assign until triage resolves conflict
|
||||
3. **Emit triage event:** Notify VEX operators of conflict with evidence links
|
||||
4. **Evidence overlay:** Show both static and runtime evidence for manual review
|
||||
|
||||
### Contested Resolution Workflow
|
||||
|
||||
```
|
||||
1. System detects X state
|
||||
2. VEX status locked to "under_investigation"
|
||||
3. Triage event emitted to operator queue
|
||||
4. Operator reviews:
|
||||
a. Static evidence (graph, paths)
|
||||
b. Runtime evidence (probes, hits)
|
||||
5. Operator provides resolution:
|
||||
a. Trust static → state becomes SU/SR
|
||||
b. Trust runtime → state becomes RU/RO
|
||||
c. Add new evidence → recompute lattice
|
||||
6. Gate re-evaluates with new state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Override Mechanism
|
||||
|
||||
Operators with `vex:gate:override` permission can bypass gates with mandatory fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"override": {
|
||||
"gateId": "gate:vex:not_affected:...",
|
||||
"operator": "user:alice@example.com",
|
||||
"justification": "Manual review confirms code path is dead code",
|
||||
"evidence": {
|
||||
"type": "ManualReview",
|
||||
"reviewId": "review:2025-12-13:001",
|
||||
"attachments": ["cas://evidence/review/..."]
|
||||
},
|
||||
"approvedAt": "2025-12-13T11:00:00Z",
|
||||
"expiresAt": "2026-01-13T11:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Override requirements:
|
||||
- `justification` is mandatory and logged
|
||||
- Overrides expire after configurable period (default: 30 days)
|
||||
- All overrides are auditable and appear in compliance reports
|
||||
|
||||
---
|
||||
|
||||
## 7. Configuration
|
||||
|
||||
Gate thresholds are configurable via `PolicyGatewayOptions`:
|
||||
|
||||
```yaml
|
||||
PolicyGateway:
|
||||
Gates:
|
||||
LatticeState:
|
||||
AllowSUForNotAffected: true # Allow SU with warning
|
||||
AllowRUForNotAffected: true # Allow RU with warning
|
||||
RequireJustificationForWeakStates: true
|
||||
UncertaintyTier:
|
||||
BlockT1ForNotAffected: true
|
||||
WarnT2ForNotAffected: true
|
||||
EvidenceCompleteness:
|
||||
RequireGraphHashForNotAffected: true
|
||||
MinConfidenceForNotAffected: 0.8
|
||||
MinConfidenceWarning: 0.6
|
||||
Override:
|
||||
DefaultExpirationDays: 30
|
||||
RequireJustification: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. API Integration
|
||||
|
||||
### POST `/api/v1/vex/status`
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"vulnId": "CVE-2025-12345",
|
||||
"purl": "pkg:maven/com.example/foo@1.0.0",
|
||||
"status": "not_affected",
|
||||
"justification": "vulnerable_code_not_present",
|
||||
"reachabilityEvidence": {
|
||||
"factDigest": "sha256:...",
|
||||
"graphHash": "blake3:..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response (gate blocked):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"gateDecision": {
|
||||
"decision": "block",
|
||||
"blockedBy": "LatticeState",
|
||||
"reason": "Lattice state SR (StaticallyReachable) incompatible with not_affected",
|
||||
"currentState": "SR",
|
||||
"requiredStates": ["CU", "SU", "RU"],
|
||||
"suggestion": "Submit runtime probe evidence or change to under_investigation"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Metrics & Alerts
|
||||
|
||||
The policy gateway emits metrics:
|
||||
|
||||
| Metric | Labels | Description |
|
||||
|--------|--------|-------------|
|
||||
| `stellaops_gate_decisions_total` | `gate`, `result`, `status` | Total gate decisions |
|
||||
| `stellaops_gate_blocks_total` | `gate`, `reason` | Total blocked requests |
|
||||
| `stellaops_gate_overrides_total` | `operator` | Total override uses |
|
||||
| `stellaops_contested_states_total` | `vulnId` | Active contested states |
|
||||
|
||||
Alert conditions:
|
||||
- `stellaops_gate_overrides_total` rate > threshold → Audit review
|
||||
- `stellaops_contested_states_total` > 10 → Triage backlog alert
|
||||
|
||||
---
|
||||
|
||||
## 10. Related Documents
|
||||
|
||||
- [Lattice Model](./lattice.md) — v1 formal 7-state lattice
|
||||
- [Uncertainty States](../uncertainty/README.md) — Tier definitions and risk scoring
|
||||
- [Evidence Schema](./evidence-schema.md) — richgraph-v1 schema
|
||||
- [VEX Contract](../contracts/vex-v1.md) — VEX document schema
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 1.0.0 | 2025-12-13 | Policy Guild | Initial design from Sprint 0401 |
|
||||
Reference in New Issue
Block a user