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

audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories

Browse Source
This commit is contained in:
master
2026-01-07 18:49:59 +02:00
parent 04ec098046
commit 608a7f85c0
866 changed files with 56323 additions and 6231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
CLAUDE.md
View File

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview
StellaOps is a self-hostable, sovereign container-security platform released under AGPL-3.0-or-later. It provides reproducible vulnerability scanning with VEX-first decisioning, SBOM generation (SPDX 3.0.1 and CycloneDX 1.7), in-toto/DSSE attestations, and optional Sigstore Rekor transparency. The platform is designed for offline/air-gapped operation with regional crypto support (eIDAS/FIPS/GOST/SM).
StellaOps is a self-hostable, sovereign container-security platform released under AGPL-3.0-or-later. It provides reproducible vulnerability scanning with VEX-first decisioning, SBOM generation (SPDX 2.2/2.3 and CycloneDX 1.7; SPDX 3.0.1 planned), in-toto/DSSE attestations, and optional Sigstore Rekor transparency. The platform is designed for offline/air-gapped operation with regional crypto support (eIDAS/FIPS/GOST/SM).
## Build Commands
@@ -606,6 +606,71 @@ var createdAt = reader.GetDateTime(reader.GetOrdinal("created_at"));
var createdAt = reader.GetFieldValue<DateTimeOffset>(reader.GetOrdinal("created_at"));
```
### 8.19) Hybrid Logical Clock (HLC) Usage
| Rule | Guidance |
|------|----------|
| **Use IHybridLogicalClock for ordering** | For distributed ordering and audit-safe sequencing, use `IHybridLogicalClock` from `StellaOps.HybridLogicalClock`. Never rely on wall-clock time alone for ordering in distributed scenarios. |
```csharp
// BAD - wall-clock ordering in distributed system
public async Task EnqueueAsync(Job job)
{
job.EnqueuedAt = DateTimeOffset.UtcNow; // Clock skew risk!
await _store.SaveAsync(job);
}
// GOOD - HLC ordering
public async Task EnqueueAsync(Job job, CancellationToken ct)
{
job.THlc = _hlc.Tick(); // Monotonic, skew-tolerant
job.EnqueuedAtWall = _timeProvider.GetUtcNow(); // Informational only
await _store.SaveAsync(job, ct);
}
```
| Rule | Guidance |
|------|----------|
| **Deterministic event IDs** | Generate event IDs deterministically from content, not randomly. Use `SHA-256(correlationId \|\| tHlc \|\| service \|\| kind)` for timeline events. This ensures replay produces identical IDs. |
```csharp
// BAD - random ID breaks replay determinism
var eventId = Guid.NewGuid().ToString();
// GOOD - deterministic ID from content
var eventId = EventIdGenerator.Generate(correlationId, tHlc, service, kind);
// Returns: SHA-256(inputs)[0:32] as hex
```
| Rule | Guidance |
|------|----------|
| **HLC state persistence** | Persist HLC state on graceful shutdown via `IHlcStateStore`. On startup, call `InitializeFromStateAsync()` to restore monotonicity. This prevents HLC regression after restarts. |
```csharp
// Service startup
public async Task StartAsync(CancellationToken ct)
{
await _hlc.InitializeFromStateAsync(ct);
// HLC will now be >= last persisted value
}
// Service shutdown
public async Task StopAsync(CancellationToken ct)
{
await _hlc.PersistStateAsync(ct);
}
```
| Rule | Guidance |
|------|----------|
| **HLC in event envelopes** | Timeline events must include both `tHlc` (ordering) and `tsWall` (debugging). Use `HlcTimestamp.ToSortableString()` for string representation. Never parse HLC from user input without validation. |
| Rule | Guidance |
|------|----------|
| **Clock skew handling** | Configure reasonable `MaxClockSkew` tolerance (default: 5 seconds). Events with excessive skew throw `HlcClockSkewException`. Monitor `hlc_clock_skew_rejections_total` metric. |
**Reference:** See `docs/modules/eventing/event-envelope-schema.md` for the canonical event envelope specification.
### Documentation Updates
When scope, contracts, or workflows change, update the relevant docs under: