For the complete documentation index, see llms.txt. This page is also available as Markdown.

pylynk

pylynk is the official command-line interface for the Interlynk platform. It provides programmatic access to SBOM upload, download, product management, vulnerability queries, and processing status checks — designed for both interactive use and CI/CD automation.

Repository: github.com/interlynk-io/pylynk


When to Use pylynk

Use Case
pylynk
API (curl)
UI

CI/CD SBOM upload

Recommended

Possible

Not practical

Bulk vulnerability export

Recommended

Possible

Manual

Interactive product browsing

Good

Verbose

Best

SBOM download with enrichment

Recommended

Complex

Manual

One-off queries

Good

Good

Good

Scripted automation

Recommended

Recommended

Not applicable

Use pylynk when you need repeatable, scriptable access to the platform. Use the API directly when you need fine-grained control over GraphQL queries. Use the UI for visual exploration and ad hoc operations.


Installation

pip (from source)

git clone https://github.com/interlynk-io/pylynk.git
cd pylynk
pip3 install -r requirements.txt
python3 pylynk.py --help

Docker

Verify Installation

Expected output:


Authentication

This is the recommended method for both local use and CI/CD. The token is read automatically by all commands.

Command-Line Flag

API Endpoint Override

The default API endpoint is https://api.interlynk.io/lynkapi. Override it with:

Token Security Best Practices

  • Store tokens in a secrets manager (Vault, AWS Secrets Manager, GitHub Secrets).

  • Never commit tokens to source control.

  • Use service tokens for automation; user tokens for interactive sessions.

  • Set expiration dates — 90 days for CI/CD, 30 days for development.

  • Rotate tokens proactively. See Rotation Strategy.


Core Commands

prods — List Products

Lists all products in the organization.

Parameter
Required
Default
Description

--output

No

table

Output format: table, json, csv

--human-time

No

Off

Show relative timestamps (e.g., "2 days ago")

--token

No

Env var

Override authentication token

-v, --verbose

No

Off

Enable debug output

Output columns: NAME, ID, VERSIONS, UPDATED AT


vers — List Versions

Lists all versions (SBOMs) for a product.

Parameter
Required
Default
Description

--prod

Yes

—

Product name

--env

No

default

Environment name

--output

No

table

Output format: table, json, csv

--human-time

No

Off

Relative timestamps

-v, --verbose

No

Off

Debug output

Output columns: ID, VERSION, PRIMARY COMPONENT, UPDATED AT

Use the ID value from this output as --verId in other commands.


upload — Upload SBOM

Uploads an SBOM file to the platform.

Parameter
Required
Default
Description

--prod

Yes

—

Product name

--sbom

Yes

—

Path to SBOM file

--env

No

default

Target environment

--retries

No

3

Retry count on transient failures

-v, --verbose

No

Off

Debug output

Supported formats: CycloneDX (JSON, XML), SPDX (JSON, tag-value)

Retry behavior:

Condition
Behavior

5xx server error

Retries with exponential backoff (1s, 2s, 4s)

429 rate limit

Retries with exponential backoff

401 unauthorized

Fails immediately — no retry

Other 4xx

Fails immediately — no retry

Network error

Retries with exponential backoff

CI metadata: When running in a CI environment (CI=true), pylynk automatically captures build metadata (PR number, commit SHA, branch name, build URL) and sends it as HTTP headers with the upload.


gate — Policy Gate for CI/CD

Returns a single pass/fail policy verdict for one SBOM version and exits non-zero when it does not pass. Run it after upload to block a pull request on policy failures.

Parameter
Required
Default
Description

--prod

Conditional

—

Product name (use with --env and --ver)

--env

No

default

Environment name

--ver

Conditional

—

Version name (mutually exclusive with --verId)

--verId

Conditional

—

Version ID (mutually exclusive with --ver)

--fail-on

No

fail

Lowest policy severity that blocks: fail or warn

--policy-name

No

—

Gate on one active policy by exact name

--policy-id

No

—

Gate on one active policy by ID

--no-wait

No

Off

Check the current state once instead of waiting for the scan

--timeout

No

600

Total seconds to wait for version resolution and policy scan

--poll-interval

No

15

Seconds between polls

--output

No

table

Output format: table or json

An explicit version is required. Unlike other commands, gate does not fall back to the latest version, because that is racy when parallel CI runs upload concurrently.

Statuses and exit codes:

Status
Exit
Meaning

PASS

0

All active policies evaluated, no blocking violations

NO_POLICIES

0

The organization has no active policies (a warning is printed)

FAIL

3

At least one active policy of blocking severity was violated

IN_PROGRESS

4

Scan still queued or running when the timeout was reached

