Idea: correlate Trivy findings with SRAC safety-relevance assertions

[devashridatta-dotcom]

Summary

Would the Trivy community be interested in an experimental plugin or companion integration that correlates Trivy vulnerability findings with externally authored Safety Relevance and System Impact Analysis assertions?

The proposed capability is called Safety Relevance Assertion Capability (SRAC). It is a small, format-neutral JSON sidecar bound to an exact component identity using its PURL, version, repository and optional component path. It carries safety relevance, classification, evidence references, reviewer state and optional change-impact-analysis records.

SRAC does not infer that a component is safe, and it does not infer that a vulnerability has a safety impact. Those conclusions must remain externally authored and approved by qualified project safety personnel.

The current Eclipse S-CORE proof of concept is available here:

• Eclipse proposal/discussion: Proposal: Define a minimum SRAC profile for an S-CORE pilot eclipse-score/score#3282
• cdxgen interoperability proposal: Proposal: experimental SRAC safety-relevance sidecar integration cdxgen/cdxgen#4392

Motivation

Trivy already generates and scans CycloneDX and SPDX SBOMs. In safety-oriented environments, vulnerability triage also needs to distinguish between:

• a component that has no established safety relevance;
• a component externally classified as safety-related;
• a draft assertion that still needs review; and
• an approved impact-analysis decision supported by evidence.

The useful correlation is therefore:

Trivy vulnerability finding
        + exact SBOM component identity
        + externally authored SRAC assertion
        = vulnerability report with safety context

This adds context for prioritization without turning Trivy into a functional-safety assessor.

Proposed initial experiment

The lowest-risk implementation appears to be a standalone Trivy plugin or external companion command rather than a change to Trivy's vulnerability engine.

Conceptual workflow:

trivy image --format cyclonedx --output app.cdx.json IMAGE
trivy sbom --format json --output trivy-results.json app.cdx.json

trivy srac \
  --sbom app.cdx.json \
  --trivy-report trivy-results.json \
  --assertion component.srac.json \
  --output combined-report.json

Illustrative output:

Component: score_lifecycle::health_monitor
Safety relevance: safety-related
Classification: ASIL-B
Assertion status: draft
Reviewer: not assigned
Reachable vulnerability: yes
Safety impact: not assessed

The Eclipse prototype currently provides reusable validation and test vectors for:

• deterministic PURL/version matching;
• an integrity-protected known-good revision;
• matched and fail-closed unmatched behavior;
• SHA-256 integrity for the assertion, source SBOM and report;
• both SPDX and CycloneDX inputs;
• optional trigger, impact scope, decision and verification records;
• a Persistency KVS pilot and Lifecycle Health Monitor pilot; and
• referential-integrity and safety-integrity-level consistency checks.

Expected behavior

• Correlate only exact component identities and revisions.
• Fail closed when the component is absent, ambiguous or has a different version.
• Preserve the original assertion, reviewer and approval state.
• Never convert vulnerability severity, EPSS or reachability directly into a safety-impact decision.
• Clearly distinguish draft, reviewed and approved assertions.
• Verify the assertion digest before displaying its safety context.
• Keep the original Trivy report and source SBOM unchanged.
• Produce machine-readable JSON plus an optional human-readable table.

Possible future integration

If the external plugin proves useful, a later experiment could retrieve an integrity-protected SRAC sidecar from an SBOM external reference, similar in spirit to Trivy's optional retrieval of external VEX information. That should only be considered after the matching, trust and user-experience behavior is validated outside Trivy core.

Standards status

This is interoperability experimentation, not a claim that SRAC is already a released standard.

• SPDX FunctionalSafety work for SPDX 3.1:
  • [FuSa] Add AnalysisTrigger and SystemImpactAnalysis for system impact analysis spdx/spdx-3-model#1442
  • [FuSa] Add SRAC system impact analysis examples spdx/spdx-3-model#1443
  • [Core] Add reusable Decision model spdx/spdx-3-model#1458
• CycloneDX safety proposal/discussion:
  • Proposal: CycloneDX Safety Perspective for SRAC and safety impact workflows CycloneDX/specification#1122

Questions for maintainers and community

1. Does a standalone trivy srac plugin fit Trivy's intended plugin model for this experiment?
2. Is Trivy's JSON report plus the original SBOM the preferred stable interface for correlating findings with exact component identities?
3. If an external proof of concept is successful, would submission to the Trivy plugin index and a documentation example be appropriate next steps?

I am happy to prepare a small compatibility pilot using the same public KVS and Health Monitor test vectors as Eclipse PR #370 after agreeing on the preferred approach.

[devashridatta-dotcom]

@DmitriyLewen @knqyf263, could you please advise on the appropriate boundary for this proposal?

