How-to › Release and secure packages

How to generate an SBOM for a generated SDK#

Scan the SDK as users install it with `syft` or `cdxgen`, then add what no scanner sees: the generator, the OpenAPI document it read, and the code it vendored.

Audience
API producer
Level
intermediate
Topic
Secure the supply chain
Languages
TypeScript, Python and Go
Verified

A customer asks for an SBOM of your SDK, and the one you send from the repository lists nothing at all, or a machine-learning model called main.kit.entity. Scanning the source tree missed the versions your users install. A scan of the installed tree finds those versions but names no package for the library code the generator copied in, so a vulnerability scanner has nothing to match for that code.

What you get

You will end up with SPDX and CycloneDX SBOMs taken from the SDK as users install it, stamped with the generator, the OpenAPI document and the vendored code. This is for you if you ship an SDK that a generator wrote.

Short answer

Build and install the SDK the way a user receives it, then run syft for SPDX or cdxgen for CycloneDX over the installed tree. Read the generator’s manifest first: the sdkgen TypeScript SDK here had no third-party packages and the Kiota client eleven. Then add what no scanner sees, the generator and its version, the OpenAPI document’s hash, and the files the generator vendored, as SPDX relationships or a CycloneDX formulation.

You will need

A generated SDK in a repository, Node 22 or later, and Go and Python for those SDKs. The sample generates TypeScript, Python and Go SDKs with sdkgen and a TypeScript client with Kiota, from the five-operation Bookshelf document. Verified 2026-11-21.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
cdxgenOne CycloneDX tool across npm, PyPI and Go in one repositoryRead two TypeScript model keys as AI models here, and runs pip itself for PythonYou need SPDX, or a source scan you can trust
KiotaYou want the runtime as separate packages that a CVE fix updatesEleven npm packages in the SBOM of a five-operation client, all from one bundleYou want an SDK with no runtime packages to track
sbom-toolSPDX 2.2 or 3.0 with file hashes for a build dropFound no Python package in a pip install --target tree, and writes no CycloneDXYour SDK is Python, or your customers ask for CycloneDX
sdkgenYou want TypeScript and Go SDKs with no third-party runtime packagesVendored library copies no scanner lists, so you record them yourselfYou patch runtime code through the package manager
SpeakeasyA hosted generator, with SBOMs left to your own pipelineZod as a regular dependency of every TypeScript SDK, and an account to generateYou cannot send your document to a hosted service
syftSPDX or CycloneDX from an installed tree, a binary or an imageLists what is installed, so it needs the build firstYou can only scan the repository

Voxgig maintains sdkgen, which is one of six rows here and carries its own cost in the table.

The three tools agreed on both npm installs and differed on Python, so pick by format and ecosystem. The generators decide what the SBOM says. Kiota’s runtime arrives as eleven packages you update with npm. sdkgen’s arrives as copied files that only a regeneration updates.

Install the SDK the way your users get it

A scanner lists what it finds installed, so build and install first. record.sh packs the TypeScript SDK and installs the tarball into an empty project, installs the Python wheel with pip, and links the Go module into a program:

pybuild/bin/pip install --quiet --disable-pip-version-check --target use-py dist-py/voxgig_sdk_bookshelf_sdk-0.0.1-py3-none-any.whl

Then each tool reads each installed tree. The syft step:

for s in sdkgen-ts:dir:use-ts sdkgen-py:dir:use-py sdkgen-go:file:use-go/usego kiota-ts:dir:use-kiota \
  sdkgen-ts-source:dir:bookshelf-sdk/ts sdkgen-py-source:dir:bookshelf-sdk/py; do
  name=${s%%:*}
  $SYFT scan "${s#*:}" -q -o "spdx-json=$SBOM/$name.syft.spdx.json"
done

