diff --git a/skills/vuln-management/sbom-analysis/SKILL.md b/skills/vuln-management/sbom-analysis/SKILL.md index 14b1679e..9c0ba189 100644 --- a/skills/vuln-management/sbom-analysis/SKILL.md +++ b/skills/vuln-management/sbom-analysis/SKILL.md @@ -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 @@ -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. @@ -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. @@ -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: @@ -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 @@ -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 | @@ -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 diff --git a/skills/vuln-management/sbom-analysis/sbom-quality-examples.md b/skills/vuln-management/sbom-analysis/sbom-quality-examples.md new file mode 100644 index 00000000..36b82132 --- /dev/null +++ b/skills/vuln-management/sbom-analysis/sbom-quality-examples.md @@ -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.