The initial concept is intentionally lightweight: Trivy would continue producing its normal machine-readable vulnerability results, while an optional downstream correlator would join those results with externally authored SRAC safety-relevance assertions. Trivy would not create or approve a safety classification.

A minimal prototype could demonstrate:

• Trivy JSON input;
• an integrity-checked SRAC document;
• deterministic matching by pURL/version or component digest;
• safety context displayed beside affected findings; and
• explicit unmatched, ambiguous and invalid states.

Would you prefer this to remain an external post-processing integration, use a Trivy reporting/plugin extension point, or be explored within the repository? I can prepare a small reproducible prototype once you confirm the preferred boundary.

[devashridatta-dotcom]

Hi @knqyf263, could you please advise on the appropriate extension point for this proposal?
The intent is not to change Trivy’s vulnerability-matching logic. The proposed MVP would post-process Trivy’s machine-readable output, correlate components with an externally authored SRAC safety-relevance document using strong identifiers, and report matched, unmatched, ambiguous and digest-mismatch states. Trivy would not create or approve safety decisions.
Would you recommend keeping this as an external post-processor initially, or is there a Trivy report/plugin integration point suitable for a small prototype?
The published Aqua Slack invitations also appear to have expired, so I’m following up here as the permanent technical record.

[DmitriyLewen]

Hi @devashridatta-dotcom, thanks for the detailed write-up, and sorry for the slow reply.

Please keep this as an external tool or a regular Trivy plugin, outside the Trivy repository.
The workflow you describe is post-processing of artifacts that already exist, and no change in Trivy core is needed for it.

Some notes that should help:

• Regular plugin rather than output plugin.
  Your flow works on saved files (the Trivy report, the SBOM and the SRAC document), computes digests over them and keeps the originals unchanged, so a regular trivy srac ... plugin (or just a standalone CLI) fits best.
  An output plugin receives the scan result on stdin, and with --output plugin=... the report is not written to a file, so you would not have the original report to hash and keep.
  If a one-step CI usage becomes useful later, the same plugin can also declare output: true in plugin.yaml and support both modes.
• Use Trivy JSON as the input.
  The JSON report is a stable interface versioned by SchemaVersion, see the compatibility policy.
  Within one SchemaVersion, optional fields may be added or omitted, so please ignore unknown fields and don't assume optional fields are always present.
  Packages and vulnerabilities carry PkgIdentifier.PURL, so matching by PURL and version may not need the SBOM at all; the SBOM is only needed if the SRAC binding relies on something that is not in the JSON report (for example a component path or bom-ref).
  Please don't import Trivy Go packages for this: Trivy is a CLI, and its Go packages are not a supported API.
• Scan results themselves can change between Trivy and DB versions, and that is not considered a breaking change.
  Matching by identity (PURL/version), as you already plan, rather than by the set or order of findings, keeps the tool robust to that.
• Plugin index.
  No prior approval is needed: once the plugin is published, you can open a PR adding its YAML file to aquasecurity/trivy-plugin-index, see Distributing plugins via the Trivy plugin index.
  Please also note the security considerations: plugins run with the user's privileges and are not sandboxed or audited, which is worth stating in your plugin's README given its safety context.

As for fetching SRAC from an SBOM external reference inside Trivy, I agree that it's too early.
Let's come back to it once the SPDX and CycloneDX work has landed and the plugin has real users.

Regards, Dmitriy

[devashridatta-dotcom]

The SBOM input will be optional. The plugin will first use component identity available in the Trivy JSON report particularly PkgIdentifier.PURL and version and require the SBOM only when the SRAC binding depends on additional information such as a bom-ref, component path or another identifier that is not present in the report.
The initial MVP will:

• consume a saved Trivy JSON report and an explicitly supplied SRAC document;
• validate the Trivy SchemaVersion;
• ignore unknown fields and tolerate absent optional fields within a supported schema version;
• correlate components deterministically using PURL and version, digest or an applicable SBOM identifier;
• never use component names alone as sufficient identity;
• avoid depending on the number, order or exact set of vulnerability findings;
• preserve the original Trivy report, SBOM and SRAC document without modification;
• record input digests and provenance in a separate correlation report;
• report matched, unmatched, ambiguous, invalid and stale states;
• remain read-only and never create, modify or approve a safety decision; and
• avoid importing Trivy Go packages, treating the versioned JSON output as the supported integration interface.
  I will also document the Trivy plugin security boundary clearly: plugins execute with the user’s privileges and are not sandboxed or audited by Trivy.
  Existing transport mechanisms can already be used to reference an SRAC sidecar:
