Skip to content

Improve SBOM graph completeness and VEX credibility gates #1551

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shapris wants to merge 1 commit into
base: main
Choose a base branch
from
+232 −4
Open

Improve SBOM graph completeness and VEX credibility gates #1551

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 110 additions & 4 deletions skills/vuln-management/sbom-analysis/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ phase: [build, operate]
frameworks: [CycloneDX-1.5, SPDX-2.3, VEX-CSAF, NTIA-SBOM-Minimum-Elements]
difficulty: intermediate
time_estimate: "20-40min"
version: "1.0.0"
version: "1.0.1"
author: unitoneai
license: MIT
allowed-tools: Read, Grep, Glob
Expand Down Expand Up @@ -133,6 +133,21 @@ NTIA Completeness Assessment:
| **Partial** | 5-6 elements present for majority of components; significant gaps in supplier or dependency data |
| **Incomplete** | Fewer than 5 elements consistently present; SBOM not suitable for compliance or risk assessment |

#### Graph Completeness Gate

Do not treat a flat component list as fully complete just because each component has a relationship field. A usable SBOM must support transitive dependency tracing from top-level components to reachable leaves.

Record these graph signals:

| Field | Strong Evidence | Weak Evidence |
|---|---|---|
| `traceable_depth_max` | Top-level components map through full transitive chains | Depth is 0-1 while transitive components are present |
| `orphan_component_relationships` | No unexplained components outside the dependency graph | Components are listed but not reachable from any root |
| `transitive_parent_linkage` | Each transitive component has a parent path | Transitive components are flat-listed without parent-child linkage |
| `graph_completeness_rating` | `Complete Graph` / `Partial Graph` / `Flat List` / `Missing Graph` | Flat or missing graph downgrades NTIA usefulness |

If the NTIA minimum fields are present but the dependency graph is flat, report `NTIA fields present, graph incomplete` instead of a simple `Complete` rating.

### Step 3: VEX Status Interpretation

