stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 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

84
docs/modules/scanner/image-inspection.md Normal file
View File

@@ -0,0 +1,84 @@
# OCI Image Inspection
## Overview
OCI image inspection resolves an image reference to its manifest or index, enumerates platform manifests, and returns ordered layer metadata. The inspector is used by CLI workflows that need deterministic image metadata without pulling layers.
## Architecture
### Components
| Component | Location | Responsibility |
| --- | --- | --- |
| `IOciImageInspector` | `Scanner.Storage.Oci` | Public interface for image inspection |
| `OciImageInspector` | `Scanner.Storage.Oci` | Implements manifest/index resolution, auth flow, and ordering |
| `ImageInspectionResult` | `Scanner.Contracts` | Output model for index, platform, and layer data |
### Data flow
1. Parse the image reference into registry, repository, tag or digest.
2. HEAD the manifest to obtain media type and digest.
3. GET the manifest payload.
4. If media type is index, enumerate platform manifests and optionally resolve each manifest.
5. For each manifest, fetch config (for platform metadata) and list layers in manifest order.
6. Return ordered results with warnings and a deterministic inspection timestamp.
## Media type support
| Media type | Type | Handling |
| --- | --- | --- |
| `application/vnd.oci.image.index.v1+json` | OCI index | Parse as index and enumerate manifests |
| `application/vnd.docker.distribution.manifest.list.v2+json` | Docker list | Parse as index |
| `application/vnd.oci.image.manifest.v1+json` | OCI manifest | Parse as manifest |
| `application/vnd.docker.distribution.manifest.v2+json` | Docker manifest | Parse as manifest |
## Configuration
The inspector uses `OciRegistryOptions`:
| Field | Purpose |
| --- | --- |
| `DefaultRegistry` | Registry to use when no registry is specified |
| `AllowInsecure` | Allow HTTP and insecure TLS for registry calls |
| `Auth.Username` / `Auth.Password` | Basic auth credentials |
| `Auth.Token` | Bearer token |
| `Auth.AllowAnonymousFallback` | Allow retry without auth after 401 |
CLI configuration binding uses the `OciRegistry` section (example):
```json
{
"OciRegistry": {
"DefaultRegistry": "docker.io",
"AllowInsecure": false,
"Auth": {
"Username": "registry-user",
"Password": "registry-pass",
"AllowAnonymousFallback": true
}
}
}
```
## Output model
`ImageInspectionResult` returns:
- Resolved digest and media type
- Multi-arch indicator
- Ordered platform manifests (os, arch, variant)
- Ordered layer list with size and media type
- UTC inspection timestamp from `TimeProvider`
- Deterministic, sorted warnings
## Determinism
- Platforms sorted by `os`, `architecture`, `variant`.
- Layers preserve manifest order (0-indexed).
- Warnings sorted lexicographically and de-duplicated.
- Timestamps come from injected `TimeProvider`.
## Integration points
- CLI: `stella image inspect` consumes the inspector result for table and JSON output.
- Scanner services can reuse the inspector for registry resolution without pulling layers.