Complete batch 012 (golden set diff) and 013 (advisory chat), fix build errors
Sprints completed: - SPRINT_20260110_012_* (golden set diff layer - 10 sprints) - SPRINT_20260110_013_* (advisory chat - 4 sprints) Build fixes applied: - Fix namespace conflicts with Microsoft.Extensions.Options.Options.Create - Fix VexDecisionReachabilityIntegrationTests API drift (major rewrite) - Fix VexSchemaValidationTests FluentAssertions method name - Fix FixChainGateIntegrationTests ambiguous type references - Fix AdvisoryAI test files required properties and namespace aliases - Add stub types for CveMappingController (ICveSymbolMappingService) - Fix VerdictBuilderService static context issue Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
master
340
docs/modules/attestor/fix-chain-predicate.md
Normal file
340
docs/modules/attestor/fix-chain-predicate.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# FixChain Attestation Predicate
|
||||
|
||||
> **Sprint:** SPRINT_20260110_012_005_ATTESTOR
|
||||
> **Predicate Type:** `https://stella-ops.org/predicates/fix-chain/v1`
|
||||
> **Last Updated:** 10-Jan-2026
|
||||
|
||||
## Overview
|
||||
|
||||
The FixChain predicate provides cryptographically verifiable proof that a patch eliminates a vulnerable code path. It bridges the gap between vulnerability disclosure and fix verification by encoding evidence from binary analysis into a DSSE-signed attestation.
|
||||
|
||||
## Why FixChain?
|
||||
|
||||
| Current State | With FixChain |
|
||||
|---------------|---------------|
|
||||
| Trust vendor claims | Verify with evidence chain |
|
||||
| No attestable fix evidence | DSSE-signed fix proofs |
|
||||
| Version-based assumptions | Binary signature comparison |
|
||||
| No air-gap verification | Offline-verifiable bundles |
|
||||
|
||||
## Predicate Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"$id": "https://stella-ops.org/schemas/predicates/fix-chain/v1",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"cveId", "component", "goldenSetRef", "vulnerableBinary",
|
||||
"patchedBinary", "sbomRef", "signatureDiff", "reachability",
|
||||
"verdict", "analyzer", "analyzedAt"
|
||||
],
|
||||
"properties": {
|
||||
"cveId": {
|
||||
"description": "CVE or GHSA identifier",
|
||||
"pattern": "^CVE-\\d{4}-\\d{4,}$|^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$"
|
||||
},
|
||||
"component": {
|
||||
"description": "Component being verified"
|
||||
},
|
||||
"goldenSetRef": {
|
||||
"description": "Content-addressed reference to golden set definition"
|
||||
},
|
||||
"vulnerableBinary": {
|
||||
"description": "Pre-patch binary identity (SHA-256, architecture)"
|
||||
},
|
||||
"patchedBinary": {
|
||||
"description": "Post-patch binary identity (SHA-256, architecture, PURL)"
|
||||
},
|
||||
"sbomRef": {
|
||||
"description": "Reference to SBOM containing the component"
|
||||
},
|
||||
"signatureDiff": {
|
||||
"description": "Summary of signature differences"
|
||||
},
|
||||
"reachability": {
|
||||
"description": "Reachability analysis outcome"
|
||||
},
|
||||
"verdict": {
|
||||
"description": "Final fix determination",
|
||||
"properties": {
|
||||
"status": { "enum": ["fixed", "partial", "not_fixed", "inconclusive"] },
|
||||
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
|
||||
"rationale": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"analyzer": {
|
||||
"description": "Analyzer metadata for reproducibility"
|
||||
},
|
||||
"analyzedAt": {
|
||||
"description": "ISO 8601 timestamp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Evidence Chain
|
||||
|
||||
The FixChain attestation encodes evidence from multiple analysis stages:
|
||||
|
||||
```
|
||||
Golden Set Definition (CVE signature)
|
||||
|
|
||||
v
|
||||
+------------------+ +------------------+
|
||||
| Vulnerable Binary| --> | Patch Diff Engine|
|
||||
+------------------+ +------------------+
|
||||
| |
|
||||
v v
|
||||
+------------------+ +------------------+
|
||||
| Patched Binary | --> | Signature Diff |
|
||||
+------------------+ +------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| Reachability |
|
||||
| Analysis |
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| FixChain |
|
||||
| Attestation |
|
||||
+------------------+
|
||||
```
|
||||
|
||||
## Verdict Calculation
|
||||
|
||||
The verdict is calculated based on multiple factors:
|
||||
|
||||
### Status Values
|
||||
|
||||
| Status | Description | Conditions |
|
||||
|--------|-------------|------------|
|
||||
| `fixed` | Vulnerability fully addressed | High confidence (>=80%), all paths eliminated |
|
||||
| `partial` | Vulnerability partially addressed | Medium confidence (50-80%), some paths remain |
|
||||
| `not_fixed` | Vulnerability still present | Diff shows no fix, paths unchanged |
|
||||
| `inconclusive` | Cannot determine | Low confidence, insufficient evidence |
|
||||
|
||||
### Confidence Scoring
|
||||
|
||||
```
|
||||
Confidence = Base + FunctionBonus + EdgeBonus + PathBonus
|
||||
|
||||
Base = Diff.Confidence (from analysis)
|
||||
|
||||
FunctionBonus:
|
||||
- +0.1 per vulnerable function removed
|
||||
- +0.05 per vulnerable function modified
|
||||
|
||||
EdgeBonus:
|
||||
- +0.05 per vulnerable edge eliminated
|
||||
|
||||
PathBonus:
|
||||
- +0.3 if all paths eliminated
|
||||
- +0.1 if paths reduced by >50%
|
||||
```
|
||||
|
||||
### Rationale Generation
|
||||
|
||||
The rationale array explains the verdict:
|
||||
|
||||
```json
|
||||
{
|
||||
"rationale": [
|
||||
"3 vulnerable function(s) removed",
|
||||
"5 vulnerable edge(s) eliminated",
|
||||
"All paths to vulnerable sink eliminated"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Example Attestation
|
||||
|
||||
```json
|
||||
{
|
||||
"_type": "https://in-toto.io/Statement/v1",
|
||||
"subject": [{
|
||||
"name": "pkg:deb/debian/openssl@3.1.0",
|
||||
"digest": {
|
||||
"sha256": "abc123..."
|
||||
}
|
||||
}],
|
||||
"predicateType": "https://stella-ops.org/predicates/fix-chain/v1",
|
||||
"predicate": {
|
||||
"cveId": "CVE-2024-0727",
|
||||
"component": "openssl",
|
||||
"goldenSetRef": {
|
||||
"digest": "sha256:def456..."
|
||||
},
|
||||
"vulnerableBinary": {
|
||||
"sha256": "111111...",
|
||||
"architecture": "x86_64"
|
||||
},
|
||||
"patchedBinary": {
|
||||
"sha256": "222222...",
|
||||
"architecture": "x86_64",
|
||||
"purl": "pkg:deb/debian/openssl@3.1.0"
|
||||
},
|
||||
"sbomRef": {
|
||||
"digest": "sha256:789abc..."
|
||||
},
|
||||
"signatureDiff": {
|
||||
"vulnerableFunctionsRemoved": 1,
|
||||
"vulnerableFunctionsModified": 2,
|
||||
"vulnerableEdgesEliminated": 5,
|
||||
"sanitizersInserted": 0,
|
||||
"details": ["Function X509_VERIFY_PARAM_set_flags rewritten"]
|
||||
},
|
||||
"reachability": {
|
||||
"prePathCount": 3,
|
||||
"postPathCount": 0,
|
||||
"eliminated": true,
|
||||
"reason": "All 3 path(s) to vulnerable sink eliminated"
|
||||
},
|
||||
"verdict": {
|
||||
"status": "fixed",
|
||||
"confidence": 0.95,
|
||||
"rationale": [
|
||||
"1 vulnerable function(s) removed",
|
||||
"5 vulnerable edge(s) eliminated",
|
||||
"All paths to vulnerable sink eliminated"
|
||||
]
|
||||
},
|
||||
"analyzer": {
|
||||
"name": "StellaOps.BinaryIndex",
|
||||
"version": "1.0.0",
|
||||
"sourceDigest": "sha256:analyzerxyz..."
|
||||
},
|
||||
"analyzedAt": "2026-01-10T12:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
### Create FixChain Attestation
|
||||
|
||||
```bash
|
||||
stella attest fixchain \
|
||||
--sbom sbom.cdx.json \
|
||||
--diff diff-result.json \
|
||||
--golden golden-set.yaml \
|
||||
--out fixchain.dsse.json \
|
||||
--arch x86_64 \
|
||||
--purl "pkg:deb/debian/openssl@3.1.0"
|
||||
```
|
||||
|
||||
### Verify FixChain Attestation
|
||||
|
||||
```bash
|
||||
stella attest fixchain-verify \
|
||||
--attestation fixchain.dsse.json \
|
||||
--format summary
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
[OK] FixChain attestation is valid
|
||||
CVE: CVE-2024-0727
|
||||
Component: openssl
|
||||
Verdict: fixed (95%)
|
||||
Analyzed: 2026-01-10T12:00:00Z
|
||||
```
|
||||
|
||||
### JSON Output
|
||||
|
||||
```bash
|
||||
stella attest fixchain-verify \
|
||||
--attestation fixchain.dsse.json \
|
||||
--format json
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
### Service Registration
|
||||
|
||||
```csharp
|
||||
services.AddFixChainAttestation(opts =>
|
||||
{
|
||||
opts.AnalyzerName = "MyAnalyzer";
|
||||
opts.AnalyzerVersion = "1.0.0";
|
||||
opts.FixedConfidenceThreshold = 0.80m;
|
||||
});
|
||||
```
|
||||
|
||||
### Creating Attestation
|
||||
|
||||
```csharp
|
||||
var request = new FixChainBuildRequest
|
||||
{
|
||||
CveId = "CVE-2024-0727",
|
||||
Component = "openssl",
|
||||
GoldenSetDigest = goldenSetDigest,
|
||||
SbomDigest = sbomDigest,
|
||||
VulnerableBinary = new BinaryIdentity { ... },
|
||||
PatchedBinary = new BinaryIdentity { ... },
|
||||
ComponentPurl = "pkg:deb/debian/openssl@3.1.0",
|
||||
DiffResult = diffResult
|
||||
};
|
||||
|
||||
var result = await attestationService.CreateAsync(request);
|
||||
// result.EnvelopeJson - DSSE envelope
|
||||
// result.ContentDigest - SHA-256 of statement
|
||||
// result.Predicate - Parsed predicate
|
||||
```
|
||||
|
||||
### Verifying Attestation
|
||||
|
||||
```csharp
|
||||
var result = await attestationService.VerifyAsync(envelopeJson);
|
||||
if (result.IsValid)
|
||||
{
|
||||
var verdict = result.Predicate!.Verdict;
|
||||
Console.WriteLine($"Status: {verdict.Status}");
|
||||
Console.WriteLine($"Confidence: {verdict.Confidence:P0}");
|
||||
}
|
||||
```
|
||||
|
||||
## Air-Gap Verification
|
||||
|
||||
FixChain attestations support offline verification:
|
||||
|
||||
1. **Bundle Export**: Export attestation with all referenced artifacts
|
||||
2. **Signature Verification**: Verify DSSE signature with bundled public key
|
||||
3. **Content Validation**: Validate predicate structure and content
|
||||
4. **Optional Rekor Proof**: Include offline Rekor inclusion proof
|
||||
|
||||
```bash
|
||||
# Export bundle for air-gap
|
||||
stella attest bundle export \
|
||||
--attestation fixchain.dsse.json \
|
||||
--include-artifacts \
|
||||
--out fixchain-bundle.tar.gz
|
||||
|
||||
# Verify in air-gap
|
||||
stella attest bundle verify \
|
||||
--bundle fixchain-bundle.tar.gz \
|
||||
--offline
|
||||
```
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Golden Set Schema](../binary-index/golden-set-schema.md)
|
||||
- [SBOM Extension Fields](../binary-index/sbom-extensions.md)
|
||||
- [Proof Chain Specification](./proof-chain-specification.md)
|
||||
- [DSSE Roundtrip Verification](./dsse-roundtrip-verification.md)
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
Attestor:
|
||||
Predicates:
|
||||
FixChain:
|
||||
Enabled: true
|
||||
AnalyzerName: "StellaOps.BinaryIndex"
|
||||
AnalyzerVersion: "1.0.0"
|
||||
FixedConfidenceThreshold: 0.80
|
||||
PartialConfidenceThreshold: 0.50
|
||||
PublishToRekor: true
|
||||
Archive: true
|
||||
```
|
||||
368
docs/modules/binary-index/golden-set-schema.md
Normal file
368
docs/modules/binary-index/golden-set-schema.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Golden Set Schema Documentation
|
||||
|
||||
> **Version:** 1.0.0
|
||||
> **Module:** BinaryIndex.GoldenSet
|
||||
> **Last Updated:** 2026-01-10
|
||||
|
||||
## Overview
|
||||
|
||||
Golden Sets are ground-truth definitions of vulnerability code-level manifestations. They capture the specific functions, basic block edges, sinks, and constants that characterize a vulnerability, enabling:
|
||||
|
||||
- **Deterministic vulnerability detection** via fingerprint matching
|
||||
- **Backport verification** through pre/post patch comparison
|
||||
- **Audit trail** for security claims with content-addressed provenance
|
||||
|
||||
## YAML Schema
|
||||
|
||||
Golden sets are stored as human-readable YAML files for git-friendliness and easy review.
|
||||
|
||||
### Full Example
|
||||
|
||||
```yaml
|
||||
# GoldenSet.yaml schema v1.0.0
|
||||
id: "CVE-2024-0727"
|
||||
component: "openssl"
|
||||
|
||||
targets:
|
||||
- function: "PKCS12_parse"
|
||||
edges:
|
||||
- "bb3->bb7"
|
||||
- "bb7->bb9"
|
||||
sinks:
|
||||
- "memcpy"
|
||||
- "OPENSSL_malloc"
|
||||
constants:
|
||||
- "0x400"
|
||||
- "0xdeadbeef"
|
||||
taint_invariant: "len(field) <= 0x400 required before memcpy"
|
||||
source_file: "crypto/pkcs12/p12_kiss.c"
|
||||
source_line: 142
|
||||
|
||||
- function: "PKCS12_unpack_p7data"
|
||||
edges:
|
||||
- "bb1->bb3"
|
||||
sinks:
|
||||
- "d2i_ASN1_OCTET_STRING"
|
||||
|
||||
witness:
|
||||
arguments:
|
||||
- "--file"
|
||||
- "<fuzz.bin>"
|
||||
invariant: "Malformed PKCS12 with oversized authsafe"
|
||||
poc_file_ref: "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abc123"
|
||||
|
||||
metadata:
|
||||
author_id: "security-team@example.com"
|
||||
created_at: "2025-01-10T12:00:00Z"
|
||||
source_ref: "https://nvd.nist.gov/vuln/detail/CVE-2024-0727"
|
||||
reviewed_by: "senior-analyst@example.com"
|
||||
reviewed_at: "2025-01-11T09:00:00Z"
|
||||
tags:
|
||||
- "memory-corruption"
|
||||
- "heap-overflow"
|
||||
- "pkcs12"
|
||||
schema_version: "1.0.0"
|
||||
```
|
||||
|
||||
### Minimal Example
|
||||
|
||||
```yaml
|
||||
id: "CVE-2024-0727"
|
||||
component: "openssl"
|
||||
targets:
|
||||
- function: "vulnerable_function"
|
||||
metadata:
|
||||
author_id: "analyst@example.com"
|
||||
created_at: "2025-01-10T12:00:00Z"
|
||||
source_ref: "https://nvd.nist.gov/vuln/detail/CVE-2024-0727"
|
||||
```
|
||||
|
||||
## Field Reference
|
||||
|
||||
### Root Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `id` | string | Yes | Vulnerability identifier (CVE-YYYY-NNNN or GHSA-xxxx-xxxx-xxxx) |
|
||||
| `component` | string | Yes | Affected component name (e.g., "openssl", "glibc") |
|
||||
| `targets` | array | Yes | List of vulnerable code targets (min 1) |
|
||||
| `witness` | object | No | Reproduction witness input |
|
||||
| `metadata` | object | Yes | Authorship and review metadata |
|
||||
|
||||
### Vulnerable Target Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `function` | string | Yes | Function name (symbol or demangled) |
|
||||
| `edges` | array | No | Basic block edges (format: "bbN->bbM") |
|
||||
| `sinks` | array | No | Sink functions reached (e.g., "memcpy") |
|
||||
| `constants` | array | No | Magic values identifying the vulnerability |
|
||||
| `taint_invariant` | string | No | Human-readable exploitation invariant |
|
||||
| `source_file` | string | No | Source file hint |
|
||||
| `source_line` | integer | No | Source line hint |
|
||||
|
||||
### Witness Input Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `arguments` | array | No | Command-line arguments to trigger vulnerability |
|
||||
| `invariant` | string | No | Human-readable precondition |
|
||||
| `poc_file_ref` | string | No | Content-addressed PoC file reference |
|
||||
|
||||
### Metadata Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `author_id` | string | Yes | Author identifier (email or handle) |
|
||||
| `created_at` | string | Yes | Creation timestamp (ISO 8601 UTC) |
|
||||
| `source_ref` | string | Yes | Advisory URL or commit hash |
|
||||
| `reviewed_by` | string | No | Reviewer identifier |
|
||||
| `reviewed_at` | string | No | Review timestamp (ISO 8601 UTC) |
|
||||
| `tags` | array | No | Classification tags |
|
||||
| `schema_version` | string | No | Schema version (default: "1.0.0") |
|
||||
|
||||
## JSON Schema
|
||||
|
||||
The following JSON Schema can be used for validation:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stella-ops.org/schemas/golden-set/v1.0.0",
|
||||
"title": "Golden Set Definition",
|
||||
"type": "object",
|
||||
"required": ["id", "component", "targets", "metadata"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^CVE-\\d{4}-\\d{4,}$|^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$",
|
||||
"description": "Vulnerability identifier"
|
||||
},
|
||||
"component": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "Affected component name"
|
||||
},
|
||||
"targets": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": { "$ref": "#/$defs/vulnerableTarget" },
|
||||
"description": "Vulnerable code targets"
|
||||
},
|
||||
"witness": {
|
||||
"$ref": "#/$defs/witnessInput",
|
||||
"description": "Reproduction witness input"
|
||||
},
|
||||
"metadata": {
|
||||
"$ref": "#/$defs/metadata",
|
||||
"description": "Authorship and review metadata"
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"vulnerableTarget": {
|
||||
"type": "object",
|
||||
"required": ["function"],
|
||||
"properties": {
|
||||
"function": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "Function name"
|
||||
},
|
||||
"edges": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"pattern": "^bb\\d+->bb\\d+$"
|
||||
},
|
||||
"description": "Basic block edges"
|
||||
},
|
||||
"sinks": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Sink functions"
|
||||
},
|
||||
"constants": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Magic values"
|
||||
},
|
||||
"taint_invariant": {
|
||||
"type": "string",
|
||||
"description": "Exploitation invariant"
|
||||
},
|
||||
"source_file": {
|
||||
"type": "string",
|
||||
"description": "Source file hint"
|
||||
},
|
||||
"source_line": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "Source line hint"
|
||||
}
|
||||
}
|
||||
},
|
||||
"witnessInput": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"arguments": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Command-line arguments"
|
||||
},
|
||||
"invariant": {
|
||||
"type": "string",
|
||||
"description": "Human-readable precondition"
|
||||
},
|
||||
"poc_file_ref": {
|
||||
"type": "string",
|
||||
"pattern": "^sha256:[a-f0-9]{64}$",
|
||||
"description": "Content-addressed PoC reference"
|
||||
}
|
||||
}
|
||||
},
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"required": ["author_id", "created_at", "source_ref"],
|
||||
"properties": {
|
||||
"author_id": {
|
||||
"type": "string",
|
||||
"description": "Author identifier"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "Creation timestamp (ISO 8601)"
|
||||
},
|
||||
"source_ref": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Advisory URL or commit hash"
|
||||
},
|
||||
"reviewed_by": {
|
||||
"type": "string",
|
||||
"description": "Reviewer identifier"
|
||||
},
|
||||
"reviewed_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "Review timestamp (ISO 8601)"
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Classification tags"
|
||||
},
|
||||
"schema_version": {
|
||||
"type": "string",
|
||||
"pattern": "^\\d+\\.\\d+\\.\\d+$",
|
||||
"description": "Schema version"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Edge Format
|
||||
|
||||
Basic block edges follow the format `bbN->bbM` where:
|
||||
- `bbN` is the source basic block identifier
|
||||
- `bbM` is the target basic block identifier
|
||||
- The `->` separator indicates control flow direction
|
||||
|
||||
Examples:
|
||||
- `bb3->bb7` - Control flows from block 3 to block 7
|
||||
- `bb7->bb9` - Control flows from block 7 to block 9
|
||||
- `bb1->bb3` - Control flows from block 1 to block 3
|
||||
|
||||
Edge identifiers match common disassembler output (IDA, Ghidra, Binary Ninja).
|
||||
|
||||
## Sink Registry
|
||||
|
||||
Known sinks are validated against the sink registry. Categories include:
|
||||
|
||||
| Category | Examples | CWEs |
|
||||
|----------|----------|------|
|
||||
| `memory` | memcpy, strcpy, free, malloc | CWE-120, CWE-787, CWE-415, CWE-416 |
|
||||
| `command_injection` | system, exec, popen | CWE-78 |
|
||||
| `code_injection` | dlopen, LoadLibrary | CWE-427 |
|
||||
| `path_traversal` | fopen, open | CWE-22 |
|
||||
| `network` | connect, send, recv | CWE-918, CWE-319 |
|
||||
| `sql_injection` | sqlite3_exec, mysql_query | CWE-89 |
|
||||
| `crypto` | EVP_DecryptUpdate, PKCS12_parse | CWE-327, CWE-295 |
|
||||
|
||||
Unknown sinks generate validation warnings but do not block acceptance.
|
||||
|
||||
## Content Addressing
|
||||
|
||||
Golden sets are content-addressed using SHA256:
|
||||
|
||||
1. Definition is serialized to canonical JSON (sorted keys, no whitespace)
|
||||
2. SHA256 hash is computed over UTF-8 bytes
|
||||
3. Digest is formatted as `sha256:<64-hex-chars>`
|
||||
|
||||
Example: `sha256:a1b2c3d4e5f6...`
|
||||
|
||||
Content addressing enables:
|
||||
- Deduplication in storage
|
||||
- Audit trail verification
|
||||
- Immutable references in attestations
|
||||
|
||||
## Status Workflow
|
||||
|
||||
Golden sets progress through these statuses:
|
||||
|
||||
```
|
||||
Draft → InReview → Approved
|
||||
↓
|
||||
Draft (if changes requested)
|
||||
|
||||
Approved → Deprecated (if CVE retracted)
|
||||
→ Archived (for historical reference)
|
||||
```
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `Draft` | Initial creation, editable |
|
||||
| `InReview` | Submitted for review |
|
||||
| `Approved` | Active in corpus, used for detection |
|
||||
| `Deprecated` | CVE retracted or superseded |
|
||||
| `Archived` | Historical reference only |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Authoring Golden Sets
|
||||
|
||||
1. **Start minimal** - Begin with function name only, add edges/sinks as verified
|
||||
2. **Use authoritative sources** - NVD, vendor advisories, upstream commits
|
||||
3. **Document invariants** - Explain exploitation conditions in human-readable text
|
||||
4. **Tag appropriately** - Use consistent classification tags
|
||||
5. **Review carefully** - Treat golden sets like unit tests
|
||||
|
||||
### Edge Selection
|
||||
|
||||
1. **Focus on vulnerable paths** - Only include edges on the exploitation path
|
||||
2. **Avoid over-specification** - Fewer edges = more robust matching
|
||||
3. **Document rationale** - Explain why specific edges are included
|
||||
|
||||
### Sink Selection
|
||||
|
||||
1. **Use known sinks** - Prefer sinks from the registry
|
||||
2. **Include all relevant sinks** - List all sinks on the vulnerable path
|
||||
3. **Order consistently** - Alphabetical ordering aids diffing
|
||||
|
||||
## API Reference
|
||||
|
||||
See [StellaOps.BinaryIndex.GoldenSet](../../../src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/) for:
|
||||
|
||||
- `GoldenSetDefinition` - Domain model
|
||||
- `IGoldenSetValidator` - Validation service
|
||||
- `IGoldenSetStore` - Storage interface
|
||||
- `GoldenSetYamlSerializer` - YAML serialization
|
||||
- `ISinkRegistry` - Sink lookup service
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [BinaryIndex Architecture](architecture.md)
|
||||
- [Delta Signature Matching](delta-signatures.md)
|
||||
- [VEX Evidence Generation](../vex-lens/architecture.md)
|
||||
202
docs/modules/binary-index/sbom-extensions.md
Normal file
202
docs/modules/binary-index/sbom-extensions.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# SBOM Extension Fields for FixChain Attestation
|
||||
|
||||
> **Sprint:** SPRINT_20260110_012_005_ATTESTOR
|
||||
> **Last Updated:** 10-Jan-2026
|
||||
|
||||
This document describes the extension fields used to link FixChain attestations to SBOM components.
|
||||
|
||||
## Overview
|
||||
|
||||
When a FixChain attestation verifies that a patch eliminates a vulnerability, the results can be embedded in the SBOM as extension properties. This enables consumers to verify fix status directly from the SBOM without separate attestation lookup.
|
||||
|
||||
## CycloneDX Properties
|
||||
|
||||
CycloneDX 1.4+ supports custom properties on components. StellaOps uses the `stellaops:` namespace for FixChain-related properties.
|
||||
|
||||
### Component-Level Properties
|
||||
|
||||
```json
|
||||
{
|
||||
"components": [
|
||||
{
|
||||
"type": "library",
|
||||
"name": "openssl",
|
||||
"version": "3.1.0",
|
||||
"purl": "pkg:deb/debian/openssl@3.1.0",
|
||||
"properties": [
|
||||
{
|
||||
"name": "stellaops:fixChainRef",
|
||||
"value": "sha256:abc123def456789..."
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainVerdict",
|
||||
"value": "fixed"
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainConfidence",
|
||||
"value": "0.97"
|
||||
},
|
||||
{
|
||||
"name": "stellaops:goldenSetRef",
|
||||
"value": "sha256:def456abc789012..."
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainCve",
|
||||
"value": "CVE-2024-0727"
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainAnalyzedAt",
|
||||
"value": "2026-01-15T12:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Property Definitions
|
||||
|
||||
| Property | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `stellaops:fixChainRef` | Content digest of the FixChain attestation | `sha256:abc123...` |
|
||||
| `stellaops:fixChainVerdict` | Verdict status: `fixed`, `partial`, `not_fixed`, `inconclusive` | `fixed` |
|
||||
| `stellaops:fixChainConfidence` | Confidence score (0.0 - 1.0) | `0.97` |
|
||||
| `stellaops:goldenSetRef` | Content digest of the golden set definition | `sha256:def456...` |
|
||||
| `stellaops:fixChainCve` | CVE identifier being verified | `CVE-2024-0727` |
|
||||
| `stellaops:fixChainAnalyzedAt` | ISO 8601 timestamp of analysis | `2026-01-15T12:00:00Z` |
|
||||
|
||||
### Multiple CVE Verification
|
||||
|
||||
When multiple CVEs are verified for the same component, use indexed properties:
|
||||
|
||||
```json
|
||||
{
|
||||
"properties": [
|
||||
{
|
||||
"name": "stellaops:fixChainRef:0",
|
||||
"value": "sha256:abc123..."
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainCve:0",
|
||||
"value": "CVE-2024-0727"
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainVerdict:0",
|
||||
"value": "fixed"
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainRef:1",
|
||||
"value": "sha256:def456..."
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainCve:1",
|
||||
"value": "CVE-2024-0728"
|
||||
},
|
||||
{
|
||||
"name": "stellaops:fixChainVerdict:1",
|
||||
"value": "partial"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## SPDX Annotations
|
||||
|
||||
SPDX 2.3 supports annotations for attaching additional information to packages.
|
||||
|
||||
### Package Annotation
|
||||
|
||||
```json
|
||||
{
|
||||
"packages": [
|
||||
{
|
||||
"SPDXID": "SPDXRef-Package-openssl",
|
||||
"name": "openssl",
|
||||
"versionInfo": "3.1.0"
|
||||
}
|
||||
],
|
||||
"annotations": [
|
||||
{
|
||||
"annotationDate": "2026-01-15T12:00:00Z",
|
||||
"annotationType": "OTHER",
|
||||
"annotator": "Tool: StellaOps FixChain Analyzer v1.0.0",
|
||||
"comment": "Fix verified: CVE-2024-0727 (97% confidence). FixChain: sha256:abc123..., GoldenSet: sha256:def456..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Structured Annotation Format
|
||||
|
||||
For machine-readable annotations, use JSON within the comment field:
|
||||
|
||||
```json
|
||||
{
|
||||
"annotations": [
|
||||
{
|
||||
"annotationDate": "2026-01-15T12:00:00Z",
|
||||
"annotationType": "OTHER",
|
||||
"annotator": "Tool: StellaOps FixChain Analyzer v1.0.0",
|
||||
"comment": "{\"type\":\"stellaops:fixchain\",\"cveId\":\"CVE-2024-0727\",\"verdict\":\"fixed\",\"confidence\":0.97,\"fixChainRef\":\"sha256:abc123...\",\"goldenSetRef\":\"sha256:def456...\"}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## SPDX 3.0 Extensions
|
||||
|
||||
SPDX 3.0 introduces external references which provide better support for attestations.
|
||||
|
||||
### Security External Reference
|
||||
|
||||
```json
|
||||
{
|
||||
"@type": "software_Package",
|
||||
"@id": "urn:spdx:Package-openssl",
|
||||
"name": "openssl",
|
||||
"packageVersion": "3.1.0",
|
||||
"externalRef": [
|
||||
{
|
||||
"@type": "ExternalRef",
|
||||
"externalRefType": "securityOther",
|
||||
"locator": "sha256:abc123def456789...",
|
||||
"comment": "FixChain attestation for CVE-2024-0727"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Verification Workflow
|
||||
|
||||
1. **Extract Properties**: Parse SBOM and extract `stellaops:fixChainRef` properties
|
||||
2. **Fetch Attestation**: Retrieve attestation by content digest
|
||||
3. **Verify Signature**: Validate DSSE envelope signature
|
||||
4. **Verify Predicate**: Parse and validate FixChainPredicate
|
||||
5. **Match Component**: Verify SBOM component matches attestation subject
|
||||
6. **Check Verdict**: Confirm verdict meets policy requirements
|
||||
|
||||
## CLI Usage
|
||||
|
||||
```bash
|
||||
# Annotate SBOM with FixChain attestation
|
||||
stella sbom annotate \
|
||||
--sbom sbom.cdx.json \
|
||||
--fixchain attestation.dsse.json \
|
||||
--output sbom-annotated.cdx.json
|
||||
|
||||
# Verify SBOM annotations
|
||||
stella sbom verify-fixchain \
|
||||
--sbom sbom-annotated.cdx.json \
|
||||
--attestation-store /path/to/store
|
||||
|
||||
# Export fix status report
|
||||
stella sbom fixchain-report \
|
||||
--sbom sbom-annotated.cdx.json \
|
||||
--format markdown
|
||||
```
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Golden Set Schema](./golden-set-schema.md)
|
||||
- [FixChain Predicate Schema](../attestor/fix-chain-predicate.md)
|
||||
- [Binary Index Architecture](./architecture.md)
|
||||
318
docs/modules/policy/fix-chain-gates.md
Normal file
318
docs/modules/policy/fix-chain-gates.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# Policy Engine FixChain Gates
|
||||
|
||||
> **Sprint:** SPRINT_20260110_012_008_POLICY
|
||||
> **Last Updated:** 10-Jan-2026
|
||||
|
||||
## Overview
|
||||
|
||||
FixChain gates are policy predicates that control release promotion based on verified fix status. They integrate FixChain attestations from the binary-level fix verification system into policy decisions, blocking or warning on releases that contain critical vulnerabilities without verified fixes.
|
||||
|
||||
## Why This Matters
|
||||
|
||||
| Current State | With FixChain Gates |
|
||||
|---------------|---------------------|
|
||||
| Manual fix verification | Automated policy gates |
|
||||
| Trust vendor fix claims | Require verification evidence |
|
||||
| Inconsistent release criteria | Codified fix requirements |
|
||||
| Post-deployment discovery | Pre-deployment blocking |
|
||||
|
||||
## Configuration
|
||||
|
||||
### YAML Policy Configuration
|
||||
|
||||
```yaml
|
||||
# stellaops.yaml
|
||||
Policy:
|
||||
Predicates:
|
||||
FixChainGate:
|
||||
Enabled: true
|
||||
DefaultMinConfidence: 0.85
|
||||
DefaultGracePeriodDays: 7
|
||||
NotifyOnBlock: true
|
||||
NotifyOnWarn: true
|
||||
|
||||
policies:
|
||||
release-gates:
|
||||
name: "Release Gate Policy"
|
||||
version: "1.0.0"
|
||||
description: "Gates for production release promotion"
|
||||
|
||||
gates:
|
||||
# Critical vulnerabilities - strict requirements
|
||||
- name: "critical-fix-required"
|
||||
predicate: fixChainRequired
|
||||
parameters:
|
||||
severities: ["critical"]
|
||||
minConfidence: 0.95
|
||||
allowInconclusive: false
|
||||
gracePeriodDays: 3
|
||||
requireApprovedGoldenSet: true
|
||||
action: block
|
||||
message: "Critical vulnerabilities require verified fix with 95%+ confidence"
|
||||
|
||||
# High vulnerabilities - moderate requirements
|
||||
- name: "high-fix-recommended"
|
||||
predicate: fixChainRequired
|
||||
parameters:
|
||||
severities: ["high"]
|
||||
minConfidence: 0.80
|
||||
allowInconclusive: true
|
||||
gracePeriodDays: 14
|
||||
requireApprovedGoldenSet: true
|
||||
action: warn
|
||||
message: "High vulnerabilities should have verified fix"
|
||||
|
||||
# Exception for specific components
|
||||
- name: "vendor-component-exception"
|
||||
predicate: componentException
|
||||
parameters:
|
||||
components:
|
||||
- "pkg:deb/debian/vendor-lib@*"
|
||||
reason: "Vendor provides attestation separately"
|
||||
action: allow
|
||||
|
||||
fallback: block
|
||||
auditLog: true
|
||||
```
|
||||
|
||||
### Parameter Reference
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `severities` | string[] | `["critical", "high"]` | Severity levels requiring verification |
|
||||
| `minConfidence` | decimal | `0.85` | Minimum confidence for "fixed" verdict |
|
||||
| `allowInconclusive` | bool | `false` | Whether inconclusive verdicts pass |
|
||||
| `gracePeriodDays` | int | `7` | Days after CVE publication before gate applies |
|
||||
| `requireApprovedGoldenSet` | bool | `true` | Require golden set to be approved |
|
||||
| `failureAction` | string | `block` | Action on failure: `block` or `warn` |
|
||||
|
||||
## Gate Outcomes
|
||||
|
||||
| Outcome | Passed | Description |
|
||||
|---------|--------|-------------|
|
||||
| `FixVerified` | Yes | Fix verified with sufficient confidence |
|
||||
| `SeverityExempt` | Yes | Severity does not require verification |
|
||||
| `GracePeriod` | Yes | Within grace period after CVE publication |
|
||||
| `AttestationRequired` | No | No attestation found, severity requires it |
|
||||
| `InsufficientConfidence` | No | Confidence below threshold |
|
||||
| `InconclusiveNotAllowed` | No | Inconclusive verdict, policy doesn't allow |
|
||||
| `StillVulnerable` | No | Verification shows vulnerability present |
|
||||
| `GoldenSetNotApproved` | No | Golden set not reviewed/approved |
|
||||
| `PartialFix` | Depends | Partial fix detected |
|
||||
|
||||
## K4 Lattice Integration
|
||||
|
||||
```
|
||||
+-----------------+
|
||||
| ReleaseBlocked |
|
||||
+--------+--------+
|
||||
|
|
||||
+--------------------+--------------------+
|
||||
| |
|
||||
v v
|
||||
+---------------+ +---------------+
|
||||
| FixRequired | | ManualReview |
|
||||
| (Critical+ | | Required |
|
||||
| Unverified) | | |
|
||||
+-------+-------+ +-------+-------+
|
||||
| |
|
||||
+--------------------+--------------------+
|
||||
|
|
||||
v
|
||||
+-----------------+
|
||||
| ReleaseAllowed |
|
||||
+-----------------+
|
||||
|
||||
Lattice Rules:
|
||||
Critical AND NoFixChain -> ReleaseBlocked
|
||||
Critical AND FixChain(>=0.95) -> ReleaseAllowed
|
||||
Critical AND Inconclusive -> ManualReviewRequired
|
||||
High AND NoFixChain -> ManualReviewRequired
|
||||
High AND FixChain(>=0.80) -> ReleaseAllowed
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Programmatic Evaluation
|
||||
|
||||
```csharp
|
||||
// Inject the predicate
|
||||
var predicate = services.GetRequiredService<IFixChainGatePredicate>();
|
||||
|
||||
// Create context for a finding
|
||||
var context = new FixChainGateContext
|
||||
{
|
||||
CveId = "CVE-2024-12345",
|
||||
ComponentPurl = "pkg:npm/lodash@4.17.20",
|
||||
Severity = "critical",
|
||||
CvssScore = 9.8m,
|
||||
BinarySha256 = binaryDigest,
|
||||
CvePublishedAt = DateTimeOffset.Parse("2024-01-15")
|
||||
};
|
||||
|
||||
// Configure parameters
|
||||
var parameters = new FixChainGateParameters
|
||||
{
|
||||
Severities = ImmutableArray.Create("critical", "high"),
|
||||
MinConfidence = 0.90m,
|
||||
AllowInconclusive = false,
|
||||
GracePeriodDays = 7,
|
||||
RequireApprovedGoldenSet = true
|
||||
};
|
||||
|
||||
// Evaluate
|
||||
var result = await predicate.EvaluateAsync(context, parameters, ct);
|
||||
|
||||
if (!result.Passed)
|
||||
{
|
||||
Console.WriteLine($"Gate blocked: {result.Reason}");
|
||||
foreach (var rec in result.Recommendations)
|
||||
{
|
||||
Console.WriteLine($" - {rec}");
|
||||
}
|
||||
foreach (var cmd in result.CliCommands)
|
||||
{
|
||||
Console.WriteLine($" $ {cmd}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Batch Evaluation
|
||||
|
||||
```csharp
|
||||
var batchService = services.GetRequiredService<IFixChainGateBatchService>();
|
||||
|
||||
var contexts = findings.Select(f => new FixChainGateContext
|
||||
{
|
||||
CveId = f.CveId,
|
||||
ComponentPurl = f.ComponentPurl,
|
||||
Severity = f.Severity,
|
||||
CvssScore = f.CvssScore
|
||||
}).ToList();
|
||||
|
||||
var batchResult = await batchService.EvaluateBatchAsync(contexts, parameters, ct);
|
||||
|
||||
if (!batchResult.AllPassed)
|
||||
{
|
||||
Console.WriteLine($"Blocking issues: {batchResult.BlockingResults.Length}");
|
||||
Console.WriteLine($"Warnings: {batchResult.WarningResults.Length}");
|
||||
}
|
||||
```
|
||||
|
||||
### Policy Gate Registry Integration
|
||||
|
||||
```csharp
|
||||
// In Startup/Program.cs
|
||||
services.AddFixChainGate(configuration);
|
||||
|
||||
// Register with policy gate registry
|
||||
var registry = services.BuildServiceProvider()
|
||||
.GetRequiredService<IPolicyGateRegistry>();
|
||||
registry.RegisterFixChainGate();
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
### Check Gates for an Artifact
|
||||
|
||||
```bash
|
||||
stella policy check-gates \
|
||||
--artifact sha256:abc123... \
|
||||
--policy release-gates \
|
||||
--format table
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Release Gate Evaluation: sha256:abc123...
|
||||
Policy: release-gates
|
||||
|
||||
+----------------------------+---------+----------------------------------------+
|
||||
| Gate | Status | Reason |
|
||||
+----------------------------+---------+----------------------------------------+
|
||||
| critical-fix-required | PASS | No critical vulnerabilities |
|
||||
| high-fix-recommended | WARN | 2 findings without verified fix |
|
||||
| vendor-component-exception | PASS | Exception applied |
|
||||
+----------------------------+---------+----------------------------------------+
|
||||
|
||||
Warnings (2):
|
||||
- CVE-2024-1234 on pkg:npm/lodash@4.17.20: No FixChain attestation
|
||||
- CVE-2024-5678 on pkg:npm/axios@0.21.0: Inconclusive verdict
|
||||
|
||||
Recommendations:
|
||||
- stella scanner golden init --cve CVE-2024-1234 --component lodash
|
||||
- stella scanner golden init --cve CVE-2024-5678 --component axios
|
||||
|
||||
Overall: ALLOWED (with warnings)
|
||||
```
|
||||
|
||||
### JSON Output
|
||||
|
||||
```bash
|
||||
stella policy check-gates \
|
||||
--artifact sha256:abc123... \
|
||||
--policy release-gates \
|
||||
--format json
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
The gate exposes OpenTelemetry metrics:
|
||||
|
||||
| Metric | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `policy_fixchain_gate_evaluations_total` | Counter | Total evaluations |
|
||||
| `policy_fixchain_gate_passes_total` | Counter | Gate passes |
|
||||
| `policy_fixchain_gate_blocks_total` | Counter | Gate blocks |
|
||||
| `policy_fixchain_gate_warnings_total` | Counter | Gate warnings |
|
||||
| `policy_fixchain_gate_evaluation_duration_seconds` | Histogram | Evaluation duration |
|
||||
| `policy_fixchain_gate_errors_total` | Counter | Evaluation errors |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Gate Blocking Unexpectedly
|
||||
|
||||
1. **Check severity configuration**: Ensure the severity matches configured severities
|
||||
```bash
|
||||
stella policy show --policy release-gates
|
||||
```
|
||||
|
||||
2. **Verify attestation exists**: Check if attestation is present
|
||||
```bash
|
||||
stella attestor query --cve CVE-2024-XXXX --predicate fixchain
|
||||
```
|
||||
|
||||
3. **Check confidence level**: Verify confidence meets threshold
|
||||
```bash
|
||||
stella scanner golden show --cve CVE-2024-XXXX --verbose
|
||||
```
|
||||
|
||||
4. **Review golden set status**: Check if golden set is approved
|
||||
```bash
|
||||
stella scanner golden status --cve CVE-2024-XXXX
|
||||
```
|
||||
|
||||
### Grace Period Issues
|
||||
|
||||
- Grace period starts from CVE publication date in the advisory
|
||||
- If publication date is unknown, grace period doesn't apply
|
||||
- Use `--grace-period-override` for manual override
|
||||
|
||||
### Inconclusive Verdicts
|
||||
|
||||
Inconclusive verdicts typically occur when:
|
||||
- Binary is stripped and symbols unavailable
|
||||
- Golden set incomplete or too generic
|
||||
- Compiler optimizations changed code structure
|
||||
|
||||
Resolution:
|
||||
1. Obtain debug symbols
|
||||
2. Enhance golden set with more specific targets
|
||||
3. Consider policy exception with justification
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [FixChain Attestation Predicate](../../attestor/fix-chain-predicate.md)
|
||||
- [Golden Set Schema](../../binary-index/golden-set-schema.md)
|
||||
- [Risk Engine FixChain Integration](../../risk-engine/fix-chain-integration.md)
|
||||
- [Policy Engine Architecture](./architecture.md)
|
||||
296
docs/modules/risk-engine/fix-chain-integration.md
Normal file
296
docs/modules/risk-engine/fix-chain-integration.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Risk Engine FixChain Integration
|
||||
|
||||
> **Sprint:** SPRINT_20260110_012_007_RISK
|
||||
> **Last Updated:** 10-Jan-2026
|
||||
|
||||
## Overview
|
||||
|
||||
The Risk Engine FixChain integration enables automatic risk score adjustment based on verified fix status from FixChain attestations. When a vulnerability has a verified fix, the risk score is reduced proportionally to the verification confidence level.
|
||||
|
||||
## Why This Matters
|
||||
|
||||
| Current State | With FixChain Integration |
|
||||
|---------------|---------------------------|
|
||||
| Risk scores ignore fix verification | Fix confidence reduces risk |
|
||||
| Binary matches = always vulnerable | Verified fixes lower severity |
|
||||
| No credit for patched backports | Backport fixes recognized |
|
||||
| Manual risk exceptions needed | Automatic risk adjustment |
|
||||
|
||||
## Risk Adjustment Model
|
||||
|
||||
### Verdict to Risk Modifier Mapping
|
||||
|
||||
| Verdict | Confidence | Risk Modifier | Rationale |
|
||||
|---------|------------|---------------|-----------|
|
||||
| `fixed` | >= 95% | -80% to -90% | High-confidence verified fix |
|
||||
| `fixed` | 85-95% | -60% to -80% | Verified fix, some uncertainty |
|
||||
| `fixed` | 70-85% | -40% to -60% | Likely fixed, needs confirmation |
|
||||
| `fixed` | 60-70% | -20% to -40% | Possible fix, low confidence |
|
||||
| `fixed` | < 60% | 0% | Below threshold, no adjustment |
|
||||
| `partial` | >= 60% | -25% to -50% | Partial fix applied |
|
||||
| `inconclusive` | any | 0% | Cannot determine, conservative |
|
||||
| `still_vulnerable` | any | 0% | No fix detected |
|
||||
| No attestation | N/A | 0% | No verification performed |
|
||||
|
||||
### Modifier Formula
|
||||
|
||||
```
|
||||
AdjustedRisk = BaseRisk * (1 - (Modifier * ConfidenceWeight))
|
||||
|
||||
Where:
|
||||
Modifier = verdict-based modifier from table above
|
||||
ConfidenceWeight = min(1.0, (Confidence - MinThreshold) / (1.0 - MinThreshold))
|
||||
```
|
||||
|
||||
### Example Calculation
|
||||
|
||||
```
|
||||
CVE-2024-0727 on pkg:deb/debian/openssl@3.0.11-1~deb12u2:
|
||||
BaseRisk = 8.5 (HIGH)
|
||||
FixChain Verdict = "fixed"
|
||||
FixChain Confidence = 0.97
|
||||
|
||||
Modifier = 0.90 (high confidence tier)
|
||||
ConfidenceWeight = (0.97 - 0.60) / (1.0 - 0.60) = 0.925
|
||||
|
||||
AdjustedRisk = 8.5 * (1 - 0.90 * 0.925) = 8.5 * 0.1675 = 1.42 (LOW)
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### IFixChainRiskProvider
|
||||
|
||||
Main interface for FixChain risk integration:
|
||||
|
||||
```csharp
|
||||
public interface IFixChainRiskProvider
|
||||
{
|
||||
Task<FixVerificationStatus?> GetFixStatusAsync(
|
||||
string cveId,
|
||||
string binarySha256,
|
||||
string? componentPurl = null,
|
||||
CancellationToken ct = default);
|
||||
|
||||
double ComputeRiskAdjustment(FixVerificationStatus status);
|
||||
|
||||
FixChainRiskFactor CreateRiskFactor(FixVerificationStatus status);
|
||||
}
|
||||
```
|
||||
|
||||
### FixChainRiskProvider
|
||||
|
||||
Implementation that:
|
||||
1. Queries the attestation store for FixChain predicates
|
||||
2. Computes risk adjustment based on verdict and confidence
|
||||
3. Creates structured risk factors for UI display
|
||||
|
||||
### IFixChainAttestationClient
|
||||
|
||||
Client for querying attestations:
|
||||
|
||||
```csharp
|
||||
public interface IFixChainAttestationClient
|
||||
{
|
||||
Task<FixChainAttestationData?> GetFixChainAsync(
|
||||
string cveId,
|
||||
string binarySha256,
|
||||
string? componentPurl = null,
|
||||
CancellationToken ct = default);
|
||||
|
||||
Task<ImmutableArray<FixChainAttestationData>> GetForComponentAsync(
|
||||
string componentPurl,
|
||||
CancellationToken ct = default);
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### YAML Configuration
|
||||
|
||||
```yaml
|
||||
RiskEngine:
|
||||
Providers:
|
||||
FixChain:
|
||||
Enabled: true
|
||||
HighConfidenceThreshold: 0.95
|
||||
MediumConfidenceThreshold: 0.85
|
||||
LowConfidenceThreshold: 0.70
|
||||
MinConfidenceThreshold: 0.60
|
||||
FixedReduction: 0.90
|
||||
PartialReduction: 0.50
|
||||
MaxRiskReduction: 0.90
|
||||
CacheMaxAgeHours: 24
|
||||
```
|
||||
|
||||
### Service Registration
|
||||
|
||||
```csharp
|
||||
services.AddOptions<FixChainRiskOptions>()
|
||||
.Bind(config.GetSection("RiskEngine:Providers:FixChain"))
|
||||
.ValidateDataAnnotations()
|
||||
.ValidateOnStart();
|
||||
|
||||
services.AddSingleton<IFixChainRiskProvider, FixChainRiskProvider>();
|
||||
services.AddHttpClient<IFixChainAttestationClient, FixChainAttestationClient>();
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Getting Fix Status
|
||||
|
||||
```csharp
|
||||
var provider = services.GetRequiredService<IFixChainRiskProvider>();
|
||||
|
||||
var status = await provider.GetFixStatusAsync(
|
||||
"CVE-2024-0727",
|
||||
binarySha256,
|
||||
componentPurl);
|
||||
|
||||
if (status is not null)
|
||||
{
|
||||
var adjustment = provider.ComputeRiskAdjustment(status);
|
||||
var adjustedRisk = baseRisk * adjustment;
|
||||
}
|
||||
```
|
||||
|
||||
### Creating Risk Factors
|
||||
|
||||
```csharp
|
||||
var status = await provider.GetFixStatusAsync(cveId, binarySha256);
|
||||
if (status is not null)
|
||||
{
|
||||
var factor = provider.CreateRiskFactor(status);
|
||||
|
||||
// For UI display
|
||||
var display = factor.ToDisplay();
|
||||
var badge = factor.ToBadge();
|
||||
var summary = factor.ToSummary();
|
||||
}
|
||||
```
|
||||
|
||||
### Signal-Based Scoring
|
||||
|
||||
For batch processing via signals:
|
||||
|
||||
```csharp
|
||||
var signals = new Dictionary<string, double>
|
||||
{
|
||||
[FixChainRiskProvider.SignalFixConfidence] = 0.95,
|
||||
[FixChainRiskProvider.SignalFixStatus] = FixChainRiskProvider.EncodeStatus("fixed")
|
||||
};
|
||||
|
||||
var request = new ScoreRequest("fixchain", subject, signals);
|
||||
var adjustment = await provider.ScoreAsync(request, ct);
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
The integration exposes the following OpenTelemetry metrics:
|
||||
|
||||
| Metric | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `risk_fixchain_lookups_total` | Counter | Total attestation lookups |
|
||||
| `risk_fixchain_hits_total` | Counter | Attestations found |
|
||||
| `risk_fixchain_misses_total` | Counter | Lookups with no attestation |
|
||||
| `risk_fixchain_cache_hits_total` | Counter | Lookups served from cache |
|
||||
| `risk_fixchain_lookup_duration_seconds` | Histogram | Lookup duration |
|
||||
| `risk_fixchain_adjustments_total` | Counter | Risk adjustments applied |
|
||||
| `risk_fixchain_reduction_percent` | Histogram | Reduction percentage distribution |
|
||||
| `risk_fixchain_errors_total` | Counter | Lookup errors |
|
||||
|
||||
### Recording Metrics
|
||||
|
||||
```csharp
|
||||
// Automatically recorded by the provider, or manually:
|
||||
FixChainRiskMetrics.RecordLookup(
|
||||
found: true,
|
||||
fromCache: false,
|
||||
durationSeconds: 0.05,
|
||||
verdict: "fixed");
|
||||
|
||||
FixChainRiskMetrics.RecordAdjustment(
|
||||
verdict: FixChainVerdictStatus.Fixed,
|
||||
confidence: 0.95m,
|
||||
reductionPercent: 0.80);
|
||||
```
|
||||
|
||||
## UI Integration
|
||||
|
||||
### Display Model
|
||||
|
||||
```csharp
|
||||
var display = factor.ToDisplay();
|
||||
// display.Label = "Fix Verification"
|
||||
// display.Value = "Fixed (95% confidence)"
|
||||
// display.Impact = -0.80
|
||||
// display.ImpactDirection = "decrease"
|
||||
// display.EvidenceRef = "fixchain://sha256:..."
|
||||
// display.Details = { verdict, confidence, verified_at, ... }
|
||||
```
|
||||
|
||||
### Badge Component
|
||||
|
||||
```csharp
|
||||
var badge = factor.ToBadge();
|
||||
// badge.Status = "Fixed"
|
||||
// badge.Color = "green"
|
||||
// badge.Icon = "check-circle"
|
||||
// badge.Confidence = 0.95m
|
||||
// badge.Tooltip = "Verified fix (95% confidence)"
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```csharp
|
||||
[Fact]
|
||||
public async Task FixedVerdict_HighConfidence_ReturnsLowRisk()
|
||||
{
|
||||
var provider = new FixChainRiskProvider(options);
|
||||
var status = new FixVerificationStatus
|
||||
{
|
||||
Verdict = "fixed",
|
||||
Confidence = 0.97m,
|
||||
VerifiedAt = DateTimeOffset.UtcNow,
|
||||
AttestationDigest = "sha256:test"
|
||||
};
|
||||
|
||||
var adjustment = provider.ComputeRiskAdjustment(status);
|
||||
|
||||
adjustment.Should().BeLessThan(0.3);
|
||||
}
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```csharp
|
||||
[Fact]
|
||||
public async Task FullWorkflow_FixedVerdict_ReducesRisk()
|
||||
{
|
||||
var attestationClient = new InMemoryFixChainAttestationClient();
|
||||
attestationClient.AddAttestation(cveId, binarySha256, attestation);
|
||||
|
||||
var provider = new FixChainRiskProvider(options, attestationClient, logger);
|
||||
var status = await provider.GetFixStatusAsync(cveId, binarySha256);
|
||||
|
||||
status.Should().NotBeNull();
|
||||
status!.Verdict.Should().Be("fixed");
|
||||
}
|
||||
```
|
||||
|
||||
## Decisions and Trade-offs
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| Conservative thresholds | Start high, can lower based on accuracy data |
|
||||
| No automatic upgrade | Inconclusive doesn't increase risk |
|
||||
| Cache TTL 30 minutes | Balances freshness vs. performance |
|
||||
| Attestation required | No reduction without verifiable evidence |
|
||||
| Minimum confidence 60% | Below this, evidence is too weak for adjustment |
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [FixChain Attestation Predicate](../attestor/fix-chain-predicate.md)
|
||||
- [Golden Set Schema](../binary-index/golden-set-schema.md)
|
||||
- [Risk Engine Architecture](./architecture.md)
|
||||
311
docs/modules/scanner/golden-set-authoring.md
Normal file
311
docs/modules/scanner/golden-set-authoring.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Golden Set Authoring Guide
|
||||
|
||||
This document describes the authoring workflow for creating and curating Golden Sets - ground-truth definitions of vulnerability code-level manifestation facts used for binary vulnerability detection.
|
||||
|
||||
## Overview
|
||||
|
||||
Golden Sets are YAML-based definitions that describe:
|
||||
- **Vulnerable functions** - Entry points where vulnerabilities manifest
|
||||
- **Sink functions** - Dangerous API calls that enable exploitation
|
||||
- **Edge patterns** - Control flow patterns indicating vulnerability presence
|
||||
- **Constants** - Magic numbers, buffer sizes, or version markers
|
||||
- **Witness inputs** - Example triggers for the vulnerability
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Golden Set Authoring Pipeline │
|
||||
├──────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────┐ ┌─────────────────┐ ┌──────────────────────┐ │
|
||||
│ │ CVE/Advisory │───>│ Extractors │───>│ Draft Golden Set │ │
|
||||
│ │ Sources │ │ (NVD/OSV/GHSA) │ │ │ │
|
||||
│ └────────────────┘ └─────────────────┘ └──────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ v v │
|
||||
│ ┌─────────────────┐ ┌──────────────────────┐ │
|
||||
│ │ Upstream Commit │ │ AI Enrichment │ │
|
||||
│ │ Analyzer │───>│ Service │ │
|
||||
│ └─────────────────┘ └──────────────────────┘ │
|
||||
│ │ │
|
||||
│ v │
|
||||
│ ┌─────────────────┐ ┌──────────────────────┐ │
|
||||
│ │ Validator │<───│ Review Workflow │ │
|
||||
│ └─────────────────┘ └──────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ v v │
|
||||
│ ┌─────────────────────────────────────────────┐ │
|
||||
│ │ PostgreSQL Storage │ │
|
||||
│ │ (content-addressed, versioned) │ │
|
||||
│ └─────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### 1. Extractors
|
||||
|
||||
Extractors pull vulnerability data from advisory sources:
|
||||
|
||||
```csharp
|
||||
// Extract from NVD/OSV/GHSA
|
||||
var extractor = serviceProvider.GetRequiredService<IGoldenSetExtractor>();
|
||||
|
||||
var result = await extractor.ExtractAsync(
|
||||
"CVE-2024-1234",
|
||||
"openssl",
|
||||
new ExtractionOptions
|
||||
{
|
||||
UseAiEnrichment = true,
|
||||
IncludeUpstreamCommits = true,
|
||||
IncludeRelatedCves = true
|
||||
});
|
||||
```
|
||||
|
||||
**Supported Sources:**
|
||||
- **NVD** - National Vulnerability Database
|
||||
- **OSV** - Open Source Vulnerabilities
|
||||
- **GHSA** - GitHub Security Advisories
|
||||
|
||||
### 2. Upstream Commit Analyzer
|
||||
|
||||
Analyzes fix commits to extract:
|
||||
- Modified functions (from hunk headers)
|
||||
- Added constants (hex values, buffer sizes)
|
||||
- Added conditions (bounds checks, NULL checks)
|
||||
|
||||
```csharp
|
||||
var analyzer = serviceProvider.GetRequiredService<IUpstreamCommitAnalyzer>();
|
||||
|
||||
// Parse commit URL
|
||||
var parsed = analyzer.ParseCommitUrl("https://github.com/curl/curl/commit/abc123");
|
||||
|
||||
// Analyze commits
|
||||
var result = await analyzer.AnalyzeAsync([
|
||||
"https://github.com/curl/curl/commit/abc123",
|
||||
"https://github.com/curl/curl/commit/def456"
|
||||
]);
|
||||
|
||||
// Result contains:
|
||||
// - ModifiedFunctions: ["parse_header", "validate_length"]
|
||||
// - AddedConstants: ["0x1000", "sizeof(buffer)"]
|
||||
// - AddedConditions: ["bounds_check", "null_check"]
|
||||
```
|
||||
|
||||
**Supported Platforms:**
|
||||
- GitHub (`github.com/owner/repo/commit/hash`)
|
||||
- GitLab (`gitlab.com/owner/repo/-/commit/hash`)
|
||||
- Bitbucket (`bitbucket.org/owner/repo/commits/hash`)
|
||||
|
||||
### 3. CWE-to-Sink Mapper
|
||||
|
||||
Maps CWE classifications to relevant sink functions:
|
||||
|
||||
```csharp
|
||||
// Get sinks for buffer overflow CWEs
|
||||
var sinks = CweToSinkMapper.GetSinksForCwes(["CWE-120", "CWE-122"]);
|
||||
// Returns: ["memcpy", "strcpy", "sprintf", "gets", ...]
|
||||
|
||||
// Get all mapped CWEs
|
||||
var cwes = CweToSinkMapper.GetMappedCwes();
|
||||
```
|
||||
|
||||
**Supported CWE Categories:**
|
||||
| Category | CWE IDs | Example Sinks |
|
||||
|----------|---------|---------------|
|
||||
| Buffer Overflow | CWE-120, CWE-121, CWE-122, CWE-787 | `memcpy`, `strcpy`, `sprintf` |
|
||||
| Format String | CWE-134 | `printf`, `fprintf`, `sprintf` |
|
||||
| Integer Overflow | CWE-190, CWE-191 | `malloc`, `calloc`, `realloc` |
|
||||
| Use After Free | CWE-416 | `free`, `delete`, `delete[]` |
|
||||
| Command Injection | CWE-78 | `system`, `popen`, `execve` |
|
||||
| SQL Injection | CWE-89 | `PQexec`, `mysql_query`, `sqlite3_exec` |
|
||||
| Path Traversal | CWE-22 | `fopen`, `open`, `access` |
|
||||
| NULL Pointer | CWE-476 | (dereference detection) |
|
||||
|
||||
### 4. AI Enrichment Service
|
||||
|
||||
Optional AI-assisted enrichment using advisory text and commit analysis:
|
||||
|
||||
```csharp
|
||||
var enrichmentService = serviceProvider.GetRequiredService<IGoldenSetEnrichmentService>();
|
||||
|
||||
if (enrichmentService.IsAvailable)
|
||||
{
|
||||
var result = await enrichmentService.EnrichAsync(
|
||||
draftGoldenSet,
|
||||
new GoldenSetEnrichmentContext
|
||||
{
|
||||
CommitAnalysis = commitResult,
|
||||
CweIds = ["CWE-787"],
|
||||
AdvisoryText = "Buffer overflow in parse_header..."
|
||||
});
|
||||
|
||||
// Result.EnrichedDraft contains improved definition
|
||||
// Result.ActionsApplied describes what was added/refined
|
||||
}
|
||||
```
|
||||
|
||||
**Enrichment Actions:**
|
||||
- `function_added` - New vulnerable function identified
|
||||
- `sink_added` - New sink function from CWE mapping
|
||||
- `constant_extracted` - Magic value from commits
|
||||
- `edge_suggested` - Control flow pattern suggested
|
||||
- `witness_hint_added` - Example trigger input
|
||||
|
||||
### 5. Review Workflow
|
||||
|
||||
State machine for golden set curation:
|
||||
|
||||
```
|
||||
Draft ──> InReview ──> Approved ──> Deprecated ──> Archived
|
||||
│ │ │
|
||||
└───────────┴────────────┴── (can return to Draft)
|
||||
```
|
||||
|
||||
```csharp
|
||||
var reviewService = serviceProvider.GetRequiredService<IGoldenSetReviewService>();
|
||||
|
||||
// Submit for review
|
||||
await reviewService.SubmitForReviewAsync("CVE-2024-1234", "author@example.com");
|
||||
|
||||
// Approve
|
||||
await reviewService.ApproveAsync("CVE-2024-1234", "reviewer@example.com", "LGTM");
|
||||
|
||||
// Or request changes
|
||||
await reviewService.RequestChangesAsync(
|
||||
"CVE-2024-1234",
|
||||
"reviewer@example.com",
|
||||
"Needs specific function name",
|
||||
[new ChangeRequest { Field = "targets[0].functionName", Suggestion = "parse_header" }]);
|
||||
```
|
||||
|
||||
## Golden Set Schema
|
||||
|
||||
```yaml
|
||||
# CVE-2024-1234.golden.yaml
|
||||
schema_version: "1.0"
|
||||
id: CVE-2024-1234
|
||||
component: openssl
|
||||
|
||||
targets:
|
||||
- function: parse_header
|
||||
sinks:
|
||||
- memcpy
|
||||
- strcpy
|
||||
constants:
|
||||
- "0x1000"
|
||||
- "sizeof(buffer)"
|
||||
edges:
|
||||
- bb1->bb2 # bounds check bypass
|
||||
|
||||
witness:
|
||||
stdin: "AAAA..."
|
||||
argv:
|
||||
- "--vulnerable-option"
|
||||
env:
|
||||
BUFFER_SIZE: "99999"
|
||||
|
||||
metadata:
|
||||
author_id: researcher@example.com
|
||||
source_ref: https://nvd.nist.gov/vuln/detail/CVE-2024-1234
|
||||
created_at: 2024-01-15T10:30:00Z
|
||||
tags:
|
||||
- memory-corruption
|
||||
- heap-overflow
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
# appsettings.yaml
|
||||
BinaryIndex:
|
||||
GoldenSet:
|
||||
SchemaVersion: "1.0"
|
||||
Validation:
|
||||
ValidateCveExists: true
|
||||
ValidateSinks: true
|
||||
StrictEdgeFormat: true
|
||||
OfflineMode: false
|
||||
Storage:
|
||||
PostgresSchema: golden_sets
|
||||
ConnectionStringName: BinaryIndex
|
||||
Caching:
|
||||
SinkRegistryCacheMinutes: 60
|
||||
DefinitionCacheMinutes: 15
|
||||
Authoring:
|
||||
EnableAiEnrichment: true
|
||||
EnableCommitAnalysis: true
|
||||
MaxCommitsToAnalyze: 5
|
||||
AutoAcceptConfidenceThreshold: 0.8
|
||||
```
|
||||
|
||||
## Service Registration
|
||||
|
||||
```csharp
|
||||
// Program.cs or Startup.cs
|
||||
services.AddGoldenSetServices(configuration);
|
||||
services.AddGoldenSetAuthoring();
|
||||
services.AddGoldenSetPostgresStorage();
|
||||
|
||||
// Optional: Add HTTP client for commit analysis
|
||||
services.AddHttpClient("upstream-commits", client =>
|
||||
{
|
||||
client.Timeout = TimeSpan.FromSeconds(30);
|
||||
client.DefaultRequestHeaders.Add("User-Agent", "StellaOps-GoldenSet/1.0");
|
||||
});
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
```bash
|
||||
# Initialize a golden set from CVE
|
||||
stella scanner golden init CVE-2024-1234 --component openssl
|
||||
|
||||
# With options
|
||||
stella scanner golden init CVE-2024-1234 \
|
||||
--component openssl \
|
||||
--output ./golden-sets/CVE-2024-1234.yaml \
|
||||
--no-ai \
|
||||
--store
|
||||
|
||||
# Interactive mode for refinement
|
||||
stella scanner golden init CVE-2024-1234 --interactive
|
||||
|
||||
# Export as JSON
|
||||
stella scanner golden init CVE-2024-1234 --json
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
1. **CVE Format** - Must match `CVE-YYYY-NNNNN` or `GHSA-xxxx-xxxx-xxxx`
|
||||
2. **Component Required** - Non-empty component name
|
||||
3. **Targets Required** - At least one vulnerable target
|
||||
4. **Sinks Validation** - Sinks must be in the sink registry
|
||||
5. **Edge Format** - Must match `bbN->bbM` pattern (if strict mode)
|
||||
6. **Constants Format** - Hex constants must be valid (`0x...`)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with Commit Analysis** - Fix commits are the most reliable source
|
||||
2. **Use CWE Mapping** - Automatic sink suggestions based on vulnerability type
|
||||
3. **Validate Locally** - Always validate before submitting for review
|
||||
4. **Include Witness Data** - Example inputs help verify detection accuracy
|
||||
5. **Tag Appropriately** - Use consistent tags for categorization
|
||||
6. **Document Source** - Always include source_ref for traceability
|
||||
|
||||
## Metrics
|
||||
|
||||
Track authoring quality with:
|
||||
- **Extraction Confidence** - Overall, per-source, per-field
|
||||
- **Enrichment Actions** - What was added automatically
|
||||
- **Review Iterations** - How many rounds before approval
|
||||
- **Detection Rate** - How well the golden set detects known-vulnerable binaries
|
||||
|
||||
## See Also
|
||||
|
||||
- [Golden Set Schema Reference](../schemas/golden-set-schema.md)
|
||||
- [Sink Registry](../modules/scanner/sink-registry.md)
|
||||
- [Binary Analysis Architecture](../modules/scanner/architecture.md)
|
||||
- [Vulnerability Detection](../modules/scanner/vulnerability-detection.md)
|
||||
Reference in New Issue
Block a user