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

audit, advisories and doctors/setup work

Browse Source
This commit is contained in:
master
2026-01-13 18:53:39 +02:00
parent 9ca7cb183e
commit d7be6ba34b
811 changed files with 54242 additions and 4056 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/modules/scanner/binary-diff-attestation.md
View File

@@ -26,36 +26,14 @@ The attestation provides the *evidence* that supports VEX claims. For example, a
### Component Diagram
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ Binary Diff Attestation Flow │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ OCI │ │ Layer │ │ Binary │ │ Section │ │
│ │ Registry │───▶│ Extraction │───▶│ Detection │───▶│ Hash │ │
│ │ Client │ │ │ │ │ │ Extractor │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └──────┬──────┘ │
│ │ │
│ Base Image ─────────────────────────────────────┐ │ │
│ Target Image ───────────────────────────────────┤ ▼ │
│ │ ┌─────────────┐ │
│ └─▶│ Diff │ │
│ │ Computation │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ DSSE │◀───│ Predicate │◀───│ Finding │◀───│ Verdict │ │
│ │ Signer │ │ Builder │ │ Aggregation │ │ Classifier │ │
│ └──────┬──────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Rekor │ │ File │ │
│ │ Submission │ │ Output │ │
│ └─────────────┘ └─────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
+-------------------+ +--------------------+ +--------------------+ +----------------------+
| OCI Registry |-->| Layer Extraction |-->| ELF Detection |-->| Section Hash Extract |
+-------------------+ +--------------------+ +--------------------+ +----------------------+
| base + target images
v
+-------------------+ +--------------------+ +------------------+ +------------------+
| Diff Computation |-->| Predicate Builder |-->| DSSE Signer |-->| Output Files |
+-------------------+ +--------------------+ +------------------+ +------------------+
```
### Key Components
@@ -63,8 +41,8 @@ The attestation provides the *evidence* that supports VEX claims. For example, a
| Component | Location | Responsibility |
|-----------|----------|----------------|
| `ElfSectionHashExtractor` | `Scanner.Analyzers.Native` | Extract per-section SHA-256 hashes from ELF binaries |
| `BinaryDiffService` | `Cli.Services` | Orchestrate diff computation between two images |
| `BinaryDiffPredicateBuilder` | `Attestor.StandardPredicates` | Construct BinaryDiffV1 in-toto predicates |
| `BinaryDiffService` | `Cli.Commands.Scan` | Orchestrate diff computation between two images |
| `BinaryDiffPredicateBuilder` | `Attestor.StandardPredicates` | Construct BinaryDiffV1 predicate payloads |
| `BinaryDiffDsseSigner` | `Attestor.StandardPredicates` | Sign predicates with DSSE envelopes |
### Data Flow
@@ -74,9 +52,9 @@ The attestation provides the *evidence* that supports VEX claims. For example, a
3. **Binary Identification**: Identify ELF binaries in both filesystems
4. **Section Hash Computation**: Compute SHA-256 for each target section in each binary
5. **Diff Computation**: Compare section hashes between base and target
6. **Verdict Classification**: Classify changes as patched/vanilla/unknown
6. **Verdict Classification**: Basic classification of unchanged vs modified binaries
7. **Predicate Construction**: Build BinaryDiffV1 predicate with findings
8. **DSSE Signing**: Sign predicate and optionally submit to Rekor
8. **DSSE Signing**: Sign predicate; optional transparency log submission is handled by attestor tooling
## ELF Section Hashing
@@ -131,26 +109,24 @@ All operations produce deterministic output:
### Schema Overview
The `BinaryDiffV1` predicate follows in-toto attestation format:
The `BinaryDiffV1` predicate payload uses the following structure:
```json
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [
"predicateType": "stellaops.binarydiff.v1",
"subjects": [
{
"name": "docker://repo/app@sha256:target...",
"digest": { "sha256": "target..." }
"digest": { "sha256": "target..." },
"platform": { "os": "linux", "architecture": "amd64" }
}
],
"predicateType": "stellaops.binarydiff.v1",
"predicate": {
"inputs": {
"base": { "digest": "sha256:base..." },
"target": { "digest": "sha256:target..." }
},
"findings": [...],
"metadata": {...}
}
"inputs": {
"base": { "digest": "sha256:base..." },
"target": { "digest": "sha256:target..." }
},
"findings": [...],
"metadata": { ... }
}
```
@@ -175,15 +151,18 @@ Each finding represents a binary comparison:
"binaryFormat": "elf",
"sectionDeltas": [
{ "section": ".text", "status": "modified" },
{ "section": ".rodata", "status": "identical" }
{ "section": ".rodata", "status": "added" }
],
"confidence": 0.95,
"verdict": "patched"
"confidence": 0.50,
"verdict": "unknown"
}
```
### Verdicts
Current CLI output uses `vanilla` for unchanged binaries and `unknown` for modified binaries.
Advanced verdict classification (patched/vanilla) is planned for follow-up work.
| Verdict | Meaning | Confidence Threshold |
|---------|---------|---------------------|
| `patched` | Binary shows evidence of security patch | >= 0.90 |
@@ -210,13 +189,12 @@ Each finding represents a binary comparison:
### Signature Algorithm
- **Default**: Ed25519
- **Alternative**: ECDSA P-256, RSA-PSS (via `ICryptoProviderRegistry`)
- **Keyless**: Sigstore Fulcio certificate chain
- **CLI output**: ECDSA (P-256/384/521) with operator-provided PEM key
- **Library support**: Ed25519 available via `EnvelopeSignatureService`
### Rekor Submission
When Rekor is enabled:
When Rekor is enabled in attestor tooling:
1. DSSE envelope is submitted to Rekor transparency log
2. Inclusion proof is retrieved
@@ -229,22 +207,28 @@ When Rekor is enabled:
"integratedTime": "2026-01-13T12:00:00Z"
}
```
Note: `stella scan diff` does not submit to Rekor; it only emits local DSSE outputs.
### Verification
Binary diff attestations can be verified with:
```bash
# Using cosign
# Attach the DSSE envelope to the image
stella attest attach \
--image docker://repo/app:1.0.1 \
--attestation ./binarydiff.dsse.json
# Verify with cosign (key-based)
cosign verify-attestation \
--type stellaops.binarydiff.v1 \
--certificate-identity-regexp '.*' \
--certificate-oidc-issuer-regexp '.*' \
--key ./keys/binarydiff.pub \
docker://repo/app:1.0.1
# Using stella CLI
stella verify attestation ./binarydiff.dsse.json \
--type stellaops.binarydiff.v1
# Verify with stella CLI
stella attest verify \
--image docker://repo/app:1.0.1 \
--predicate-type stellaops.binarydiff.v1
```
## Integration Points
@@ -335,7 +319,7 @@ See [CLI Reference](../../API_CLI_REFERENCE.md#stella-scan-diff) for full option
1. **ELF only**: PE and Mach-O support planned for M2
2. **Single platform**: Multi-platform diff requires multiple invocations
3. **No function-level analysis**: Section-level granularity only
4. **Confidence scoring**: Based on section changes, not semantic analysis
4. **Confidence scoring**: Placeholder scoring only; verdict classifier is minimal
### Roadmap