partly or unimplemented features - now implemented
This commit is contained in:
master
@@ -226,6 +226,191 @@ All artifacts are identified by BLAKE3-256 digest:
|
||||
- [PoE Predicate Spec](../../../src/Attestor/POE_PREDICATE_SPEC.md)
|
||||
- [Module AGENTS.md](../../../src/__Libraries/StellaOps.ReachGraph/AGENTS.md)
|
||||
|
||||
## Unified Query Interface
|
||||
|
||||
The ReachGraph module exposes a **Unified Reachability Query API** that provides a single facade for static, runtime, and hybrid queries.
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/v1/reachability/static` | POST | Query static reachability from call graph analysis |
|
||||
| `/v1/reachability/runtime` | POST | Query runtime reachability from observed execution facts |
|
||||
| `/v1/reachability/hybrid` | POST | Combine static and runtime for best-effort verdict |
|
||||
| `/v1/reachability/batch` | POST | Batch query for CVE vulnerability analysis |
|
||||
|
||||
### Adapters
|
||||
|
||||
The unified query interface is backed by two adapters:
|
||||
|
||||
1. **ReachGraphStoreAdapter**: Implements `IReachGraphAdapter` from `StellaOps.Reachability.Core`
|
||||
- Queries static reachability from stored call graphs
|
||||
- Uses BFS from entrypoints to target symbols
|
||||
- Returns `StaticReachabilityResult` with distance, path, and evidence URIs
|
||||
|
||||
2. **InMemorySignalsAdapter**: Implements `ISignalsAdapter` from `StellaOps.Reachability.Core`
|
||||
- Queries runtime observation facts
|
||||
- Supports observation window filtering
|
||||
- Returns `RuntimeReachabilityResult` with hit count, contexts, and evidence URIs
|
||||
- Note: Production deployments should integrate with the actual Signals runtime service
|
||||
|
||||
### Hybrid Query Flow
|
||||
|
||||
```
|
||||
┌────────────────┐
|
||||
│ Hybrid Query │
|
||||
│ Request │
|
||||
└───────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────────┐
|
||||
│ ReachabilityIndex Facade │
|
||||
│ (StellaOps.Reachability.Core) │
|
||||
└───────┬───────────────────────┬───────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐
|
||||
│ ReachGraph │ │ Signals │
|
||||
│ StoreAdapter │ │ Adapter │
|
||||
└───────┬───────┘ └───────┬───────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐
|
||||
│ PostgreSQL + │ │ Runtime Facts │
|
||||
│ Valkey Cache │ │ (In-Memory) │
|
||||
└───────────────┘ └───────────────┘
|
||||
```
|
||||
|
||||
### Query Models
|
||||
|
||||
**SymbolRef** - Identifies a code symbol:
|
||||
```json
|
||||
{
|
||||
"namespace": "System.Net.Http",
|
||||
"typeName": "HttpClient",
|
||||
"memberName": "GetAsync"
|
||||
}
|
||||
```
|
||||
|
||||
**StaticReachabilityResult**:
|
||||
```json
|
||||
{
|
||||
"symbol": { "namespace": "...", "typeName": "...", "memberName": "..." },
|
||||
"artifactDigest": "sha256:abc123...",
|
||||
"isReachable": true,
|
||||
"distanceFromEntrypoint": 3,
|
||||
"path": ["entry -> A -> B -> target"],
|
||||
"evidenceUris": ["stella:evidence/reachgraph/sha256:abc123/symbol:..."]
|
||||
}
|
||||
```
|
||||
|
||||
**RuntimeReachabilityResult**:
|
||||
```json
|
||||
{
|
||||
"symbol": { ... },
|
||||
"artifactDigest": "sha256:abc123...",
|
||||
"wasObserved": true,
|
||||
"hitCount": 1250,
|
||||
"firstSeen": "2025-06-10T08:00:00Z",
|
||||
"lastSeen": "2025-06-15T12:00:00Z",
|
||||
"contexts": [{ "environment": "production", "service": "api-gateway" }],
|
||||
"evidenceUris": ["stella:evidence/signals/sha256:abc123/symbol:..."]
|
||||
}
|
||||
```
|
||||
|
||||
**HybridReachabilityResult**:
|
||||
```json
|
||||
{
|
||||
"symbol": { ... },
|
||||
"artifactDigest": "sha256:abc123...",
|
||||
"staticResult": { ... },
|
||||
"runtimeResult": { ... },
|
||||
"confidence": 0.92,
|
||||
"verdict": "reachable",
|
||||
"reasoning": "Static analysis shows 3-hop path; runtime confirms 1250 observations"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 2025-12-27_
|
||||
## 14. Lattice Triage Service
|
||||
|
||||
### Overview
|
||||
|
||||
The Lattice Triage Service provides a workflow-oriented surface on top of the
|
||||
8-state reachability lattice, enabling operators to visualise lattice states,
|
||||
apply evidence, perform manual overrides, and maintain a full audit trail of
|
||||
every state transition.
|
||||
|
||||
Library: `StellaOps.Reachability.Core`
|
||||
Namespace: `StellaOps.Reachability.Core`
|
||||
|
||||
### Models
|
||||
|
||||
| Type | Purpose |
|
||||
|------|---------|
|
||||
| `LatticeTriageEntry` | Per-(component, CVE) snapshot: current state, confidence, VEX status, full transition history. Content-addressed `EntryId` (`triage:sha256:…`). Computed `RequiresReview` / `HasOverride`. |
|
||||
| `LatticeTransitionRecord` | Immutable log entry per state change: from/to state, confidence before/after, trigger, reason, actor, evidence digests, timestamp. Computed `IsManualOverride`. |
|
||||
| `LatticeTransitionTrigger` | Enum: `StaticAnalysis`, `RuntimeObservation`, `ManualOverride`, `SystemReset`, `AutomatedRule`. Serialised as `JsonStringEnumConverter`. |
|
||||
| `LatticeOverrideRequest` | Operator request to force a target state with reason, actor, and evidence digests. |
|
||||
| `LatticeOverrideResult` | Outcome of an override: applied flag, updated entry, transition, optional warning. |
|
||||
| `LatticeTriageQuery` | Filters: `State?`, `RequiresReview?`, `ComponentPurlPrefix?`, `Cve?`, `Limit` (default 100), `Offset`. |
|
||||
|
||||
### Service Interface (`ILatticeTriageService`)
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `GetOrCreateEntryAsync(purl, cve)` | Returns existing entry or creates one at `Unknown` state. |
|
||||
| `ApplyEvidenceAsync(purl, cve, evidenceType, digests, actor, reason)` | Delegates to `ReachabilityLattice.ApplyEvidence`, records transition. |
|
||||
| `OverrideStateAsync(request)` | Forces target state via Reset + ForceState sequence. Warns when overriding `Confirmed*` states. |
|
||||
| `ListAsync(query)` | Filters + pages entries; ordered by `UpdatedAt` descending. |
|
||||
| `GetHistoryAsync(purl, cve)` | Returns full transition log for an entry. |
|
||||
| `ResetAsync(purl, cve, actor, reason)` | Resets entry to `Unknown`, records `SystemReset` transition. |
|
||||
|
||||
### VEX Status Mapping
|
||||
|
||||
| Lattice State | VEX Status |
|
||||
|---------------|------------|
|
||||
| `Unknown`, `StaticReachable`, `Contested` | `under_investigation` |
|
||||
| `StaticUnreachable`, `RuntimeUnobserved`, `ConfirmedUnreachable` | `not_affected` |
|
||||
| `RuntimeObserved`, `ConfirmedReachable` | `affected` |
|
||||
|
||||
### Manual Override Behaviour
|
||||
|
||||
When an operator overrides state, the service:
|
||||
1. Resets the lattice to `Unknown`.
|
||||
2. Applies the minimal evidence sequence to reach the target state (e.g., `ConfirmedReachable` = `StaticReachable` + `RuntimeObserved`).
|
||||
3. Sets confidence to the midpoint of the target state's confidence range.
|
||||
4. Returns a **warning** when overriding from `ConfirmedReachable` or `ConfirmedUnreachable`, since these are high-certainty states.
|
||||
|
||||
### DI Registration
|
||||
|
||||
`AddReachabilityCore()` registers `ILatticeTriageService → LatticeTriageService` (singleton, via `TryAddSingleton`).
|
||||
|
||||
### Observability (OTel Metrics)
|
||||
|
||||
Meter: `StellaOps.Reachability.Core.Triage`
|
||||
|
||||
| Metric | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `reachability.triage.entries_created` | Counter | Entries created |
|
||||
| `reachability.triage.evidence_applied` | Counter | Evidence applications |
|
||||
| `reachability.triage.overrides_applied` | Counter | Manual overrides |
|
||||
| `reachability.triage.resets` | Counter | Lattice resets |
|
||||
| `reachability.triage.contested` | Counter | Contested state transitions |
|
||||
|
||||
### Test Coverage
|
||||
|
||||
22 tests in `StellaOps.Reachability.Core.Tests/LatticeTriageServiceTests.cs`:
|
||||
- Entry creation (new, idempotent, distinct keys)
|
||||
- Evidence application (static→reachable, confirmed paths, conflicting→contested, digest recording)
|
||||
- Override (target state, warnings on confirmed, HasOverride flag)
|
||||
- Listing with filters (state, review, PURL prefix)
|
||||
- History retrieval
|
||||
- Reset transitions
|
||||
- VEX mapping (theory test)
|
||||
- Edge-case validation (null PURL, empty reason)
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 2026-02-08_
|
||||
|
||||
Reference in New Issue
Block a user