git.stella-ops.org/docs/modules/scanner/design/binary-evidence-alignment.md

Binary Evidence Alignment with SBOM/VEX Outputs (SC6)

Status: Draft · Date: 2025-12-04 Scope: Define how binary-level evidence (build-id, symbols, patch oracle) aligns with SBOM/VEX outputs to feed policy engines and VEX decisioning.

Objectives

• Link binary-level evidence to SBOM component identities.
• Ensure evidence fields are available for policy/VEX correlation.
• Define required joins between binary analysis and vulnerability data.
• Enable deterministic evidence chain from binary → SBOM → VEX → policy.

Evidence Types

Build Identity Evidence

Evidence Type	Source	SBOM Field	VEX Field	Policy Input
Build ID	ELF .note.gnu.build-id	component.properties[evidence:build-id]	statement.products[].identifiers.buildId	binary.buildId
Go Build Info	runtime.BuildInfo	component.properties[evidence:go-build]	n/a	binary.goBuildInfo
PE Version	PE resource section	component.properties[evidence:pe-version]	n/a	binary.peVersion
Mach-O UUID	LC_UUID command	component.properties[evidence:macho-uuid]	n/a	binary.machoUuid

Symbol Evidence

Evidence Type	Source	SBOM Field	VEX Field	Policy Input
Exported Symbols	ELF .dynsym / PE exports	component.properties[evidence:symbols-hash]	n/a	binary.symbolsHash
Debug Symbols	DWARF / PDB	component.properties[evidence:debug-hash]	n/a	binary.debugHash
Function Names	Symbol table	component.properties[evidence:functions]	statement.justification.functions	binary.functions[]

Patch Oracle Evidence

Evidence Type	Source	SBOM Field	VEX Field	Policy Input
Patch Signature	Function hash diff	component.properties[evidence:patch-sig]	statement.justification.patchSignature	patch.signature
CVE Fix Commit	Commit mapping	component.properties[evidence:fix-commit]	statement.justification.fixCommit	patch.fixCommit
Binary Diff	objdiff hash	component.properties[evidence:binary-diff]	n/a	patch.binaryDiffHash

Evidence Chain

Binary → SBOM Component → VEX Statement → Policy Evaluation
   │          │                │                │
   │          │                │                └── policy://input/component/{purl}
   │          │                └── vex://statement/{cve}/{product}
   │          └── sbom://component/{purl}
   └── binary://evidence/{hash}

Join Keys

Source	Target	Join Field	Required
Binary	SBOM Component	evidence:hash → component.hashes[]	Yes
SBOM Component	VEX Product	component.purl → statement.products[].purl	Yes
VEX Statement	Policy Input	statement.cve → policy.advisoryId	Yes
Binary Evidence	VEX Justification	evidence:patch-sig → justification.patchSignature	No

Required SBOM Evidence Properties

For binary evidence to flow through the pipeline, components MUST include:

{
  "type": "library",
  "name": "openssl",
  "version": "3.0.0",
  "purl": "pkg:generic/openssl@3.0.0",
  "hashes": [
    {"alg": "SHA-256", "content": "..."}
  ],
  "properties": [
    {"name": "evidence:hash", "value": "b3:..."},
    {"name": "evidence:source", "value": "scanner:binary-analyzer:v1.0.0"},
    {"name": "evidence:build-id", "value": "abc123..."},
    {"name": "evidence:symbols-hash", "value": "b3:..."},
    {"name": "evidence:patch-sig", "value": "b3:..."},
    {"name": "evidence:confidence", "value": "0.95"}
  ]
}

VEX Integration

VEX statements can reference binary evidence for justification:

{
  "vulnerability": "CVE-2025-0001",
  "products": [
    {
      "purl": "pkg:generic/openssl@3.0.0",
      "identifiers": {
        "buildId": "abc123...",
        "evidenceHash": "b3:..."
      }
    }
  ],
  "status": "not_affected",
  "justification": {
    "category": "vulnerable_code_not_present",
    "patchSignature": "b3:...",
    "fixCommit": "deadbeef...",
    "functions": ["EVP_EncryptUpdate", "EVP_DecryptUpdate"],
    "evidenceRef": "cas://evidence/openssl/3.0.0/binary-analysis.json"
  }
}

Policy Engine Integration

Policy rules can reference binary evidence fields:

# policy/scanner/binary-evidence.rego
package scanner.binary

import rego.v1

# Require build-id for high-severity vulns
deny contains msg if {
    input.vulnerability.severity == "critical"
    not input.component.properties["evidence:build-id"]
    msg := sprintf("Critical vuln %s requires build-id evidence", [input.vulnerability.id])
}

# Accept patch oracle evidence as mitigation
allow contains decision if {
    input.component.properties["evidence:patch-sig"]
    input.vex.status == "not_affected"
    input.vex.justification.patchSignature == input.component.properties["evidence:patch-sig"]
    decision := {
        "action": "accept",
        "reason": "Patch signature verified",
        "confidence": input.component.properties["evidence:confidence"]
    }
}

# Confidence threshold for binary analysis
warn contains msg if {
    conf := to_number(input.component.properties["evidence:confidence"])
    conf < 0.8
    msg := sprintf("Low confidence (%v) binary evidence for %s", [conf, input.component.purl])
}

Evidence Fields by Binary Format

ELF (Linux)

Section	Evidence Extracted	Deterministic
.note.gnu.build-id	Build ID (SHA1/UUID)	Yes
.gnu.hash	Symbol hash table	Yes
.dynsym	Dynamic symbols	Yes
.debug_info	DWARF debug symbols	Yes
.rodata	String literals	Yes

PE (Windows)

Section	Evidence Extracted	Deterministic
PE Header	Timestamp, Machine type	Partial*
Resource	Version info, Product name	Yes
Export Table	Exported functions	Yes
Import Table	Dependencies	Yes
Debug Directory	PDB path, GUID	Yes

*PE timestamp may be zeroed for reproducible builds

Mach-O (macOS)

Command	Evidence Extracted	Deterministic
LC_UUID	Binary UUID	Yes
LC_VERSION_MIN	Min OS version	Yes
LC_BUILD_VERSION	Build version	Yes
LC_CODE_SIGNATURE	Code signature	Yes
SYMTAB	Symbol table	Yes

Determinism Requirements

1. Stable ordering: Evidence properties sorted by name
2. Hash computation: BLAKE3-256 over canonical JSON
3. Confidence scores: 4 decimal places, MidpointRounding.ToZero
4. Function lists: Sorted lexicographically, deduplicated
5. Symbol hashes: Computed over sorted symbol names

CAS Storage

Binary evidence artifacts stored in CAS:

cas://evidence/{component}/{version}/
├── binary-analysis.json      # Full analysis result
├── symbols.txt               # Extracted symbols (sorted)
├── functions.txt             # Extracted functions (sorted)
└── patch-signatures.json     # Patch oracle signatures

Links

• Sprint: docs/implplan/SPRINT_0186_0001_0001_record_deterministic_execution.md (SC6)
• Roadmap: docs/modules/scanner/design/standards-convergence-roadmap.md (SC1)
• Contract: docs/modules/scanner/design/cdx17-cbom-contract.md (SC2)
• Entropy: docs/modules/scanner/entropy.md