Versions

Definition

A Version represents a point-in-time snapshot of a Product's software composition within a specific Environment. Each Version is created when an SBOM is uploaded or ingested.

A Version may have multiple SBOMs associated with it (e.g., when an SBOM is re-uploaded to correct errors or add details), but only one SBOM is considered active at any time.

Relationship to Product and Environment

Product
  └── Environment
      └── Version (Sbom)
          ├── project_version: "v1.2.0"
          ├── spec: "CycloneDX" or "SPDX"
          └── lifecycle: processing → active → archived

A Version is uniquely identified by the combination of Product + Environment + Version string. The same version string (e.g., v1.2.0) can exist in multiple Environments but represents independent snapshots.

Supported SBOM Formats

Format	Versions	Encodings
CycloneDX	1.2, 1.3, 1.4, 1.5, 1.6, 1.7	JSON, XML
SPDX	2.2, 2.3	JSON

Upload Workflow

When an SBOM is uploaded, the platform executes a processing pipeline:

Upload → SBOM Checks → Internal Labeling → Automation Rules → Vulnerability Scan → Component Support Analysis → Policy Evaluation

Each stage has a tracked status: NOT_STARTED, IN_PROGRESS, COMPLETED.

Via UI

1. Navigate to the Product detail page.

2. Click Upload SBOM.

3. Select the target Environment from the dropdown.

4. Drag and drop the SBOM file or click to browse.

5. Click Upload.

Via CLI

# Upload to default environment
pylynk upload --prod "my-backend-service" --sbom sbom.cdx.json

# Upload to a specific environment
pylynk upload --prod "my-backend-service" --env "production" --sbom sbom.cdx.json

# Upload with retry (useful in CI/CD)
pylynk upload --prod "my-backend-service" --sbom sbom.cdx.json --retries 5

The CLI automatically retries on transient failures with exponential backoff (1s, 2s, 4s between attempts). It does not retry on authentication errors (401) or client errors (4xx), except rate limiting (429).

Via API

curl -X POST https://api.interlynk.io/lynkapi \
  -H "Authorization: Bearer $INTERLYNK_SECURITY_TOKEN" \
  -F operations='{"query":"mutation UploadSbom($input: UploadSbomInput!) { uploadSbom(input: $input) { sbom { id projectVersion } errors } }","variables":{"input":{"projectGroupName":"my-backend-service","projectName":"production","sbom":null}}}' \
  -F map='{"0":["variables.input.sbom"]}' \
  -F [email protected]

Via CI/CD

GitHub Actions:

env:
  INTERLYNK_SECURITY_TOKEN: ${{ secrets.INTERLYNK_SERVICE_TOKEN }}

steps:
  - name: Generate SBOM
    run: syft . -o cyclonedx-json > sbom.cdx.json

  - name: Upload SBOM to Interlynk
    run: pylynk upload --prod "my-backend-service" --env "production" --sbom sbom.cdx.json

GitLab CI:

variables:
  INTERLYNK_SECURITY_TOKEN: $INTERLYNK_SERVICE_TOKEN

upload_sbom:
  script:
    - syft . -o cyclonedx-json > sbom.cdx.json
    - pylynk upload --prod "my-backend-service" --env "production" --sbom sbom.cdx.json

When running in a supported CI environment (GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure DevOps), pylynk automatically captures CI metadata — commit SHA, PR details, build URL — and attaches it to the Version.

Checking Processing Status

After upload, monitor the processing pipeline:

# By version ID
pylynk status --prod "my-backend-service" --verId "abc-123-def"

# By product, environment, and version name
pylynk status --prod "my-backend-service" --env "production" --ver "v1.2.0"

The status command tracks five processing stages: checksStatus, policyStatus, labelingStatus, automationStatus, vulnScanStatus.

Downloading SBOMs

The platform can return enhanced SBOMs — the original SBOM enriched with vulnerability data, support status, and compliance annotations.

# Download enhanced SBOM with vulnerabilities
pylynk download --prod "my-backend-service" --env "production" --ver "v1.2.0" \
  --out-file enhanced-sbom.json \
  --vuln true \
  --include-support-status

# Download in a specific format
pylynk download --verId "abc-123-def" \
  --spec CycloneDX --spec-version 1.5 \
  --out-file sbom.json

# Download original (unmodified) SBOM
pylynk download --verId "abc-123-def" --original --out-file original-sbom.json

Version Metadata

Each Version may include:

Field	Description
Version string	The product version identifier (e.g., v1.2.0, build-456)
Spec	SBOM format (CycloneDX or SPDX)
Lifecycle	Current state (processing, active, archived)
TLP Classification	Traffic Light Protocol classification for sharing restrictions
Creation date	When the SBOM was created
Release date	When the software was released
End-of-support date	When support ends for this version
End-of-life date	When the version reaches end of life
CI metadata	Build URL, commit SHA, PR details (captured automatically in CI)

Version Comparison (Drift Analysis)

The MCP server supports comparing two Versions to identify drift:

compare_versions       # Shows added, removed, and modified components between two versions

This is useful for tracking component changes across releases and identifying newly introduced risks.

Best Practices

• Use meaningful version strings. Align with your release versioning scheme (semver, build numbers, commit SHAs) so that Versions are traceable to specific builds.

• Upload SBOMs in CI/CD, not manually. Automated uploads ensure every build is tracked and reduce the risk of missed or inconsistent data.

• Enable "Retain Vulnerability Status with Version" in Environment settings to preserve VEX triage work when re-uploading SBOMs.

• Enable "Copy VEX Across Versions on Import" if your workflow involves frequent SBOM updates, so triage decisions carry forward to new Versions.

• Set a data retention policy. Use at least 90 days for audit trail purposes. Use "Forever" for Products with regulatory requirements.

• Download enhanced SBOMs for distribution. The enhanced SBOM includes vulnerability and support data not present in the original upload.

Common Misconfigurations

Issue	Symptom	Fix
Same SBOM uploaded repeatedly with no version change	Duplicate Versions clutter the list	Use unique version strings for each build
VEX status lost on re-upload	Triage work disappears after SBOM update	Enable "Retain Vulnerability Status with Version" in Environment settings
Processing stuck in IN_PROGRESS	Status never completes	Check for malformed SBOM; verify the SBOM format is supported
No CI metadata attached	Build traceability missing	Ensure pylynk runs in a supported CI environment or set PYLYNK_INCLUDE_CI_METADATA=true
Version uploaded to wrong Environment	Data appears in unexpected location	Verify --env flag in CLI or Environment Rules configuration