Work with the AI Bill of Materials

An AI Bill of Materials (AI-BOM) lists the models, providers, frameworks, data assets, prompts and relationships that CodeStax found in one repository at one exact commit. Each BOM is versioned, can be compared with earlier versions, and exports as CycloneDX or SPDX.

The BOM is built from the AI Attack Surface inventory. This page covers the tasks; the format rules are described in Build an AI Bill of Materials.

Before you start

• Connect the repository and run a Smart or Deep scan on its default branch.
• The scan’s AI inventory run must be Complete. Partial, failed and feature-branch runs never become BOM versions, because missing evidence is not proof that an asset was removed.
• Viewers and above can read and export BOMs. Only a signed-in organization admin or owner can complete declarations.

How BOM versions work

Every complete, authoritative default-branch run of a repository creates a new generation: an immutable snapshot of the assets and relationships at that commit. The AI BOM tab always shows the latest generation, and you can export or compare any earlier one.

Changing a verified declaration changes the BOM version, timestamp and digest without rewriting the scan snapshot.

View a repository’s BOM

1. Open AI Attack Surface from the dashboard sidebar.
2. Select one repository in the repository scope picker. A BOM always belongs to one repository.
3. Open the AI BOM tab.

The tab shows:

• BOM assets, Relationships, Models and Data assets counts;
• Artifact identity: artifact ID, generation, BOM version, declaration revision, commit, snapshot fidelity, scan completion time and BOM completeness;
• Metadata coverage for Identity, Version, Supplier, License, Source provenance and Governance review, shown as present out of total; and
• Standards exports, with independent readiness for each format.

Export CycloneDX or SPDX

Under Standards exports, click Download CycloneDX or Download SPDX. A button is disabled while its format is blocked, and the card states why.

Each ready card shows the file size and the start of its SHA-256 digest. Exports are deterministic: exporting the same inputs again produces the same bytes and digest.

Export from the API

Use an API key with the read:ai-bom scope. Keys are created under Settings → API keys and are available on the Growth plan and above.

# Latest generation, CycloneDX (default format)
$ curl -H "X-API-Key: $CODESTAX_API_KEY" -o ai-bom.cdx.json \
  "https://codestax.co/api/ai-bom/repositories/<repo_id>/export"
 
# One historical generation, SPDX
$ curl -H "X-API-Key: $CODESTAX_API_KEY" -o ai-bom.spdx.json \
  "https://codestax.co/api/ai-bom/repositories/<repo_id>/versions/<generation>/export?format=spdx-3.0.1-jsonld"

format accepts cyclonedx-1.7-json (default) or spdx-3.0.1-jsonld. Each export response carries these headers:

List the available generations with GET /api/ai-bom/repositories/{repo_id}/versions. See the AI Attack Surface API for every BOM route.

Complete asset declarations for SPDX

SPDX AI Profile requires facts that CodeStax cannot infer from source code. Until they are declared, the SPDX card lists SPDX AI Profile blockers, one row per asset with the missing facts.

To complete a declaration:

1. In the blockers list, click Complete declaration beside the asset. Members and viewers see Admin action required instead.
2. Fill in Supplier or originator, Package version, Download location and Release time. For data assets, also fill in Built time and Dataset type.
3. Optionally fill in Declared license, Concluded license, Model card URL, Intended use and Limitations. A license must be a valid SPDX license expression or NOASSERTION.
4. Under Declaration provenance, choose a Source type (Manual, Upstream, Repository or Imported attestation) and enter the Source URI, the Source SHA-256, or both. A non-manual source requires at least one of them.
5. Check I verified these values against the cited source. and click Save verified declaration. The save button stays disabled until the box is checked.

URIs must be absolute and use http, https, git, ssh, s3, gs, oci, pkg or urn. A SHA-256 digest must be 64 hexadecimal characters.

Every save creates a new declaration revision and is written to the organization audit log with the changed fields. If another admin saved the same asset after you opened it, the save is rejected with AI BOM declaration was updated by another administrator; reopen the asset and try again.

Compare two generations

1. On the AI BOM tab, find Generation comparison. It needs at least two authoritative generations.
2. Pick a Baseline generation and a Target generation, then click Compare.

The result counts Added, Removed, Modified, Evidence changed, Edges added, Edges removed and Unchanged assets and lists the first 20 changed assets.

A warning appears above the counts when the comparison is not exact:

• the canonicalization version changed between the generations, so you should rebaseline before reading identity changes as real additions and removals;
• at least one run has incomplete coverage, so removals may reflect missing evidence; or
• at least one generation uses inferred legacy snapshots, so modified-field claims are not exact.

The API equivalent is GET /api/ai-bom/repositories/{repo_id}/diff?from_generation=<n>&to_generation=<m>.

Track AI stack drift

The Changes tab records what changed in the AI bill of materials since the previous verified run of each repository. The first verified run establishes the baseline; changes are reported from the run after it.

Filter by time window (Last 7 days, Last 30 days, Last 90 days, Last year), change type and severity. The Stack changes (30d) card on the Overview tab counts recent changes.

High and critical changes are also delivered automatically, grouped per repository:

• as an ai_drift event to your organization’s active SCA webhooks, which receive it by default; and
• as an email to organization owners and admins, unless they turned off critical-alert emails in their notification settings.

Lower-severity changes stay visible on the Changes tab but are not delivered.

Related

• AI Attack Surface Management
• AI security rules and dataflow analysis
• AI Attack Surface API
• SBOM export for dependencies