more audit work
This commit is contained in:
master
222
docs/modules/scanner/pedigree-support.md
Normal file
222
docs/modules/scanner/pedigree-support.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# CycloneDX 1.7 Pedigree Support
|
||||
|
||||
> **Status:** Implementation in progress
|
||||
> **Sprint:** SPRINT_20260107_005_002
|
||||
> **Last Updated:** 2026-01-08
|
||||
|
||||
## Overview
|
||||
|
||||
StellaOps Scanner now supports native CycloneDX 1.7 `component.pedigree.*` fields, enabling detailed representation of component lineage, upstream ancestry, patch history, and commit provenance.
|
||||
|
||||
This integration connects Feedser's backport detection capabilities directly into the SBOM output, providing:
|
||||
|
||||
- **Ancestry tracking**: Links to upstream source packages
|
||||
- **Variant mapping**: Distribution-specific package versions
|
||||
- **Commit provenance**: Security fix commit references
|
||||
- **Patch documentation**: Backport and cherry-pick evidence
|
||||
|
||||
## CycloneDX 1.7 Pedigree Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"components": [
|
||||
{
|
||||
"type": "library",
|
||||
"name": "openssl",
|
||||
"version": "1.1.1n-0+deb11u5",
|
||||
"purl": "pkg:deb/debian/openssl@1.1.1n-0+deb11u5",
|
||||
"pedigree": {
|
||||
"ancestors": [
|
||||
{
|
||||
"type": "library",
|
||||
"name": "openssl",
|
||||
"version": "1.1.1n",
|
||||
"purl": "pkg:generic/openssl@1.1.1n"
|
||||
}
|
||||
],
|
||||
"variants": [
|
||||
{
|
||||
"type": "library",
|
||||
"name": "openssl",
|
||||
"version": "1.1.1k-9.el9",
|
||||
"purl": "pkg:rpm/rhel/openssl@1.1.1k-9.el9"
|
||||
}
|
||||
],
|
||||
"commits": [
|
||||
{
|
||||
"uid": "abc123def456789",
|
||||
"url": "https://github.com/openssl/openssl/commit/abc123",
|
||||
"message": "Fix CVE-2024-1234"
|
||||
}
|
||||
],
|
||||
"patches": [
|
||||
{
|
||||
"type": "backport",
|
||||
"diff": {
|
||||
"url": "https://salsa.debian.org/...",
|
||||
"text": "--- a/crypto/x509/x509_vfy.c\n+++ b/crypto/x509/x509_vfy.c\n..."
|
||||
},
|
||||
"resolves": [
|
||||
{
|
||||
"type": "security",
|
||||
"id": "CVE-2024-1234",
|
||||
"source": { "name": "NVD" }
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"notes": "Backported security fix from upstream 1.1.1o (CVE-2024-1234). Confidence: 95%. Tier 1 (exact match)."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## API Usage
|
||||
|
||||
### Basic Pedigree Lookup
|
||||
|
||||
```csharp
|
||||
// Inject IPedigreeDataProvider
|
||||
public class SbomEnricher(IPedigreeDataProvider pedigreeProvider)
|
||||
{
|
||||
public async Task EnrichAsync(Component component, CancellationToken ct)
|
||||
{
|
||||
var pedigree = await pedigreeProvider.GetPedigreeAsync(component.Purl, ct);
|
||||
|
||||
if (pedigree is not null)
|
||||
{
|
||||
var mapper = new CycloneDxPedigreeMapper();
|
||||
component.Pedigree = mapper.Map(pedigree);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Batch Pedigree Enrichment
|
||||
|
||||
```csharp
|
||||
// Efficient batch lookup for multiple components
|
||||
var purls = components.Select(c => c.Purl).ToList();
|
||||
var pedigrees = await pedigreeProvider.GetPedigreesBatchAsync(purls, ct);
|
||||
|
||||
foreach (var component in components)
|
||||
{
|
||||
if (pedigrees.TryGetValue(component.Purl, out var data))
|
||||
{
|
||||
component.Pedigree = mapper.Map(data);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Building Pedigree Data Manually
|
||||
|
||||
```csharp
|
||||
// Use builders for custom pedigree construction
|
||||
var ancestorBuilder = new AncestorComponentBuilder();
|
||||
ancestorBuilder
|
||||
.AddGenericUpstream("openssl", "1.1.1n", "https://www.openssl.org")
|
||||
.AddGitHubUpstream("openssl", "openssl", "openssl-1.1.1n");
|
||||
|
||||
var variantBuilder = new VariantComponentBuilder();
|
||||
variantBuilder
|
||||
.AddDebianPackage("openssl", "1.1.1n-0+deb11u5", "bullseye", "amd64")
|
||||
.AddRpmPackage("openssl", "1.1.1k-9.el9", "rhel", "9", "x86_64")
|
||||
.AddAlpinePackage("openssl", "1.1.1t-r2", "3.17");
|
||||
|
||||
var commitBuilder = new CommitInfoBuilder();
|
||||
commitBuilder
|
||||
.AddGitHubCommit("openssl", "openssl", "abc123def", "Fix CVE-2024-1234");
|
||||
|
||||
var patchBuilder = new PatchInfoBuilder();
|
||||
patchBuilder
|
||||
.AddBackport(
|
||||
diffUrl: "https://salsa.debian.org/...",
|
||||
resolvesCves: new[] { "CVE-2024-1234" },
|
||||
source: "debian-security");
|
||||
|
||||
var pedigree = new PedigreeData
|
||||
{
|
||||
Ancestors = ancestorBuilder.Build(),
|
||||
Variants = variantBuilder.Build(),
|
||||
Commits = commitBuilder.Build(),
|
||||
Patches = patchBuilder.Build()
|
||||
};
|
||||
```
|
||||
|
||||
## Feedser Integration
|
||||
|
||||
### Tier Mapping
|
||||
|
||||
| Feedser Tier | Confidence | Description |
|
||||
|--------------|------------|-------------|
|
||||
| Tier 1 | 95-100% | Exact function signature match |
|
||||
| Tier 2 | 80-94% | Changelog/commit message correlation |
|
||||
| Tier 3 | 60-79% | Patch header/context match |
|
||||
| Tier 4 | 40-59% | Binary fingerprint correlation |
|
||||
| Tier 5 | 20-39% | NVD version range heuristic |
|
||||
|
||||
### Patch Origin Mapping
|
||||
|
||||
| Feedser Origin | CycloneDX Patch Type | Description |
|
||||
|----------------|---------------------|-------------|
|
||||
| `upstream` | `cherry-pick` | Direct cherry-pick from upstream |
|
||||
| `distro` | `backport` | Distro-maintained backport |
|
||||
| `vendor` | `unofficial` | Vendor-specific fix |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Scanner Options
|
||||
|
||||
```yaml
|
||||
scanner:
|
||||
sbom:
|
||||
pedigree:
|
||||
enabled: true # Enable pedigree population
|
||||
include_diff: true # Include patch diff text
|
||||
max_diff_size: 50000 # Truncate large diffs
|
||||
cache:
|
||||
enabled: true
|
||||
max_entries: 10000
|
||||
sliding_expiration: 30m
|
||||
absolute_expiration: 4h
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Enable/disable pedigree
|
||||
STELLAOPS_SCANNER_PEDIGREE_ENABLED=true
|
||||
|
||||
# Cache configuration
|
||||
STELLAOPS_PEDIGREE_CACHE_MAX_ENTRIES=10000
|
||||
STELLAOPS_PEDIGREE_CACHE_TTL=4h
|
||||
```
|
||||
|
||||
## Notes Field Format
|
||||
|
||||
The `pedigree.notes` field provides human-readable context:
|
||||
|
||||
```
|
||||
Security patches: 2 backports resolving 3 CVEs.
|
||||
Derived from upstream openssl 1.1.1n.
|
||||
Variants exist for: alpine, debian, rhel.
|
||||
Evidence: confidence 95%, Tier 1 (exact match).
|
||||
Generated: 2026-01-08T12:00:00Z by StellaOps Feedser.
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
1. **Batch lookups**: Use `GetPedigreesBatchAsync` for multiple components to avoid N+1 queries.
|
||||
|
||||
2. **Caching**: The `CachedPedigreeDataProvider` wraps the Feedser client with bounded MemoryCache.
|
||||
|
||||
3. **Negative caching**: Components without pedigree are cached with shorter TTL to reduce repeated lookups.
|
||||
|
||||
4. **Diff truncation**: Large patch diffs are automatically truncated with a link to the full source.
|
||||
|
||||
## See Also
|
||||
|
||||
- [CycloneDX 1.7 Specification - Pedigree](https://cyclonedx.org/docs/1.7/json/#components_items_pedigree)
|
||||
- [Feedser Architecture](../feedser/architecture.md)
|
||||
- [SBOM Generation Guide](./sbom-generation.md)
|
||||
Reference in New Issue
Block a user