Copy GitHub Repository PowerShell migration toolkit

Vulnerability applicability and VEX decision

This document records the project’s decision about Vulnerability Exploitability eXchange (VEX) evidence. It complements the release SBOM, vulnerability-reporting policy, dependency monitoring, security architecture, and software-assurance package; it does not redefine those authorities.

Decision

CopyGitHubRepo will not generate an empty or boilerplate VEX document for every v0.1.0 release.

The current release SBOM remains SPDX 2.3 JSON as defined in release-sbom.md. The module currently declares no third-party runtime PowerShell module dependencies, so routine VEX generation would add release machinery without communicating an actual vulnerability applicability determination.

VEX becomes appropriate when the project has a specific vulnerability for which a release-scoped applicability statement provides material value. The first such case triggers a fresh standards/tooling review and implementation against the exact affected release evidence.

This is a deferral of unnecessary machinery, not a policy that VEX is unimportant. A scanner finding must never be dismissed merely because the project has not yet implemented machine-readable VEX.

Why this fits the current release evidence model

The v0.1.0 release contract already binds an SPDX 2.3 SBOM to the completed release ZIP and exact source commit, and publishes GitHub build-provenance and SBOM attestations. VEX answers a different question: whether a known vulnerability is applicable to a particular product/release and what the current response is.

Keeping those concepts separate prevents several category errors:

  • Dependency/component presence — answered by the SBOM.
  • Vulnerability existence — established by a vulnerability source/advisory, not by the SBOM.
  • Applicability — whether the vulnerability affects this exact CopyGitHubRepo release in its actual component/use context.
  • Exploitability/impact — technical conditions under which the applicable vulnerability can be exploited or cause harm.
  • Remediation status — whether the issue is being investigated, mitigated, fixed, or otherwise addressed.

A VEX statement may communicate applicability and response. It must not be used to erase evidence that a component or vulnerability exists.

Standards evaluation

SPDX

The project currently emits SPDX 2.3 SBOMs. That remains the v0.1.0 release format and is not changed by this decision.

SPDX 3.0.1 adds a Security profile with explicit VEX vulnerability-assessment relationship classes. The model includes relationships for affected, not affected, fixed, and under-investigation states. A not-affected assessment requires a machine-readable justification and/or an impact statement; an affected assessment includes an action statement.

That model is attractive if the project later migrates the release SBOM/evidence model to SPDX 3, because the component and vulnerability evidence can share one standards family. Migrating from the established SPDX 2.3 release contract to SPDX 3 is nevertheless a separate compatibility/tooling decision and must not be smuggled into a vulnerability response merely to obtain VEX fields.

Primary specification references:

CycloneDX

CycloneDX 1.7 directly supports vulnerability exploitability analysis. Its vulnerability analysis model represents states such as exploitable, in triage, false positive, not affected, and resolved, together with justification, response, detail, and timestamps. CycloneDX explicitly identifies VEX as a supported security use case.

CycloneDX therefore provides a practical standalone VEX option if a material applicability statement is needed while the project’s authoritative SBOM remains SPDX 2.3. Using CycloneDX for that purpose would not change the fact that the release SBOM is SPDX 2.3; the VEX document would be separate release/security evidence tied to the same exact product identity.

Primary specification references:

GitHub artifact attestations

GitHub’s current actions/attest action supports provenance, SBOM, and custom-predicate attestation modes. The GitHub attestations API can also filter by freeform custom predicate type. This means a future machine-readable VEX document can be evaluated for binding to the exact release ZIP through a custom attestation without replacing the existing build-provenance or SBOM attestations.

Attestation capability alone is not a reason to generate VEX. Authentication proves who/what workflow issued a statement about a subject; it does not prove that the vulnerability analysis inside the statement is technically correct.

Primary references:

Independent publisher signing remains a separate open control under #80.

Format-selection rule when VEX is actually needed

When a trigger below occurs, select the narrowest interoperable option supported at that time:

  1. If the release evidence model has already migrated to SPDX 3 and its Security profile is supported by the project’s producer/consumer tooling, prefer SPDX VEX so component and vulnerability applicability evidence remain in one standards family.
  2. If the authoritative release SBOM is still SPDX 2.3, prefer a separate CycloneDX VEX document when current enterprise/security tooling can consume it reliably. Do not replace the release SBOM merely to issue one applicability statement.
  3. If neither option has defensible producer/consumer interoperability at the time of need, publish a precise human-readable security advisory first and keep machine-readable VEX as follow-up work rather than emitting a misleading or non-consumable document.

The selected serialization must be validated against the then-current standard and consumer/tooling behavior. This document intentionally does not freeze a future schema version beyond the current evaluation references.

Publication triggers

VEX implementation/publication is triggered when at least one of these conditions exists:

  • a vulnerability is reported against a component represented in the shipped release evidence and the project’s applicability differs materially from a scanner’s generic finding;
  • a first-party CopyGitHubRepo vulnerability needs a machine-readable affected/fixed/under-investigation statement for consumers;
  • an enterprise consumer needs machine-readable vulnerability applicability evidence for an actual finding, and the project has enough technical evidence to make the determination; or
  • vulnerability volume/dependency complexity grows enough that repeated human-only applicability statements become error-prone.

