feat: add reason codes, Error field, and ReasonFriendlyText to scanfailure

[kooomix]

Summary

Add structured failure reason codes and ReasonFriendlyText() mapping for scan failure notifications. UNS renders friendly text at notification time, so wording can change without redeploying in-cluster scanners.

Changes (single file: scanfailure/types.go)

12 reason code constants:

Code	Friendly Text
sbom_generation_failed	Failed to generate software inventory (SBOM) for this image
image_too_large	Image exceeds the maximum size limit for vulnerability scanning
sbom_too_large	Generated software inventory (SBOM) exceeds the maximum size limit
sbom_incomplete	SBOM generation was incomplete — the scan may have timed out or the image exceeded size limits
image_auth_failed	Failed to authenticate when pulling the container image
image_not_found	Container image manifest not found in registry
cve_matching_failed	Failed to match image components against vulnerability databases
result_upload_failed	Scan completed but results could not be uploaded to the platform
sbom_storage_failed	Failed to store the generated software inventory (SBOM)
scanner_oom_killed	SBOM scanner was killed due to memory limits
scan_timeout	Vulnerability scan timed out before completion
unexpected_error	An unexpected error occurred during vulnerability scanning

ReasonFriendlyText(code) string — maps code to friendly text, falls back to returning the code itself.

Error string field on ScanFailureReport — raw error for R&D debugging (not rendered in notifications).

Field alignment fix — ImageHash/JobID aligned to match gofmt conventions.

Consumers

• kubevuln (#334) — classifies errors → picks reason codes
• node-agent (#760) — reports SBOM failures with reason codes
• UNS — calls ReasonFriendlyText() in Slack/Teams template rendering

Related

• Jira: SUB-7074

Test plan

• go build ./scanfailure/... passes

Summary by CodeRabbit

• New Features
  • Scan failures now report with specific error codes and human-readable error messages for improved troubleshooting.
  • Enhanced error diagnostics help users quickly identify and understand the root cause of scan operation failures.
  • Improved error information enables faster issue resolution and recovery.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 88c5848c-9e12-46ec-8b5a-3d42a2b0b0af

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added twelve new failure reason string constants to standardize error classification codes. Introduced a ReasonFriendlyText() helper function for mapping reason codes to human-readable messages. Extended ScanFailureReport struct with an optional Error field to capture error details.

Changes

Cohort / File(s)

Summary

Failure Reason Constants & Helper scanfailure/types.go

Added 12 exported reason code constants (ReasonSBOMGenerationFailed, ReasonImageTooLarge, ReasonSBOMTooLarge, ReasonSBOMIncomplete, ReasonImageAuthFailed, ReasonImageNotFound, ReasonCVEMatchingFailed, ReasonResultUploadFailed, ReasonSBOMStorageFailed, ReasonScannerOOMKilled, ReasonScanTimeout, ReasonUnexpected). Introduced ReasonFriendlyText() function with lookup map for user-friendly error text. Added optional Error string field to ScanFailureReport struct (JSON/BSON serialized as error).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• #621: Modifies ScanFailureReport struct in the same file with related field additions.
• #620: Updates failure reason representation in scanfailure/types.go with alternative enumeration approach.
• #624: Introduces identical reason constants and Error field to ScanFailureReport.

Suggested reviewers

• slashben

Poem

🐰 When scans go awry and failures appear,
We've coded the reasons, both crystal and clear!
From timeouts to auth, from sizes too large,
Each error now speaks in a language at large.
A friendly translation—no more cryptic despair! 📋✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main changes: adding reason codes (12 new constants), an Error field, and a ReasonFriendlyText helper function to the scanfailure package.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/SUB-7074-reason-codes-and-error-field

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scanfailure/types.go`:
- Around line 56-63: ReasonFriendlyText currently returns an empty string when
reasonCode == ""; update the function (ReasonFriendlyText) to handle an empty
input by returning a sensible default human-friendly string (e.g., "Unknown
reason" or "No reason provided") instead of falling back to the empty code; keep
the existing lookup against reasonFriendlyText for non-empty codes and only use
the default when reasonCode is empty or all-whitespace.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fb3fe9ae-3594-4cdc-8d6b-172dba80868d

📥 Commits

Reviewing files that changed from the base of the PR and between 853034f and 7d0dae5.

📒 Files selected for processing (1)

• scanfailure/types.go

[kooomix]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}