282 lines
8.4 KiB
Markdown
282 lines
8.4 KiB
Markdown
# Linkset Conflicts API Reference (v1)
|
|
|
|
Status: stable; aligns with LNM v1 (frozen 2025-11-17).
|
|
|
|
## Intent
|
|
- Document conflict detection and representation in the Link-Not-Merge system.
|
|
- Conflicts are surfaced but never automatically resolved; consumers implement their own resolution strategy.
|
|
- This reference describes conflict types, detection logic, and how conflicts appear in API responses.
|
|
|
|
## Philosophy: Link-Not-Merge
|
|
The Concelier LNM (Link-Not-Merge) approach differs from traditional advisory aggregation:
|
|
- **Link**: Observations from multiple sources are linked together via shared identifiers (CVE, GHSA, PURL, CPE).
|
|
- **Not Merge**: Conflicting data is preserved with full provenance rather than collapsed into a single "truth".
|
|
- **Surface, Don't Resolve**: Conflicts are clearly marked for downstream consumers to handle according to their own policies.
|
|
|
|
## Conflict Types
|
|
|
|
### severity-mismatch
|
|
Sources disagree on severity rating.
|
|
```json
|
|
{
|
|
"field": "severity",
|
|
"reason": "severity-mismatch",
|
|
"observedValue": "critical",
|
|
"observedAt": "2025-11-18T08:00:00Z",
|
|
"evidenceHash": "sha256:f6e5d4c3b2a1098765432109876543210fedcba0987654321fedcba098765432"
|
|
}
|
|
```
|
|
|
|
**Detection**: Triggered when severity labels (critical, high, medium, low) or CVSS scores differ by more than 1.0 points between observations.
|
|
|
|
**Common causes**:
|
|
- Different CVSS versions (v2 vs v3 vs v3.1)
|
|
- Vendor-specific severity assessments
|
|
- Time lag between source updates
|
|
|
|
### version-range-conflict
|
|
Sources disagree on affected version ranges.
|
|
```json
|
|
{
|
|
"field": "affected.ranges",
|
|
"reason": "version-range-conflict",
|
|
"observedValue": "{\"fixed\": \"2.0.0\"}",
|
|
"observedAt": "2025-11-19T12:00:00Z",
|
|
"evidenceHash": "sha256:a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
|
|
}
|
|
```
|
|
|
|
**Detection**: Triggered when version range events differ between observations for the same package.
|
|
|
|
**Common causes**:
|
|
- Backports creating different fix points per distribution
|
|
- Vendor patches not reflected in upstream
|
|
- Different ecosystem-specific versioning
|
|
|
|
### status-conflict
|
|
Sources disagree on vulnerability status.
|
|
```json
|
|
{
|
|
"field": "status",
|
|
"reason": "status-conflict",
|
|
"observedValue": "not_affected",
|
|
"observedAt": "2025-11-20T09:00:00Z",
|
|
"evidenceHash": "sha256:b2c3d4e5f6a789012345678901234567890abcdef1234567890abcdef1234567b"
|
|
}
|
|
```
|
|
|
|
**Detection**: Triggered when status values (affected, not_affected, under_investigation, fixed) differ.
|
|
|
|
**Common causes**:
|
|
- VEX statements from vendors
|
|
- Incomplete upstream analysis
|
|
- Context-specific applicability (e.g., platform-dependent)
|
|
|
|
### cpe-mismatch
|
|
Sources disagree on CPE identifiers.
|
|
```json
|
|
{
|
|
"field": "cpe",
|
|
"reason": "cpe-mismatch",
|
|
"observedValue": "cpe:2.3:a:example:lib:*:*:*:*:*:*:*:*",
|
|
"observedAt": "2025-11-18T16:00:00Z",
|
|
"evidenceHash": "sha256:c3d4e5f6a789012345678901234567890abcdef1234567890abcdef123456789c"
|
|
}
|
|
```
|
|
|
|
**Detection**: Triggered when CPE identifiers for the same advisory don't match.
|
|
|
|
**Common causes**:
|
|
- Different CPE dictionary versions
|
|
- Vendor vs product naming variations
|
|
- Platform-specific CPE assignments
|
|
|
|
### reference-conflict
|
|
Sources provide conflicting reference information.
|
|
```json
|
|
{
|
|
"field": "references",
|
|
"reason": "reference-conflict",
|
|
"observedValue": "https://example.com/advisory/different",
|
|
"observedAt": "2025-11-21T10:00:00Z",
|
|
"evidenceHash": "sha256:d4e5f6a789012345678901234567890abcdef1234567890abcdef123456789def"
|
|
}
|
|
```
|
|
|
|
## Conflict in Linkset Response
|
|
|
|
Full linkset with multiple conflicts:
|
|
```json
|
|
{
|
|
"advisoryId": "CVE-2024-9999",
|
|
"source": "aggregated",
|
|
"purl": ["pkg:maven/org.example/library@1.5.0"],
|
|
"cpe": [
|
|
"cpe:2.3:a:example:library:1.5.0:*:*:*:*:*:*:*",
|
|
"cpe:2.3:a:example_inc:lib:1.5.0:*:*:*:*:java:*:*"
|
|
],
|
|
"summary": "Deserialization vulnerability in example library",
|
|
"publishedAt": "2024-09-01T00:00:00Z",
|
|
"modifiedAt": "2024-09-15T00:00:00Z",
|
|
"severity": "high",
|
|
"status": "affected",
|
|
"provenance": {
|
|
"ingestedAt": "2025-11-20T10:30:00Z",
|
|
"connectorId": "multi-source-aggregator",
|
|
"evidenceHash": "sha256:aggregated-evidence-hash"
|
|
},
|
|
"conflicts": [
|
|
{
|
|
"field": "severity",
|
|
"reason": "severity-mismatch",
|
|
"observedValue": "critical",
|
|
"observedAt": "2025-11-15T10:00:00Z",
|
|
"evidenceHash": "sha256:nvd-observation-hash"
|
|
},
|
|
{
|
|
"field": "severity",
|
|
"reason": "severity-mismatch",
|
|
"observedValue": "medium",
|
|
"observedAt": "2025-11-18T14:00:00Z",
|
|
"evidenceHash": "sha256:vendor-observation-hash"
|
|
},
|
|
{
|
|
"field": "cpe",
|
|
"reason": "cpe-mismatch",
|
|
"observedValue": "cpe:2.3:a:example_inc:lib:1.5.0:*:*:*:*:java:*:*",
|
|
"observedAt": "2025-11-17T08:00:00Z",
|
|
"evidenceHash": "sha256:github-observation-hash"
|
|
},
|
|
{
|
|
"field": "affected.ranges",
|
|
"reason": "version-range-conflict",
|
|
"observedValue": "{\"type\": \"SEMVER\", \"events\": [{\"introduced\": \"1.0.0\"}, {\"fixed\": \"1.5.1\"}]}",
|
|
"observedAt": "2025-11-19T12:00:00Z",
|
|
"evidenceHash": "sha256:distro-observation-hash"
|
|
}
|
|
],
|
|
"timeline": [
|
|
{"event": "first-observed", "at": "2025-11-15T10:00:00Z", "evidenceHash": "sha256:nvd-observation-hash"},
|
|
{"event": "conflict-detected", "at": "2025-11-17T08:00:00Z", "evidenceHash": "sha256:github-observation-hash"},
|
|
{"event": "conflict-detected", "at": "2025-11-18T14:00:00Z", "evidenceHash": "sha256:vendor-observation-hash"},
|
|
{"event": "conflict-detected", "at": "2025-11-19T12:00:00Z", "evidenceHash": "sha256:distro-observation-hash"}
|
|
],
|
|
"normalized": {
|
|
"aliases": ["CVE-2024-9999", "GHSA-xxxx-yyyy-zzzz"],
|
|
"severities": [
|
|
{"source": "nvd", "type": "CVSS_V3", "score": 9.8, "label": "critical"},
|
|
{"source": "github", "type": "CVSS_V3", "score": 7.5, "label": "high"},
|
|
{"source": "vendor", "type": "CVSS_V3", "score": 5.3, "label": "medium"}
|
|
],
|
|
"ranges": [
|
|
{"source": "nvd", "type": "SEMVER", "introduced": "0", "fixed": "1.6.0"},
|
|
{"source": "distro", "type": "SEMVER", "introduced": "1.0.0", "fixed": "1.5.1"}
|
|
]
|
|
},
|
|
"cached": false,
|
|
"observations": [
|
|
"obs:nvd:CVE-2024-9999:2025-11-15",
|
|
"obs:github:GHSA-xxxx-yyyy-zzzz:2025-11-17",
|
|
"obs:vendor:CVE-2024-9999:2025-11-18",
|
|
"obs:distro:CVE-2024-9999:2025-11-19"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Querying for Conflicts
|
|
|
|
### List Only Linksets with Conflicts
|
|
```bash
|
|
GET /v1/lnm/linksets?includeConflicts=true&hasConflicts=true
|
|
X-Stella-Tenant: acme
|
|
```
|
|
|
|
### Filter by Conflict Type
|
|
```bash
|
|
POST /v1/lnm/linksets/search
|
|
X-Stella-Tenant: acme
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"conflictTypes": ["severity-mismatch", "version-range-conflict"],
|
|
"includeConflicts": true,
|
|
"pageSize": 50
|
|
}
|
|
```
|
|
|
|
### Advisory Summary with Conflicts
|
|
```bash
|
|
GET /advisories/summary?conflicts_only=true
|
|
X-Stella-Tenant: acme
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"meta": {
|
|
"tenant": "acme",
|
|
"count": 3,
|
|
"sort": "advisory"
|
|
},
|
|
"items": [
|
|
{
|
|
"advisoryKey": "CVE-2024-9999",
|
|
"aliases": ["CVE-2024-9999", "GHSA-xxxx-yyyy-zzzz"],
|
|
"source": "aggregated",
|
|
"confidence": 0.65,
|
|
"conflicts": [
|
|
{"field": "severity", "reason": "severity-mismatch", "sourceIds": ["nvd", "vendor", "github"]}
|
|
],
|
|
"counts": {
|
|
"observations": 4,
|
|
"conflictFields": 2
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Conflict Resolution Strategies
|
|
|
|
Concelier does not resolve conflicts, but here are common strategies consumers implement:
|
|
|
|
### Source Priority
|
|
Prioritize sources by trust level:
|
|
```
|
|
nvd > vendor > github > community
|
|
```
|
|
|
|
### Most Recent
|
|
Use the most recently observed value:
|
|
```
|
|
Sort by observedAt desc, take first
|
|
```
|
|
|
|
### Most Conservative
|
|
For severity, use the highest rating:
|
|
```
|
|
critical > high > medium > low
|
|
```
|
|
|
|
### Voting/Consensus
|
|
Use the value with most agreement:
|
|
```
|
|
Count occurrences, take majority
|
|
```
|
|
|
|
## Conflict Confidence Impact
|
|
The `confidence` field in linksets reflects conflict presence:
|
|
- **No conflicts**: confidence ≥ 0.9
|
|
- **Minor conflicts** (1-2 fields): confidence 0.7-0.9
|
|
- **Major conflicts** (3+ fields or severity): confidence < 0.7
|
|
|
|
## Notes
|
|
- Conflicts are preserved indefinitely; they are only removed if all observations align.
|
|
- Evidence hashes allow consumers to trace conflicts back to specific observations.
|
|
- The `timeline` array shows when conflicts were first detected.
|
|
- Multiple conflicts on the same field from different sources create multiple entries.
|
|
|
|
## Changelog
|
|
- 2025-12-06: Initial conflict reference documentation (CONCELIER-WEB-OAS-62-001).
|
|
- 2025-11-17: LNM v1 conflict model frozen.
|