Add signal contracts for reachability, exploitability, trust, and unknown symbols
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals DSSE Sign & Evidence Locker / sign-signals-artifacts (push) Has been cancelled
Signals DSSE Sign & Evidence Locker / verify-signatures (push) Has been cancelled

- Introduced `ReachabilityState`, `RuntimeHit`, `ExploitabilitySignal`, `ReachabilitySignal`, `SignalEnvelope`, `SignalType`, `TrustSignal`, and `UnknownSymbolSignal` records to define various signal types and their properties.
- Implemented JSON serialization attributes for proper data interchange.
- Created project files for the new signal contracts library and corresponding test projects.
- Added deterministic test fixtures for micro-interaction testing.
- Included cryptographic keys for secure operations with cosign.
This commit is contained in:
StellaOps Bot
2025-12-05 00:27:00 +02:00
parent b018949a8d
commit 8768c27f30
192 changed files with 27569 additions and 2552 deletions

View File

@@ -0,0 +1,82 @@
# StellaOps.Signals.Contracts
Shared signal contracts for cross-module signal communication in StellaOps.
## Purpose
This library provides the common contracts (interfaces and DTOs) for signal-based communication between StellaOps modules. It enables:
- **Concelier** to emit reachability and trust signals
- **Scanner** to emit entropy and unknown symbol signals
- **Policy Engine** to consume all signal types for risk scoring
- **Signals service** to aggregate and cache signals
- **Authority** to emit trust/provenance signals
## Signal Types
| Type | Producer | Description |
|------|----------|-------------|
| `Reachability` | Concelier, Scanner | Whether vulnerable code paths are reachable |
| `Entropy` | Scanner | Code complexity and risk metrics |
| `Exploitability` | Concelier | KEV status, EPSS scores, exploit availability |
| `Trust` | Authority, Scanner | Publisher reputation, provenance, signatures |
| `UnknownSymbol` | Scanner | Unresolved dependencies during analysis |
| `Custom` | Any | Extension point for module-specific signals |
## Usage
### Emitting Signals
```csharp
public class MySignalProducer
{
private readonly ISignalEmitter _emitter;
private readonly ISignalContext _context;
public async Task EmitReachabilityAsync(string purl, bool isReachable)
{
var signal = new ReachabilitySignal
{
Purl = purl,
IsReachable = isReachable,
Confidence = 0.95
};
var envelope = _context.CreateReachabilityEnvelope(purl, signal);
await _emitter.EmitAsync(envelope);
}
}
```
### Consuming Signals
```csharp
public class MySignalConsumer
{
private readonly ISignalConsumer _consumer;
public async Task ProcessSignalsAsync(CancellationToken ct)
{
await foreach (var signal in _consumer.ConsumeAsync(SignalType.Reachability, ct))
{
// Process signal
}
}
}
```
## Dependencies
- `Microsoft.Extensions.DependencyInjection.Abstractions` — DI registration helpers
## Implementation Notes
This library contains only contracts. Actual transport implementations are provided by:
- `StellaOps.Signals.Nats` — NATS JetStream transport
- `StellaOps.Signals.InMemory` — In-memory transport for testing
## Related
- [Signal Flow Architecture](../../docs/modules/signals/architecture.md)
- [Policy Engine Signals Integration](../../docs/modules/policy/signals.md)