ERROR

4

Evaluation incomplete or errored, such as an interrupted scan

NOT_EVALUATED

4

No policy scan applies, such as vulnerability scanning disabled for the environment

Exit 4 is the fail-closed case. An incomplete scan never reads as a pass. Exit codes 3 and 4 are distinct so pipelines can alert differently on a real policy failure than on a scan that never completed.

Waiting behavior: policy evaluation runs asynchronously after upload, chained behind the vulnerability scan. By default gate first retries version resolution until the uploaded version appears, then polls the verdict until the scan finishes. Both phases share the single --timeout budget.

Requirements: the token's role must grant the View Policies permission (all built-in roles include it). --ver must match the primary component version embedded in the uploaded SBOM, the same value shown by pylynk vers.

Example output:

Counts are per policy, not per violation. A policy with four violations counts once as failed.


download — Download SBOM

Downloads an SBOM from the platform, optionally enriched with vulnerabilities, support status, or converted to a different format.

Identification — provide one of:

Method
Parameters Required

By version ID

--verId

By name

--prod + --env + --ver

Parameter
Required
Default
Description

--verId

Conditional

—

Version ID (from vers command output)

--prod

Conditional

—

Product name

--env

Conditional

—

Environment name

--ver

Conditional

—

Version name

--out-file

No

stdout

Output file path

--vuln

No

false

Include vulnerabilities (true/false)

--spec

No

Original

Output spec: SPDX or CycloneDX

--spec-version

No

Original

Spec version (e.g., 2.3, 1.5)

--lite

No

Off

Download lightweight version

--original

No

Off

Download exact uploaded SBOM

--dont-package-sbom

No

Off

Keep multi-SBOM files separate

--exclude-parts

No

Off

Exclude linked parts

--include-support-status

No

Off

Add support status metadata

--support-level-only

No

Off

CSV output with support levels only


vulns — List Vulnerabilities

Queries vulnerabilities across products.

Parameter
Required
Default
Description

--prod

No

—

Product name (uses latest version if no version specified)

--env

No

default

Environment name

--verId

No

—

Specific version ID

--ver

No

—

Version name

--output

No

table

Output format: table, json, csv

--columns

No

Default set

Comma-separated column names

--vuln-details

No

Off

Include severity, CVSS, EPSS, KEV, CWE

--vex-details

No

Off

Include VEX status, justification, actions

--timestamp-details

No

Off

Include all timestamp columns

--human-time

No

Off

Relative timestamps

--list-columns

No

—

Display available column names and exit

Default columns: id, part_name, part_version, component_name, component_version, severity, source, status, assigned

Vulnerability detail columns (--vuln-details): severity, kev, cvss, cvss_vector, epss, cwe

VEX detail columns (--vex-details): status, details, justification, action_statement, impact_statement, response


status — Check Processing Status

Checks the processing status of an uploaded SBOM.

Parameter
Required
Default
Description

--prod

Yes

—

Product name

--verId

Conditional

—

Version ID

--ver

Conditional

—

Version name (requires --env)

--env

No

default

Environment name

--output

No

table

Output format: table, json

Status types tracked:

Status
Description

checksStatus

SBOM quality and format checks

policyStatus

Policy evaluation

labelingStatus

Internal labeling

automationStatus

Automation rule execution

vulnScanStatus

Vulnerability scanning

Status values: UNKNOWN, NOT_STARTED, IN_PROGRESS, COMPLETED


vex — Update VEX Data

Sets VEX disposition on component vulnerabilities from the command line, one at a time or in bulk.

Update a single component vulnerability:

Identify the target with either --component-vuln-id or --vuln; the two are mutually exclusive and one is required. --component and --component-version narrow a --vuln match to one component.

Update several at once:

--file accepts CSV or JSON. Rows may carry component_vuln_id directly, or the vuln, component, and component_version names instead.

VEX fields (both actions):

Parameter
Description

--status / --status-id

VEX status, by name or ID

--justification / --justification-id

Justification, by name or ID

--response / --response-id

CycloneDX response, by name or ID

--note

VEX note

--impact

Impact statement

--detail

VEX detail

--action

Action statement

--fixed-in

Fixed-in version

--propagate / --no-propagate

Apply the disposition to related component vulnerabilities, or do not

--custom-fields-file

JSON file of component vulnerability custom field values

--output

Output format: table (default), json

For the status and justification vocabularies, see Vulnerabilities. For custom fields, see Vulnerability Custom Fields.


report — Generate Reports

Generates a report for one Version. The attribution report lists the components and their licenses, for shipping alongside a release.

Parameter
Required
Default
Description

--type

Yes

—

Report type. Currently attribution

