Fix build and code structure improvements. New but essential UI functionality. CI improvements. Documentation improvements. AI module improvements.
This commit is contained in:
StellaOps Bot
37
docs/modules/aoc/README.md
Normal file
37
docs/modules/aoc/README.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# AOC (Append-Only Contracts)
|
||||
|
||||
**Status:** Implemented
|
||||
**Source:** `src/Aoc/`
|
||||
**Owner:** Platform Team
|
||||
|
||||
## Purpose
|
||||
|
||||
AOC provides compile-time enforcement of append-only contract rules during data ingestion. Uses Roslyn analyzers to prevent connectors from writing to fields that should only be computed by downstream merge/decisioning pipelines.
|
||||
|
||||
## Components
|
||||
|
||||
**Analyzers:**
|
||||
- `StellaOps.Aoc.Analyzers` - Roslyn DiagnosticAnalyzers (AOC0001, AOC0002, AOC0003)
|
||||
|
||||
**Libraries:**
|
||||
- `StellaOps.Aoc` - Core abstractions (IAocGuard)
|
||||
- `StellaOps.Aoc.AspNetCore` - ASP.NET Core integration
|
||||
|
||||
**CLI:**
|
||||
- `StellaOps.Aoc.Cli` - Manual validation tool
|
||||
|
||||
## Key Concepts
|
||||
|
||||
**Forbidden Fields** (ingestion-time writes forbidden):
|
||||
- `severity`, `cvss`, `cvss_vector` - Computed from CVSS + context
|
||||
- `effective_status`, `effective_range` - VEX consensus outcomes
|
||||
- `risk_score`, `reachability`, `asset_criticality` - Runtime analysis
|
||||
|
||||
**Derived Fields:**
|
||||
- Any field prefixed with `effective_*` is treated as derived and forbidden
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- Architecture: `./architecture.md`
|
||||
- Concelier: `../concelier/` (uses AOC for connectors)
|
||||
- Excititor: `../excititor/` (uses AOC for VEX ingestion)
|
||||
126
docs/modules/aoc/architecture.md
Normal file
126
docs/modules/aoc/architecture.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user