127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# component_architecture_aoc.md - **Stella Ops AOC** (2025Q4)
|
|
|
|
> Append-Only Contract enforcement via Roslyn analyzers.
|
|
|
|
> **Scope.** Library architecture for **AOC** (Append-Only Contracts): Roslyn-based code analyzers that enforce data integrity rules during vulnerability ingestion.
|
|
|
|
---
|
|
|
|
## 0) Mission & boundaries
|
|
|
|
**Mission.** Enforce **append-only contract rules** during data ingestion. Prevent connectors from writing to fields that should only be computed by downstream merge/decisioning pipelines (severity, CVSS, effective status, risk scores).
|
|
|
|
**Boundaries.**
|
|
|
|
* AOC provides **compile-time enforcement** via Roslyn analyzers.
|
|
* AOC analyzers run on **ingestion code** (Connectors, Ingestion assemblies).
|
|
* AOC **does not** run on merge/decisioning code (those are allowed to write derived fields).
|
|
|
|
---
|
|
|
|
## 1) Solution & project layout
|
|
|
|
```
|
|
src/Aoc/
|
|
├─ __Analyzers/
|
|
│ └─ StellaOps.Aoc.Analyzers/ # Roslyn DiagnosticAnalyzers
|
|
│ ├─ AocForbiddenFieldAnalyzer.cs # Main analyzer
|
|
│ └─ ...
|
|
│
|
|
├─ __Libraries/
|
|
│ ├─ StellaOps.Aoc/ # Core abstractions (IAocGuard, etc.)
|
|
│ └─ StellaOps.Aoc.AspNetCore/ # ASP.NET Core integration
|
|
│
|
|
├─ StellaOps.Aoc.Cli/ # CLI for manual validation
|
|
│
|
|
└─ __Tests/
|
|
├─ StellaOps.Aoc.Analyzers.Tests/
|
|
├─ StellaOps.Aoc.AspNetCore.Tests/
|
|
└─ StellaOps.Aoc.Tests/
|
|
```
|
|
|
|
---
|
|
|
|
## 2) Core concept
|
|
|
|
### 2.1 Forbidden Fields
|
|
|
|
During ingestion, the following fields are **forbidden** (computed by decisioning pipeline):
|
|
|
|
| Field | Reason |
|
|
|-------|--------|
|
|
| `severity` | Computed from CVSS + context |
|
|
| `cvss` | Normalized from multiple sources |
|
|
| `cvss_vector` | Parsed/validated post-merge |
|
|
| `effective_status` | VEX consensus outcome |
|
|
| `effective_range` | Merged affected ranges |
|
|
| `merged_from` | Provenance tracking |
|
|
| `consensus_provider` | VEX provider selection |
|
|
| `reachability` | Runtime analysis result |
|
|
| `asset_criticality` | Policy engine computation |
|
|
| `risk_score` | Final risk calculation |
|
|
|
|
### 2.2 Derived Fields
|
|
|
|
Any field prefixed with `effective_` is treated as derived and forbidden in ingestion context.
|
|
|
|
---
|
|
|
|
## 3) Diagnostic Rules
|
|
|
|
| ID | Severity | Description |
|
|
|----|----------|-------------|
|
|
| `AOC0001` | Error | Forbidden field write detected |
|
|
| `AOC0002` | Error | Derived field (effective_*) write detected |
|
|
| `AOC0003` | Warning | Unguarded database write without IAocGuard validation |
|
|
|
|
---
|
|
|
|
## 4) Usage
|
|
|
|
### 4.1 Analyzer Reference
|
|
|
|
Add analyzer reference to connector projects:
|
|
|
|
```xml
|
|
<ItemGroup>
|
|
<PackageReference Include="StellaOps.Aoc.Analyzers" PrivateAssets="all" />
|
|
</ItemGroup>
|
|
```
|
|
|
|
### 4.2 Guard Usage
|
|
|
|
Wrap database writes with AOC guard:
|
|
|
|
```csharp
|
|
public class MyConnector
|
|
{
|
|
private readonly IAocGuard _aocGuard;
|
|
|
|
public async Task IngestAsync(Advisory advisory, CancellationToken ct)
|
|
{
|
|
// Guard validates no forbidden fields are written
|
|
await _aocGuard.ValidateAsync(advisory, ct);
|
|
await _repository.InsertAsync(advisory, ct);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5) Configuration
|
|
|
|
AOC analyzers activate based on assembly/namespace patterns:
|
|
|
|
- `*.Connector.*` assemblies
|
|
- `*.Ingestion` assemblies
|
|
- `*.Connector` assemblies
|
|
- Namespaces containing `.Connector.` or `.Ingestion`
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
* Concelier: `../concelier/architecture.md` (uses AOC for connectors)
|
|
* Excititor: `../excititor/architecture.md` (uses AOC for VEX ingestion)
|
|
* Determinism: `../../telemetry/` (AOC ensures deterministic merge inputs)
|