record.sh sets SYFT_CHECK_FOR_APP_UPDATE=false, KIOTA_CLI_TELEMETRY_OPTOUT=true and KIOTA_OFFLINE_ENABLED=true; sbom-tool’s README puts its telemetry in the output path, and cdxgen 12.9.3 has no telemetry setting.1 A last step of record.sh normalizes the SBOMs it commits. It removes the work directory’s absolute path, so each path reads relative to that directory. count.mjs reads them and counts the third-party packages in each:

node count.mjs
third-party packages  syft 1.57.2       cdxgen 12.9.3     sbom-tool 4.1.5
sdkgen-ts             0                 0                 0
sdkgen-py             5                 -                 0
sdkgen-go             0                 0                 -
kiota-ts              11                11                11
sdkgen-ts-source      0                 2                 -
sdkgen-py-source      0                 5                 -
sdkgen-py, syft: pkg:pypi/certifi@2026.11.20 pkg:pypi/charset-normalizer@3.5.2 pkg:pypi/idna@3.20 pkg:pypi/requests@2.34.2 pkg:pypi/urllib3@2.8.0
sdkgen-ts-source, cdxgen: pkg:generic/ai/main.kit.entity pkg:generic/ollama/main.kit.optspec
sdkgen-py-source, cdxgen: pkg:pypi/certifi@2026.11.20 pkg:pypi/charset-normalizer@3.5.2 pkg:pypi/idna@3.20 pkg:pypi/requests@2.34.2 pkg:pypi/urllib3@2.8.0
kiota-ts: the three tools list the same 11 packages
sdkgen-go: syft read the built binary, cdxgen the go.mod

The generated manifests explain the rows. sdkgen’s TypeScript package.json and Go go.mod declare no third-party dependency, and its Python pyproject.toml declares requests>=2.33, which brought four more. Kiota’s TypeScript output has no manifest of its own; kiota info names the bundle, and the bundle brought seven @microsoft/ packages and four others.

Add the generator, the document and the vendored code

Every sdkgen SDK here carries a copy of @voxgig/struct, marked by a VENDORED: line at the top of the file.2 No manifest lists it, so no tool listed it as a package. syft’s Python SBOM names voxgig_struct.py among its 187 file entries. The entry carries a hash but no version to match a vulnerability record against. vendored.mjs finds the marker in the installed files, and stamp.mjs adds the copies with the build inputs. In SPDX it uses two relationship types, GENERATED_FROM and BUILD_TOOL_OF, plus CONTAINS for each copy:

  out.relationships.push(
    { spdxElementId: target.SPDXID, relationshipType: 'GENERATED_FROM', relatedSpdxElement: specId },
    { spdxElementId: genId, relationshipType: 'BUILD_TOOL_OF', relatedSpdxElement: target.SPDXID },
  )

In CycloneDX it writes a formulation entry, whose workflow takes the document as input and the SDK as output. show.mjs rebuilds the stamped SPDX document and checks it against the hash record.sh validated:

node show.mjs
vendored copies found by their marker, which no SBOM above lists as a package:
  bookshelf-sdk/go/utility/struct/voxgigstruct.go  @voxgig/struct 0.1.6 @ 621057e
  use-py/bookshelf_sdk/utility/voxgig_struct/voxgig_struct.py  @voxgig/struct 0.1.1 @ 621057e
  use-ts/node_modules/@voxgig-sdk/bookshelf-sdk/dist/utility/StructUtility.js  @voxgig/struct 0.3.7 @ 621057e
stamped sdkgen-py.syft.spdx.json:
packages 7 -> 10, relationships 216 -> 219
  voxgig-sdk-bookshelf-sdk 0.0.1 GENERATED_FROM api.json
  @voxgig/sdkgen 4.44.3 BUILD_TOOL_OF voxgig-sdk-bookshelf-sdk 0.0.1
  voxgig-sdk-bookshelf-sdk 0.0.1 CONTAINS @voxgig/struct 0.1.1
  api.json: sha256 554e49a1d327...
  @voxgig/struct 0.1.1: sha256 356b030f0fd3...

Both stamped documents passed their schema checks:

