git.stella-ops.org/docs/modules/scanner/design/surface-fs.md

Surface.FS Design (Epic: SURFACE-SHARING)

Status: Draft v1.1 — aligns with tasks SURFACE-FS-01..06, SCANNER-SURFACE-01..05, ZASTAVA-SURFACE-01..02, SCHED-SURFACE-01, OPS-SECRETS-01..02.

Audience: Scanner Worker/WebService, Zastava, Scheduler, DevOps. Component map: See Scanner architecture — §1 System landscape for end-to-end placement.

1. Purpose

Surface.FS provides a unified content-addressable cache for Scanner-derived artefacts (layer manifests, entry traces, SBOM fragments, runtime deltas). It enables:

• Sharing scan results between Worker, WebService, Zastava Observer/Webhook, Scheduler planners, Export Center, and future CLI operations.
• Deterministic reproduction of scan evidence (manifests and payloads) in both connected and air-gapped environments.
• Efficient data movement by storing manifests once and referencing them via stable pointers.

2. Core Concepts

2.1 Artefact Key

Each artefact is addressed by a tuple (tenant, surfaceKind, contentDigest) where contentDigest is a SHA256 of the canonical payload. surfaceKind identifies artefact type (see Manifest schema below).

2.2 Manifest

Manifests describe the artefact metadata and storage pointers. They are stored in the surface-manifests bucket and fetched by consumers before retrieving bulk data.

{
  "schema": "stellaops.surface.manifest@1",
  "tenant": "acme",
  "imageDigest": "sha256:cafe...",
  "scanId": "scan-1234",
  "generatedAt": "2025-10-29T12:00:00Z",
  "source": {
    "component": "scanner.worker",
    "version": "2025.10.0",
    "workerInstance": "scanner-worker-1",
    "attempt": 1
  },
  "artifacts": [
    {
      "kind": "entrytrace.graph",
      "uri": "cas://surface-cache/manifests/acme/ab/cd/abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789.json",
      "digest": "sha256:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
      "mediaType": "application/vnd.stellaops.entrytrace+json",
      "format": "json",
      "sizeBytes": 524288,
      "view": "runtime",
      "attestations": [
        {
          "kind": "dsse",
          "mediaType": "application/vnd.dsse+json",
          "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
          "uri": "cas://surface-cache/attestations/entrytrace.graph.dsse/e3b0c442....json"
        }
      ],
      "storage": {
        "bucket": "surface-cache",
        "objectKey": "payloads/acme/entrytrace/sha256/ab/cd/abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789.ndjson.zst",
        "sizeBytes": 524288,
        "contentType": "application/x-ndjson+zstd"
      },
      "metadata": {
        "entrypoint": "/usr/bin/java",
        "surfaceVersion": "1"
      }
    }
  ]
}

Manifest URIs follow the deterministic pattern:

cas://{bucket}/{prefix}/{tenant}/{digest[0..1]}/{digest[2..3]}/{digest}.json

The hex portion of the manifest digest is split into two directory levels to avoid hot directories. The same layout is mirrored on disk by the default FileSurfaceManifestStore, which keeps offline bundle sync trivial (copy the manifests/ tree verbatim).

Deterministic composition adds:

• Artifact kind composition.recipe (media type application/vnd.stellaops.composition.recipe+json) describing the merge recipe and Merkle root.
• attestations[] per artefact (currently DSSE envelopes) so offline kits can verify payloads without re-signing.
• determinismRoot and determinism metadata on the manifest that capture the Merkle root plus the composition recipe digest/URI.

2.3 Payload Storage

Large payloads (SBOM fragments, entry traces, runtime events) live in the same object store as manifests (RustFS/S3). Manifests record relative paths so offline bundles can copy both manifest and payload without modification.

3. APIs

Surface.FS exposes .NET-first abstractions that hosts consume via DI:

