64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# Advisory Lens Architecture
|
|
|
|
## Purpose
|
|
|
|
StellaOps.AdvisoryLens is a deterministic, offline-first library for semantic case matching of vulnerability advisories. It produces ranked suggestions and contextual hints without AI/LLM inference.
|
|
|
|
## Scope
|
|
|
|
- Working directory: `src/__Libraries/StellaOps.AdvisoryLens/`
|
|
- Tests: `src/__Libraries/__Tests/StellaOps.AdvisoryLens.Tests/`
|
|
- Integration entry point: `services.AddAdvisoryLens(...)`
|
|
|
|
## Models
|
|
|
|
| Type | Purpose |
|
|
|------|---------|
|
|
| `AdvisoryCase` | Advisory input including CVE, PURL, severity, and metadata |
|
|
| `LensContext` | Evaluation envelope (advisory case, tenant id, evidence refs, optional timestamp) |
|
|
| `CasePattern` | Matching rule with severity/ecosystem/CVE conditions and default suggestion payload |
|
|
| `LensSuggestion` | Ranked operator-facing recommendation with confidence and action |
|
|
| `LensHint` | Contextual evidence hint grouped by deterministic categories |
|
|
| `LensResult` | Evaluation output containing suggestions, hints, matched pattern ids, timestamp, and input hash |
|
|
|
|
## Matching Algorithm
|
|
|
|
1. `CaseMatcher` evaluates each `CasePattern` against the input `AdvisoryCase`
|
|
2. Scoring factors are severity range match, PURL ecosystem match, and CVE pattern match
|
|
3. Disqualifying mismatches (severity out of range, wrong ecosystem) return score `0.0`
|
|
4. If no factors are configured for a pattern, score defaults to `0.5`
|
|
5. Positive-score matches are sorted by score descending, then `PatternId` ascending for deterministic tie-breaking
|
|
6. `AdvisoryLensService` maps sorted matches into suggestions with rank = position + 1
|
|
|
|
## Hint Generation
|
|
|
|
Hints are derived from `LensContext` and sorted by category ordinal then text:
|
|
|
|
- Severity: `High` or `Critical` advisories emit a priority remediation hint
|
|
- Reachability: non-empty reachability evidence emits code-path guidance
|
|
- VEX: non-empty VEX references emit a count-based hint
|
|
- Policy: non-empty policy traces emit a count-based hint
|
|
|
|
## Integration
|
|
|
|
```csharp
|
|
services.AddAdvisoryLens(patterns, timeProvider);
|
|
```
|
|
|
|
- Registers `IAdvisoryLensService` as a singleton
|
|
- Uses empty patterns when none are provided
|
|
- Uses `TimeProvider.System` when no provider is injected
|
|
|
|
## Determinism Guarantees
|
|
|
|
- Stable ordering for matches and hints
|
|
- Input hash computed as `sha256:` + SHA-256 over canonical JSON (`camelCase`, no indentation, nulls ignored)
|
|
- Timestamp comes from `LensContext.EvaluationTimestampUtc` or injected `TimeProvider`
|
|
- Identical inputs and clock source produce identical `LensResult`
|
|
|
|
## Offline Posture
|
|
|
|
- No network dependencies in library behavior
|
|
- In-process, side-effect-free evaluation and scoring
|
|
- Tests validate execution with no HTTP or external service setup
|