CLI'yi kurun, yapılandırın ve CI/CD içinde güvenle kullanın

Dağıtım kaynakları

Önerilen kurulum yolu Go module proxy üzerinden sürüm sabitleyerek go install çalıştırmaktır. Go ve Docker kartları yönetim arayüzündeki filtrelenmiş Hosted release repository listelerini açar; v1.0.40 ZIP bağlantısı ise çalıştırılabilir dosya değil Go module kaynak arşividir. Erişim politikası varsa credential'ı URL'ye gömmek yerine istemcinin güvenli credential mekanizmasını kullanın.

• Go release repositoryHosted Go release repository'lerini format ve release aramasıyla listeler.
• Kubaba CLI v1.0.40 kaynak ZIP'iSürümün kaynak arşivi; binary dağıtımı değildir ve repository yetkisi isteyebilir.
• Docker release repositoryHosted Docker release repository'lerini format ve release aramasıyla listeler.

Kurulum ve sürüm doğrulama

Go 1.24 veya daha yeni bir toolchain gerekir. Sürümü açıkça sabitleyin; latest gibi hareketli bir referansı üretim pipeline'ında kullanmayın. GOBIN veya GOPATH/bin dizininin PATH üzerinde olduğunu doğrulayın.

1. go install yalnız CLI kaynak modülünü derler; Smart Kubaba backend'e bağlanmak için ayrıca KUBABA_URL ve KUBABA_TOKEN gerekir.
2. Kurulumdan sonra kubaba version ile embedded sürümü, kubaba --help ile komut yüzeyini doğrulayın.
3. Go repository kimlik doğrulaması gerekiyorsa token'ı GOPROXY URL'sine, komut satırına veya source arşiv adına yazmayın.

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

Yapılandırma modeli ve öncelik

Komut flag'leri environment değerlerini; environment kalıcı config dosyasını; config dosyası güvenli varsayılanları ezer. Token yalnız environment üzerinden alınır ve config set tarafından kabul edilmez.

• Kalıcı anahtarlar: server/url, project, organization, timeout, output, poll-interval ve insecure.
• Environment: KUBABA_URL, KUBABA_TOKEN, KUBABA_PROJECT, KUBABA_ORGANIZATION, KUBABA_ENVIRONMENT, KUBABA_TIMEOUT, KUBABA_OUTPUT, KUBABA_INSECURE ve KUBABA_CONFIG.
• Varsayılan overall timeout 5 dakika, polling aralığı 2 saniye ve output table'dır; duration değerleri Go duration biçimindedir.
• Config dosyası işletim sistemi user-config dizininde smart-kubaba/config.json altında owner-only permission ile tutulur; KUBABA_CONFIG izole dosya seçer.
• Server mutlak HTTP/HTTPS URL olmalı; credential, query, fragment veya path içeremez. Production'da HTTPS ve TLS doğrulaması zorunlu tutulmalıdır.

# 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 yetkileri ve secret güvenliği

Tarama için token sahibinde CreateScan, UploadSbom ve ViewScan bulunmalıdır. Eksik projeyi --create-project ile oluşturmak için ayrıca CreateScanProject gerekir; reevaluation yalnız gerektiğinde RunScanReevaluation ister.

• Token yalnız oluşturulduğu anda gösterilir; CI secret store'a kaydedin, expiry belirleyin, rotate edin ve önceki token'ı revoke edin.
• KUBABA_TOKEN komut argümanı, config dosyası, artifact, log, pipeline URL veya environment etiketi içine taşınmamalıdır.
• Token scope'ları owner'ın güncel permission'larıyla kesişir; kullanıcı yetkisi kaldırılırsa eski token daha geniş hak sağlamaz.
• Shell tracing'i token environment'a alındıktan önce kapatın; maskelenme tek başına token'ı yazdırma izni değildir.

Proje audit'i, SBOM üretimi ve SBOM gönderimi

audit kaynak ağacındaki desteklenen manifestleri statik olarak keşfeder; sbom generate backend olmadan CycloneDX 1.5 üretir; sbom scan mevcut CycloneDX belgesini checksum ile gönderip terminal policy kararını bekler.

1. --create-project eksik projeyi key ile oluşturur veya yalnız boş default branch/repository URL alanlarını doldurur; dolu değerleri ve organization sahipliğini değiştirmez.
2. Audit Git çalışma ağacındaysa commit, symbolic branch ve sanitize edilmiş origin URL'yi ekler; açık --branch/--commit değerleri keşfi ezer.
3. --output cyclonedx veya sbom generate --output - stdout'a yalnız JSON yazar; warning'ler stderr'de kalır.
4. --resolve varsayılan değildir; Maven metadata'sına kontrollü HTTP erişimi veya tek go.mod için izole go mod graph çalıştırması açan ayrı güven sınırıdır.

# 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

Desteklenen proje manifestleri

Discovery en fazla sekiz dizin derinliğinde ve 1.000 desteklenen manifest ile sınırlıdır; .git, node_modules, target, build, dist ve vendor gibi üretilen dizinleri atlar ve symlink takip etmez.

