feat: Add guild charters and task boards for various components
	
		
			
	
		
	
	
		
	
		
			Some checks failed
		
		
	
	
		
			
				
	
				Docs CI / lint-and-preview (push) Has been cancelled
				
			
		
		
	
	
				
					
				
			
		
			Some checks failed
		
		
	
	Docs CI / lint-and-preview (push) Has been cancelled
				
			- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform. - Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds. - Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies. - Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
This commit is contained in:
		
							
								
								
									
										41
									
								
								docs/forensics/provenance-attestation.md
									
									
									
									
									
										Normal file
									
								
							
							
						
						
									
										41
									
								
								docs/forensics/provenance-attestation.md
									
									
									
									
									
										Normal file
									
								
							@@ -0,0 +1,41 @@
 | 
			
		||||
# Provenance & Attestation Reference
 | 
			
		||||
 | 
			
		||||
This guide explains how StellaOps generates, signs, verifies, and distributes DSSE attestations for SBOMs, policy evaluations, and runtime evidence.
 | 
			
		||||
 | 
			
		||||
## 1. Attestation Workflow
 | 
			
		||||
 | 
			
		||||
1. **Scanner** produces signed payload requests (SBOM, report metadata).
 | 
			
		||||
2. **Signer** authenticates the caller, verifies release integrity, and issues DSSE bundles (keyless or KMS-backed).
 | 
			
		||||
3. **Attestor** submits bundles to Rekor v2, caches inclusion proofs, and serves verification packages.
 | 
			
		||||
4. **Consumers** (Export Center, Evidence Locker, CLI, Policy Engine) fetch bundles for verification.
 | 
			
		||||
 | 
			
		||||
## 2. DSSE Payload Types
 | 
			
		||||
 | 
			
		||||
- `StellaOps.BuildProvenance@1`
 | 
			
		||||
- `StellaOps.SBOMAttestation@1`
 | 
			
		||||
- `StellaOps.ScanResults@1`
 | 
			
		||||
- `StellaOps.PolicyEvaluation@1`
 | 
			
		||||
- `StellaOps.VEXAttestation@1`
 | 
			
		||||
- `StellaOps.RiskProfileEvidence@1`
 | 
			
		||||
 | 
			
		||||
Schemas live under `src/Attestor/StellaOps.Attestor.Types` and are documented in module architecture guides.
 | 
			
		||||
 | 
			
		||||
## 3. Verification
 | 
			
		||||
 | 
			
		||||
- CLI command `stella attest verify` requests proofs from Attestor.
 | 
			
		||||
- Services embed Rekor UUID/index and DSSE digests in their APIs for downstream verification.
 | 
			
		||||
- Verification pipeline checks signature trust roots, Rekor inclusion proofs, and transparency witness endorsements when enabled.
 | 
			
		||||
 | 
			
		||||
## 4. Offline/air-gap considerations
 | 
			
		||||
 | 
			
		||||
- Export Center bundles incorporate attestations and proofs for offline verification.
 | 
			
		||||
- Evidence Locker stores immutable attestation bundles with retention policies.
 | 
			
		||||
 | 
			
		||||
## 5. References
 | 
			
		||||
 | 
			
		||||
- `docs/modules/signer/architecture.md`
 | 
			
		||||
- `docs/modules/attestor/architecture.md`
 | 
			
		||||
- `docs/modules/export-center/architecture.md`
 | 
			
		||||
- `docs/modules/policy/architecture.md`
 | 
			
		||||
- `docs/modules/telemetry/architecture.md`
 | 
			
		||||
- `src/Provenance/StellaOps.Provenance.Attestation`
 | 
			
		||||
							
								
								
									
										41
									
								
								docs/forensics/timeline.md
									
									
									
									
									
										Normal file
									
								
							
							
						
						
									
										41
									
								
								docs/forensics/timeline.md
									
									
									
									
									
										Normal file
									
								
							@@ -0,0 +1,41 @@
 | 
			
		||||
# Timeline Forensics Guide
 | 
			
		||||
 | 
			
		||||
The Timeline Indexer service aggregates structured events (scanner runs, policy verdicts, runtime posture, evidence locker activity) so operators can audit changes over time. This guide summarises the event schema, query surfaces, and integration points.
 | 
			
		||||
 | 
			
		||||
## 1. Event Model
 | 
			
		||||
 | 
			
		||||
| Field | Description |
 | 
			
		||||
|-------|-------------|
 | 
			
		||||
| `event_id` | ULID identifying the event. |
 | 
			
		||||
| `tenant` | Tenant scope. |
 | 
			
		||||
| `timestamp` | UTC ISO-8601 time the event occurred. |
 | 
			
		||||
| `category` | Logical grouping (scanner, policy, runtime, evidence). |
 | 
			
		||||
| `details` | JSON payload describing the event; contract defined per producer. |
 | 
			
		||||
| `trace_id` | Optional distributed trace correlation ID. |
 | 
			
		||||
 | 
			
		||||
Events are stored append-only with tenant-specific partitions. Producers include Scanner WebService, Policy Engine, Zastava Observer, Evidence Locker, and Notify.
 | 
			
		||||
 | 
			
		||||
## 2. APIs
 | 
			
		||||
 | 
			
		||||
- `GET /api/v1/timeline/events` – paginated event stream with filters (tenant, category, time window, correlation IDs).
 | 
			
		||||
- `GET /api/v1/timeline/events/{id}` – fetch single event payload.
 | 
			
		||||
- `GET /api/v1/timeline/export` – NDJSON export for offline review.
 | 
			
		||||
 | 
			
		||||
## 3. Query Tips
 | 
			
		||||
 | 
			
		||||
- Use `category` + `trace_id` to follow a scan-to-policy-to-notification flow.
 | 
			
		||||
- Combine `tenant` and `timestamp` filters for SLA audits.
 | 
			
		||||
- CLI command `stella timeline list` mirrors the API for automation.
 | 
			
		||||
 | 
			
		||||
## 4. Integration
 | 
			
		||||
 | 
			
		||||
- Evidence Locker attaches evidence bundle digests; the console links from timeline to evidence viewer.
 | 
			
		||||
- Notifier creates acknowledgement events for incident workflows.
 | 
			
		||||
- Offline kits package timeline exports for compliance reviews.
 | 
			
		||||
 | 
			
		||||
## 5. References
 | 
			
		||||
 | 
			
		||||
- `docs/modules/telemetry/architecture.md`
 | 
			
		||||
- `docs/modules/zastava/architecture.md`
 | 
			
		||||
- `docs/modules/export-center/architecture.md`
 | 
			
		||||
- `src/TimelineIndexer/StellaOps.TimelineIndexer`
 | 
			
		||||
		Reference in New Issue
	
	Block a user