feat: Add guild charters and task boards for various components
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:
2025-11-01 02:21:46 +02:00
parent e5629454cf
commit 66cb6c4b8a
227 changed files with 9913 additions and 6210 deletions

View 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`

View 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`