stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Refactor code structure and optimize performance across multiple modules

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-26 20:03:22 +02:00
parent c786faae84
commit f10d83c444
1385 changed files with 69732 additions and 10280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/modules/scanner/architecture.md
View File

@@ -316,10 +316,45 @@ Semantic data flows into:
See `docs/modules/scanner/operations/entrypoint-semantic.md` for full schema reference.
**E) Attestation & SBOM bind (optional)**
**E) Binary Vulnerability Lookup (Sprint 20251226_014_BINIDX)**
The **BinaryLookupStageExecutor** enriches scan results with binary-level vulnerability evidence:
* **Identity Extraction**: For each ELF/PE/Mach-O binary, extract Build-ID, file SHA256, and architecture. Generate a `binary_key` for catalog lookups.
* **Build-ID Catalog Lookup**: Query the BinaryIndex known-build catalog using Build-ID as primary key. Returns CVE matches with high confidence (>=0.95) when the exact binary version is indexed.
* **Fingerprint Matching**: For binaries not in the catalog, compute position-independent fingerprints (basic-block, CFG, string-refs) and match against the vulnerability corpus. Returns similarity scores and confidence.
* **Fix Status Detection**: For each CVE match, query distro-specific backport information to determine if the vulnerability was fixed via distro patch. Methods: `changelog`, `patch_analysis`, `advisory`.
* **Valkey Cache**: All lookups are cached with configurable TTL (default 1 hour for identities, 30 minutes for fingerprints). Target cache hit rate: >80% for repeat scans.
**BinaryFindingMapper** converts matches to standard findings format with `BinaryFindingEvidence`:
```csharp
public sealed record BinaryFindingEvidence
{
public required string BinaryKey { get; init; }
public string? BuildId { get; init; }
public required string MatchMethod { get; init; } // buildid_catalog, fingerprint_match, range_match
public required decimal Confidence { get; init; }
public string? FixedVersion { get; init; }
public string? FixStatus { get; init; } // fixed, vulnerable, not_affected, wontfix
}
```
**Proof Segments**: The **Attestor** generates `binary_fingerprint_evidence` proof segments with DSSE signatures for each binary with vulnerability matches. Schema: `https://stellaops.dev/predicates/binary-fingerprint-evidence@v1`.
**UI Badges**: Scan results display status badges:
* **Backported & Safe** (green): Distro backported the fix
* **Affected & Reachable** (red): Vulnerable and in code path
* **Unknown** (gray): Could not determine status
**CLI Commands** (Sprint 20251226_014):
* `stella binary inspect <file>`: Extract identity (Build-ID, hashes, architecture)
* `stella binary lookup <build-id>`: Query vulnerabilities by Build-ID
* `stella binary fingerprint <file>`: Generate position-independent fingerprint
**F) Attestation & SBOM bind (optional)**
* For each **file hash** or **binary hash**, query local cache of **Rekor v2** indices; if an SBOM attestation is found for **exact hash**, bind it to the component (origin=`attested`).
* For the **image** digest, likewise bind SBOM attestations (build‑time referrers).
* For the **image** digest, likewise bind SBOM attestations (build-time referrers).
### 5.4 Component normalization (exact only)

280
docs/modules/scanner/guides/binary-evidence-guide.md Normal file
View File

@@ -0,0 +1,280 @@
# 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)