git.stella-ops.org/docs/operations/runbooks/scanner-sbom-generation-failed.md

Runbook: Scanner - SBOM Generation Failures

Sprint: SPRINT_20260117_029_DOCS_runbook_coverage Task: RUN-002 - Scanner Runbooks

Metadata

Field	Value
Component	Scanner
Severity	High
On-call scope	Platform team
Last updated	2026-01-17
Doctor check	check.scanner.sbom-generation

---

Symptoms

• Scans completing but SBOM generation failing
• Alert ScannerSbomGenerationFailed firing
• Error: "SBOM generation failed" or "unsupported package format"
• Partial SBOM with missing components
• Metric scanner_sbom_generation_failures_total increasing

---

Impact

Impact Type	Description
User-facing	Incomplete vulnerability coverage; missing dependencies not scanned
Data integrity	Partial SBOM may miss vulnerabilities; attestations incomplete
SLA impact	SBOM completeness SLO violated (target: > 95%)

---

Diagnosis

Quick checks

1. Check Doctor diagnostics:

   stella doctor --check check.scanner.sbom-generation
   

2. Check failed SBOM jobs:

   stella scanner jobs list --status sbom_failed --last 1h
   

3. Check SBOM completeness rate:

   stella scanner stats --sbom-metrics
   

Deep diagnosis

1. Analyze specific failure:

   stella scanner job details <job-id> --sbom-errors
   

   Look for: Specific package manager or file type causing failure

2. Check for unsupported ecosystems:

   stella sbom analyze --image <image-ref> --verbose
   

   Look for: "unsupported", "unknown package format", "parsing failed"

3. Check scanner plugin status:

   stella scanner plugins list --status
   

   Problem if: Package manager plugin disabled or erroring

4. Check for corrupted package files:

   stella image inspect <image-ref> --check-integrity
   

---

Resolution

Immediate mitigation

1. Enable fallback SBOM generation:

   stella scanner config set sbom.fallback_mode true
   stella scan image --image <image-ref> --sbom-fallback
   

2. Use alternative SBOM generator:

   stella sbom generate --image <image-ref> --generator syft --output sbom.json
   

3. Generate partial SBOM and continue:

   stella scan image --image <image-ref> --sbom-partial-ok
   

Root cause fix

If package manager not supported:

1. Check supported package managers:

   stella scanner plugins list --type package-manager
   

2. Enable additional plugins:

   stella scanner plugins enable <plugin-name>
   

3. For custom package formats, add mapping:

   stella scanner config set sbom.custom_mappings.<format> <handler>
   

If package file corrupted:

1. Identify corrupted files:

   stella image layers <image-ref> --verify-packages
   

2. Report to image owner for fix

If memory/resource issue during generation:

1. Increase SBOM generator resources:

   stella scanner config set sbom.memory_limit 4Gi
   stella scanner config set sbom.timeout 10m
   

2. Enable streaming mode:

   stella scanner config set sbom.streaming_mode true
   

If plugin crashed:

1. Check plugin logs:

   stella scanner plugins logs <plugin-name> --last 30m
   

2. Restart plugin:

   stella scanner plugins restart <plugin-name>
   

Verification

# Retry SBOM generation
stella sbom generate --image <image-ref> --output sbom.json

# Validate SBOM completeness
stella sbom validate --file sbom.json --check-completeness

# Check component count
stella sbom stats --file sbom.json

# Full scan with SBOM
stella scan image --image <image-ref>

---

Prevention

• Plugins: Keep all package manager plugins enabled and updated
• Monitoring: Alert on SBOM completeness < 90%
• Fallback: Configure fallback SBOM generator for resilience
• Testing: Test SBOM generation for new image types before production

---

Related Resources

• Architecture: docs/modules/scanner/sbom-generation.md
• Related runbooks: scanner-oom.md, scanner-timeout.md
• SBOM formats: docs/formats/sbom-spdx.md, docs/formats/sbom-cyclonedx.md