Install, configure, and use the CLI safely in CI/CD

Distribution sources

The recommended installation path pins a version with go install through the Go module proxy. The Go and Docker cards open filtered Hosted release-repository lists in the management interface; the v1.0.40 ZIP URL is a Go-module source archive, not an executable. When access policy applies, use the client's secure credential mechanism instead of embedding credentials in URLs.

• Go release repositoryLists Hosted Go release repositories filtered by format and the release search term.
• Kubaba CLI v1.0.40 source ZIPVersioned source archive; it is not a binary distribution and may require repository permission.
• Docker release repositoryLists Hosted Docker release repositories filtered by format and the release search term.

Installation and version verification

Go 1.24 or newer is required. Pin an explicit version and avoid a moving reference such as latest in production pipelines. Verify that GOBIN or GOPATH/bin is on PATH.

1. go install builds only the CLI source module; connecting to the Smart Kubaba backend also requires KUBABA_URL and KUBABA_TOKEN.
2. After installation, verify the embedded version with kubaba version and the command surface with kubaba --help.
3. When the Go repository requires authentication, never put the token in the GOPROXY URL, command line, or source-archive name.

# Go 1.24 or newer is required.
export GOPROXY="https://kubaba.s3t.co/repository/go/go-release/"
go install github.com/smart-kubaba/smart-kubaba/cli/cmd/kubaba@v1.0.40
kubaba version
kubaba --help

# PowerShell equivalent:
$env:GOPROXY = "https://kubaba.s3t.co/repository/go/go-release/"
go install github.com/smart-kubaba/smart-kubaba/cli/cmd/kubaba@v1.0.40
kubaba.exe version

# If the repository requires authentication, configure the Go client's
# credential mechanism. Never put a username or token in GOPROXY or shell history.

Configuration model and precedence

Command flags override environment values, environment overrides the persisted configuration file, and the file overrides safe defaults. The token is accepted only from the environment and is rejected by config set.

• Persisted keys: server or url, project, organization, timeout, output, poll-interval, and insecure.
• Environment: KUBABA_URL, KUBABA_TOKEN, KUBABA_PROJECT, KUBABA_ORGANIZATION, KUBABA_ENVIRONMENT, KUBABA_TIMEOUT, KUBABA_OUTPUT, KUBABA_INSECURE, and KUBABA_CONFIG.
• The default overall timeout is five minutes, polling interval is two seconds, and output is table; durations use Go duration syntax.
• The config file is stored with owner-only permissions under smart-kubaba/config.json in the OS user-config directory; KUBABA_CONFIG selects an isolated file.
• The server must be an absolute HTTP or HTTPS URL with no credentials, query, fragment, or path. Production must retain HTTPS and TLS verification.

# Persist only non-secret defaults.
kubaba config set server https://kubaba.example.com
kubaba config set organization platform
kubaba config set project smart-kubaba
kubaba config set timeout 5m
kubaba config set output table
kubaba config view

# Supply secrets only to the current process through the CI/local secret store.
export KUBABA_TOKEN="<api-token>"
export KUBABA_ENVIRONMENT="staging"

# PowerShell:
$env:KUBABA_TOKEN = "<api-token>"
$env:KUBABA_ENVIRONMENT = "staging"

Token scopes and secret safety

Scanning requires CreateScan, UploadSbom, and ViewScan on the token owner. Creating a missing project with --create-project additionally requires CreateScanProject, while reevaluation needs RunScanReevaluation only when used.

• The token is shown only at creation; store it in the CI secret store, set an expiry, rotate it, and revoke the previous token.
• Never move KUBABA_TOKEN into a command argument, config file, artifact, log, pipeline URL, or environment label.
• Token scopes intersect the owner's current permissions; an old token cannot retain broader rights after user permissions are removed.
• Disable shell tracing before placing the token in the environment; masking alone is not permission to print it.

Project audit, SBOM generation, and SBOM submission

audit statically discovers supported manifests in a source tree; sbom generate creates CycloneDX 1.5 without a backend; sbom scan submits an existing CycloneDX document with its checksum and waits for a terminal policy decision.

1. --create-project creates a missing project from its key or fills only empty default branch and repository URL fields; it never changes populated values or organization ownership.
2. Inside a Git worktree, audit adds the commit, symbolic branch, and sanitized origin URL; explicit --branch or --commit values override discovery.
3. --output cyclonedx or sbom generate --output - writes only JSON to stdout while warnings remain on stderr.
4. --resolve is not the default; it is a separate trust boundary enabling bounded Maven metadata access or an isolated go mod graph for exactly one go.mod.

# 1. Generate CycloneDX 1.5 JSON without contacting the backend.
kubaba sbom generate . --output build/application.cdx.json

# 2. Discover the project, submit it, and wait for the policy decision.
kubaba audit . \
  --project smart-kubaba \
  --organization platform \
  --create-project \
  --environment staging \
  --output table

# 3. Submit an existing CycloneDX document.
kubaba sbom scan build/application.cdx.json \
  --project smart-kubaba \
  --branch main \
  --commit "<git-commit>" \
  --build-number "<build-number>" \
  --pipeline-url "<pipeline-url>" \
  --output json \
  --fail-on-policy

Supported project manifests

Discovery is bounded to eight directory levels and 1,000 supported manifests; it skips generated directories such as .git, node_modules, target, build, dist, and vendor and does not follow symlinks.

