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
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 --helpDocker
Verify Installation
Expected output:
Authentication
Environment Variable (Recommended)
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.
--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.
--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.
--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:
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.
--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:
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:
By version ID
--verId
By name
--prod + --env + --ver
--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.
--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.
--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:
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):
--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.
--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
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:
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
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
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:
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
--envto separate staging, production, and development SBOMs.Version tracking: Capture the version ID from
versoutput after upload for downstream status checks.Error handling: Always check exit codes. Use
--retries 0to 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
COMPLETEDstatus before downloading enriched SBOMs. Processing is asynchronous.
Common Misconfigurations
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