Routine releases with no assessed vulnerability do not require a VEX file.

Required release binding

A VEX statement must be release-specific. At minimum, the assessment record must identify or bind to:

  • the exact CopyGitHubRepo module version and release tag;
  • the exact source commit;
  • the exact release ZIP SHA-256 subject digest;
  • the corresponding release SBOM identity/checksum;
  • the vulnerability identifier and authoritative source used for analysis;
  • the assessed component/product identity and version/range; and
  • issue/assessment and last-updated timestamps.

If GitHub custom artifact attestation is used, the release ZIP digest should be the attestation subject and the VEX document should be the custom predicate or an equivalently unambiguous predicate payload. The predicate type must be a stable URI appropriate to the selected VEX representation.

A VEX statement for one release must never be worded or structured so that consumers could reasonably apply it to unrelated versions or artifacts.

Status and evidence requirements

The project uses the following semantic decision states regardless of the eventual wire format:

Semantic state Minimum project meaning/evidence
Under investigation / in triage The vulnerability/component/release identity is credible, but technical applicability is not yet resolved. Record what is being investigated and update the statement when the determination changes.
Affected / exploitable Evidence shows the release is affected. Record the affected component/path/conditions and concrete mitigation/remediation action. Do not soften an affected finding merely because exploitation is inconvenient.
Not affected Defensible technical evidence demonstrates why the vulnerability does not affect the exact release. A rationale such as code not present/reachable, required dependency/configuration/environment absent, or a verified mitigating control must be supported by product-specific evidence.
Fixed / resolved The vulnerable condition was removed or remediated in the identified release. Bind the statement to the fixed release and preserve the affected status of earlier releases where applicable.
False positive The vulnerability was incorrectly associated with the identified component/product, rather than being present-but-not-exploitable. Do not use false positive as a substitute for not affected.

Evidence before not affected

A not affected statement requires more than a maintainer assertion. The assessment record should preserve or link the applicable evidence, which may include:

  • exact component/package/file presence evidence from the release SBOM;
  • source-level analysis identifying the vulnerable function/path and whether it is present/reachable;
  • configuration, environment, dependency, or execution preconditions required for exploitation;
  • targeted tests or reproduction attempts relevant to the vulnerability claim;
  • upstream advisory/vendor analysis and version-range evidence;
  • implemented mitigating controls and evidence that they apply to the exact release; and
  • reviewer rationale explaining why the evidence supports the selected justification.

Absence of a known exploit, lack of observed attacks, a low CVSS score, or a passing general Quality Gate is not sufficient evidence that a vulnerability is not affected.

Decision authority

Vulnerability applicability is a security-sensitive project decision. Authority follows governance.md: the current primary maintainer owns the project security determination unless maintainership changes are formally recorded.

The person making the determination is responsible for ensuring that the evidence above is sufficient and that affected/not-affected/fixed/under-investigation semantics are used accurately. When a separate qualified reviewer is available, review is desirable, especially for a not affected statement with material consumer impact. The current governance model does not claim independent review when the primary maintainer performs the assessment and self-review.

Organizational consumers remain responsible for their own risk acceptance; project VEX evidence does not force an adopting organization’s scanner or approval process to suppress a finding.

Lifecycle and updates

A published applicability statement is not immutable truth about all future information. When new vulnerability data, exploit conditions, affected-version information, or project evidence changes the determination:

  1. reassess the exact supported releases involved;
  2. issue an updated VEX/advisory with a new last-updated timestamp/version as required by the chosen format;
  3. preserve enough history for consumers to understand that the earlier determination changed;
  4. publish a fixed release when remediation is required and available; and
  5. update the security advisory/support evidence rather than silently editing away a prior affected state.

The latest statement should identify the releases it supersedes or updates where the selected standard supports that relationship.

Relationship to the release SBOM

The release SBOM remains the authoritative machine-readable shipped-content inventory. A future VEX statement consumes/references that identity; it does not replace or rewrite the SBOM to hide a vulnerable component.

For v0.1.0, the expected release evidence set therefore remains the ZIP, SHA-256 checksum, SPDX 2.3 SBOM, GitHub build-provenance attestation, and GitHub SBOM attestation. No VEX sidecar or VEX attestation is currently required.

If a trigger causes VEX support to be implemented, release/security documentation and tests must be updated in the same change to define the exact filename/schema, validation, publication, update, and optional attestation behavior.

Assurance wording

The following claims are intentionally avoided:

  • that the absence of a VEX statement means the software has no applicable vulnerabilities;
  • that a not affected statement means the dependency or vulnerability does not exist;
  • that GitHub/Sigstore attestation proves the technical correctness of a VEX conclusion;
  • that machine-readable VEX constitutes independent security assessment or certification; or
  • that an adopting organization must accept the project’s applicability determination.

VEX is evidence for vulnerability triage and communication, not a mechanism for suppressing inconvenient scanner results.