• CycloneDX 1.6/1.7 can use an externalReference with its native hash fields.
• SPDX 2.3 can use an ExternalRef with category OTHER; because that structure has no native checksum field, the digest can be carried by an explicitly documented convention or protected through a separate attestation.
  Therefore, the first plugin does not need to wait for native safety models. It will accept the SRAC document explicitly and, when an SBOM is supplied, may validate an existing reference and advertised digest.
  I agree that automatic SRAC discovery and network retrieval should not be added to Trivy core at this stage. That can be considered later as an optional plugin capability after there is implementation experience and real usage. At that point, discovery would need explicit network policy, supported URI restrictions, digest verification before parsing, and fail-closed handling of missing, ambiguous or mismatched references.
  Native safety representation is a separate evolution path: SPDX 3.1 FunctionalSafety is progressing through the SPDX 3.1 release-candidate work, while the CycloneDX 2.0 safety and impact model remains under review. The plugin can later add adapters for those native representations without changing its correlation and reporting contract.
  Once the MVP, tests, documentation and reproducible fixtures are available, I will publish the plugin and submit its YAML descriptor to aquasecurity/trivy-plugin-index. If one-step CI usage becomes useful later, the same plugin can additionally support output mode while retaining regular file-based operation.
  Thank you again for clarifying the extension point and compatibility requirements. I will link the implementation here when the first working version is ready.

[devashridatta-dotcom]

Implementation update: the first working SRAC correlation plugin is now published, following the regular-plugin boundary and JSON compatibility guidance above.

• Plugin repository: https://github.com/devashridatta-dotcom/trivy-plugin-srac
• Merged implementation PR: feat: add SRAC safety-relevance correlation plugin devashridatta-dotcom/trivy-plugin-srac#1
• Published release: https://github.com/devashridatta-dotcom/trivy-plugin-srac/releases/tag/v0.1.0
• End-to-end release and installation test: https://github.com/devashridatta-dotcom/trivy-plugin-srac/actions/runs/37943279431
• Official plugin-index submission: feat: add SRAC safety-relevance correlation plugin trivy-plugin-index#23

The implementation:

• remains a regular plugin outside Trivy core;
• consumes saved Trivy JSON through SchemaVersion and does not import Trivy Go packages;
• ignores unknown fields and tolerates omitted optional fields;
• correlates by exact pURL identity, never package name alone;
• accepts an optional CycloneDX SBOM only when bom-ref resolution is needed;
• verifies an expected SRAC SHA-256 digest and fails closed on mismatch;
• preserves the original inputs and records their digests and assertion provenance;
• reports matched, unmatched, ambiguous, invalid, and stale states; and
• remains read-only and never creates, modifies, or approves a safety decision.

The release workflow built Linux, macOS, and Windows packages. Its smoke test installed the published release using:

trivy plugin install github.com/devashridatta-dotcom/trivy-plugin-srac

It then ran trivy srac correlate against the published fixtures and verified the matched component and associated CVE in the generated report.

The plugin-index PR is currently awaiting maintainer review and workflow approval, so the plugin is submitted to—but not yet listed in—the official index. Automatic retrieval through SBOM external references remains deferred; the current implementation requires explicit local inputs and performs no network retrieval.

Thank you again for the detailed guidance on the appropriate integration boundary.

[devashridatta-dotcom]

Implementation update: Phase 1 of the shared SRAC correlation-report contract is now complete.

• Merged implementation: feat: stabilize SRAC correlation report contract devashridatta-dotcom/trivy-plugin-srac#3
• Published release: https://github.com/devashridatta-dotcom/trivy-plugin-srac/releases/tag/v0.2.0
• Successful release and end-to-end Trivy smoke test: https://github.com/devashridatta-dotcom/trivy-plugin-srac/actions/runs/37954866101
• Official Trivy plugin-index submission (maintainer review pending): feat: add SRAC safety-relevance correlation plugin trivy-plugin-index#23

The v0.2.0 release adds a versioned 1.0.0 correlation-report contract, a published JSON Schema, a validate-report command, explicit deterministic matching rules, typed input provenance with SHA-256 digests, a compatibility policy, and positive/negative/forward-compatibility fixtures. The release publishes binaries for all supported platforms together with the schema and checksum manifest.

The authority boundary remains unchanged: the plugin consumes saved Trivy JSON and externally authored SRAC assertions, then validates and correlates them read-only. It does not create or approve a safety decision. Automatic retrieval through SPDX/CycloneDX external references remains deferred until there is sufficient standards and implementation experience.

[devashridatta-dotcom]

@DmitriyLewen Just a quick follow-up on the Trivy integration. The only remaining item is the trivy-plugin-index PR #23, which adds the already-published SRAC plugin (v0.1.0) to the official plugin index.

The PR is currently mergeable, and the only pending step appears to be maintainer approval for the "Test indexes" workflow to run. Once that's approved and passes, the remaining action would be review and merge.

Would you mind taking a look when you have a chance? We'd appreciate your help getting it across