• Java and JVM: pom.xml, repository-style *.pom, gradle.lockfile, and build.gradle or build.gradle.kts; an unlocked Gradle build fails with an actionable error.
• JavaScript: package-lock v1 through v3, Yarn Classic or Berry, and pnpm lockfile v6+; precedence in one directory is pnpm, Yarn, then npm.
• Python: exact requirements pins, Poetry lock, and Pipfile.lock; precedence is Poetry, Pipenv, then requirements. Unpinned or VCS inputs produce unresolved warnings.
• NuGet: packages.lock.json, packages.config, and *.csproj; only exact evidence proving the restored version produces a versioned PURL.
• Go, Cargo, RubyGems, and Composer: go.mod and go.sum, Cargo.toml and Cargo.lock, Gemfile.lock, and composer.json and composer.lock.

Packaged-artifact and container-image scanning

scan inspects ZIP and TAR-family artifacts or directories without execution. image scan analyzes one Linux image manifest from Docker-save, OCI layout or archive, an HTTPS registry reference, or an explicit docker-daemon:// source.

• Artifacts: JAR, WAR, EAR, ZIP, TAR, TAR.GZ, and TGZ plus NUPKG, Wheel or Egg, Crate, and Gem metadata are supported; content is never extracted or executed.
• Images: OCI or Docker manifest, config, layer digest and size, and diff_id are verified; --platform selects one os, arch, and variant from a multi-platform list.
• Registry credentials are scoped to the exact target with KUBABA_REGISTRY_HOST; token or username and password stay in the environment and authorization is removed on cross-host redirects.
• docker-daemon:// accepts only a local Unix socket or Windows named pipe; it never pulls a missing image or runs a container.

# Packaged artifact or a directory of supported archives.
kubaba scan target/application.jar --project smart-kubaba --output table
kubaba scan target/release.tar.gz --project smart-kubaba --output json
kubaba scan target/dist --project smart-kubaba --output table

# Docker-save archive or OCI layout.
kubaba image scan application-image.tar --project smart-kubaba --platform linux/amd64
kubaba image scan application-oci-layout --project smart-kubaba --platform linux/arm64/v8

# Explicit local daemon source. The CLI saves the image; it never runs a container.
kubaba image scan docker-daemon://team/application:42 --project smart-kubaba

# Remote registry source. Credentials, when required, stay environment-only.
export KUBABA_REGISTRY_HOST="registry.example.com"
export KUBABA_REGISTRY_TOKEN="<registry-token>"
kubaba image scan registry://registry.example.com/team/application:42 \
  --project smart-kubaba \
  --platform linux/amd64

Status, finding queries, and CI use

scan status reads the current snapshot; scan findings reads paged findings from the latest completed evaluation. These queries are read-only and do not apply policy gating; use the submitting audit or scan command's exit code for gating.

1. Finding pages are zero-based; size is bounded to 1 through 200 with asc or desc and the documented sort-field list.
2. --output table is for humans and --output json for automation; CI may parse JSON but should make the success decision from the exit code.
3. --fail-on-policy maps WARN to code 1 while BLOCK is always 1. A successful status or findings query returns 0 even when it reports BLOCK.

# Read a scan snapshot without changing it.
kubaba scan status "<scan-id>" --output json

# Query the latest completed evaluation; pages are zero-based and size is 1..200.
kubaba scan findings "<scan-id>" \
  --severity high \
  --status open \
  --search log4j \
  --page 0 \
  --size 50 \
  --sort-field cvssScore \
  --sort-order desc \
  --output table

# Minimal CI gate. Keep shell tracing disabled while KUBABA_TOKEN is present.
set +x
kubaba audit . \
  --project smart-kubaba \
  --environment production \
  --output json \
  --fail-on-policy

Exit-code contract

Pipeline conditions must bind to the stable exit-code contract below rather than stdout text.

• 0 — scan completed with PASS; WARN is also 0 unless --fail-on-policy is set. Successful read-only queries also return 0.
• 1 — policy BLOCK, or WARN when --fail-on-policy is enabled.
• 2 — scan FAILED or CANCELLED, no terminal evaluation, or a scan-workflow failure.
• 3 — configuration, authentication, or authorization failure.
• 4 — backend connectivity, server failure, or overall polling timeout.
• 5 — invalid, unsupported, rejected, or oversized SBOM or input.

Retries, timeouts, and idempotency

--timeout or KUBABA_TIMEOUT is the hard deadline for the entire command. Safe GET and checksum-addressed uploads make at most four total attempts for transport failures or 408, 425, 429, 502, 503, and 504; non-idempotent scan creation is never retried automatically.

• Backoff starts at 200 ms, doubles, and is capped at five seconds; a valid Retry-After is honored up to the same cap.
• A CI wrapper must not blindly retry the whole command; after an uncertain create result, inspect the scan identity and state first.
• Uploading the same checksum to the same scan is idempotent; different content or a checksum mismatch is rejected.

Security boundaries and troubleshooting

The CLI never executes project code, build scripts, or artifact or image content. Parser, archive, component, and dependency limits fail closed, and limit increases are allowed only within documented hard ceilings.

• Code 3: check KUBABA_URL and KUBABA_TOKEN, server URL syntax, and the intersection of token-owner permissions and scopes.
• Code 4: inspect DNS and TLS, backend readiness, proxy or egress, overall timeout, and server 5xx evidence in the same correlation window.
• Code 5: verify CycloneDX specVersion, JSON syntax, checksum, archive traversal or encryption, platform selection, and resource limits.
• --insecure is a temporary diagnostic only for explicitly accepted local development; the production fix is to correct the CA and TLS trust chain.
• Reconcile terminal state, component and finding counts, policy result, branch, commit, and environment metadata, and audit or task identities in the Scan UI with CLI output.