Add signal contracts for reachability, exploitability, trust, and unknown symbols
- 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:
82
src/__Libraries/StellaOps.Signals.Contracts/AGENTS.md
Normal file
82
src/__Libraries/StellaOps.Signals.Contracts/AGENTS.md
Normal 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)
|
||||
Reference in New Issue
Block a user