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
144
src/__Libraries/StellaOps.Verdict/AGENTS.md
Normal file
144
src/__Libraries/StellaOps.Verdict/AGENTS.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# AGENTS.md — StellaOps.Verdict Module
|
||||
|
||||
## Overview
|
||||
|
||||
The StellaOps.Verdict module provides a **unified StellaVerdict artifact** that consolidates vulnerability disposition decisions into a single, signed, portable proof. It combines PolicyVerdict, ProofBundle, and KnowledgeSnapshot into a content-addressable artifact with JSON-LD support.
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
src/__Libraries/StellaOps.Verdict/
|
||||
├── Schema/
|
||||
│ └── StellaVerdict.cs # Core verdict schema and supporting types
|
||||
├── Contexts/
|
||||
│ └── verdict-1.0.jsonld # JSON-LD context for standards interop
|
||||
├── Services/
|
||||
│ ├── VerdictAssemblyService.cs # Assembles verdicts from components
|
||||
│ ├── VerdictSigningService.cs # DSSE signing integration
|
||||
│ └── IVerdictAssemblyService.cs
|
||||
├── Persistence/
|
||||
│ ├── PostgresVerdictStore.cs # PostgreSQL storage implementation
|
||||
│ ├── IVerdictStore.cs # Storage interface
|
||||
│ ├── VerdictRow.cs # EF Core entity
|
||||
│ └── Migrations/
|
||||
│ └── 001_create_verdicts.sql
|
||||
├── Api/
|
||||
│ ├── VerdictEndpoints.cs # REST API endpoints
|
||||
│ └── VerdictContracts.cs # Request/response DTOs
|
||||
├── Oci/
|
||||
│ └── OciAttestationPublisher.cs # OCI registry attestation
|
||||
├── Export/
|
||||
│ └── VerdictBundleExporter.cs # Replay bundle export
|
||||
└── StellaOps.Verdict.csproj
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### StellaVerdict Schema
|
||||
The core `StellaVerdict` record contains:
|
||||
- `VerdictId`: Content-addressable ID (`urn:stella:verdict:sha256:...`)
|
||||
- `Subject`: Vulnerability ID + Component PURL
|
||||
- `Claim`: Status, confidence, reason
|
||||
- `Inputs`: Advisory sources, VEX, CVSS, EPSS, KEV, reachability
|
||||
- `EvidenceGraph`: Proof nodes and edges from ProofBundle
|
||||
- `PolicyPath`: Rule evaluation trace
|
||||
- `Result`: Disposition, score, expiration
|
||||
- `Provenance`: Generator, run ID, timestamp
|
||||
- `Signatures`: DSSE signatures
|
||||
|
||||
### Verdict Status Values
|
||||
- `Pass`: Component passed all policy checks
|
||||
- `Blocked`: Component blocked by policy
|
||||
- `Ignored`: Finding ignored per policy
|
||||
- `Warned`: Warning issued but not blocking
|
||||
- `Deferred`: Decision deferred for manual review
|
||||
- `Escalated`: Escalated for security team
|
||||
- `RequiresVex`: Needs VEX statement to resolve
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Assembling a Verdict
|
||||
```csharp
|
||||
var context = new VerdictAssemblyContext
|
||||
{
|
||||
VulnerabilityId = "CVE-2024-1234",
|
||||
Purl = "pkg:npm/lodash@4.17.15",
|
||||
PolicyVerdict = policyResult,
|
||||
Knowledge = knowledgeInputs,
|
||||
Generator = "StellaOps Scanner",
|
||||
RunId = scanId
|
||||
};
|
||||
|
||||
var verdict = assemblyService.AssembleVerdict(context);
|
||||
```
|
||||
|
||||
### Storing and Querying
|
||||
```csharp
|
||||
await store.StoreAsync(verdict, tenantId, cancellationToken);
|
||||
|
||||
var query = new VerdictQuery { Purl = "pkg:npm/lodash@*", Status = VerdictStatus.Blocked };
|
||||
var results = await store.QueryAsync(query, cancellationToken);
|
||||
```
|
||||
|
||||
### CLI Verification
|
||||
```bash
|
||||
# Verify by ID (fetches from API)
|
||||
stella verify verdict --verdict urn:stella:verdict:sha256:abc123
|
||||
|
||||
# Verify from file with replay bundle
|
||||
stella verify verdict --verdict ./verdict.json --replay ./bundle/
|
||||
|
||||
# Show full policy trace
|
||||
stella verify verdict --verdict ./verdict.json --show-trace
|
||||
```
|
||||
|
||||
### OCI Attestation
|
||||
```csharp
|
||||
var result = await publisher.PublishAsync(verdict, "registry.io/app:latest@sha256:...");
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/v1/verdicts` | POST | Create and store verdict |
|
||||
| `/v1/verdicts/{id}` | GET | Get verdict by ID |
|
||||
| `/v1/verdicts` | GET | Query verdicts (purl, cve, status) |
|
||||
| `/v1/verdicts/{id}/verify` | POST | Verify signature and content ID |
|
||||
| `/v1/verdicts/{id}/download` | GET | Download as JSON-LD |
|
||||
| `/v1/verdicts/latest` | GET | Get latest for purl+cve |
|
||||
| `/v1/verdicts/expired` | DELETE | Clean up expired verdicts |
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `StellaOps.Policy`: PolicyVerdict, PolicyExplanation
|
||||
- `StellaOps.Attestor.Envelope`: DSSE signing
|
||||
- `StellaOps.Cryptography`: BLAKE3/SHA256 hashing
|
||||
- `StellaOps.Replay.Core`: Bundle structures
|
||||
|
||||
## Testing
|
||||
|
||||
Unit tests should cover:
|
||||
- Schema serialization determinism (sorted keys)
|
||||
- Content-addressable ID computation
|
||||
- Assembly from various input combinations
|
||||
- Signature verification
|
||||
- Query filtering and pagination
|
||||
|
||||
Integration tests should cover:
|
||||
- Full assembly → sign → store → query → verify flow
|
||||
- OCI publish/fetch cycle
|
||||
- Replay bundle export and verification
|
||||
|
||||
## Coding Guidelines
|
||||
|
||||
1. **Determinism**: All JSON output must be deterministic (sorted keys, stable ordering)
|
||||
2. **Content Addressing**: VerdictId must match `ComputeVerdictId()` output
|
||||
3. **Immutability**: Use records with `init` properties
|
||||
4. **Tenant Isolation**: All store operations must include tenantId
|
||||
5. **Offline Support**: OCI publisher and CLI must handle offline mode
|
||||
|
||||
## Related Sprints
|
||||
|
||||
- SPRINT_1227_0014_0001: StellaVerdict Unified Artifact Consolidation
|
||||
- SPRINT_1227_0014_0002: Verdict UI Components (pending)
|
||||
Reference in New Issue
Block a user