• Java/JVM: pom.xml, repository-style *.pom, gradle.lockfile ve build.gradle(.kts); unlocked Gradle build'i actionable hata verir.
• JavaScript: package-lock v1–v3, Yarn Classic/Berry ve pnpm lockfile v6+; aynı dizinde öncelik pnpm, Yarn, npm'dir.
• Python: exact requirements pin'leri, Poetry lock ve Pipfile.lock; öncelik Poetry, Pipenv, requirements'tır. Unpinned/VCS girdiler unresolved warning üretir.
• NuGet: packages.lock.json, packages.config ve *.csproj; yalnız restore edilmiş sürümü kanıtlayan exact bilgiler versioned PURL üretir.
• Go, Cargo, RubyGems ve Composer: go.mod/go.sum, Cargo.toml/Cargo.lock, Gemfile.lock ve composer.json/composer.lock.

Paketlenmiş artifact ve container image taraması

scan ZIP/TAR ailesi artifact'ları veya dizinlerini çalıştırmadan inceler. image scan Docker-save, OCI layout/archive, HTTPS registry reference veya açık docker-daemon:// kaynağından tek bir Linux image manifestini analiz eder.

• Artifact: JAR/WAR/EAR/ZIP, TAR/TAR.GZ/TGZ ile NUPKG, Wheel/Egg, Crate ve Gem metadata'sı desteklenir; içerik extract veya execute edilmez.
• Image: OCI/Docker manifest, config, layer digest/size ve diff_id doğrulanır; --platform multi-platform listeden tek os/arch/variant seçer.
• Registry credentials KUBABA_REGISTRY_HOST ile tam hedefe scope edilir; token veya username/password environment'tadır ve cross-host redirect'te authorization kaldırılır.
• docker-daemon:// yalnız local unix socket veya Windows named pipe kabul eder; image yoksa pull etmez ve container çalıştırmaz.

# 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

Durum, bulgu sorguları ve CI kullanımı

scan status anlık snapshot'ı; scan findings en son tamamlanan evaluation'ın sayfalı bulgularını okur. Bu sorgular salt-okunurdur ve policy gating uygulamaz; gating submit eden audit/scan komutunun exit code'uyla yapılır.

1. Finding page numarası sıfır tabanlıdır; size 1–200, sort order asc/desc ve tanımlı sort field listesiyle sınırlandırılır.
2. --output table insan okuması, --output json otomasyon içindir; CI JSON'u parse edebilir fakat başarı kararını exit code üzerinden vermelidir.
3. --fail-on-policy WARN sonucunu code 1 yapar; BLOCK her zaman 1'dir. Status/findings sorgusu BLOCK görse bile sorgu başarılıysa 0 döner.

# 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 sözleşmesi

Pipeline koşulları stdout metnine değil aşağıdaki sabit exit code sözleşmesine bağlanmalıdır.

• 0 — scan tamamlandı ve policy PASS oldu; WARN da --fail-on-policy yoksa 0'dır. Salt-okunur sorgu başarıları da 0 döner.
• 1 — policy BLOCK; veya --fail-on-policy açıkken WARN.
• 2 — scan FAILED/CANCELLED, terminal değerlendirme üretilememesi veya scan workflow hatası.
• 3 — config, authentication veya authorization hatası.
• 4 — backend connectivity, server failure veya overall polling timeout.
• 5 — invalid, unsupported, rejected ya da limit üstü SBOM/girdi.

Retry, timeout ve idempotency

--timeout/KUBABA_TIMEOUT bütün komut için hard deadline'dır. Güvenli GET ve checksum-addressed upload istekleri transport veya 408/425/429/502/503/504 için en fazla dört toplam deneme yapar; non-idempotent scan creation otomatik tekrarlanmaz.

• Backoff 200 ms ile başlar, iki katına çıkar ve 5 saniyede sınırlandırılır; geçerli Retry-After en fazla aynı limite kadar uygulanır.
• CI wrapper tüm komutu körlemesine retry etmemelidir; belirsiz create sonucunda önce scan kimliği/state kontrol edilmelidir.
• Aynı scan'e aynı checksum upload idempotent'tır; farklı içerik/checksum mismatch reddedilir.

Güvenlik sınırları ve sorun giderme

CLI proje kodunu, build scriptlerini veya artifact/image içeriğini çalıştırmaz. Parser, archive, component ve dependency limitleri fail-closed uygulanır; limit artırımı yalnız dokümante hard ceiling içinde yapılabilir.

• Code 3: KUBABA_URL/KUBABA_TOKEN varlığını, server URL biçimini ve token owner permission/scope kesişimini kontrol edin.
• Code 4: DNS/TLS, backend readiness, proxy/egress, overall timeout ve server 5xx kayıtlarını aynı correlation zaman aralığında inceleyin.
• Code 5: CycloneDX specVersion, JSON biçimi, checksum, archive traversal/encryption, platform seçimi ve resource limitini doğrulayın.
• --insecure yalnız açıkça kabul edilmiş local development için geçici tanı aracıdır; production çözümü CA/TLS trust zincirini düzeltmektir.
• Scan UI'da terminal durum, component/finding sayaçları, policy result, branch/commit/environment metadata ve audit/task kimliklerini CLI çıktısıyla uzlaştırın.