feat(release): attest build provenance and SBOM for release artifacts (#143)

* feat(release): attest build provenance and SBOM for release artifacts

SLSA provenance over dist/* and release assets via
actions/attest-build-provenance; CycloneDX SBOM generated from the
frozen uv export through a locked sbom dependency group and bound to
the distributions via actions/attest-sbom. Proposed in #111.

* fix(llm): allow Vertex AI to use ambient Application Default Credentials

ProviderConfig.validate() required a truthy credential for every provider
except Bedrock and Ollama, and the only credential source it checked for
Vertex was GOOGLE_APPLICATION_CREDENTIALS. This blocked ambient auth via
a GCE/Cloud Run attached service account or Workload Identity, even though
LiteLLM/google-auth already fall back to it automatically when no explicit
credential is passed -- the same pattern already supported for Bedrock's
IAM role. Excludes is_vertex from the check, mirroring the Bedrock/Ollama
precedent, and documents the fallback.

* Bumps to resolve security findings

* fix(llm): don't leak Vertex ADC credential path into GEMINI_API_KEY

- _resolve_api_key() now returns None for Vertex instead of the
  GOOGLE_APPLICATION_CREDENTIALS path, since vertex_ai/gemini-* models
  set both is_vertex and is_gemini, which was causing the file path to
  be written into GEMINI_API_KEY.
- Regenerated configuration-reference.md via generate_reference_docs.py
  instead of hand-editing, and updated the underlying descriptions so
  the doc doesn't drift on next regeneration.

Addresses CodeRabbit review feedbak on #144.

* revert unrelated cli-command-reference.md regeneration

---------

Co-authored-by: gyrospectre <7224858+gyrospectre@users.noreply.github.com>
Co-authored-by: Vineeth Sai Narajala <vnarajal@cisco.com>

Author: 3 people

.github/workflows/release.yml

@@ -24,6 +24,7 @@ jobs:
     permissions:
       id-token: write
       contents: write  # needed to create/update the GitHub release assets
+      attestations: write  # needed to store build provenance and SBOM attestations
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -53,6 +54,38 @@ jobs:
             --no-emit-project \
             --output-file release-assets/requirements.txt
 
+      # SBOM is generated from the frozen export above so all release artifacts
+      # describe one locked tree. The project version is dynamic (VCS-derived),
+      # so it is stamped from the workflow input.
+      - name: Generate CycloneDX SBOM
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          uv sync --frozen --only-group sbom
+          uv run --no-sync cyclonedx-py requirements \
+            release-assets/requirements.txt \
+            --pyproject pyproject.toml \
+            --output-reproducible \
+            --output-file release-assets/sbom.cdx.json
+          jq --arg v "$VERSION" \
+            '.metadata.component.version = $v
+             | .metadata.component.purl = "pkg:pypi/cisco-ai-skill-scanner@\($v)"' \
+            release-assets/sbom.cdx.json > sbom.tmp
+          mv sbom.tmp release-assets/sbom.cdx.json
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        with:
+          subject-path: |
+            dist/*
+            release-assets/*
+
+      - name: Attest SBOM
+        uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e # v4.1.0
+        with:
+          subject-path: dist/*
+          sbom-path: release-assets/sbom.cdx.json
+
       - name: Check GitHub release state
         id: release-state
         env:
@@ -66,7 +99,7 @@ jobs:
 
             if [[ "$is_draft" == "false" ]]; then
               echo "published=true" >> "$GITHUB_OUTPUT"
-              echo "::warning::GitHub release $VERSION is already published. Immutable releases cannot accept new assets, so requirements.txt upload will be skipped."
+              echo "::warning::GitHub release $VERSION is already published. Immutable releases cannot accept new assets, so release asset upload will be skipped."
             else
               echo "published=false" >> "$GITHUB_OUTPUT"
             fi
@@ -76,12 +109,14 @@ jobs:
             echo "published=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Attach requirements.txt to draft GitHub release
+      - name: Attach requirements.txt and SBOM to draft GitHub release
         if: steps.release-state.outputs.published != 'true'
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ inputs.version }}
-          files: release-assets/requirements.txt
+          files: |
+            release-assets/requirements.txt
+            release-assets/sbom.cdx.json
           fail_on_unmatched_files: true
           draft: true
 

SECURITY.md

@@ -65,7 +65,18 @@ following steps:
   who install with `pip` can reproduce the exact same dependency tree we ship
   and tested against, with hash verification.
 - **PyPI Trusted Publishers.** Releases are uploaded to PyPI via OIDC; no
-  long-lived API tokens are stored in the repository or in CI secrets.
+  long-lived API tokens are stored in the repository or in CI secrets. Uploads
+  carry [PEP 740](https://peps.python.org/pep-0740/) attestations generated
+  during publish.
+- **SLSA build provenance.** Every release run attests the wheel, sdist, and
+  release assets with
+  [`actions/attest-build-provenance`](https://github.com/actions/attest-build-provenance).
+  Verify any artifact with
+  `gh attestation verify <artifact> --repo cisco-ai-defense/skill-scanner`.
+- **CycloneDX SBOM.** Each GitHub release includes an `sbom.cdx.json` generated
+  from the same frozen export as `requirements.txt` and bound to the
+  distributions with
+  [`actions/attest-sbom`](https://github.com/actions/attest-sbom).
 - **Loose abstract constraints in `pyproject.toml`.** Library consumers can
   resolve transitive security patches forward without forced cascades. See
   [`CONTRIBUTING.md` § Dependency Policy](/CONTRIBUTING.md#dependency-policy)

pyproject.toml

@@ -130,6 +130,9 @@ dev = [
     "liccheck==0.9.2",
     "pip-audit==2.10.0",
 ]
+sbom = [
+    "cyclonedx-bom==7.3.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/cisco-ai-defense/skill-scanner"