Advisory Lens Architecture

Status: Archived (2026-03-04). AdvisoryLens is preserved under src/__Libraries/_archived/StellaOps.AdvisoryLens/ with tests at src/__Libraries/_archived/StellaOps.AdvisoryLens.Tests/. It was archived in Sprint 217 after consumer verification confirmed zero production usage.

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/_archived/StellaOps.AdvisoryLens/
Tests: src/__Libraries/_archived/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

CaseMatcher evaluates each CasePattern against the input AdvisoryCase
Scoring factors are severity range match, PURL ecosystem match, and CVE pattern match
Disqualifying mismatches (severity out of range, wrong ecosystem) return score 0.0
If no factors are configured for a pattern, score defaults to 0.5
Positive-score matches are sorted by score descending, then PatternId ascending for deterministic tie-breaking
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

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

3.0 KiB Raw Blame History