stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity
Files
0cb5c9abfbb4abeb778bc2371842a38cbfdcfe87
git.stella-ops.org/docs/modules/excititor/operations/graph-linkouts-implementation.md
master b7059d523e Refactor and update test projects, remove obsolete tests, and upgrade dependencies 
- Deleted obsolete test files for SchedulerAuditService and SchedulerMongoSessionFactory.
- Removed unused TestDataFactory class.
- Updated project files for Mongo.Tests to remove references to deleted files.
- Upgraded BouncyCastle.Cryptography package to version 2.6.2 across multiple projects.
- Replaced Microsoft.Extensions.Http.Polly with Microsoft.Extensions.Http.Resilience in Zastava.Webhook project.
- Updated NetEscapades.Configuration.Yaml package to version 3.1.0 in Configuration library.
- Upgraded Pkcs11Interop package to version 5.1.2 in Cryptography libraries.
- Refactored Argon2idPasswordHasher to use BouncyCastle for hashing instead of Konscious.
- Updated JsonSchema.Net package to version 7.3.2 in Microservice project.
- Updated global.json to use .NET SDK version 10.0.101.
2025-12-10 19:13:29 +02:00

3.4 KiB
Raw Blame History

Excititor · Graph Linkouts & Overlays — Implementation Notes (Graph 21-001/002/005/24-101/24-102)

  • Date: 2025-11-21
  • Scope: EXCITITOR-GRAPH-21-001, EXCITITOR-GRAPH-21-002, EXCITITOR-GRAPH-21-005
  • Status: Implementation guidance (storage wiring pending).

Endpoints

  1. Linkouts (21-001)

    • POST /internal/graph/linkouts
    • Body: tenant, purls[] (max 500), includeJustifications?, includeProvenance?
    • Response: ordered by input purls; each item includes advisories[] (advisoryId, source, status, justification?, modifiedAt, evidenceHash, connectorId, dsseEnvelopeHash?) plus conflicts[]; notFound[].

  2. Overlays (21-002)

    • GET /v1/graph/overlays?purl=<purl>&purl=<purl>&includeJustifications=true|false
    • Response per PURL: summary counts (open, not_affected, under_investigation, no_statement), latestModifiedAt, justifications[] (unique, sorted), provenance (sources[], lastEvidenceHash), cached, cacheAgeMs.

  3. Status summaries (24-101)

    • GET /v1/graph/status?purl=<purl>&purl=<purl>
    • Response mirrors overlay summaries but omits justification payloads; includes sources[], lastEvidenceHash, cached, cacheAgeMs. Intended for Vuln Explorer status colouring.

  4. Batch observations for tooltips (24-102)

    • GET /v1/graph/observations?purl=<purl>[&purl=...]&includeJustifications=true|false[&limitPerPurl=50][&cursor=<base64>]
    • Response per PURL: ordered observations[] (observationId, advisoryId, status, justification?, providerId, modifiedAt, evidenceHash, dsseEnvelopeHash?) plus truncated; top-level nextCursor, hasMore enable paging. Limits enforced per PURL and globally.

Storage & Indexes (21-005)

  • vex_observations indexes:
    • { tenant: 1, component.purl: 1, advisoryId: 1, source: 1, modifiedAt: -1 }
    • Sparse { tenant: 1, component.purl: 1, status: 1 }
  • Optional materialized vex_overlays cache: unique { tenant: 1, purl: 1 }, TTL on cachedAt driven by excititor:graph:overlayTtlSeconds (default 300s); payload must validate against docs/modules/excititor/schemas/vex_overlay.schema.json (schemaVersion 1.0.0). Bundle sample payload docs/samples/excititor/vex-overlay-sample.json in Offline Kits.

Determinism

  • Ordering: input PURL order → advisoryId → source for linkouts; overlays follow input order.
  • Truncation: max 200 advisories per PURL; when truncated, include truncated: true and nextCursor (advisoryId, source).

Config knobs

  • excititor:graph:overlayTtlSeconds (default 300)
  • excititor:graph:maxPurls (default 500)
  • excititor:graph:maxAdvisoriesPerPurl (default 200)
  • excititor:graph:maxTooltipItemsPerPurl (default 50)
  • excititor:graph:maxTooltipTotal (default 1000)

Telemetry

  • Counter excititor.graph.linkouts.requests tags: tenant, includeJustifications, includeProvenance.
  • Counter excititor.graph.overlays.cache tags: tenant, hit (true|false).
  • Histogram excititor.graph.linkouts.latency.ms tags: tenant.

Steps to implement

  • Bind GraphOptions to Excititor:Graph.
  • Add endpoints to WebService with tenant guard; enforce limits.
  • Implement overlay cache with deterministic sort; respect TTL; surface cached + cacheAgeMs.
  • Backfill Mongo indexes above.
  • Integration tests (WebApplicationFactory + Mongo2Go) for ordering, truncation, cache metadata, tenant isolation.