fix tests. new product advisories enhancements
This commit is contained in:
master
358
docs/modules/attestor/diagrams/trust-architecture.md
Normal file
358
docs/modules/attestor/diagrams/trust-architecture.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# Trust Architecture Diagrams
|
||||
|
||||
> Sprint: SPRINT_20260125_003 - WORKFLOW-008
|
||||
> Last updated: 2026-01-25
|
||||
|
||||
This document provides architectural diagrams for the StellaOps TUF-based trust
|
||||
distribution system.
|
||||
|
||||
---
|
||||
|
||||
## 1. Trust Hierarchy
|
||||
|
||||
The TUF trust hierarchy showing roles and key relationships.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "TUF Roles & Keys"
|
||||
ROOT[("Root<br/>(threshold: 3/5)")]
|
||||
TARGETS[("Targets<br/>(threshold: 1)")]
|
||||
SNAPSHOT[("Snapshot<br/>(threshold: 1)")]
|
||||
TIMESTAMP[("Timestamp<br/>(threshold: 1)")]
|
||||
end
|
||||
|
||||
subgraph "Trust Targets"
|
||||
REKOR_KEY["Rekor Public Key<br/>rekor-key-v1.pub"]
|
||||
FULCIO_CHAIN["Fulcio Chain<br/>fulcio-chain.pem"]
|
||||
SERVICE_MAP["Service Map<br/>sigstore-services-v1.json"]
|
||||
ORG_KEY["Org Signing Key<br/>org-signing-key.pub"]
|
||||
end
|
||||
|
||||
ROOT --> TARGETS
|
||||
ROOT --> SNAPSHOT
|
||||
ROOT --> TIMESTAMP
|
||||
SNAPSHOT --> TARGETS
|
||||
TIMESTAMP --> SNAPSHOT
|
||||
TARGETS --> REKOR_KEY
|
||||
TARGETS --> FULCIO_CHAIN
|
||||
TARGETS --> SERVICE_MAP
|
||||
TARGETS --> ORG_KEY
|
||||
|
||||
style ROOT fill:#ff6b6b,stroke:#333,stroke-width:2px
|
||||
style TARGETS fill:#4ecdc4,stroke:#333
|
||||
style SNAPSHOT fill:#45b7d1,stroke:#333
|
||||
style TIMESTAMP fill:#96ceb4,stroke:#333
|
||||
```
|
||||
|
||||
### Role Descriptions
|
||||
|
||||
| Role | Purpose | Update Frequency |
|
||||
|------|---------|-----------------|
|
||||
| Root | Ultimate trust anchor, defines all other roles | Rarely (ceremony) |
|
||||
| Targets | Lists trusted targets with hashes | When targets change |
|
||||
| Snapshot | Point-in-time view of all metadata | With targets |
|
||||
| Timestamp | Freshness guarantee | Every few hours |
|
||||
|
||||
---
|
||||
|
||||
## 2. Online Verification Flow
|
||||
|
||||
Client verification of attestations when network is available.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as StellaOps Client
|
||||
participant TUF as TUF Repository
|
||||
participant Rekor as Rekor Transparency Log
|
||||
participant Cache as Local Cache
|
||||
|
||||
Note over Client: Start verification
|
||||
|
||||
Client->>Cache: Check TUF metadata freshness
|
||||
alt Metadata stale
|
||||
Client->>TUF: Fetch timestamp.json
|
||||
TUF-->>Client: timestamp.json
|
||||
Client->>TUF: Fetch snapshot.json (if needed)
|
||||
TUF-->>Client: snapshot.json
|
||||
Client->>TUF: Fetch targets.json (if needed)
|
||||
TUF-->>Client: targets.json
|
||||
Client->>Cache: Update cached metadata
|
||||
end
|
||||
|
||||
Client->>Cache: Load Rekor public key
|
||||
Client->>Cache: Load service map
|
||||
|
||||
Note over Client: Resolve Rekor URL from service map
|
||||
|
||||
Client->>Rekor: GET /api/v2/log/entries/{uuid}/proof
|
||||
Rekor-->>Client: Inclusion proof + checkpoint
|
||||
|
||||
Note over Client: Verify:
|
||||
Note over Client: 1. Checkpoint signature (Rekor key)
|
||||
Note over Client: 2. Merkle inclusion proof
|
||||
Note over Client: 3. Entry matches attestation
|
||||
|
||||
Client-->>Client: Verification Result
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Offline Verification Flow
|
||||
|
||||
Client verification using sealed trust bundle (air-gapped).
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as StellaOps Client
|
||||
participant Bundle as Trust Bundle
|
||||
participant Tiles as Cached Tiles
|
||||
|
||||
Note over Client: Start offline verification
|
||||
|
||||
Client->>Bundle: Load TUF metadata
|
||||
Bundle-->>Client: root.json, targets.json, etc.
|
||||
|
||||
Client->>Bundle: Load Rekor public key
|
||||
Bundle-->>Client: rekor-key-v1.pub
|
||||
|
||||
Client->>Bundle: Load checkpoint
|
||||
Bundle-->>Client: Signed checkpoint
|
||||
|
||||
Note over Client: Verify checkpoint signature
|
||||
|
||||
Client->>Tiles: Load Merkle tiles for proof
|
||||
Tiles-->>Client: tile/data/..., tile/...
|
||||
|
||||
Note over Client: Reconstruct inclusion proof
|
||||
|
||||
Client->>Client: Verify Merkle path
|
||||
|
||||
Note over Client: No network calls required!
|
||||
|
||||
Client-->>Client: Verification Result
|
||||
```
|
||||
|
||||
### Trust Bundle Contents
|
||||
|
||||
```
|
||||
trust-bundle.tar.zst/
|
||||
├── manifest.json # Bundle metadata & checksums
|
||||
├── tuf/
|
||||
│ ├── root.json
|
||||
│ ├── targets.json
|
||||
│ ├── snapshot.json
|
||||
│ └── timestamp.json
|
||||
├── targets/
|
||||
│ ├── rekor-key-v1.pub
|
||||
│ ├── sigstore-services-v1.json
|
||||
│ └── fulcio-chain.pem
|
||||
└── tiles/ # Pre-fetched Merkle tiles
|
||||
├── checkpoint
|
||||
└── tile/
|
||||
├── 0/...
|
||||
├── 1/...
|
||||
└── data/...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Key Rotation Flow
|
||||
|
||||
Dual-key rotation with grace period.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> SingleKey: Initial State
|
||||
SingleKey --> DualKey: Add new key
|
||||
DualKey --> DualKey: Grace period<br/>(7-14 days)
|
||||
DualKey --> SingleKey: Remove old key
|
||||
SingleKey --> [*]
|
||||
|
||||
note right of SingleKey
|
||||
Only one key trusted
|
||||
All signatures use this key
|
||||
end note
|
||||
|
||||
note right of DualKey
|
||||
Both keys trusted
|
||||
Old attestations verify (old key)
|
||||
New attestations verify (new key)
|
||||
Clients sync new key
|
||||
end note
|
||||
```
|
||||
|
||||
### Detailed Rotation Timeline
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title Key Rotation Timeline
|
||||
dateFormat YYYY-MM-DD
|
||||
|
||||
section TUF Admin
|
||||
Generate new key :done, gen, 2026-01-01, 1d
|
||||
Add to TUF repository :done, add, after gen, 1d
|
||||
Sign & publish metadata :done, pub, after add, 1d
|
||||
|
||||
section Grace Period
|
||||
Dual-key active :active, grace, after pub, 14d
|
||||
Monitor client sync :monitor, after pub, 14d
|
||||
|
||||
section Completion
|
||||
Remove old key :remove, after grace, 1d
|
||||
Sign & publish final :final, after remove, 1d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Failover Flow
|
||||
|
||||
Circuit breaker and mirror failover during primary outage.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Closed: Normal operation
|
||||
|
||||
state "Circuit Breaker" as CB {
|
||||
Closed --> Open: Failures > threshold
|
||||
Open --> HalfOpen: After timeout
|
||||
HalfOpen --> Closed: Success
|
||||
HalfOpen --> Open: Failure
|
||||
}
|
||||
|
||||
state "Request Routing" as Routing {
|
||||
Primary: Primary Rekor
|
||||
Mirror: Mirror Rekor
|
||||
}
|
||||
|
||||
Closed --> Primary: Route to primary
|
||||
Open --> Mirror: Failover to mirror
|
||||
HalfOpen --> Primary: Probe primary
|
||||
|
||||
note right of Open
|
||||
Primary unavailable
|
||||
Use mirror if configured
|
||||
Cache tiles locally
|
||||
end note
|
||||
```
|
||||
|
||||
### Failover Decision Tree
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START([Request]) --> CB{Circuit<br/>Breaker<br/>State?}
|
||||
|
||||
CB -->|Closed| PRIMARY[Try Primary]
|
||||
CB -->|Open| MIRROR_CHECK{Mirror<br/>Enabled?}
|
||||
CB -->|HalfOpen| PROBE[Probe Primary]
|
||||
|
||||
PRIMARY -->|Success| SUCCESS([Return Result])
|
||||
PRIMARY -->|Failure| RECORD[Record Failure]
|
||||
RECORD --> THRESHOLD{Threshold<br/>Exceeded?}
|
||||
THRESHOLD -->|Yes| OPEN_CB[Open Circuit]
|
||||
THRESHOLD -->|No| FAIL([Return Error])
|
||||
|
||||
OPEN_CB --> MIRROR_CHECK
|
||||
|
||||
MIRROR_CHECK -->|Yes| MIRROR[Try Mirror]
|
||||
MIRROR_CHECK -->|No| CACHE{Cached<br/>Data?}
|
||||
|
||||
MIRROR -->|Success| SUCCESS
|
||||
MIRROR -->|Failure| CACHE
|
||||
|
||||
CACHE -->|Yes| CACHED([Return Cached])
|
||||
CACHE -->|No| FAIL
|
||||
|
||||
PROBE -->|Success| CLOSE_CB[Close Circuit]
|
||||
PROBE -->|Failure| OPEN_CB
|
||||
|
||||
CLOSE_CB --> SUCCESS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Component Architecture
|
||||
|
||||
Full system component view.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Client Layer"
|
||||
CLI[stella CLI]
|
||||
SDK[StellaOps SDK]
|
||||
end
|
||||
|
||||
subgraph "Trust Layer"
|
||||
TUF_CLIENT[TUF Client]
|
||||
CACHE[(Local Cache)]
|
||||
CB[Circuit Breaker]
|
||||
end
|
||||
|
||||
subgraph "Service Layer"
|
||||
TUF_SERVER[TUF Server]
|
||||
REKOR_PRIMARY[Rekor Primary]
|
||||
REKOR_MIRROR[Rekor Mirror / Tile Proxy]
|
||||
end
|
||||
|
||||
subgraph "Storage Layer"
|
||||
TUF_STORE[(TUF Metadata)]
|
||||
LOG_STORE[(Transparency Log)]
|
||||
TILE_STORE[(Tile Storage)]
|
||||
end
|
||||
|
||||
CLI --> TUF_CLIENT
|
||||
SDK --> TUF_CLIENT
|
||||
|
||||
TUF_CLIENT --> CACHE
|
||||
TUF_CLIENT --> CB
|
||||
CB --> REKOR_PRIMARY
|
||||
CB --> REKOR_MIRROR
|
||||
|
||||
TUF_CLIENT --> TUF_SERVER
|
||||
TUF_SERVER --> TUF_STORE
|
||||
|
||||
REKOR_PRIMARY --> LOG_STORE
|
||||
REKOR_MIRROR --> TILE_STORE
|
||||
|
||||
style CB fill:#ff9999
|
||||
style CACHE fill:#99ff99
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Data Flow Summary
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph "Bootstrap"
|
||||
A[Initialize TUF] --> B[Fetch Root]
|
||||
B --> C[Fetch Metadata Chain]
|
||||
C --> D[Cache Targets]
|
||||
end
|
||||
|
||||
subgraph "Attestation"
|
||||
E[Create Attestation] --> F[Sign DSSE]
|
||||
F --> G[Submit to Rekor]
|
||||
G --> H[Store Proof]
|
||||
end
|
||||
|
||||
subgraph "Verification"
|
||||
I[Load Attestation] --> J[Check TUF Freshness]
|
||||
J --> K[Fetch Inclusion Proof]
|
||||
K --> L[Verify Merkle Path]
|
||||
L --> M[Check Checkpoint Sig]
|
||||
M --> N[Return Result]
|
||||
end
|
||||
|
||||
D --> E
|
||||
H --> I
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [TUF Integration Guide](../tuf-integration.md)
|
||||
- [Rekor Verification Design](../rekor-verification-design.md)
|
||||
- [Bootstrap Guide](../../../operations/bootstrap-guide.md)
|
||||
- [Key Rotation Runbook](../../../operations/key-rotation-runbook.md)
|
||||
- [Disaster Recovery](../../../operations/disaster-recovery.md)
|
||||
Reference in New Issue
Block a user