• ISurfaceManifestWriter.PublishAsync(document) – normalises artefact lists, computes the canonical SHA-256 digest, persists the manifest via the configured store, and returns a SurfaceManifestPublishResult containing the digest, canonical URI, and the normalised document.
• ISurfaceManifestReader.TryGetByUriAsync(uri) – resolves a manifest pointer (e.g. cas://surface-cache/manifests/...) back into a SurfaceManifestDocument.
• ISurfaceManifestReader.TryGetByDigestAsync(digest) – looks up a manifest by digest, scanning tenant prefixes when necessary (used by Offline Kit importers).
• ISurfaceCache (GetOrCreateAsync, TryGetAsync, SetAsync) – lightweight content-addressable cache for hot artefacts (layer fragments, entry trace outputs) hosted on local disk.

All components honour configuration bound from Surface:Cache and Surface:Manifest (or environment mirrors like SCANNER_SURFACE_CACHE_ROOT). SurfaceManifestStoreOptions controls the URI scheme/bucket/prefix and allows overriding the manifest directory while still defaulting to <cacheRoot>/manifests.

WebService integration (2025-11-05)

• /api/v1/scans/{id} and /api/v1/reports responses now include a surface block containing:
  • manifestUri – cas:// pointer to the Surface manifest JSON.
  • manifestDigest – canonical SHA-256 over the manifest payload.
  • manifest.artifacts[] – deterministic list with kind, uri, digest, mediaType, format, and optional view. URIs reuse the ArtifactObjectKeyBuilder semantics (cas://{bucket}/{rootPrefix}/images/...).
• This allows UI/CLI consumers to fetch manifests or artefacts without additional Surface.FS round-trips.

4. Library Responsibilities

Surface.FS library for .NET hosts provides:

• ISurfaceManifestWriter / ISurfaceManifestReader with the default FileSurfaceManifestStore implementation (single-writer semaphore, digest reuse, optional overwrite warning).
• Deterministic pointer builder (SurfaceManifestPathBuilder) and options (SurfaceManifestStoreOptions, SurfaceCacheOptions) that align with Surface.Env configuration.
• Local cache abstraction ISurfaceCache with default FileSurfaceCache implementation (uses Surface:Cache:Root / SCANNER_SURFACE_CACHE_ROOT, enforces per-key semaphores, stores bytes verbatim).
• SurfaceCacheKey helper that normalises cache entries as {namespace}/{tenant}/{sha256}. EntryTrace graphs use the entrytrace.graph namespace so Worker/WebService/CLI can share cached results deterministically.
• JSON serialiser (SurfaceCacheJsonSerializer) that applies camelCase naming, ignores nulls, and uses a stable encoder for reproducible hashing.
• Metrics: surface_manifest_published_total, surface_manifest_cache_hit_total, plus host-specific counters wired via Scanner Worker instrumentation.

5. Retention & Eviction

• Manifests capture generatedAt; retention windows (30 days for SBOM fragments, 7 days for entry traces) are enforced by job configuration and object-store lifecycle policies. An expiresAt field is reserved for future use when automated eviction is introduced.
• Background job SurfaceCacheMaintenanceService evicts local cache entries exceeding quota, oldest-first.
• Object storage retention policies are managed by DevOps; library exposes metrics but does not auto-delete unless instructed.

6. Offline Kit Handling

Offline kits include:

offline/surface/
  manifests/
    <tenant>/<digest[0..1]>/<digest[2..3]>/<digest>.json
  payloads/
    <tenant>/<kind>/<digest[0..1]>/<digest[2..3]>/<digest>.json.zst
  manifest-index.json

Import script uses ISurfaceManifestWriter.PublishAsync for each manifest after verifying the embedded digest, keeping Offline Kit replays identical to online flows. This enables Zastava and Scheduler running offline to consume cached data without re-scanning.

6.1 EntryTrace Cache Usage

Scanner.Worker serialises EntryTrace graphs into Surface.FS using SurfaceCacheKey(namespace: "entrytrace.graph", tenant, sha256(options|env|entrypoint)). At runtime the worker checks the cache before invoking analyzers; cache hits bypass parsing and feed the result store/attestor pipeline directly. The same namespace is consumed by WebService and CLI to retrieve cached graphs for reporting.

6.2 BuildX generator path

StellaOps.Scanner.Sbomer.BuildXPlugin reuses the same CAS layout via the --surface-* descriptor flags (or STELLAOPS_SURFACE_* env vars). When layer fragment JSON, EntryTrace graph JSON, or NDJSON files are supplied, the plug-in writes them under scanner/surface/** within the configured CAS root and emits a manifest pointer so Scanner.WebService can pick up the artefacts without re-scanning. The Surface manifest JSON can also be copied to an arbitrary path via --surface-manifest-output for CI artefacts/offline kits.

7. Security & Tenancy

• Tenant ID is mandatory; Surface.Validation enforces match with Authority token.
• Manifests/payloads stored in tenant-specific prefixes to prevent leakage.
• Optional manifest signing (future) will use Surface.Secrets to load signing keys.
• TLS enforced between hosts and Surface.FS endpoint; certificate pins configured via Surface.Env.

8. Observability

• Logs include manifest SHA, tenant, kind, and cache namespace; payload paths are truncated for brevity.
• Prometheus metrics (emitted by Scanner.Worker) now include:
  • scanner_worker_surface_manifests_published_total, scanner_worker_surface_manifests_failed_total, scanner_worker_surface_manifests_skipped_total with labels {queue, job_kind, surface_result, reason?, surface_payload_count}.
  • scanner_worker_surface_payload_persisted_total with {surface_kind} to track cache churn (entrytrace.graph, entrytrace.ndjson, layer.fragments, …).
  • scanner_worker_surface_manifest_publish_duration_ms histogram for end-to-end persistence latency.
• Grafana dashboard JSON: docs/modules/scanner/operations/surface-worker-grafana-dashboard.json (panels for publish outcomes, latency, per-kind cache rate, and failure reasons). Import alongside the analyzer dashboard and point it to the Scanner Prometheus datasource.
• Tracing spans: surface.fs.put, surface.fs.get, surface.fs.cache.

9. Testing Strategy

• Unit tests for path builder, manifest serializer, and local cache eviction.
• Determinism verifier tests assert that composition.recipe + DSSE payloads match the Merkle root and surface artefact digests.
• Integration tests using embedded RustFS or MinIO container to validate API interactions.
• Offline kit tests verifying export/import cycle round-trips manifests and payloads.

10. Future Enhancements

• Manifest signing (DSSE) to support tamper detection in hostile environments.
• Differential manifests to optimise large SBOM updates.
• Cross-region replication for multi-site deployments.

11. References

• Surface.Env Design (docs/modules/scanner/design/surface-env.md)
• Surface.Secrets Design (docs/modules/scanner/design/surface-secrets.md)
• Surface.Validation Design (docs/modules/scanner/design/surface-validation.md)
• Zastava Deployment Runbook (docs/modules/devops/runbooks/zastava-deployment.md)