FAQ

Practical answers for generating SBOMs with lynkctl. For platform-wide questions, see the main Frequently Asked Questions.

---

Basics

What is the simplest command?

lynkctl generate .

This auto-detects the project and writes the SBOM to stdout. Add -o to write to a file:

lynkctl generate . -o sbom.cdx.json

Does lynkctl build my project?

No. For compiled projects, lynkctl reads your build system — build files and, where available, build metadata — to work out what would be compiled and linked, without ever executing the build. For package-manager projects, it reads the manifests and lockfiles directly. No compiler, toolchain, or package manager needs to run.

Which ecosystems does lynkctl support?

lynkctl has two provider families. Build providers cover compiled C/C++ and embedded projects: GNU Make, CMake, and IAR Embedded Workbench for Arm. Manifest providers cover package-manager projects: JavaScript/npm (including Yarn, pnpm, Bun), Python, Go, Rust/Cargo, Ruby/RubyGems, PHP/Composer, .NET/NuGet, and Java (Maven and Gradle). See the Overview for the full list and the files each provider is detected from.

How does lynkctl know which provider to use?

It auto-detects from root-level signals — a Makefile, a go.mod, a pom.xml, and so on. If a directory contains signals for more than one ecosystem, detection is ambiguous and lynkctl reports MULTI_ECOSYSTEM_DETECTED; pass --provider to choose.

Does lynkctl need the package manager installed?

No. Manifest providers read package.json, go.mod, pom.xml, lockfiles, and similar descriptors directly. The package manager does not run, and no network access is required.

What output format does lynkctl produce?

CycloneDX 1.6+ and SPDX 3.0+ (Experimental) SBOMs, validated against the official schemas. The SBOM is written to stdout, or to the path given with --output (-o).

What command should I use in CI?

lynkctl generate . --strict -o sbom.cdx.json

--strict exits non-zero if lynkctl reports warnings; errors always exit non-zero. See Running in CI/CD.

What SBOM should I send to Interlynk support for analysis?

For a compiled C/C++ or embedded project, this is the most useful shape to share:

lynkctl generate . \
  --reproducible --timestamp 2023-11-14T22:13:20Z \
  --include-source-files --exclude-header-files \
  --evidence \
  -o sbom.cdx.json

It produces deterministic output, includes source-file components, drops header-file noise, and records evidence for how every field was determined. Add -v for verbose diagnostics on stderr when troubleshooting. For a package-manifest project, drop --include-source-files --exclude-header-files — those apply only to C/C++ build providers.

How do I get lynkctl?

lynkctl is distributed by Interlynk. Contact Interlynk to obtain the binary for your platform. See Installation.

Build Systems

How do I choose the build system?

Use auto-detection unless the project contains more than one build system, or you need to match a specific customer build. Force one with --provider:

lynkctl generate . --provider gnu-make -o sbom.cdx.json
lynkctl generate ./project.ewp --provider iar --iar-config Debug -o sbom.cdx.json

If both a Makefile and an IAR project are present, pass --provider explicitly. See the GNU Make, CMake, and IAR guides.

Source Detail

How do I include source files as SBOM components?

lynkctl generate . --include-source-files --exclude-header-files -o sbom.cdx.json

--include-source-files emits one component per first-party source file; --exclude-header-files drops the headers. This is usually the better shape for C and embedded firmware audits. Both flags apply to C/C++ build providers only.

How do I see how lynkctl decided a name, version, or license?

Pass --evidence. lynkctl then emits CycloneDX evidence — identity methods, occurrences, license and copyright evidence, confidence values, and tool references. Use it when the SBOM needs to be reviewed or defended. See Evidence & Confidence.

What does the confidence score on a component mean?

It indicates how strongly a conclusion is supported. Scores of 0.85 and above come from authoritative sources such as explicit declarations and build commands; 0.60 to 0.84 are inferred from build structure or heuristics; below 0.60 are fallback heuristics that warrant review. See Evidence & Confidence.

Why is a component missing a version or license?

lynkctl could not find authoritative information for that field, and reports it with NO_VERSION_FOUND or NO_LICENSE_FOUND. Run with -v to see which components are affected. If you know the correct value, supply it through a --overrides file.

How do I make output stable for diffs?

lynkctl generate . --reproducible --timestamp 2023-11-14T22:13:20Z -o sbom.cdx.json

--reproducible sorts collections and makes identifiers deterministic; --timestamp sets the embedded timestamp. You can also use the SOURCE_DATE_EPOCH environment variable. See Reproducible SBOMs.

Third-Party and Vendored Code

How do I mark a third-party source directory as a component?

Use --vendored-root, repeating it for multiple subtrees:

lynkctl generate . \
  --vendored-root third_party/ringbuf \
  --vendored-root third_party/mbedtls \
  -o sbom.cdx.json

Use this when a third-party subtree should be its own component rather than a set of individual source files. --vendored-root applies to the GNU Make, CMake, and IAR providers.

How do I include third-party code that is compiled but not linked?

lynkctl generate . --include-unlinked-vendored -o sbom.cdx.json

This emits vendored code seen during build analysis even when it is not linked into the final binary.

How do I identify modified or patched OSS copies?

lynkctl generate . --deep-scan -o sbom.cdx.json

--deep-scan uses slower fingerprint matching to catch modified copies of open-source code.

--deep-scan is a work in progress. Treat results from this path as experimental for now.

Enrichment and Corrections

How do I run lynkctl in an air-gapped environment?

Pre-fetch the OSS-index database on a connected machine, transfer it, and point lynkctl at the local copy with --oss-index-db. See Air-Gapped Environments for the full procedure.

How do I disable enrichment?

Disable only the OSS-index matching, or every enrichment step:

lynkctl generate . --no-oss-index -o sbom.cdx.json   # OSS-index only
lynkctl generate . --no-enrich -o sbom.cdx.json      # git, pkg-config, OS packages, OSS-index, overrides

Use --no-enrich when the SBOM should reflect only build-system extraction.

lynkctl got a component wrong. How do I correct it?

Use a --overrides YAML file. Each entry matches a component by name or by source-file glob and replaces its fields. Overrides resolve at confidence 1.0 and win over auto-detected values; an entry that matches nothing emits OVERRIDE_NO_MATCH. See Generating SBOMs for the file format.

Diagnostics and Output

Why did my build fail after I added --strict?

--strict turns any warning-level diagnostic into a non-zero exit. The SBOM is still written; lynkctl exits 1 because warnings were present. Run with -v to see the warnings, then resolve them or remove --strict. See Diagnostics & Exit Codes.

What do the exit codes mean?

0 is success. 1 is a runtime error, a diagnostic error, or a --strict run with warnings. 2 is a usage error such as a bad flag or missing path.

How do I reduce console output?

lynkctl generate . -q suppresses the per-SBOM summary line. Errors still print.

How do I get more diagnostic detail?

--verbose (-v) is repeatable:

Flag	Detail shown
-v	Per-diagnostic detail and pipeline debug events
-vv	Adds debug and provenance detail
-vvv	Adds trace-level timing detail

Can I pipe the SBOM into another tool?

Yes. The SBOM goes to stdout; all diagnostics, summaries, and progress go to stderr, so piping stdout never mixes in diagnostic noise.

OSS-Index Database

Do I need the OSS-index database?

Only for vendored open-source identification. If you do not need it, pass --no-oss-index and lynkctl skips that step. Otherwise download it once with lynkctl db download (roughly 300 MB).

How do I keep the database current?

lynkctl db check compares the cache against the published manifest without changing anything — exit 0 when current, 1 when stale. A common pattern is lynkctl db check || lynkctl db download.