Files

StellaOps Bot f10d83c444 Refactor code structure and optimize performance across multiple modules

2025-12-26 20:03:41 +02:00

7.5 KiB

Raw Blame History

Binary Evidence User Guide

Sprint: SPRINT_20251226_014_BINIDX Task: SCANINT-25 Version: 1.0.0

This guide explains how to use binary vulnerability evidence in StellaOps scans, including CLI commands, understanding scan results, and interpreting backport status.

Overview

Binary Evidence provides vulnerability detection for compiled binaries (ELF, PE, Mach-O) beyond traditional package-based scanning. It identifies vulnerabilities in stripped binaries where package metadata may be missing or inaccurate, and detects when distribution maintainers have backported security fixes.

Key Features

Build-ID Catalog Lookup: High-confidence matching using GNU Build-IDs
Fingerprint Matching: Position-independent code matching for stripped binaries
Backport Detection: Identifies distribution-patched binaries
Cryptographic Evidence: DSSE-signed proof segments for audit trails

CLI Commands

Inspect Binary Identity

Extract identity information from a binary file:

stella binary inspect /path/to/binary

# JSON output
stella binary inspect /path/to/binary --format json

Output:

Binary Identity
  Format:       ELF
  Architecture: x86_64
  Build-ID:     8d8f09a0d7e2c1b3a5f4e6d8c0b2a4e6f8d0c2b4
  SHA256:       sha256:abcd1234567890abcdef1234567890abcdef1234...
  Binary Key:   openssl:1.1.1w-1

Lookup Vulnerabilities by Build-ID

Query the vulnerability database using a Build-ID:

stella binary lookup 8d8f09a0d7e2c1b3a5f4e6d8c0b2a4e6f8d0c2b4

# With distribution context
stella binary lookup 8d8f09a0d7e2c1b3a5f4e6d8c0b2a4e6f8d0c2b4 \
  --distro debian --release bookworm

# JSON output
stella binary lookup 8d8f09a0d7e2c1b3a5f4e6d8c0b2a4e6f8d0c2b4 --format json

Output:

Vulnerability Matches for Build-ID: 8d8f09a0d7e2c1b3a5f4...

CVE-2023-5678
  Status:     FIXED (Backported)
  Package:    pkg:deb/debian/openssl@1.1.1n-0+deb11u4
  Method:     buildid_catalog
  Confidence: 95%
  Fixed In:   1.1.1w-1

CVE-2023-4807
  Status:     FIXED (Backported)
  Package:    pkg:deb/debian/openssl@1.1.1n-0+deb11u4
  Method:     buildid_catalog
  Confidence: 92%
  Fixed In:   1.1.1w-1

Generate Binary Fingerprint

Create a position-independent fingerprint for matching:

stella binary fingerprint /path/to/binary

# Specific algorithm
stella binary fingerprint /path/to/binary --algorithm cfg

# Fingerprint specific function
stella binary fingerprint /path/to/binary --function SSL_read

# Hex output
stella binary fingerprint /path/to/binary --format hex

Algorithms:

combined (default): Combines all methods for robust matching
basic-block: Basic block hashes (good for minor changes)
cfg: Control flow graph structure (resilient to reordering)
string-refs: String constant references (fast, less precise)

Understanding Scan Results

Status Badges

When viewing scan results in the UI or CLI, binaries display status badges:

Badge	Color	Meaning
Backported & Safe	Green	The distribution backported the security fix. The binary is not vulnerable despite the CVE matching.
Affected & Reachable	Red	The binary contains vulnerable code and is in an executable code path.
Affected (Low Priority)	Orange	Vulnerable but not in the main execution path.
Unknown	Gray	Could not determine vulnerability or fix status.

Match Methods

Vulnerability matches use different detection methods with varying confidence:

Method	Confidence	Description
`buildid_catalog`	High (95%+)	Exact Build-ID match in the known-build catalog
`fingerprint_match`	Medium (70-90%)	Position-independent code similarity
`range_match`	Low (50-70%)	Version range inference

Fix Status Detection

Fix status is determined by analyzing:

Changelog: Parsing distribution changelogs for CVE mentions
Patch Analysis: Comparing function signatures pre/post patch
Advisory: Cross-referencing distribution security advisories

Configuration

Enabling Binary Analysis

In scanner.yaml:

scanner:
  analyzers:
    binary:
      enabled: true
      fingerprintOnMiss: true  # Generate fingerprints when catalog miss
  binaryIndex:
    enabled: true
    batchSize: 100
    timeoutMs: 5000
    minConfidence: 0.7
    cache:
      enabled: true
      identityTtl: 1h
      fixStatusTtl: 1h
      fingerprintTtl: 30m

Cache Configuration

Binary lookups are cached in Valkey for performance:

binaryIndex:
  cache:
    keyPrefix: "stellaops:binary:"
    identityTtl: 1h        # Cache Build-ID lookups
    fixStatusTtl: 1h       # Cache fix status queries
    fingerprintTtl: 30m    # Shorter TTL for fingerprints
    targetHitRate: 0.80    # Target 80% cache hit rate

Interpreting Evidence

Binary Fingerprint Evidence Proof Segment

Each binary with vulnerability matches generates a binary_fingerprint_evidence proof segment:

{
  "predicateType": "https://stellaops.dev/predicates/binary-fingerprint-evidence@v1",
  "version": "1.0.0",
  "binary_identity": {
    "format": "elf",
    "build_id": "8d8f09a0d7e2c1b3a5f4e6d8c0b2a4e6f8d0c2b4",
    "file_sha256": "sha256:abcd1234...",
    "architecture": "x86_64",
    "binary_key": "openssl:1.1.1w-1",
    "path": "/usr/lib/x86_64-linux-gnu/libssl.so.1.1"
  },
  "layer_digest": "sha256:layer1abc123...",
  "matches": [
    {
      "cve_id": "CVE-2023-5678",
      "method": "buildid_catalog",
      "confidence": 0.95,
      "vulnerable_purl": "pkg:deb/debian/openssl@1.1.1n-0+deb11u4",
      "fix_status": {
        "state": "fixed",
        "fixed_version": "1.1.1w-1",
        "method": "changelog",
        "confidence": 0.98
      }
    }
  ]
}

Viewing Proof Chain

In the UI, click "View Proof Chain" on any CVE match to see:

The binary identity used for lookup
The match method and confidence
The fix status determination method
The DSSE signature and Rekor log entry (if enabled)

Troubleshooting

No Matches Found

If binaries show no vulnerability matches:

Check Build-ID: Run stella binary inspect to verify the binary has a Build-ID
Verify Catalog Coverage: Not all binaries are in the known-build catalog
Enable Fingerprinting: Set fingerprintOnMiss: true to fall back to fingerprint matching

Low Confidence Matches

Matches below the minConfidence threshold (default 0.7) are not reported. To see all matches:

stella binary lookup <build-id> --min-confidence 0.5

Cache Issues

Clear the binary cache if results seem stale:

# Via CLI
stella cache clear --prefix binary

# Via Redis CLI
redis-cli KEYS "stellaops:binary:*" | xargs redis-cli DEL

Build-ID Missing

Stripped binaries may lack Build-IDs. Options:

Rebuild with -Wl,--build-id=sha1
Use fingerprint matching instead
Map to package using file path heuristics

Best Practices

Include Build-IDs: Ensure your build pipeline preserves GNU Build-IDs
Use Distro Context: Always specify --distro and --release for accurate backport detection
Review Unknown Status: Investigate binaries with "Unknown" status manually
Monitor Cache Hit Rate: Target >80% for repeat scans

7.5 KiB Raw Blame History