# 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.

Source: https://voxgig.com/howto/generate-an-sbom-for-a-generated-sdk

- Audience: api-producer
- Level: intermediate
- Languages: typescript, python, go
- Verified: 2026-11-21
- Published: 2026-11-21

## 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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [`cdxgen`](https://cdxgen.github.io/cdxgen/) | One CycloneDX tool across npm, PyPI and Go in one repository | Read two TypeScript model keys as AI models here, and runs pip itself for Python | You need SPDX, or a source scan you can trust |
| [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/dependencies) | You want the runtime as separate packages that a CVE fix updates | Eleven npm packages in the SBOM of a five-operation client, all from one bundle | You want an SDK with no runtime packages to track |
| [sbom-tool](https://github.com/microsoft/sbom-tool) | SPDX 2.2 or 3.0 with file hashes for a build drop | Found no Python package in a `pip install --target` tree, and writes no CycloneDX | Your SDK is Python, or your customers ask for CycloneDX |
| [sdkgen](https://github.com/voxgig/sdkgen) | You want TypeScript and Go SDKs with no third-party runtime packages | Vendored library copies no scanner lists, so you record them yourself | You patch runtime code through the package manager |
| [Speakeasy](https://www.speakeasy.com/docs/sdks/languages/typescript/methodology-ts) | A hosted generator, with SBOMs left to your own pipeline | Zod as a regular dependency of every TypeScript SDK, and an account to generate | You cannot send your document to a hosted service |
| [`syft`](https://oss.anchore.com/docs/guides/sbom/formats/) | SPDX or CycloneDX from an installed tree, a binary or an image | Lists what is installed, so it needs the build first | You 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:

```bash title="record.sh"
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:

```bash title="record.sh"
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](https://github.com/microsoft/sbom-tool) 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:

```bash
node count.mjs
```

```text output
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](https://spdx.github.io/spdx-spec/v2.3.1/relationships-between-SPDX-elements/),
`GENERATED_FROM` and `BUILD_TOOL_OF`, plus `CONTAINS` for each copy:

```js title="stamp.mjs"
  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](https://cyclonedx.org/docs/1.7/json/) 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:

```bash
node show.mjs
```

```text output
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:

```bash
grep -E 'exit|schemaValid|^[a-z]' evidence/validate.txt
```

```text output
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](https://learn.microsoft.com/en-us/openapi/kiota/dependencies)
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](https://www.speakeasy.com/docs/sdks/languages/typescript/methodology-ts) says Zod is
bundled as a regular dependency, so expect it in every TypeScript SBOM, and its
[`gen.yaml` reference](https://www.speakeasy.com/docs/speakeasy-reference/generation/gen-yaml)
names a `gen.lock` saved from the previous generation. Scan the built package with `syft` or `cdxgen`.

## Check it worked

```bash
node --test sbom.test.mjs
```

```text output
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.

## Related how-tos

- [Write a CVE response runbook for an SDK](/howto/write-a-cve-response-runbook-for-an-sdk)

- [Automate dependency updates with Dependabot or Renovate](/howto/automate-dependency-updates-with-dependabot-or-renovate)

- [Choose a SLSA build level for a package release pipeline](/howto/choose-a-slsa-build-level)

- [Check whether two generator runs produce identical output](/howto/check-two-generator-runs-are-identical)

- [Verify a generated SDK is reproducible from its spec](/howto/verify-a-generated-sdk-is-reproducible)

## 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.

[^1]: The [sbom-tool README](https://github.com/microsoft/sbom-tool) 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.

[^2]: The three copies name one commit of the [struct repository](https://github.com/voxgig/struct),
`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.