--prod

Yes

—

Product name

--env

No

default

Environment name

--ver

No

latest

Version name. Omit to use the latest version

--include-license-text

No

Off

Include full license text in the output

--output-file

No

attribution_<product>.csv

Output file path


version — Show CLI Version


CI/CD Integration

GitHub Actions

GitLab CI

Bitbucket Pipelines

Azure DevOps

Docker-Based CI

For environments where Python installation is not practical:

Handling Secrets Securely

CI Platform
Secret Storage
Reference Syntax

GitHub Actions

Repository Secrets

${{ secrets.INTERLYNK_SERVICE_TOKEN }}

GitLab CI

CI/CD Variables (masked)

$INTERLYNK_SERVICE_TOKEN

Bitbucket

Repository Variables (secured)

$INTERLYNK_SERVICE_TOKEN

Azure DevOps

Pipeline Variables (secret)

$(INTERLYNK_SERVICE_TOKEN)

Fail-the-Build Patterns

Use exit codes to gate builds on SBOM upload success:

To block the build on policy failures, use gate. It waits for the asynchronous policy scan and returns the verdict as an exit code, so no manual polling or sleep is needed:

Exit 3 means a policy of blocking severity was violated. Exit 4 means the scan never produced a verdict within the timeout, which is treated as a failure rather than a pass.

CI Metadata

When CI=true is set (automatically by most CI platforms), pylynk captures build metadata and sends it with uploads:

Header
Description

X-CI-Provider

CI platform name

X-Event-Type

Trigger type (push, pull_request, release)

X-PR-Number

Pull request number

X-Commit-SHA

Git commit hash

X-Repository-URL

Repository URL

X-Build-URL

Build/job URL

X-PR-Source-Branch

Source branch name

X-PR-Target-Branch

Target branch name

Control metadata collection:


Troubleshooting

Debug Mode

Enable verbose logging with -v or --verbose:

Debug output includes: API request/response details, token validation (masked), CI metadata detection, upload speed metrics, and timing information.

Common Errors

Error
Cause
Resolution

Security token not found

INTERLYNK_SECURITY_TOKEN not set

Export the environment variable or use --token

Authentication failed

Invalid or expired token

Verify token in UI; create a new one if expired

Product not found

Typo in product name or no access

Run pylynk prods to list available products

Version not found

Invalid version ID or name

Run pylynk vers --prod 'name' to list versions

File not found

Bad SBOM file path

Verify path; use absolute paths in Docker

Request failed with status code: 429

Rate limited

Automatic retry handles this; increase --retries if needed

RequestException

Network or connectivity issue

Check firewall, proxy, and INTERLYNK_API_URL

Error uploading sbom

Invalid SBOM format

Verify SBOM is valid CycloneDX or SPDX

Exit Codes

Code
Meaning

0

Success

1

General error (authentication, network, or version resolution failure)

2

Argument parsing error

3

Policy gate failed (gate only)

4

Policy gate could not reach a verdict (gate only)

Codes 3 and 4 are returned only by gate. Treat any non-zero exit as blocking in CI.


Best Practices

Least Privilege Token Usage

Create service tokens with the minimum role required:

Workflow
Recommended Role

SBOM upload only

Custom role with upload permission

Upload + vulnerability review

Operator

Full automation

Admin (use sparingly)

Read-only reporting

Viewer

Automation Design Patterns

  • Idempotent uploads: Uploading the same SBOM twice to the same product/environment creates a new version. Design pipelines to upload only on meaningful changes.

  • Environment separation: Use --env to separate staging, production, and development SBOMs.

  • Version tracking: Capture the version ID from vers output after upload for downstream status checks.

  • Error handling: Always check exit codes. Use --retries 0 to disable retries when you need fast failure.

Parallel vs Serial Execution

  • Serial: Upload SBOMs for the same product sequentially to avoid race conditions on version ordering.

  • Parallel: Upload SBOMs for different products concurrently. Each product is independent.

  • Status polling: Wait for COMPLETED status before downloading enriched SBOMs. Processing is asynchronous.


Common Misconfigurations

Issue
Symptom
Fix

Token in --token flag in CI

Token visible in build logs

Use INTERLYNK_SECURITY_TOKEN env var

Wrong INTERLYNK_API_URL

Connection errors or 401

Verify URL or remove the override to use default

Missing --prod on upload

Argument parsing error

Always specify --prod with upload

Docker volume not mounted

File not found inside container

Add -v $(pwd):/app/data and use /app/data/ paths

Using --ver without --env

Version not found

Provide both --env and --ver together

Old pylynk version

Unexpected API errors

Pull latest from repository or Docker image

Last updated