Skip to main content

Full SBOM Generation (End-to-End)

This page will help you generate the full release artifact inventory and Software Bill of Materials (SBOM) for CIVITAS from:

  • civitas-core-deployment
  • civitas-core-platform

The output is a release-ready report under SUMMARY.md, as well as individual SBOM files.

1. Install Required Tools​

macOS (Homebrew)​

brew install syft helmfile yq ripgrep jq git maven coreutils

Linux​

Install these tools with your distro package manager (or vendor install docs):

  • syft
  • helmfile
  • yq
  • ripgrep
  • jq
  • git
  • maven
  • timeout (coreutils or equivalent)

Verify installation​

syft version
helmfile --version
yq --version
rg --version
jq --version
git --version
mvn -version

2. Clone the Repositories​

# use a directory of your choice
mkdir -p ~/work/civitas && cd ~/work/civitas

git clone https://gitlab.com/civitas-connect/civitas-core/civitas-core-v2/civitas-core-deployment.git
git clone https://gitlab.com/civitas-connect/civitas-core/civitas-core-v2/civitas-core-platform.git

3. Authenticate Container Registries​

The SBOM scan must pull all referenced runtime images.

docker login registry.gitlab.com

4. Set Working Variables​

# optional, if unset use paths directly in the snippets below
export CIVITAS_ROOT=~/work/civitas
export DEPLOYMENT_REPO="$CIVITAS_ROOT/civitas-core-deployment"
export PLATFORM_REPO="$CIVITAS_ROOT/civitas-core-platform"
export ENV_NAME=production

5. Prepare the Deployment Folder​

If you haven't run a deployment from this repo before, the deployment/ folder won't exist yet. The generator script needs it for Helm rendering. Create it from the defaults:

cd "$DEPLOYMENT_REPO"

# only needed if deployment/ does not exist yet
test -d deployment || cp -r defaults/deployment deployment

6. Run the Canonical Generator Script​

cd "$DEPLOYMENT_REPO"

scripts/generate_artifact_inventory.sh \
  --platform-repo "$PLATFORM_REPO" \
  --env "$ENV_NAME"

Notes:

  • Default image scan timeout is 600 seconds per scan.
  • Each run writes outputs under out/sbom-<timestamp>/.
  • To resume a previous run (e.g. to retry failed image scans), pass --out-dir pointing to the existing output folder. Already-scanned images will be skipped automatically: 
    scripts/generate_artifact_inventory.sh \
      --platform-repo "$PLATFORM_REPO" \
      --env "$ENV_NAME" \
      --out-dir "$DEPLOYMENT_REPO/out/sbom-<previous-timestamp>"
  • Script runtime is on the order of minutes, so make yourself a coffee or beverage of your choice while it runs.

7. Validate Output Once Script Exits​

Zero errors should indicate a correct run. To validate, use the validation script (automatically picks the latest output directory):

cd "$DEPLOYMENT_REPO"

scripts/validate_sbom_output.sh

To validate a specific output directory:

scripts/validate_sbom_output.sh --out-dir "$DEPLOYMENT_REPO/out/sbom-<timestamp>"

It’s completed correctly if images/pending-images.txt is empty and every image has both *.cdx.json and *.spdx.json.

If pending or failed images remain:

  1. Check images/failed-images.txt and logs/*.log for failure reasons.
  2. Transient failures (registry timeouts, connectivity): re-run the script with --out-dir pointing to the same output folder to retry only the pending images (see step 6).
  3. Platform mismatch (e.g. amd64-only image on an arm64 host): re-run the script on a host with the matching architecture.
  4. Persistent scan timeouts: increase the per-image timeout with --scan-timeout <seconds> (default: 600).

8. Use in Release Notes​

Attach or reference:

  • SUMMARY.md (primary human-readable inventory)
  • images/failed-images.txt and images/pending-images.txt (exception evidence, if any)
  • source SBOM files in sources/

9. Troubleshooting​

  • Helm render/chart errors: validate chart repo/network reachability.
  • Registry auth errors: run docker login.
  • Repeated scan timeouts: increase --scan-timeout.