grep -E 'exit|schemaValid|^[a-z]' evidence/validate.txt
pyspdxtools (spdx-tools 0.8.5) on the stamped sdkgen-py.syft.spdx.json
  exit 0
cdx-validate (cdxgen 12.9.3) on stamped/sdkgen-ts.cdxgen.cdx.json
  schemaValid=true  deepValid=true  pass=22  fail=8  manual=65  errors=5
  exit 3

cdx-validate exited 3 and reported eight failed controls: four OWASP SCVS controls and four CRA-MIN checks. The first is that the SBOM is unsigned; the schema check passed.

Record the build inputs from Kiota and Speakeasy

Kiota writes no SBOM. Its kiota-lock.json holds the inputs to stamp: kiotaVersion 1.39.0 and a descriptionHash of the document. The dependencies page says the bundle brings most of what a client needs, and the scan confirms it: all eleven packages came through @microsoft/kiota-bundle. Pass --generator kiota@1.39.0 and the SDK’s purl to stamp.mjs.

Speakeasy was not run, because generating needs an account. None of the 1722 addresses in its sitemap contains sbom, and its llms.txt index does not mention an SBOM. Its TypeScript methodology says Zod is bundled as a regular dependency, so expect it in every TypeScript SBOM, and its gen.yaml reference names a gen.lock saved from the previous generation. Scan the built package with syft or cdxgen.

Check it worked

node --test sbom.test.mjs
1..7
# tests 7
# suites 0
# pass 7
# fail 0
# cancelled 0
# skipped 0
# todo 0

The tests pin those counts. They check that no SBOM lists struct as a package and that none holds an absolute work path. They rebuild both stamped documents, and they refuse an SBOM that lacks the SDK, a marker without its Source: line, and a generator given without a version.

When it goes wrong

The SBOM lists the SDK and nothing else. syft read the source tree, which holds a manifest and no installed packages. Scan the installed tree or the built binary.

A source scan lists machine-learning models. cdxgen 12.9.3’s source analysis read the model keys main.kit.entity and main.kit.optspec in the TypeScript source as machine-learning models. Scan the installed package, where it listed the SDK alone.

sbom-tool reports no Python packages. Version 4.1.5 found none in this pip install --target tree, where syft found five. Scan that tree with syft instead.

The vulnerability scan misses a CVE in vendored code. No tool here listed the copied struct files as a package, so stamp them in, and regenerate when the upstream fix lands.

When not to do this

Do not stamp an SBOM by hand for each release. Run record.sh’s steps in the release job, so the generator version in the SBOM is the one that built the package.

Do not read sdkgen’s zero-dependency rows as zero exposure. Its runtime is vendored code that only a regeneration updates. Kiota suits a team that patches through npm, because a fix in @microsoft/kiota-abstractions arrives with npm update. Speakeasy fits a team that wants a hosted generator and can run its own scanner.

Do not hand a customer a source scan as the SBOM of what they install.

Last verified

Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, Kiota 1.39.0, syft 1.57.2, cdxgen 12.9.3, sbom-tool 4.1.5 and spdx-tools 0.8.5. The tools ran once through record.sh, and a second run in a copy gave the same counts and the same vendored files; only serial numbers, timestamps, and temporary names differed. Each finding is about one version of one tool on one tree. Speakeasy was not run; its dependency and lock-file statements come from its TypeScript methodology and gen.yaml pages, and its sitemap and llms.txt were searched on 2026-11-21.

Footnotes

  1. The sbom-tool README says the project does not accept outside contributions, citing the sensitive, regulatory nature of SBOMs. It invites anyone outside Microsoft who needs a change to fork and maintain a version of the tool, which its MIT license permits. ↩︎ Back to text

  2. The three copies name one commit of the struct repository, 621057e, and three versions: 0.3.7 for TypeScript, 0.1.6 for Go and 0.1.1 for Python. Each language’s package keeps its own version number, so one source revision ships under three. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.