git.stella-ops.org/docs/modules/scanner/guides/binary-evidence-guide.md

# 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:

```bash
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:

```bash
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:

```bash
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:

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

---

## Configuration

### Enabling Binary Analysis

In `scanner.yaml`:

```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:

```yaml
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:

```json
{
  "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:

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

---

## Troubleshooting

### No Matches Found

If binaries show no vulnerability matches:

1. **Check Build-ID**: Run `stella binary inspect` to verify the binary has a Build-ID
2. **Verify Catalog Coverage**: Not all binaries are in the known-build catalog
3. **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:

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

### Cache Issues

Clear the binary cache if results seem stale:

```bash
# 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:

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

---

## Best Practices

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

---

## Related Documentation

- [BinaryIndex Architecture](../../binaryindex/architecture.md)
- [Scanner Architecture](../architecture.md)
- [Proof Chain Specification](../../attestor/proof-chain-specification.md)
- [CLI Reference](../../../09_API_CLI_REFERENCE.md)