stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
359fafa9da86cf6722ed82bf90d67db9c8f81b17
git.stella-ops.org/docs/features/unimplemented/binaryindex/binary-resolution-api-with-cache-layer.md
master 5bca406787 save checkpoint: save features
2026-02-12 10:27:23 +02:00

3.1 KiB
Raw Blame History

Binary Resolution API with Cache Layer

Module

BinaryIndex

Status

PARTIALLY_IMPLEMENTED

Description

REST API endpoints (POST /api/v1/resolve/vuln and /vuln/batch) for querying whether a CVE is resolved through binary-level backport detection. Includes Valkey-backed response caching, rate limiting middleware, and telemetry instrumentation.

Implementation Details

  • Modules: src/BinaryIndex/StellaOps.BinaryIndex.WebService/, src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/, src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/
  • Key Classes:
    • ResolutionController (src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/ResolutionController.cs) - REST API controller with POST /api/v1/resolve/vuln and /vuln/batch endpoints
    • ResolutionService (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Resolution/ResolutionService.cs) - core resolution logic
    • CachedResolutionService (src/BinaryIndex/StellaOps.BinaryIndex.WebService/Services/CachedResolutionService.cs) - decorator adding Valkey-backed caching around ResolutionService
    • ResolutionCacheService (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/ResolutionCacheService.cs) - Valkey cache operations for resolution results
    • RateLimitingMiddleware (src/BinaryIndex/StellaOps.BinaryIndex.WebService/Middleware/RateLimitingMiddleware.cs) - per-tenant rate limiting with X-RateLimit headers
    • ResolutionTelemetry (src/BinaryIndex/StellaOps.BinaryIndex.WebService/Telemetry/ResolutionTelemetry.cs) - OpenTelemetry metrics for resolution requests, cache hits, rate limits
  • Contracts: VulnResolutionRequest/Response, ResolutionMatchTypes (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Contracts/Resolution/VulnResolutionContracts.cs)
  • Cache Options: BinaryCacheOptions, CacheOptionsValidation (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/)

E2E Test Plan

  • Send POST /api/v1/resolve/vuln with a known CVE and package purl, verify resolution response contains match type (BuildId, DeltaSignature, etc.)
  • Send batch request to /api/v1/resolve/vuln/batch with multiple packages and verify all are resolved
  • Verify cache hit: send same request twice and confirm second response comes from cache (check telemetry counters)
  • Verify rate limiting: exceed the configured request limit and confirm 429 response with X-RateLimit headers
  • Verify telemetry: confirm resolution metrics are emitted (request count, cache hit ratio, latency histogram)
  • Verify disabled rate limiting mode passes requests through without headers

Verification Outcome

  • Tier 0/1/2 artifacts: docs/qa/feature-checks/runs/binaryindex/binary-resolution-api-with-cache-layer/run-002/.
  • Result: not implemented at claim parity.
  • Missing behavior:
    • Default runtime wiring uses InMemoryBinaryVulnerabilityService, so real BuildId/DeltaSignature vulnerability matching claims are not realized.
    • Resolution telemetry counters are not invoked end-to-end from controller/service request flow.
    • Tier 2 endpoint responses validate HTTP status behavior but do not establish production-grade CVE resolution semantics.