If VEX (Vulnerability Exploitability eXchange) documents are provided, interpret the status for each vulnerability-product pair.
Expand Down Expand Up @@ -170,6 +185,31 @@ VEX Assessment:
- Under Investigation: [N] (monitor for updates)
```

#### VEX Credibility Assessment

VEX status is not equally strong in every context. A vendor-attested `Not Affected` statement is useful, but some justifications require independent consumer validation before risk can be closed.

For each VEX entry, record:

| Field | Values |
|---|---|
| `verification_status` | `consumer_verified` / `third_party_verified` / `vendor_attested` / `not_verified` |
| `verification_evidence` | SBOM match, code review, runtime trace, vendor statement, third-party advisory |
| `verification_date` | Date when the justification was last validated |
| `vex_credibility` | `High` / `Medium` / `Low` |

Credibility guidance:

| VEX Status / Justification | Minimum Evidence for High Credibility |
|---|---|
| `component_not_present` | SBOM confirms component is absent |
| `vulnerable_code_not_present` | version/source review confirms affected code is absent |
| `vulnerable_code_not_in_execute_path` | call graph, runtime trace, or consumer code review validates reachability |
| `vulnerable_code_cannot_be_controlled_by_adversary` | threat model or data-flow evidence validates input control |
| `inline_mitigations_already_exist` | mitigation is enabled and tested in the target context |

Flag `Under Investigation` entries as stale when their age exceeds the vendor-provided investigation SLA, or 30 days when no SLA is provided.

### Step 4: Transitive Dependency Analysis

Analyze the dependency tree to identify risk concentration in transitive (indirect) dependencies.
Expand Down Expand Up @@ -239,6 +279,39 @@ License Analysis:

---

## SBOM Freshness and Trustworthiness

Evaluate whether the SBOM still represents the current software and whether it was produced by a trustworthy build process.

| Field | Strong Evidence | Warning |
|---|---|---|
| `sbom_age_category` | Fresh for current release/build | Older than current release, or age unknown |
| `timestamp_vs_latest_release` | SBOM timestamp is at or after release build | SBOM predates one or more releases |
| `cve_scan_currency` | CVE/VEX scan aligns with SBOM generation or latest release | Scan is stale or absent |
| `build_provenance_level` | signed SLSA/in-toto/Sigstore provenance | unsigned or unknown build source |
| `signer_identity` | signer is known and expected | unknown, missing, or mismatched signer |
| `generation_tool_verification` | tool and version are declared and trusted | unknown generator or unverifiable tool |

Freshness categories:

| Category | Criteria |
|---|---|
| **Fresh** | SBOM matches current release/build and latest vulnerability scan |
| **Recent** | SBOM is older but still within the organization's accepted refresh window |
| **Stale** | SBOM predates current release, dependency changes, or vulnerability scan by a material margin |
| **Unknown** | Missing timestamp, release mapping, or generation metadata |

Trustworthiness categories:

| Category | Criteria |
|---|---|
| **High** | Signed provenance, known generator, current release binding |
| **Medium** | Known generator and timestamp, but no signed provenance |
| **Low** | Unsigned, stale, or cannot be tied to current artifact |
| **Unknown** | Missing generator, timestamp, signer, or artifact binding |

---

## Findings Classification

Classify the overall SBOM analysis into one of the following states:
Expand Down Expand Up @@ -293,12 +366,27 @@ conflicts), and overall classification.]

**NTIA Completeness Rating:** [Complete / Substantially Complete / Partial / Incomplete]

### Dependency Graph Completeness

| Metric | Value | Notes |
|---|---|---|
| Traceable Depth Max | [N] | [Can top-level components be traced through transitive leaves?] |
| Orphan Components | [N] | [Components listed but unreachable from dependency roots] |
| Transitive Parent Linkage | [Complete/Partial/Missing] | [Whether transitive components have parent-child paths] |
| Graph Completeness Rating | [Complete Graph / Partial Graph / Flat List / Missing Graph] | [Impact on NTIA usefulness] |

### VEX Status Summary
[If VEX documents are provided]

| CVE ID | Component | VEX Status | Justification | Action |
|---|---|---|---|---|
| [CVE-ID] | [component] | [Not Affected/Affected/Fixed/Under Investigation] | [justification if Not Affected] | [action] |
| CVE ID | Component | VEX Status | Justification | Verification Status | Credibility | Action |
|---|---|---|---|---|---|---|
| [CVE-ID] | [component] | [Not Affected/Affected/Fixed/Under Investigation] | [justification if Not Affected] | [consumer_verified/vendor_attested/etc.] | [High/Medium/Low] | [action] |

### Stale VEX Entries

| CVE ID | Component | Status | Age | SLA | Stale? | Action |
|---|---|---|---|---|---|---|
| [CVE-ID] | [component] | [Under Investigation/etc.] | [N days] | [vendor SLA or default 30d] | [Yes/No] | [action] |

### Transitive Dependency Risk

Expand All @@ -310,6 +398,17 @@ conflicts), and overall classification.]
| High Fan-In Components | [N] | [List components] |
| Orphan Components | [N] | [List if present] |

### SBOM Freshness and Trustworthiness

| Field | Value | Rating | Notes |
|---|---|---|---|
| SBOM Age | [N days/months] | [Fresh/Recent/Stale/Unknown] | [timestamp vs current release] |
| Version Lag | [current vs SBOM version] | [OK/Warning/Unknown] | [latest release comparison] |
| CVE Scan Currency | [date] | [Fresh/Stale/Unknown] | [scan date alignment] |
| Build Provenance | [SLSA/in-toto/Sigstore/Unsigned/Unknown] | [High/Medium/Low/Unknown] | [evidence] |
| Signer Identity | [identity] | [Expected/Unexpected/Missing] | [notes] |
| Generation Tool | [tool + version] | [Verified/Unverified/Unknown] | [notes] |

### License Analysis

| License Category | Count | Components |
Expand Down Expand Up @@ -393,6 +492,13 @@ Published by NTIA in July 2021 as part of Executive Order 14028 implementation.

---

## Changelog

- **1.0.1**: Added dependency graph completeness, VEX credibility scoring, stale VEX detection, and SBOM freshness/trustworthiness gates.
- **1.0.0**: Initial SBOM analysis, VEX interpretation, transitive dependency risk, and license conflict guidance.

---

## References

- NTIA Minimum Elements for an SBOM: https://www.ntia.gov/sites/default/files/publications/sbom_minimum_elements_report_0.pdf
Expand Down
122 changes: 122 additions & 0 deletions skills/vuln-management/sbom-analysis/sbom-quality-examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# SBOM Analysis Quality Examples

Use these examples to calibrate `sbom-analysis` findings for graph completeness, VEX credibility, and SBOM freshness/trustworthiness.

## Vulnerable or Higher-Risk Cases

### 1. Flat-listed transitive dependencies

```yaml
sbom:
format: CycloneDX 1.5
components:
direct: 12
transitive: 30
dependencies:
graph_depth: 1
transitive_parent_linkage: missing
assessment:
ntia_fields_present: true
graph_completeness_rating: Flat List
risk: transitive CVE remediation cannot be traced to the consuming direct component
```

Expected handling: do not mark the SBOM as fully useful just because NTIA fields are present. Report `NTIA fields present, graph incomplete`.

### 2. Vendor-attested VEX without consumer verification

```yaml
vex:
cve: CVE-2024-3094
component: xz-utils
status: Not Affected
justification: vulnerable_code_not_in_execute_path
verification_status: vendor_attested
consumer_runtime_trace: missing
assessment:
vex_credibility: Medium
action: verify reachability before closing risk for critical systems
```

Expected handling: preserve the VEX status, but do not treat the justification as equally strong as consumer-verified evidence.

### 3. Stale SBOM for old release

```yaml
sbom_metadata:
sbom_timestamp: "2025-06-01T10:00:00Z"
sbom_software_version: "4.2.0"
latest_release_version: "5.1.0"
latest_release_date: "2026-03-15"
cve_scan_date: "2025-06-01"
assessment:
sbom_age_category: Stale
trustworthiness: Low
```

Expected handling: downgrade usefulness even if component fields look complete.

### 4. Stale Under Investigation VEX

```yaml
vex:
cve: CVE-2026-1000
status: Under Investigation
first_seen: "2026-01-01"
vendor_sla_days: 30
current_age_days: 75
assessment:
stale_vex: true
action: escalate; do not leave risk unresolved indefinitely
```

## Benign or Lower-Risk Cases

### 1. Complete dependency graph

```yaml
sbom:
components:
direct: 10
transitive: 65
dependency_graph:
traceable_depth_max: 7
orphan_component_relationships: 0
transitive_parent_linkage: complete
assessment:
graph_completeness_rating: Complete Graph
```

Expected handling: deep graph alone is not a completeness failure when parent-child paths are traceable.

### 2. Consumer-verified Not Affected VEX

```yaml
vex:
cve: CVE-2024-21626
component: runc
status: Not Affected
justification: vulnerable_code_not_present
verification_status: consumer_verified
verification_evidence: SBOM version match plus source review
assessment:
vex_credibility: High
```

Expected handling: record high credibility because the consumer verified the justification, not only the vendor.

### 3. Fresh and signed SBOM

```yaml
sbom_metadata:
timestamp: "2026-06-06T18:20:00Z"
software_version: "5.1.0"
release_version: "5.1.0"
build_provenance: Sigstore signed attestation
generation_tool: cyclonedx-cli 0.27.2
assessment:
sbom_age_category: Fresh
trustworthiness: High
```

Expected handling: freshness and provenance strengthen trust in the SBOM's current decision value.