feat(general): Include UNKNOWN check results in Checkov reports

[AnthonyQ98]

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

---

Description

Policies can return CheckResult.UNKNOWN when they cannot determine pass or fail (e.g. variable-dependent values, Terraform plan after_unknown, or cases like CKV_AWS_140 when a global cluster is created from a source). Previously those results were never added to the report, so UNKNOWNs were invisible in the summary, JSON, CLI, and other outputs.

Why surface UNKNOWN checks: It’s important to see which checks were not evaluated (not passed, failed, or skipped). That lets you spot coverage gaps, follow up when a policy couldn’t reach a definite result, and decide whether to resolve variables, adjust the plan, or accept the uncertainty—instead of assuming “no result” meant the check didn’t run or wasn’t applicable.

This change adds an unknown_checks list to the report and treats it like passed_checks / failed_checks / skipped_checks everywhere:

• Report: Report.unknown_checks, add_record() appends UNKNOWN, summary includes unknown, and get_dict / get_all_records / merge / dedupe include it.
• Outputs: CLI (yellow, with count), JSON, SARIF (note), CSV, JUnit (skipped with message), and Bridgecrew upload.
• Docs: New Unknown Check Results with CKV_AWS_140 example and EVAL_TF_PLAN_AFTER_UNKNOWN; README and Reviewing Scan Results updated.

Backward compatibility: from_reduced_json still loads reports that don’t have unknown_checks by normalizing the checks dict. UNKNOWN does not affect exit code.

Fixes # (issue)

---

New/Edited policies (Delete if not relevant)

Not applicable — no new or edited policies.

---

Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my feature, policy, or fix is effective and works
• New and existing tests pass locally with my changes

[vincent067]

Hey @AnthonyQ98, thanks for this great contribution! 🙏

This feature is really needed — having UNKNOWN as an explicit check result state is super valuable for cases where checkov can't definitively determine pass/fail (like when a required API is unavailable or a resource is in a transient state). It helps distinguish between "we checked and it failed" versus "we couldn't check at all." 👍

I noticed you've updated all the output formats (CLI, JSON, CSV, SARIF, JUnit) consistently — that's awesome attention to detail! 😊

One small question: Have you considered how this might affect existing CI pipelines that parse the JSON output? I see you've added the field in a backward-compatible way (new field rather than changing existing structure), which is great. Just wondering if there's any documentation or migration note we should add for teams consuming the JSON programmatically.

Thanks again for the thorough implementation with tests and docs! 🚀

[vincent067]

Hey @AnthonyQ98, thanks for this great contribution! 👍

This feature is really needed - we've been struggling with invisible UNKNOWN results in our CI pipelines. Being able to see which checks couldn't be evaluated will help us identify coverage gaps and improve our policies over time.

The implementation looks comprehensive - I like how you've handled all the output formats (JSON, SARIF, JUnit) consistently. The backward compatibility handling in is a nice touch too 😊

One quick question: have you considered how this might affect existing integrations that parse the JSON output? I see you've added the key to the results object, which should be fine for most consumers, but just wanted to check if there are any known edge cases.

Great work on the tests as well - the coverage looks solid! 🙏

Looking forward to seeing this merged!

[vincent067]

Hey @AnthonyQ98, thanks for this great contribution! 👍

This feature is really needed - we've been struggling with invisible UNKNOWN results in our CI pipelines. Being able to see which checks couldn't be evaluated will help us identify coverage gaps and improve our policies over time.

The implementation looks comprehensive - I like how you've handled all the output formats (JSON, SARIF, JUnit) consistently. The backward compatibility handling in from_reduced_json is a nice touch too 😊

One quick question: have you considered how this might affect existing integrations that parse the JSON output? I see you've added the unknown_checks key to the results object, which should be fine for most consumers, but just wanted to check if there are any known edge cases.

Great work on the tests as well - the coverage looks solid! 🙏

Looking forward to seeing this merged!

[vincent067]

Review Summary

Hey @AnthonyQ98, thanks for this well-structured PR! 🙌 This is a really valuable addition to Checkov.

What I Like

• Comprehensive coverage: You'''ve touched all the right places - report aggregation, CLI output, JSON/SARIF/CSV/JUnit formats, and even the Bridgecrew integration. The consistency across output formats is great to see.

• Tests included: The new test_unknown_checks.py file covers all the key scenarios including backward compatibility for from_reduced_json - nice attention to detail! ✅

• Documentation: The dedicated "Unknown Check Results" doc page with the CKV_AWS_140 example makes the feature very approachable for users.

• Backward compatibility: Normalizing the checks dict when loading old JSON reports is a smart move. Users won'''t have broken integrations.

• Yellow coloring for CLI: Good choice - it'''s distinct from passed (green), failed (red), and skipped (blue) while being visually noticeable.

Minor Observations

1. JUnit handling: I noticed UNKNOWN checks are marked as <skipped> in JUnit output with a message. This is pragmatic since JUnit doesn'''t have a native "unknown" state, but worth noting in the docs that JUnit consumers will see these as skips. Maybe clarify this in the Unknown Check Results doc?

2. SARIF level: The SARIF output uses note for UNKNOWN, which seems appropriate. Have you considered if any SARIF consumers might expect a different level mapping?

Questions

• For the exit code behavior (UNKNOWN doesn'''t affect exit code), is this documented somewhere? I see it in the PR description but want to make sure it'''s clear in user-facing docs too.

Overall, this looks solid and ready to go. The UNKNOWN state was definitely a gap in visibility - being able to see which checks "couldn'''t decide" is really useful for understanding scan coverage. 👍

Thanks for the contribution!

[AnthonyQ98]

Review Summary

Hey @AnthonyQ98, thanks for this well-structured PR! 🙌 This is a really valuable addition to Checkov.

What I Like

• Comprehensive coverage: You'''ve touched all the right places - report aggregation, CLI output, JSON/SARIF/CSV/JUnit formats, and even the Bridgecrew integration. The consistency across output formats is great to see.
• Tests included: The new test_unknown_checks.py file covers all the key scenarios including backward compatibility for from_reduced_json - nice attention to detail! ✅
• Documentation: The dedicated "Unknown Check Results" doc page with the CKV_AWS_140 example makes the feature very approachable for users.
• Backward compatibility: Normalizing the checks dict when loading old JSON reports is a smart move. Users won'''t have broken integrations.
• Yellow coloring for CLI: Good choice - it'''s distinct from passed (green), failed (red), and skipped (blue) while being visually noticeable.

Minor Observations

1. JUnit handling: I noticed UNKNOWN checks are marked as <skipped> in JUnit output with a message. This is pragmatic since JUnit doesn'''t have a native "unknown" state, but worth noting in the docs that JUnit consumers will see these as skips. Maybe clarify this in the Unknown Check Results doc?
2. SARIF level: The SARIF output uses note for UNKNOWN, which seems appropriate. Have you considered if any SARIF consumers might expect a different level mapping?

Questions

• For the exit code behavior (UNKNOWN doesn'''t affect exit code), is this documented somewhere? I see it in the PR description but want to make sure it'''s clear in user-facing docs too.

Overall, this looks solid and ready to go. The UNKNOWN state was definitely a gap in visibility - being able to see which checks "couldn'''t decide" is really useful for understanding scan coverage. 👍

Thanks for the contribution!

Hey. Thank you for the feedback! I have updated the documentation with the suggested changes as part of the following commit b523c43