165 lines
4.1 KiB
Markdown
165 lines
4.1 KiB
Markdown
# DeltaSig v2 Predicate Schema
|
|
|
|
> **Sprint**: SPRINT_20260119_004_BinaryIndex_deltasig_extensions
|
|
> **Status**: Implemented
|
|
|
|
## Overview
|
|
|
|
DeltaSig v2 extends the function-level binary diff predicate with:
|
|
|
|
- **Symbol Provenance**: Links function matches to ground-truth corpus sources (debuginfod, ddeb, buildinfo, secdb)
|
|
- **IR Diff References**: CAS-stored intermediate representation diffs for detailed analysis
|
|
- **Explicit Verdicts**: Clear vulnerability status with confidence scores
|
|
- **Function Match States**: Per-function vulnerable/patched/modified/unchanged classification
|
|
|
|
## Schema
|
|
|
|
**Predicate Type URI**: `https://stella-ops.org/predicates/deltasig/v2`
|
|
|
|
### Key Fields
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `schemaVersion` | string | Always `"2.0.0"` |
|
|
| `subject` | object | Single subject (PURL, digest, arch) |
|
|
| `functionMatches` | array | Function-level matches with evidence |
|
|
| `verdict` | string | `vulnerable`, `patched`, `partial`, `unknown`, `partially_patched`, `inconclusive` |
|
|
| `confidence` | number | 0.0-1.0 confidence score |
|
|
| `summary` | object | Aggregate statistics |
|
|
|
|
### Function Match
|
|
|
|
```json
|
|
{
|
|
"functionId": "sha256:abc123...",
|
|
"name": "ssl_handshake",
|
|
"address": 4194304,
|
|
"size": 256,
|
|
"matchScore": 0.95,
|
|
"matchMethod": "semantic_ksg",
|
|
"matchState": "patched",
|
|
"symbolProvenance": {
|
|
"sourceId": "fedora-debuginfod",
|
|
"observationId": "obs:gt:12345",
|
|
"confidence": 0.98,
|
|
"resolvedAt": "2026-01-19T12:00:00Z"
|
|
},
|
|
"irDiff": {
|
|
"casDigest": "sha256:def456...",
|
|
"statementsAdded": 5,
|
|
"statementsRemoved": 3,
|
|
"changedInstructions": 8
|
|
}
|
|
}
|
|
```
|
|
|
|
### Summary
|
|
|
|
```json
|
|
{
|
|
"totalFunctions": 150,
|
|
"vulnerableFunctions": 0,
|
|
"patchedFunctions": 12,
|
|
"unknownFunctions": 138,
|
|
"functionsWithProvenance": 45,
|
|
"functionsWithIrDiff": 12,
|
|
"avgMatchScore": 0.85,
|
|
"minMatchScore": 0.42,
|
|
"maxMatchScore": 0.99,
|
|
"totalIrDiffSize": 1234
|
|
}
|
|
```
|
|
|
|
## Version Negotiation
|
|
|
|
Clients can request specific predicate versions:
|
|
|
|
```json
|
|
{
|
|
"preferredVersion": "2",
|
|
"requiredFeatures": ["provenance", "ir-diff"]
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"version": "2.0.0",
|
|
"predicateType": "https://stella-ops.org/predicates/deltasig/v2",
|
|
"features": ["provenance", "ir-diff"]
|
|
}
|
|
```
|
|
|
|
## VEX Integration
|
|
|
|
DeltaSig v2 predicates can be converted to VEX observations via `IDeltaSigVexBridge`:
|
|
|
|
| DeltaSig Verdict | VEX Status |
|
|
|------------------|------------|
|
|
| `patched` | `fixed` |
|
|
| `vulnerable` | `affected` |
|
|
| `partially_patched` | `under_investigation` |
|
|
| `inconclusive` | `under_investigation` |
|
|
| `unknown` | `not_affected` (conservative) |
|
|
|
|
### Evidence Blocks
|
|
|
|
VEX observations include evidence blocks:
|
|
|
|
1. **deltasig-summary**: Aggregate statistics
|
|
2. **deltasig-function-matches**: High-confidence matches with provenance
|
|
3. **deltasig-predicate-ref**: Reference to full predicate
|
|
|
|
## Implementation
|
|
|
|
### Core Services
|
|
|
|
| Interface | Implementation | Description |
|
|
|-----------|----------------|-------------|
|
|
| `IDeltaSigServiceV2` | `DeltaSigServiceV2` | V2 predicate generation |
|
|
| `ISymbolProvenanceResolver` | `GroundTruthProvenanceResolver` | Ground-truth lookup |
|
|
| `IIrDiffGenerator` | `IrDiffGenerator` | IR diff generation with CAS |
|
|
| `IDeltaSigVexBridge` | `DeltaSigVexBridge` | VEX observation generation |
|
|
|
|
### DI Registration
|
|
|
|
```csharp
|
|
services.AddDeltaSigV2();
|
|
```
|
|
|
|
Or with options:
|
|
|
|
```csharp
|
|
services.AddDeltaSigV2(
|
|
configureProvenance: opts => opts.IncludeStale = false,
|
|
configureIrDiff: opts => opts.MaxParallelism = 4
|
|
);
|
|
```
|
|
|
|
## Migration from v1
|
|
|
|
Use `DeltaSigPredicateConverter`:
|
|
|
|
```csharp
|
|
// v1 → v2
|
|
var v2 = DeltaSigPredicateConverter.ToV2(v1Predicate);
|
|
|
|
// v2 → v1
|
|
var v1 = DeltaSigPredicateConverter.ToV1(v2Predicate);
|
|
```
|
|
|
|
Notes:
|
|
- v1 → v2: Provenance and IR diff will be empty (add via resolver/generator)
|
|
- v2 → v1: Provenance and IR diff are discarded; verdict/confidence are lost
|
|
|
|
## JSON Schema
|
|
|
|
Full schema: [`docs/schemas/predicates/deltasig-v2.schema.json`](../../../schemas/predicates/deltasig-v2.schema.json)
|
|
|
|
## Related Documentation
|
|
|
|
- [Ground-Truth Corpus](./ground-truth-corpus.md)
|
|
- [Semantic Diffing](./semantic-diffing.md)
|
|
- [Architecture](./architecture.md)
|