Export Center Trivy Adapters

The Trivy adapters translate StellaOps normalized advisories into the format consumed by Aqua Security’s Trivy scanner. They enable downstream tooling to reuse StellaOps’ curated data without bespoke converters, while preserving Aggregation-Only Contract (AOC) boundaries. This guide documents bundle layouts, field mappings, compatibility guarantees, validation workflows, and configuration toggles introduced in Sprint 36 (EXPORT-SVC-36-001, EXPORT-SVC-36-002).

The current Export Center build is wiring the API and workers. Treat this document as the canonical interface for adapter implementation and update any behavioural changes during task sign-off.

1. Adapter overview

Both variants ship inside the export run under /export/trivy/. Each bundle is a gzip-compressed tarball containing:

metadata.json
trivy.db                # BoltDB file with vulnerability/provider tables
packages/*.json         # Only when schema requires JSON overlays (language ecosystems)

The adapters never mutate input evidence. They only reshape normalized advisories and copy the exact upstream references so consumers can trace provenance.

2. Bundle layout

trivy/
  db.bundle
    +-- metadata.json
    +-- trivy.db
  java-db.bundle        # present when Java DB enabled
    +-- metadata.json
    +-- trivy-java.db
    +-- ecosystem/...
signatures/
  trivy-db.sig
  trivy-java-db.sig

metadata.json aligns with Trivy’s expectations (schemaVersion, buildInfo, updatedAt, etc.). Export Center adds an stella block to capture profile id, run id, and policy snapshot hints.

Example metadata.json (trimmed):

{
  "schemaVersion": 2,
  "buildInfo": {
    "trivyVersion": "0.50.1",
    "vulnerabilityDBVersion": "2025-10-28T00:00:00Z"
  },
  "updatedAt": "2025-10-29T11:42:03Z",
  "stella": {
    "runId": "run-20251029-01",
    "profileId": "prof-trivy-db",
    "tenant": "acme",
    "policySnapshotId": "policy-snap-42",
    "schemaVersion": 2
  }
}

3. Field mappings

3.1 Namespace resolution

If a record lacks a supported namespace, the adapter drops it and logs adapter.trivy.unsupported_namespace.

3.2 Vulnerability metadata

Severity mapping:

3.3 Affected packages

The adapter deduplicates entries by (namespace, package.name, vulnerableRange) to avoid duplicate records when multiple upstream segments agree.

Example mapping (Ubuntu advisory):

// Stella normalized input
{
  "source": {"vendor": "Ubuntu", "product": "22.04"},
  "identifiers": {"cve": ["CVE-2024-12345"]},
  "severity": {"normalized": "high"},
  "affects": [{
    "package": {"name": "openssl", "ecosystem": "ubuntu", "nevra": "1.1.1f-1ubuntu2.12"},
    "vulnerableRange": "< 1.1.1f-1ubuntu2.13",
    "remediations": [{"fixedVersion": "1.1.1f-1ubuntu2.13"}]
  }]
}

// Trivy vulnerability entry
{
  "namespace": "ubuntu",
  "package": {
    "name": "openssl",
    "version": "< 1.1.1f-1ubuntu2.13",
    "fixedVersion": "1.1.1f-1ubuntu2.13"
  },
  "vulnerability": {
    "ID": "CVE-2024-12345",
    "Severity": "HIGH"
  }
}

3.4 Java DB specifics

The Java supplement only includes ecosystems maven, gradle, sbt. Additional fields:

4. Compatibility matrix

Schema mismatches emit adapter.trivy.unsupported_schema_version and abort the run. Operators can pin the schema via ExportCenter:Adapters:Trivy:SchemaVersion.

5. Validation workflow

1. Unit tests (StellaOps.ExportCenter.Tests):
   • Mapping tests for OS and ecosystem packages.
   • Severity conversion and range handling property tests.
2. Integration tests (EXPORT-SVC-36-001):
   • Generate bundle from fixture dataset.
   • Run trivy module db import <bundle> (Trivy CLI) to ensure the bundle is accepted.
   • For Java DB, run trivy java-repo --db <bundle> against sample repository.
3. CI smoke (DEVOPS-EXPORT-36-001):
   • Validate metadata fields using jq.
   • Ensure signatures verify with cosign.
   • Check runtime by invoking trivy fs --cache-dir <temp> --skip-update --custom-db <bundle> fixtures/image.
4. Schema pinning (EC6):
   • CI enforces ExportCenter:Adapters:Trivy:SchemaVersion=2; higher versions fail fast with adapter.trivy.unsupported_schema_version.
   • Export manifests/OCI annotations record the pinned schema for rerun-hash stability.

Failures set the run status to failed with errorCode="adapter-trivy" so Console/CLI expose the reason.

6. Configuration knobs

ExportCenter:
  Adapters:
    Trivy:
      SchemaVersion: 2           # enforce schema version
      IncludeJavaDb: true        # enable java-db.bundle
      AllowEmpty: false          # fail when no records match
      MaxCvssVectorsPerEntry: 5  # truncate to avoid oversized payloads
  Distribution:
    Oras:
      TrivyRepository: "registry.example.com/stella/trivy-db"
      PublishDelta: false
    Download:
      FilenameFormat: "trivy-db-{runId}.tar.gz"
      IncludeMetadata: true

• AllowEmpty=false converts empty datasets into ERR_EXPORT_EMPTY.
• MaxCvssVectorsPerEntry prevents extremely large multi-vector advisories from bloating the DB.
• PublishDelta works in tandem with the planner’s delta logic; when true, only changed blobs are pushed.
• FilenameFormat lets operators align downloads with existing mirror tooling.
• IncludeMetadata toggles whether metadata.json is stored alongside the bundle in the staging directory for quick inspection.

7. Distribution guidelines

• Download profile: db.bundle placed under /export/trivy/ and signed. Recommended filename trivy-db-<runId>.tar.gz.
• OCI push: ORAS artifact with annotations:
  • org.opencontainers.artifact.description=StellaOps Trivy DB
  • io.stella.export.profile=trivy:db
  • io.stella.export.run=<runId>
  • io.stella.export.schemaVersion=2
• Offline Kit: When offlineBundle.includeTrivyDb=true, the exporter copies the latest full bundle plus the last N deltas (configurable) with manifests for quick import.

Consumers should always verify signatures using trivy-db.sig / trivy-java-db.sig before trusting the bundle.

Example verification flow:

cosign verify-blob \
  --key tenants/acme/export-center.pub \
  --signature signatures/trivy-db.sig \
  trivy/db.bundle

trivy module db import trivy/db.bundle --cache-dir /tmp/trivy-cache

8. Troubleshooting

9. References

• Export Center API reference
• Export Center CLI Guide
• Export Center Architecture
• Export Center Overview
• Aqua Security Trivy documentation (external reference for schema expectations)

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.