39 lines
3.1 KiB
Markdown
39 lines
3.1 KiB
Markdown
# 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.
|