stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
4e5300660d55be9cbce0021a645936a5f8143a2e
git.stella-ops.org/docs/features/unchecked/binaryindex/binary-resolution-api-with-cache-layer.md

2.6 KiB
Raw Blame History

Binary Resolution API with Cache Layer

Module

BinaryIndex

Status

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