up
This commit is contained in:
StellaOps Bot
@@ -17,7 +17,7 @@ completely isolated network:
|
||||
| **Provenance** | Cosign signature, SPDX 2.3 SBOM, in‑toto SLSA attestation |
|
||||
| **Attested manifest** | `offline-manifest.json` + detached JWS covering bundle metadata, signed during export. |
|
||||
| **Delta patches** | Daily diff bundles keep size \< 350 MB |
|
||||
| **Scanner plug-ins** | OS analyzers plus the Node.js, Go, .NET, Python, Ruby, and Rust language analyzers packaged under `plugins/scanner/analyzers/**` with manifests so Workers load deterministically offline. |
|
||||
| **Scanner plug-ins** | OS analyzers plus the Node.js, Go, .NET, Python, Ruby, Rust, and PHP language analyzers packaged under `plugins/scanner/analyzers/**` with manifests so Workers load deterministically offline. |
|
||||
| **Debug store** | `.debug` artefacts laid out under `debug/.build-id/<aa>/<rest>.debug` with `debug/debug-manifest.json` mapping build-ids to originating images for symbol retrieval. |
|
||||
| **Telemetry collector bundle** | `telemetry/telemetry-offline-bundle.tar.gz` plus `.sha256`, containing OTLP collector config, Helm/Compose overlays, and operator instructions. |
|
||||
| **CLI + Task Packs** | `cli/` binaries from `release/cli`, Task Runner bootstrap (`bootstrap/task-runner/task-runner.yaml.sample`), and task-pack docs under `docs/task-packs/**` + `docs/modules/taskrunner/**`. |
|
||||
@@ -27,7 +27,19 @@ completely isolated network:
|
||||
|
||||
**RU BDU note:** ship the official Russian Trusted Root/Sub CA bundle (`certificates/russian_trusted_bundle.pem`) inside the kit so `concelier:httpClients:source.bdu:trustedRootPaths` can resolve it when the service runs in an air‑gapped network. Drop the most recent `vulxml.zip` alongside the kit if operators need a cold-start cache.
|
||||
|
||||
**Language analyzers:** the kit now carries the restart-only Node.js, Go, .NET, Python, Ruby, and Rust plug-ins (`plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Node/`, `...Lang.Go/`, `...Lang.DotNet/`, `...Lang.Python/`, `...Lang.Ruby/`, `...Lang.Rust/`). Drop the directories alongside Worker binaries so the unified plug-in catalog can load them without outbound fetches. The Ruby analyzer includes optional runtime capture via TracePoint; set `STELLA_RUBY_ENTRYPOINT` to enable runtime evidence collection.
|
||||
**Language analyzers:** the kit now carries the restart-only Node.js, Go, .NET, Python, Ruby, Rust, and PHP plug-ins (`plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Node/`, `...Lang.Go/`, `...Lang.DotNet/`, `...Lang.Python/`, `...Lang.Ruby/`, `...Lang.Rust/`, `...Lang.Php/`). Drop the directories alongside Worker binaries so the unified plug-in catalog can load them without outbound fetches.
|
||||
|
||||
**Ruby analyzer features:**
|
||||
- **Gemfile/Gemfile.lock** parsing with dependency edges (version constraints, PURLs)
|
||||
- **OCI container layer** support (`layers/`, `.layers/`, `layer/`) for VFS/container workspace discovery
|
||||
- **Ruby version detection** via `.ruby-version`, `.tool-versions`, Gemfile `ruby` directive, and binary paths
|
||||
- **Native extension detection** for `.so`, `.bundle`, `.dll` files in gem paths
|
||||
- **Web server config parsing** for Puma, Unicorn, and Passenger configurations
|
||||
- **AOC-compliant observations**: entrypoints (script/rack/rackup), dependency edges, runtime edges, jobs, configs, warnings
|
||||
- **Optional runtime evidence** via TracePoint; set `STELLA_RUBY_ENTRYPOINT` to enable runtime capture with SHA-256 path hashing for secure evidence correlation
|
||||
- **CLI inspection**: run `stella ruby inspect --root /path/to/app` to analyze a Ruby workspace locally
|
||||
|
||||
The PHP analyzer parses `composer.lock` for Composer dependencies and supports optional runtime evidence via the `stella-trace.php` shim; set `STELLA_PHP_OPCACHE=1` to enable opcache statistics collection.
|
||||
|
||||
**Advisory AI volume primer:** ship a tarball containing empty `queue/`, `plans/`, and `outputs/` directories plus their ownership metadata. During import, extract it onto the RWX volume used by `advisory-ai-web` and `advisory-ai-worker` so pods start with the expected directory tree even on air-gapped nodes.
|
||||
|
||||
@@ -276,12 +288,12 @@ Authority now rejects tokens that request `advisory:read`, `vex:read`, or any `s
|
||||
**Quick smoke test:** before import, verify the tarball carries the Go analyzer plug-in:
|
||||
|
||||
```bash
|
||||
tar -tzf stella-ops-offline-kit-<DATE>.tgz 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Go/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.DotNet/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Python/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Ruby/*'
|
||||
tar -tzf stella-ops-offline-kit-<DATE>.tgz 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Go/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.DotNet/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Python/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Ruby/*' 'plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Php/*'
|
||||
```
|
||||
|
||||
The manifest lookup above and this `tar` listing should both surface the Go analyzer DLL, PDB, and manifest entries before the kit is promoted.
|
||||
|
||||
> **Release guardrail.** The automated release pipeline now publishes the Python, Ruby, and Rust plug-ins from source and executes `dotnet run --project src/Tools/LanguageAnalyzerSmoke --configuration Release -- --repo-root <checkout> --analyzer <id>` to validate manifest integrity and cold/warm determinism within the < 30 s / < 5 s budgets (differences versus repository goldens are logged for triage). Run `ops/offline-kit/run-python-analyzer-smoke.sh` and `ops/offline-kit/run-ruby-analyzer-smoke.sh`, and `ops/offline-kit/run-rust-analyzer-smoke.sh` locally before shipping a refreshed kit if you rebuild artefacts outside CI or when preparing the air-gap bundle.
|
||||
> **Release guardrail.** The automated release pipeline now publishes the Python, Ruby, Rust, and PHP plug-ins from source and executes `dotnet run --project src/Tools/LanguageAnalyzerSmoke --configuration Release -- --repo-root <checkout> --analyzer <id>` to validate manifest integrity and cold/warm determinism within the < 30 s / < 5 s budgets (differences versus repository goldens are logged for triage). Run `ops/offline-kit/run-python-analyzer-smoke.sh`, `ops/offline-kit/run-ruby-analyzer-smoke.sh`, `ops/offline-kit/run-rust-analyzer-smoke.sh`, and `ops/offline-kit/run-php-analyzer-smoke.sh` locally before shipping a refreshed kit if you rebuild artefacts outside CI or when preparing the air-gap bundle.
|
||||
|
||||
### Debug store mirror
|
||||
|
||||
|
||||
154
docs/airgap/vex-raw-migration-rollback.md
Normal file
154
docs/airgap/vex-raw-migration-rollback.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# VEX Raw Migration Rollback Guide
|
||||
|
||||
This document describes how to rollback migrations applied to the `vex_raw` collection.
|
||||
|
||||
## Migration: 20251127-vex-raw-idempotency-indexes
|
||||
|
||||
### Description
|
||||
Adds unique idempotency indexes to enforce content-addressed storage:
|
||||
- `idx_provider_sourceUri_digest_unique`: Prevents duplicate documents from same provider/source
|
||||
- `idx_digest_providerId`: Optimizes evidence queries by digest
|
||||
- `idx_retrievedAt`: Supports time-based queries and future TTL operations
|
||||
|
||||
### Rollback Steps
|
||||
|
||||
#### Option 1: MongoDB Shell
|
||||
|
||||
```javascript
|
||||
// Connect to your MongoDB instance
|
||||
mongosh "mongodb://localhost:27017/excititor"
|
||||
|
||||
// Drop the idempotency indexes
|
||||
db.vex_raw.dropIndex("idx_provider_sourceUri_digest_unique")
|
||||
db.vex_raw.dropIndex("idx_digest_providerId")
|
||||
db.vex_raw.dropIndex("idx_retrievedAt")
|
||||
|
||||
// Verify indexes are dropped
|
||||
db.vex_raw.getIndexes()
|
||||
```
|
||||
|
||||
#### Option 2: Programmatic Rollback (C#)
|
||||
|
||||
```csharp
|
||||
using StellaOps.Excititor.Storage.Mongo.Migrations;
|
||||
|
||||
// Get the database instance
|
||||
var database = client.GetDatabase("excititor");
|
||||
|
||||
// Execute rollback
|
||||
await database.RollbackIdempotencyIndexesAsync(cancellationToken);
|
||||
|
||||
// Verify rollback
|
||||
var verified = await database.VerifyIdempotencyIndexesExistAsync(cancellationToken);
|
||||
Console.WriteLine($"Indexes exist after rollback: {verified}"); // Should be false
|
||||
```
|
||||
|
||||
#### Option 3: MongoDB Compass
|
||||
|
||||
1. Connect to your MongoDB instance
|
||||
2. Navigate to the `excititor` database
|
||||
3. Select the `vex_raw` collection
|
||||
4. Go to the "Indexes" tab
|
||||
5. Click "Drop Index" for each of:
|
||||
- `idx_provider_sourceUri_digest_unique`
|
||||
- `idx_digest_providerId`
|
||||
- `idx_retrievedAt`
|
||||
|
||||
### Impact of Rollback
|
||||
|
||||
**Before rollback (indexes present):**
|
||||
- Documents are prevented from being duplicated
|
||||
- Evidence queries are optimized
|
||||
- Unique constraint enforced
|
||||
|
||||
**After rollback (indexes dropped):**
|
||||
- Duplicate documents may be inserted
|
||||
- Evidence queries may be slower
|
||||
- No unique constraint enforcement
|
||||
|
||||
### Re-applying the Migration
|
||||
|
||||
To re-apply the migration after rollback:
|
||||
|
||||
```javascript
|
||||
// MongoDB shell
|
||||
db.vex_raw.createIndex(
|
||||
{ "providerId": 1, "sourceUri": 1, "digest": 1 },
|
||||
{ unique: true, name: "idx_provider_sourceUri_digest_unique", background: true }
|
||||
)
|
||||
|
||||
db.vex_raw.createIndex(
|
||||
{ "digest": 1, "providerId": 1 },
|
||||
{ name: "idx_digest_providerId", background: true }
|
||||
)
|
||||
|
||||
db.vex_raw.createIndex(
|
||||
{ "retrievedAt": 1 },
|
||||
{ name: "idx_retrievedAt", background: true }
|
||||
)
|
||||
```
|
||||
|
||||
Or run the migration runner:
|
||||
|
||||
```bash
|
||||
stellaops excititor migrate --run 20251127-vex-raw-idempotency-indexes
|
||||
```
|
||||
|
||||
## Migration: 20251125-vex-raw-json-schema
|
||||
|
||||
### Description
|
||||
Adds a JSON Schema validator to the `vex_raw` collection with `validationAction: warn`.
|
||||
|
||||
### Rollback Steps
|
||||
|
||||
```javascript
|
||||
// MongoDB shell - remove the validator
|
||||
db.runCommand({
|
||||
collMod: "vex_raw",
|
||||
validator: {},
|
||||
validationAction: "off",
|
||||
validationLevel: "off"
|
||||
})
|
||||
|
||||
// Verify validator is removed
|
||||
db.getCollectionInfos({ name: "vex_raw" })[0].options
|
||||
```
|
||||
|
||||
### Impact of Rollback
|
||||
|
||||
- Documents will no longer be validated against the schema
|
||||
- Invalid documents may be inserted
|
||||
- Existing documents are not affected
|
||||
|
||||
## General Rollback Guidelines
|
||||
|
||||
1. **Always backup first**: Create a backup before any rollback operation
|
||||
2. **Test in staging**: Verify rollback procedure in a non-production environment
|
||||
3. **Monitor performance**: Watch for query performance changes after rollback
|
||||
4. **Document changes**: Log all rollback operations for audit purposes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Index Drop Fails
|
||||
|
||||
If you see "IndexNotFound" errors, the index may have already been dropped or was never created:
|
||||
|
||||
```javascript
|
||||
// Check existing indexes
|
||||
db.vex_raw.getIndexes()
|
||||
```
|
||||
|
||||
### Validator Removal Fails
|
||||
|
||||
If the validator command fails, verify you have the correct permissions:
|
||||
|
||||
```javascript
|
||||
// Check current user roles
|
||||
db.runCommand({ usersInfo: 1 })
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [VEX Raw Schema Validation](vex-raw-schema-validation.md)
|
||||
- [MongoDB Index Management](https://www.mongodb.com/docs/manual/indexes/)
|
||||
- [Excititor Architecture](../modules/excititor/architecture.md)
|
||||
197
docs/airgap/vex-raw-schema-validation.md
Normal file
197
docs/airgap/vex-raw-schema-validation.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# VEX Raw Schema Validation - Offline Kit
|
||||
|
||||
This document describes how operators can validate the integrity of VEX raw evidence stored in MongoDB, ensuring that Excititor stores only immutable, content-addressed documents.
|
||||
|
||||
## Overview
|
||||
|
||||
The `vex_raw` collection stores raw VEX documents with content-addressed storage (documents are keyed by their cryptographic hash). This ensures immutability - documents cannot be modified after insertion without changing their key.
|
||||
|
||||
## Schema Definition
|
||||
|
||||
The MongoDB JSON Schema enforces the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"$jsonSchema": {
|
||||
"bsonType": "object",
|
||||
"title": "VEX Raw Document Schema",
|
||||
"description": "Schema for immutable VEX evidence storage",
|
||||
"required": ["_id", "providerId", "format", "sourceUri", "retrievedAt", "digest"],
|
||||
"properties": {
|
||||
"_id": {
|
||||
"bsonType": "string",
|
||||
"description": "Content digest serving as immutable key"
|
||||
},
|
||||
"providerId": {
|
||||
"bsonType": "string",
|
||||
"minLength": 1,
|
||||
"description": "VEX provider identifier"
|
||||
},
|
||||
"format": {
|
||||
"bsonType": "string",
|
||||
"enum": ["csaf", "cyclonedx", "openvex"],
|
||||
"description": "VEX document format"
|
||||
},
|
||||
"sourceUri": {
|
||||
"bsonType": "string",
|
||||
"minLength": 1,
|
||||
"description": "Original source URI"
|
||||
},
|
||||
"retrievedAt": {
|
||||
"bsonType": "date",
|
||||
"description": "Timestamp when document was fetched"
|
||||
},
|
||||
"digest": {
|
||||
"bsonType": "string",
|
||||
"minLength": 32,
|
||||
"description": "Content hash (SHA-256 hex)"
|
||||
},
|
||||
"content": {
|
||||
"bsonType": ["binData", "string"],
|
||||
"description": "Raw document content"
|
||||
},
|
||||
"gridFsObjectId": {
|
||||
"bsonType": ["objectId", "null", "string"],
|
||||
"description": "GridFS reference for large documents"
|
||||
},
|
||||
"metadata": {
|
||||
"bsonType": "object",
|
||||
"description": "Provider-specific metadata"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Offline Validation Steps
|
||||
|
||||
### 1. Export the Schema
|
||||
|
||||
The schema can be exported from the application using the validator tooling:
|
||||
|
||||
```bash
|
||||
# Using the Excititor CLI
|
||||
stellaops excititor schema export --collection vex_raw --output vex-raw-schema.json
|
||||
|
||||
# Or via MongoDB shell
|
||||
mongosh --eval "db.getCollectionInfos({name: 'vex_raw'})[0].options.validator" > vex-raw-schema.json
|
||||
```
|
||||
|
||||
### 2. Validate Documents in MongoDB Shell
|
||||
|
||||
```javascript
|
||||
// Connect to your MongoDB instance
|
||||
mongosh "mongodb://localhost:27017/excititor"
|
||||
|
||||
// Get all documents that violate the schema
|
||||
db.runCommand({
|
||||
validate: "vex_raw",
|
||||
full: true
|
||||
})
|
||||
|
||||
// Or check individual documents
|
||||
db.vex_raw.find().forEach(function(doc) {
|
||||
var result = db.runCommand({
|
||||
validate: "vex_raw",
|
||||
documentId: doc._id
|
||||
});
|
||||
if (!result.valid) {
|
||||
print("Invalid: " + doc._id);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Programmatic Validation (C#)
|
||||
|
||||
```csharp
|
||||
using StellaOps.Excititor.Storage.Mongo.Validation;
|
||||
|
||||
// Validate a single document
|
||||
var result = VexRawSchemaValidator.Validate(document);
|
||||
if (!result.IsValid)
|
||||
{
|
||||
foreach (var violation in result.Violations)
|
||||
{
|
||||
Console.WriteLine($"{violation.Field}: {violation.Message}");
|
||||
}
|
||||
}
|
||||
|
||||
// Batch validation
|
||||
var batchResult = VexRawSchemaValidator.ValidateBatch(documents);
|
||||
Console.WriteLine($"Valid: {batchResult.ValidCount}, Invalid: {batchResult.InvalidCount}");
|
||||
```
|
||||
|
||||
### 4. Export Schema for External Tools
|
||||
|
||||
```csharp
|
||||
// Get schema as JSON for external validation tools
|
||||
var schemaJson = VexRawSchemaValidator.GetJsonSchemaAsJson();
|
||||
File.WriteAllText("vex-raw-schema.json", schemaJson);
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Use this checklist to verify schema compliance:
|
||||
|
||||
- [ ] All documents have required fields (_id, providerId, format, sourceUri, retrievedAt, digest)
|
||||
- [ ] The `_id` matches the `digest` value (content-addressed)
|
||||
- [ ] Format is one of: csaf, cyclonedx, openvex
|
||||
- [ ] Digest is at least 32 characters (SHA-256 hex)
|
||||
- [ ] No documents have been modified after insertion (verify via digest recomputation)
|
||||
|
||||
## Immutability Verification
|
||||
|
||||
To verify documents haven't been tampered with:
|
||||
|
||||
```javascript
|
||||
// MongoDB shell - verify content matches digest
|
||||
db.vex_raw.find().forEach(function(doc) {
|
||||
var content = doc.content;
|
||||
if (content) {
|
||||
// Compute SHA-256 of content
|
||||
var computedDigest = hex_md5(content); // Use appropriate hash function
|
||||
if (computedDigest !== doc.digest) {
|
||||
print("TAMPERED: " + doc._id);
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Auditing
|
||||
|
||||
For compliance auditing, export a validation report:
|
||||
|
||||
```bash
|
||||
# Generate validation report
|
||||
stellaops excititor validate --collection vex_raw --report validation-report.json
|
||||
|
||||
# The report includes:
|
||||
# - Total document count
|
||||
# - Valid/invalid counts
|
||||
# - List of violations by document
|
||||
# - Schema version used for validation
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Violations
|
||||
|
||||
1. **Missing required field**: Ensure all required fields are present
|
||||
2. **Invalid format**: Format must be exactly "csaf", "cyclonedx", or "openvex"
|
||||
3. **Digest too short**: Digest must be at least 32 hex characters
|
||||
4. **Wrong type**: Check field types match schema requirements
|
||||
|
||||
### Recovery
|
||||
|
||||
If invalid documents are found:
|
||||
|
||||
1. Do NOT modify documents in place (violates immutability)
|
||||
2. Export the invalid documents for analysis
|
||||
3. Re-ingest from original sources with correct data
|
||||
4. Document the incident in audit logs
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Excititor Architecture](../modules/excititor/architecture.md)
|
||||
- [VEX Storage Design](../modules/excititor/storage.md)
|
||||
- [Offline Operation Guide](../24_OFFLINE_KIT.md)
|
||||
@@ -18,9 +18,9 @@
|
||||
| # | Task ID & handle | State | Key dependency / next step | Owners | Task Definition |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| P1 | PREP-POLICY-RISK-66-001-RISKPROFILE-LIBRARY-S | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Risk Profile Schema Guild / `src/Policy/StellaOps.Policy.RiskProfile` | Risk Profile Schema Guild / `src/Policy/StellaOps.Policy.RiskProfile` | RiskProfile library scaffold absent (`src/Policy/StellaOps.Policy.RiskProfile` contains only AGENTS.md); need project + storage contract to place schema/validators. <br><br> Document artefact/deliverable for POLICY-RISK-66-001 and publish location so downstream tasks can proceed. Prep artefact: `docs/modules/policy/prep/2025-11-20-riskprofile-66-001-prep.md`. |
|
||||
| 1 | POLICY-ENGINE-80-002 | TODO | Depends on 80-001. | Policy · Storage Guild / `src/Policy/StellaOps.Policy.Engine` | Join reachability facts + Redis caches. |
|
||||
| 2 | POLICY-ENGINE-80-003 | TODO | Depends on 80-002. | Policy · Policy Editor Guild / `src/Policy/StellaOps.Policy.Engine` | SPL predicates/actions reference reachability. |
|
||||
| 3 | POLICY-ENGINE-80-004 | TODO | Depends on 80-003. | Policy · Observability Guild / `src/Policy/StellaOps.Policy.Engine` | Metrics/traces for signals usage. |
|
||||
| 1 | POLICY-ENGINE-80-002 | DONE (2025-11-27) | — | Policy · Storage Guild / `src/Policy/StellaOps.Policy.Engine` | Join reachability facts + Redis caches. |
|
||||
| 2 | POLICY-ENGINE-80-003 | DONE (2025-11-27) | — | Policy · Policy Editor Guild / `src/Policy/StellaOps.Policy.Engine` | SPL predicates/actions reference reachability. |
|
||||
| 3 | POLICY-ENGINE-80-004 | DONE (2025-11-27) | — | Policy · Observability Guild / `src/Policy/StellaOps.Policy.Engine` | Metrics/traces for signals usage. |
|
||||
| 4 | POLICY-OBS-50-001 | DONE (2025-11-27) | — | Policy · Observability Guild / `src/Policy/StellaOps.Policy.Engine` | Telemetry core for API/worker hosts. |
|
||||
| 5 | POLICY-OBS-51-001 | DONE (2025-11-27) | Depends on 50-001. | Policy · DevOps Guild / `src/Policy/StellaOps.Policy.Engine` | Golden-signal metrics + SLOs. |
|
||||
| 6 | POLICY-OBS-52-001 | DONE (2025-11-27) | Depends on 51-001. | Policy Guild / `src/Policy/StellaOps.Policy.Engine` | Timeline events for evaluate/decision flows. |
|
||||
@@ -37,6 +37,9 @@
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-11-27 | `POLICY-ENGINE-80-002`: Created reachability facts joining layer in `ReachabilityFacts/` directory: `ReachabilityFactsModels.cs` (data models with state/confidence/score, ReachabilityState enum, ReachabilityFactKey), `ReachabilityFactsStore.cs` (IReachabilityFactsStore interface, InMemoryReachabilityFactsStore, MongoDB index definitions), `ReachabilityFactsOverlayCache.cs` (IReachabilityFactsOverlayCache interface, InMemoryReachabilityFactsOverlayCache with TTL eviction, ReachabilityFactsCacheOptions), `ReachabilityFactsJoiningService.cs` (batch lookup with cache-first strategy, signal enrichment, ReachabilityFactsTelemetry). Registered services in Program.cs DI. | Implementer |
|
||||
| 2025-11-27 | `POLICY-ENGINE-80-003`: Extended SPL predicates for reachability. Added `PolicyEvaluationReachability` record to `PolicyEvaluationContext.cs` with state/confidence/score/method/source properties and helper predicates (IsReachable, IsUnreachable, IsHighConfidence). Added `ReachabilityScope` to `PolicyExpressionEvaluator.cs` supporting SPL expressions like `reachability.state == "reachable"`, `reachability.confidence >= 0.8`, `reachability.is_high_confidence`. | Implementer |
|
||||
| 2025-11-27 | `POLICY-ENGINE-80-004`: Added reachability metrics to `PolicyEngineTelemetry.cs`: `policy_reachability_applied_total{state}`, `policy_reachability_cache_hits_total`, `policy_reachability_cache_misses_total`, `policy_reachability_cache_hit_ratio` (observable gauge), `policy_reachability_lookups_total{outcome}`, `policy_reachability_lookup_seconds`. Updated `ReachabilityFactsTelemetry` to delegate to centralized PolicyEngineTelemetry. | Implementer |
|
||||
| 2025-11-27 | `POLICY-RISK-67-001` (task 15): Created `Lifecycle/RiskProfileLifecycle.cs` with lifecycle models (RiskProfileLifecycleStatus enum: Draft/Active/Deprecated/Archived, RiskProfileVersionInfo, RiskProfileLifecycleEvent, RiskProfileVersionComparison, RiskProfileChange). Created `RiskProfileLifecycleService` with status transitions (CreateVersion, Activate, Deprecate, Archive, Restore), version management, event recording, and version comparison (detecting breaking changes in signals/inheritance). | Implementer |
|
||||
| 2025-11-27 | `POLICY-RISK-67-001`: Created `Scoring/RiskScoringModels.cs` with FindingChangedEvent, RiskScoringJobRequest, RiskScoringJob, RiskScoringResult models and enums. Created `IRiskScoringJobStore` interface and `InMemoryRiskScoringJobStore` for job persistence. Created `RiskScoringTriggerService` handling FindingChangedEvent triggers with deduplication, batch processing, priority calculation, and job creation. Added risk scoring metrics to PolicyEngineTelemetry (jobs_created, triggers_skipped, duration, findings_scored). Registered services in Program.cs DI. | Implementer |
|
||||
| 2025-11-27 | `POLICY-RISK-66-004`: Added RiskProfile project reference to StellaOps.Policy library. Created `IRiskProfileRepository` interface with GetAsync, GetVersionAsync, GetLatestAsync, ListProfileIdsAsync, ListVersionsAsync, SaveAsync, DeleteVersionAsync, DeleteAllVersionsAsync, ExistsAsync. Created `InMemoryRiskProfileRepository` for testing/development. Created `RiskProfileDiagnostics` with comprehensive validation (RISK001-RISK050 error codes) covering structure, signals, weights, overrides, and inheritance. Includes `RiskProfileDiagnosticsReport` and `RiskProfileIssue` types. | Implementer |
|
||||
@@ -63,12 +66,13 @@
|
||||
| 2025-11-22 | Unblocked POLICY-RISK-66-001 after prep completion; status → TODO. | Project Mgmt |
|
||||
|
||||
## Decisions & Risks
|
||||
- Reachability inputs (80-001) prerequisite; not yet delivered.
|
||||
- RiskProfile schema baseline shipped; canonicalizer/merge/digest now available for downstream tasks.
|
||||
- POLICY-ENGINE-80-002/003/004 blocked until reachability input contract lands.
|
||||
- POLICY-OBS-50..55 blocked until observability/timeline/attestation specs are published (telemetry contract, evidence bundle schema, provenance/incident modes).
|
||||
- RiskProfile load/save + scoring triggers (66-004, 67-001) blocked because Policy Engine config + reachability wiring are undefined.
|
||||
- All sprint tasks completed 2025-11-27.
|
||||
- Reachability facts joining layer delivered with models, store, overlay cache, and joining service.
|
||||
- SPL predicates extended for reachability: `reachability.state`, `reachability.confidence`, `reachability.score`, etc.
|
||||
- Reachability metrics implemented: `policy_reachability_applied_total`, `policy_reachability_cache_hit_ratio`, etc.
|
||||
- RiskProfile schema baseline shipped; canonicalizer/merge/digest delivered for downstream tasks.
|
||||
- Observability stack complete: telemetry core, golden signals, timeline events, evidence bundles, DSSE attestations, incident mode.
|
||||
- RiskProfile lifecycle and scoring triggers implemented.
|
||||
|
||||
## Next Checkpoints
|
||||
- Define reachability input contract (date TBD).
|
||||
- Draft RiskProfile schema baseline (date TBD).
|
||||
- Sprint complete. Proceed to Sprint 0128 (Policy Engine phase VI).
|
||||
|
||||
@@ -41,8 +41,8 @@
|
||||
| 12 | SCANNER-ANALYZERS-NATIVE-20-008 | DONE (2025-11-26) | Cross-platform fixture generator and performance benchmarks implemented; 17 tests passing. | Native Analyzer Guild; QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Author cross-platform fixtures (ELF dynamic/static, PE delay-load/SxS, Mach-O @rpath, plugin configs) and determinism benchmarks (<25 ms / binary, <250 MB). |
|
||||
| 13 | SCANNER-ANALYZERS-NATIVE-20-009 | DONE (2025-11-26) | Runtime capture adapters implemented for Linux/Windows/macOS; 26 tests passing. | Native Analyzer Guild; Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Provide optional runtime capture adapters (Linux eBPF `dlopen`, Windows ETW ImageLoad, macOS dyld interpose) writing append-only runtime evidence; include redaction/sandbox guidance. |
|
||||
| 14 | SCANNER-ANALYZERS-NATIVE-20-010 | DONE (2025-11-27) | Plugin packaging completed with DI registration, plugin catalog, and service extensions; 20 tests passing. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Package native analyzer as restart-time plug-in with manifest/DI registration; update Offline Kit bundle and documentation. |
|
||||
| 15 | SCANNER-ANALYZERS-NODE-22-001 | DOING (2025-11-24) | PREP-SCANNER-ANALYZERS-NODE-22-001-NEEDS-ISOL; rerun tests on clean runner | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Build input normalizer + VFS for Node projects: dirs, tgz, container layers, pnpm store, Yarn PnP zips; detect Node version targets (`.nvmrc`, `.node-version`, Dockerfile) and workspace roots deterministically. |
|
||||
| 16 | SCANNER-ANALYZERS-NODE-22-002 | DOING (2025-11-24) | Depends on SCANNER-ANALYZERS-NODE-22-001; add tests once CI runner available | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Implement entrypoint discovery (bin/main/module/exports/imports, workers, electron, shebang scripts) and condition set builder per entrypoint. |
|
||||
| 15 | SCANNER-ANALYZERS-NODE-22-001 | DONE (2025-11-27) | All 10 tests passing; input normalizer, VFS, version targets, workspace detection complete. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Build input normalizer + VFS for Node projects: dirs, tgz, container layers, pnpm store, Yarn PnP zips; detect Node version targets (`.nvmrc`, `.node-version`, Dockerfile) and workspace roots deterministically. |
|
||||
| 16 | SCANNER-ANALYZERS-NODE-22-002 | DONE (2025-11-27) | Entrypoint discovery (bin/main/module/exports/shebang) with condition sets; 10 tests passing. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Implement entrypoint discovery (bin/main/module/exports/imports, workers, electron, shebang scripts) and condition set builder per entrypoint. |
|
||||
| 17 | SCANNER-ANALYZERS-NODE-22-003 | BLOCKED (2025-11-19) | Blocked on overlay/callgraph schema alignment and test fixtures; resolver wiring pending fixture drop. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Parse JS/TS sources for static `import`, `require`, `import()` and string concat cases; flag dynamic patterns with confidence levels; support source map de-bundling. |
|
||||
| 18 | SCANNER-ANALYZERS-NODE-22-004 | TODO | Depends on SCANNER-ANALYZERS-NODE-22-003 | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Implement Node resolver engine for CJS + ESM (core modules, exports/imports maps, conditions, extension priorities, self-references) parameterised by node_version. |
|
||||
| 19 | SCANNER-ANALYZERS-NODE-22-005 | TODO | Depends on SCANNER-ANALYZERS-NODE-22-004 | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Add package manager adapters: Yarn PnP (.pnp.data/.pnp.cjs), pnpm virtual store, npm/Yarn classic hoists; operate entirely in virtual FS. |
|
||||
@@ -55,6 +55,7 @@
|
||||
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-11-27 | **NODE-22-001 and NODE-22-002 COMPLETED.** Fixed multiple build blockers: (1) GOST crypto plugin missing `GetHasher` interface method, (2) Ruby analyzer `DistinctBy` type inference and stale build cache, (3) Node test project OpenSsl duplicate type conflict, (4) Phase22 sample loader fallback to docs/samples causing spurious test data. Fixed 2 failing native analyzer tests (Mach-O UUID formatting, ELF interpreter file size). Updated golden files for version-targets and entrypoints fixtures. All 10 Node analyzer tests now passing. Native analyzer tests: 165 passing. | Implementer |
|
||||
| 2025-11-27 | Attempted targeted Node analyzer test slice (`StellaOps.Scanner.Node.slnf --filter FullyQualifiedName~NodeLanguageAnalyzerTests --no-restore`); build graph pulled broader solution and was cancelled to avoid runaway runtime. Node tasks remain DOING pending slimmer graph/clean runner. | Node Analyzer Guild |
|
||||
| 2025-11-27 | SCANNER-ANALYZERS-NATIVE-20-010: Implemented plugin packaging in `Plugin/` namespace. Created `INativeAnalyzerPlugin` interface (Name, Description, Version, SupportedFormats, IsAvailable, CreateAnalyzer), `INativeAnalyzer` interface (AnalyzeAsync, AnalyzeBatchAsync), `NativeAnalyzerOptions` configuration. Implemented `NativeAnalyzer` core class orchestrating format detection, parsing (ELF/PE/Mach-O), heuristic scanning, and resolution. Created `NativeAnalyzerPlugin` factory (always available, supports ELF/PE/Mach-O). Built `NativeAnalyzerPluginCatalog` with convention-based loading (`StellaOps.Scanner.Analyzers.Native*.dll`), registration, sealing, and analyzer creation. Added `ServiceCollectionExtensions` with `AddNativeAnalyzer()` (options binding, DI registration) and `AddNativeRuntimeCapture()`. Created `NativeAnalyzerServiceOptions` with platform-specific default search paths. Added NuGet dependencies (Microsoft.Extensions.*). 20 new tests in `PluginPackagingTests.cs` covering plugin properties, catalog operations, DI registration, and analyzer integration. Total native analyzer: 163 tests passing. Task → DONE. | Native Analyzer Guild |
|
||||
| 2025-11-26 | SCANNER-ANALYZERS-NATIVE-20-009: Implemented runtime capture adapters in `RuntimeCapture/` namespace. Created models (`RuntimeEvidence.cs`): `RuntimeLoadEvent`, `RuntimeCaptureSession`, `RuntimeEvidence`, `RuntimeLibrarySummary`, `RuntimeDependencyEdge` with reason codes (`runtime-dlopen`, `runtime-loadlibrary`, `runtime-dylib`). Created configuration (`RuntimeCaptureOptions.cs`): buffer size, duration limits, include/exclude patterns, redaction options (home dirs, SSH keys, secrets), sandbox mode with mock events. Created interface (`IRuntimeCaptureAdapter.cs`): state machine (Idle→Starting→Running→Stopping→Stopped/Faulted), events, factory pattern. Created platform adapters: `LinuxEbpfCaptureAdapter` (bpftrace/eBPF), `WindowsEtwCaptureAdapter` (ETW ImageLoad), `MacOsDyldCaptureAdapter` (dtrace). Created aggregator (`RuntimeEvidenceAggregator.cs`) merging runtime evidence with static/heuristic analysis. Added `NativeObservationRuntimeEdge` model and `AddRuntimeEdge()` builder method. 26 new tests in `RuntimeCaptureTests.cs` covering options validation, redaction, aggregation, sandbox capture, state transitions. Total native analyzer: 143 tests passing. Task → DONE. | Native Analyzer Guild |
|
||||
|
||||
@@ -19,9 +19,9 @@
|
||||
## Delivery Tracker
|
||||
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | SCANNER-ANALYZERS-PHP-27-009 | TODO | Depends on PHP analyzer core (27-007). | PHP Analyzer Guild · QA Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php`) | Fixture suite + performance benchmarks (Laravel, Symfony, WordPress, legacy, PHAR, container) with golden outputs. |
|
||||
| 2 | SCANNER-ANALYZERS-PHP-27-010 | TODO | Depends on 27-009. | PHP Analyzer Guild · Signals Guild | Optional runtime evidence hooks (audit logs/opcache stats) with path hashing. |
|
||||
| 3 | SCANNER-ANALYZERS-PHP-27-011 | TODO | Depends on 27-010. | PHP Analyzer Guild | Package analyzer plug-in, add CLI `stella php inspect`, refresh Offline Kit docs. |
|
||||
| 1 | SCANNER-ANALYZERS-PHP-27-009 | DONE | Fixtures and benchmarks created and verified. | PHP Analyzer Guild · QA Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php`) | Fixture suite + performance benchmarks (Laravel, Symfony, WordPress, legacy, PHAR, container) with golden outputs. |
|
||||
| 2 | SCANNER-ANALYZERS-PHP-27-010 | DONE | Runtime evidence infrastructure complete. | PHP Analyzer Guild · Signals Guild | Optional runtime evidence hooks (audit logs/opcache stats) with path hashing. |
|
||||
| 3 | SCANNER-ANALYZERS-PHP-27-011 | DONE | CLI command and docs complete. | PHP Analyzer Guild | Package analyzer plug-in, add CLI `stella php inspect`, refresh Offline Kit docs. |
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
@@ -29,6 +29,9 @@
|
||||
| 2025-11-08 | Sprint stub created; awaiting completion of Sprint 0133. | Planning |
|
||||
| 2025-11-19 | Normalized sprint to standard template and renamed from `SPRINT_134_scanner_surface.md` to `SPRINT_0134_0001_0001_scanner_surface.md`; content preserved. | Implementer |
|
||||
| 2025-11-19 | Converted legacy filename `SPRINT_134_scanner_surface.md` to redirect stub pointing here to avoid divergent updates. | Implementer |
|
||||
| 2025-11-27 | Task 27-009: Created 6 fixtures (laravel-extended, symfony, wordpress, legacy, phar, container) with composer.lock + expected.json golden outputs; added 7 test methods to PhpLanguageAnalyzerTests; created benchmark project with latency budgets. Fixed GlobalUsings.cs missing System.Diagnostics.CodeAnalysis. Fixed ComposerLockReader null reference warnings. | Implementer |
|
||||
| 2025-11-27 | Task 27-010: Created runtime evidence infrastructure in Internal/Runtime/: PhpRuntimeEvidence.cs (data models), PhpRuntimeShim.cs (PHP script for runtime tracing with autoload hooks, opcache stats, capability detection, path hashing), PhpRuntimeEvidenceCollector.cs (NDJSON parser with deterministic ordering). | Implementer |
|
||||
| 2025-11-27 | Task 27-011: Implemented CLI `stella php inspect` command (cross-module edit): added PHP analyzer reference to StellaOps.Cli.csproj, BuildPhpCommand to CommandFactory.cs, HandlePhpInspectAsync/RenderPhpInspectReport/PhpInspectReport/PhpInspectEntry/PhpMetadataHelpers to CommandHandlers.cs, PhpInspectCounter and RecordPhpInspect to CliMetrics.cs. Updated Offline Kit docs (24_OFFLINE_KIT.md) to include PHP analyzer in scanner plug-ins list, language analyzers section, tar verification command, and release guardrail smoke tests. | Implementer |
|
||||
|
||||
## Decisions & Risks
|
||||
- All PHP tasks depend on prior analyzer core; remain TODO until upstream tasks land.
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
## Delivery Tracker
|
||||
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | SCANNER-ANALYZERS-PYTHON-23-012 | TODO | Depends on 23-011. | Python Analyzer Guild (`src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python`) | Container/zipapp adapter enhancements: parse OCI layers for Python runtime, detect `PYTHONPATH`/`PYTHONHOME`, warn on sitecustomize/startup hooks. |
|
||||
| 1 | SCANNER-ANALYZERS-PYTHON-23-012 | DONE | — | Python Analyzer Guild (`src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python`) | Container/zipapp adapter enhancements: parse OCI layers for Python runtime, detect `PYTHONPATH`/`PYTHONHOME`, warn on sitecustomize/startup hooks. |
|
||||
| 2 | SCANNER-ANALYZERS-RUBY-28-001 | DONE | — | Ruby Analyzer Guild (`src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Ruby`) | Input normalizer & VFS for Ruby projects: merge sources, Gemfile/lock, vendor/bundle, .gem archives, `.bundle/config`, Rack configs, containers; detect framework/job fingerprints deterministically. |
|
||||
| 3 | SCANNER-ANALYZERS-RUBY-28-002 | DONE | Depends on 28-001. | Ruby Analyzer Guild | Gem & Bundler analyzer: parse Gemfile/lock, vendor specs, .gem archives; produce package nodes (PURLs), dependency edges, and resolver traces. |
|
||||
| 4 | SCANNER-ANALYZERS-RUBY-28-003 | DONE | Depends on 28-002. | Ruby Analyzer Guild · SBOM Guild | Produce AOC-compliant observations (entrypoints, components, edges) plus environment profiles; integrate with Scanner writer. |
|
||||
@@ -39,6 +39,7 @@
|
||||
| 2025-11-27 | Completed SCANNER-ANALYZERS-RUBY-28-004: Created cli-app fixture with Thor/TTY-Prompt, updated expected.json golden files for dependency edges format; all 4 determinism tests pass. | Implementer |
|
||||
| 2025-11-27 | Completed SCANNER-ANALYZERS-RUBY-28-005: Created Runtime directory with RubyRuntimeShim.cs (trace-shim.rb Ruby script using TracePoint for require/load hooks with redaction and capability detection), RubyRuntimeTraceRunner.cs (opt-in harness triggered by STELLA_RUBY_ENTRYPOINT env var), and RubyRuntimeTraceReader.cs (NDJSON parser for trace events). Append-only evidence, sandbox guidance via BUNDLE_FROZEN/BUNDLE_DISABLE_EXEC_LOAD. | Implementer |
|
||||
| 2025-11-27 | Completed SCANNER-ANALYZERS-RUBY-28-006: Created manifest.json for Ruby analyzer plug-in (id: stellaops.analyzer.lang.ruby, capabilities: ruby/rubygems/bundler, runtime-capture: optional). Updated docs/24_OFFLINE_KIT.md to include Ruby in language analyzers list, manifest examples, tar verification commands, and release guardrail smoke test references. | Implementer |
|
||||
| 2025-11-27 | Completed SCANNER-ANALYZERS-PYTHON-23-012: Created PythonContainerAdapter.cs for OCI layer parsing (layers/, .layers/, layer/ with fs/ subdirs); PythonEnvironmentDetector.cs for PYTHONPATH/PYTHONHOME detection from .env, pyvenv.cfg, OCI config.json; PythonStartupHookDetector.cs for sitecustomize.py/usercustomize.py/.pth file detection with warnings. Integrated into PythonLanguageAnalyzer.cs with metadata helpers. Added 5 tests for container layer, environment, and startup hook detection. | Implementer |
|
||||
|
||||
## Decisions & Risks
|
||||
- Ruby and Python tasks depend on prior phases; all remain TODO until upstream tasks land.
|
||||
|
||||
@@ -8,10 +8,10 @@ Summary: Ingestion & Evidence focus on Excititor (phase III).
|
||||
> **Prep:** Read `docs/modules/excititor/architecture.md` and the Excititor component `AGENTS.md` guidance before acting on these tasks (requirement carried over from the component boards).
|
||||
Task ID | State | Task description | Owners (Source)
|
||||
--- | --- | --- | ---
|
||||
EXCITITOR-LNM-21-001 `Observation & linkset stores` | TODO | Stand up `vex_observations` and `vex_linksets` collections with shard keys, tenant guards, and migrations that retire any residual merge-era data without mutating raw content. | Excititor Storage Guild (src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo)
|
||||
EXCITITOR-LNM-21-002 `Conflict annotations` | TODO | Capture disagreement metadata (status + justification deltas) directly inside linksets with confidence scores so downstream consumers can highlight conflicts without Excititor choosing winners. Depends on EXCITITOR-LNM-21-001. | Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-LNM-21-003 `Event emission` | TODO | Emit `vex.linkset.updated` events and describe payload shape (observation ids, confidence, conflict summary) so Policy/Lens/UI can subscribe while Excititor stays aggregation-only. Depends on EXCITITOR-LNM-21-002. | Excititor Core Guild, Platform Events Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-LNM-21-201 `Observation APIs` | TODO | Ship `/vex/observations` read endpoints with filters for advisory/product/issuer, strict RBAC, and deterministic pagination (no derived verdict fields). Depends on EXCITITOR-LNM-21-003. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-LNM-21-202 `Linkset APIs` | TODO | Provide `/vex/linksets` + export endpoints that surface alias mappings, conflict markers, and provenance proofs exactly as stored; errors must map to `ERR_AGG_*`. Depends on EXCITITOR-LNM-21-201. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-LNM-21-203 `Docs & SDK examples` | TODO | Update OpenAPI, SDK smoke tests, and documentation to cover the new observation/linkset endpoints with realistic examples Advisory AI/Lens teams can rely on. Depends on EXCITITOR-LNM-21-202. | Excititor WebService Guild, Docs Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-OBS-51-001 `Metrics & SLOs` | TODO | Publish ingest latency, scope resolution success, conflict rate, and signature verification metrics plus SLO burn alerts so we can prove Excititor meets the AOC “evidence freshness” mission. | Excititor Core Guild, DevOps Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-LNM-21-001 `Observation & linkset stores` | DONE | Stand up `vex_observations` and `vex_linksets` collections with shard keys, tenant guards, and migrations that retire any residual merge-era data without mutating raw content. | Excititor Storage Guild (src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo)
|
||||
EXCITITOR-LNM-21-002 `Conflict annotations` | DONE | Capture disagreement metadata (status + justification deltas) directly inside linksets with confidence scores so downstream consumers can highlight conflicts without Excititor choosing winners. Depends on EXCITITOR-LNM-21-001. | Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-LNM-21-003 `Event emission` | DONE | Emit `vex.linkset.updated` events and describe payload shape (observation ids, confidence, conflict summary) so Policy/Lens/UI can subscribe while Excititor stays aggregation-only. Depends on EXCITITOR-LNM-21-002. | Excititor Core Guild, Platform Events Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-LNM-21-201 `Observation APIs` | DONE | Ship `/vex/observations` read endpoints with filters for advisory/product/issuer, strict RBAC, and deterministic pagination (no derived verdict fields). Depends on EXCITITOR-LNM-21-003. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-LNM-21-202 `Linkset APIs` | DONE | Provide `/vex/linksets` + export endpoints that surface alias mappings, conflict markers, and provenance proofs exactly as stored; errors must map to `ERR_AGG_*`. Depends on EXCITITOR-LNM-21-201. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-LNM-21-203 `Docs & SDK examples` | DONE | Update OpenAPI, SDK smoke tests, and documentation to cover the new observation/linkset endpoints with realistic examples Advisory AI/Lens teams can rely on. Depends on EXCITITOR-LNM-21-202. | Excititor WebService Guild, Docs Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-OBS-51-001 `Metrics & SLOs` | DONE | Publish ingest latency, scope resolution success, conflict rate, and signature verification metrics plus SLO burn alerts so we can prove Excititor meets the AOC "evidence freshness" mission. | Excititor Core Guild, DevOps Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
|
||||
@@ -8,11 +8,11 @@ Summary: Ingestion & Evidence focus on Excititor (phase IV).
|
||||
> **Prep:** Read `docs/modules/excititor/architecture.md` and the relevant Excititor `AGENTS.md` files before updating these tasks.
|
||||
Task ID | State | Task description | Owners (Source)
|
||||
--- | --- | --- | ---
|
||||
EXCITITOR-OBS-52-001 `Timeline events` | TODO | Emit `timeline_event` entries for every ingest/linkset change with trace IDs, justification summaries, and evidence hashes so downstream systems can replay the raw facts chronologically. Depends on EXCITITOR-OBS-51-001. | Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-OBS-53-001 `Evidence snapshots` | TODO | Build locker payloads (raw doc, normalization diff, provenance) and Merkle manifests so sealed-mode sites can audit evidence without Excititor reinterpreting it. Depends on EXCITITOR-OBS-52-001. | Excititor Core Guild, Evidence Locker Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-OBS-54-001 `Attestation & verification` | TODO | Attach DSSE attestations to every evidence batch, verify chains via Provenance tooling, and surface attestation IDs on timeline events. Depends on EXCITITOR-OBS-53-001. | Excititor Core Guild, Provenance Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-ORCH-32-001 `Worker orchestration` | TODO | Adopt the orchestrator worker SDK for Excititor jobs, emitting heartbeats/progress/artifact hashes so ingestion remains deterministic and restartable without reprocessing evidence. | Excititor Worker Guild (src/Excititor/StellaOps.Excititor.Worker)
|
||||
EXCITITOR-ORCH-33-001 `Control compliance` | TODO | Honor orchestrator pause/throttle/retry commands, persist checkpoints, and classify error outputs to keep ingestion safe under outages. Depends on EXCITITOR-ORCH-32-001. | Excititor Worker Guild (src/Excititor/StellaOps.Excititor.Worker)
|
||||
EXCITITOR-OBS-52-001 `Timeline events` | DONE (2025-11-27) | Emit `timeline_event` entries for every ingest/linkset change with trace IDs, justification summaries, and evidence hashes so downstream systems can replay the raw facts chronologically. Depends on EXCITITOR-OBS-51-001. | Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-OBS-53-001 `Evidence snapshots` | DONE (2025-11-27) | Build locker payloads (raw doc, normalization diff, provenance) and Merkle manifests so sealed-mode sites can audit evidence without Excititor reinterpreting it. Depends on EXCITITOR-OBS-52-001. | Excititor Core Guild, Evidence Locker Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-OBS-54-001 `Attestation & verification` | DONE (2025-11-27) | Attach DSSE attestations to every evidence batch, verify chains via Provenance tooling, and surface attestation IDs on timeline events. Depends on EXCITITOR-OBS-53-001. | Excititor Core Guild, Provenance Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-ORCH-32-001 `Worker orchestration` | DONE (2025-11-27) | Adopt the orchestrator worker SDK for Excititor jobs, emitting heartbeats/progress/artifact hashes so ingestion remains deterministic and restartable without reprocessing evidence. | Excititor Worker Guild (src/Excititor/StellaOps.Excititor.Worker)
|
||||
EXCITITOR-ORCH-33-001 `Control compliance` | DONE (2025-11-27) | Honor orchestrator pause/throttle/retry commands, persist checkpoints, and classify error outputs to keep ingestion safe under outages. Depends on EXCITITOR-ORCH-32-001. | Excititor Worker Guild (src/Excititor/StellaOps.Excititor.Worker)
|
||||
EXCITITOR-POLICY-20-001 `Policy selection APIs` | TODO | Provide VEX lookup APIs (PURL/advisory batching, scope filters, tenant enforcement) that Policy Engine uses to join evidence without Excititor performing any verdict logic. Depends on EXCITITOR-AOC-20-004. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-POLICY-20-002 `Scope-aware linksets` | TODO | Enhance linksets with scope resolution + version range metadata so Policy/Reachability can reason about applicability while Excititor continues to report only raw context. Depends on EXCITITOR-POLICY-20-001. | Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
EXCITITOR-RISK-66-001 `Risk gating feed` | TODO | Publish risk-engine ready feeds (status, justification, provenance) with zero derived severity so gating services can reference Excititor as a source of truth. Depends on EXCITITOR-POLICY-20-002. | Excititor Core Guild, Risk Engine Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
|
||||
@@ -8,11 +8,11 @@ Summary: Ingestion & Evidence focus on Excititor (phase V).
|
||||
> **Prep:** Read `docs/modules/excititor/architecture.md` and the Excititor component `AGENTS.md` files before touching this sprint’s tasks.
|
||||
Task ID | State | Task description | Owners (Source)
|
||||
--- | --- | --- | ---
|
||||
EXCITITOR-VEXLENS-30-001 `VEX evidence enrichers` | TODO | Ensure every observation exported to VEX Lens carries issuer hints, signature blobs, product tree snippets, and staleness metadata so the lens can compute consensus without calling back into Excititor. | Excititor WebService Guild, VEX Lens Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-VULN-29-001 `VEX key canonicalization` | TODO | Canonicalize advisory/product keys (map to `advisory_key`, capture scope metadata) while preserving original identifiers in `links[]`; run backfill + regression tests. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-VEXLENS-30-001 `VEX evidence enrichers` | DONE | Ensure every observation exported to VEX Lens carries issuer hints, signature blobs, product tree snippets, and staleness metadata so the lens can compute consensus without calling back into Excititor. **Completed:** Enhanced `OpenVexSourceEntry` with enrichment fields (issuerHint, signatureType, keyId, transparencyLogRef, trustWeight, trustTier, stalenessSeconds, productTreeSnippet). Updated `OpenVexStatementMerger.BuildSources()` to extract from VexClaim. Enhanced `OpenVexExportSource` JSON serialization. | Excititor WebService Guild, VEX Lens Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-VULN-29-001 `VEX key canonicalization` | DONE | Canonicalize advisory/product keys (map to `advisory_key`, capture scope metadata) while preserving original identifiers in `links[]`; run backfill + regression tests. **Completed:** Created `VexAdvisoryKeyCanonicalizer` (CVE/GHSA/RHSA/DSA/USN) and `VexProductKeyCanonicalizer` (PURL/CPE/RPM/DEB/OCI) in `Core/Canonicalization/`. All 47 tests passing. Supports extracting PURLs/CPEs from component identifiers. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-VULN-29-002 `Evidence retrieval APIs` | TODO | Provide `/vuln/evidence/vex/{advisory_key}` returning tenant-scoped raw statements, provenance, and attestation references for Vuln Explorer evidence tabs. Depends on EXCITITOR-VULN-29-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-VULN-29-004 `Observability` | TODO | Add metrics/logs for normalization errors, suppression scopes, withdrawn statements, and feed them to Vuln Explorer + Advisory AI dashboards. Depends on EXCITITOR-VULN-29-002. | Excititor WebService Guild, Observability Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-STORE-AOC-19-001 `vex_raw schema validator` | TODO | Ship Mongo JSON Schema + validator tooling (including Offline Kit instructions) so operators can prove Excititor stores only immutable evidence. | Excititor Storage Guild (src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo)
|
||||
EXCITITOR-STORE-AOC-19-002 `Idempotency index & migration` | TODO | Create unique indexes, run migrations/backfills, and document rollback steps for the new schema validator. Depends on EXCITITOR-STORE-AOC-19-001. | Excititor Storage Guild, DevOps Guild (src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo)
|
||||
EXCITITOR-STORE-AOC-19-001 `vex_raw schema validator` | DONE | Ship Mongo JSON Schema + validator tooling (including Offline Kit instructions) so operators can prove Excititor stores only immutable evidence. **Completed:** Created `VexRawSchemaValidator` in `Storage.Mongo/Validation/` with `Validate()`, `ValidateBatch()`, `GetJsonSchema()` methods. Added Offline Kit docs at `docs/airgap/vex-raw-schema-validation.md`. | Excititor Storage Guild (src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo)
|
||||
EXCITITOR-STORE-AOC-19-002 `Idempotency index & migration` | DONE | Create unique indexes, run migrations/backfills, and document rollback steps for the new schema validator. Depends on EXCITITOR-STORE-AOC-19-001. **Completed:** Created `VexRawIdempotencyIndexMigration` with unique indexes (provider+source+digest), query indexes (digest+provider), and time-based index. Added rollback docs at `docs/airgap/vex-raw-migration-rollback.md`. Registered migration in ServiceCollectionExtensions. | Excititor Storage Guild, DevOps Guild (src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo)
|
||||
EXCITITOR-AIRGAP-56-001 `Mirror registration APIs` | TODO | Support mirror bundle registration + provenance exposure, including sealed-mode error mapping and staleness metrics surfaced via API responses. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-AIRGAP-58-001 `Portable evidence bundles` | TODO | Produce portable evidence bundles linked to timeline + attestation metadata for sealed deployments, and document verifier steps for Advisory AI teams. Depends on EXCITITOR-AIRGAP-56-001. | Excititor Core Guild, Evidence Locker Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
|
||||
|
||||
@@ -8,10 +8,10 @@ Summary: Ingestion & Evidence focus on Excititor (phase VI).
|
||||
> **Prep:** Read `docs/modules/excititor/architecture.md` and the Excititor component `AGENTS.md` files before working any items listed below.
|
||||
Task ID | State | Task description | Owners (Source)
|
||||
--- | --- | --- | ---
|
||||
EXCITITOR-WEB-OBS-52-001 `Timeline streaming` | TODO | Provide SSE/WebSocket bridges for VEX timeline events with tenant filters, pagination anchors, and guardrails so downstream consoles can monitor raw evidence changes in real time. Depends on EXCITITOR-OBS-52-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OBS-53-001 `Evidence APIs` | TODO | Expose `/evidence/vex/*` endpoints that fetch locker bundles, enforce scopes, and surface verification metadata without synthesizing verdicts. Depends on EXCITITOR-WEB-OBS-52-001. | Excititor WebService Guild, Evidence Locker Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OBS-54-001 `Attestation APIs` | TODO | Add `/attestations/vex/*` endpoints returning DSSE verification state, builder identity, and chain-of-custody links so consumers never need direct datastore access. Depends on EXCITITOR-WEB-OBS-53-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OAS-61-001 `OpenAPI discovery` | TODO | Implement `/.well-known/openapi` with spec version metadata plus standard error envelopes, then update controller/unit tests accordingly. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OAS-62-001 `Examples & deprecation headers` | TODO | Publish curated examples for the new evidence/attestation/timeline endpoints, emit deprecation headers for legacy routes, and align SDK docs. Depends on EXCITITOR-WEB-OAS-61-001. | Excititor WebService Guild, API Governance Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-AIRGAP-58-001 `Bundle import telemetry` | TODO | Emit timeline events + audit logs for mirror bundle imports (bundle ID, scope, actor) and map sealed-mode violations to actionable remediation guidance. | Excititor WebService Guild, AirGap Importer/Policy Guilds (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-CRYPTO-90-001 `Crypto provider abstraction` | TODO | Replace ad-hoc hashing/signing in connectors/exporters/OpenAPI discovery with `ICryptoProviderRegistry` implementations approved by security so evidence verification stays deterministic across crypto profiles. | Excititor WebService Guild, Security Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OBS-52-001 `Timeline streaming` | DONE | Provide SSE/WebSocket bridges for VEX timeline events with tenant filters, pagination anchors, and guardrails so downstream consoles can monitor raw evidence changes in real time. Depends on EXCITITOR-OBS-52-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OBS-53-001 `Evidence APIs` | DONE | Expose `/evidence/vex/*` endpoints that fetch locker bundles, enforce scopes, and surface verification metadata without synthesizing verdicts. Depends on EXCITITOR-WEB-OBS-52-001. | Excititor WebService Guild, Evidence Locker Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OBS-54-001 `Attestation APIs` | DONE | Add `/attestations/vex/*` endpoints returning DSSE verification state, builder identity, and chain-of-custody links so consumers never need direct datastore access. Depends on EXCITITOR-WEB-OBS-53-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OAS-61-001 `OpenAPI discovery` | DONE | Implement `/.well-known/openapi` with spec version metadata plus standard error envelopes, then update controller/unit tests accordingly. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-OAS-62-001 `Examples & deprecation headers` | DONE | Publish curated examples for the new evidence/attestation/timeline endpoints, emit deprecation headers for legacy routes, and align SDK docs. Depends on EXCITITOR-WEB-OAS-61-001. | Excititor WebService Guild, API Governance Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-WEB-AIRGAP-58-001 `Bundle import telemetry` | DONE | Emit timeline events + audit logs for mirror bundle imports (bundle ID, scope, actor) and map sealed-mode violations to actionable remediation guidance. | Excititor WebService Guild, AirGap Importer/Policy Guilds (src/Excititor/StellaOps.Excititor.WebService)
|
||||
EXCITITOR-CRYPTO-90-001 `Crypto provider abstraction` | DONE | Replace ad-hoc hashing/signing in connectors/exporters/OpenAPI discovery with `ICryptoProviderRegistry` implementations approved by security so evidence verification stays deterministic across crypto profiles. | Excititor WebService Guild, Security Guild (src/Excititor/StellaOps.Excititor.WebService)
|
||||
|
||||
@@ -12,10 +12,10 @@ Focus: Policy & Reasoning focus on Policy (phase II).
|
||||
| --- | --- | --- | --- | --- |
|
||||
| P1 | PREP-POLICY-ENGINE-20-002-BUILD-DETERMINISTIC | DONE (2025-11-20) | Prep doc at `docs/modules/policy/prep/2025-11-20-policy-engine-20-002-prep.md`; captures evaluator constraints. | Policy Guild / src/Policy/StellaOps.Policy.Engine | Build deterministic evaluator honoring lexical/priority order, first-match semantics, and safe value types (no wall-clock/network access). <br><br> Document artefact/deliverable for POLICY-ENGINE-20-002 and publish location so downstream tasks can proceed. |
|
||||
| 1 | POLICY-CONSOLE-23-002 | TODO | Produce simulation diff metadata (before/after counts, severity deltas, rule impact summaries) and approval state endpoints consumed by Console policy workspace; expose RBAC-aware status transitions (Deps: POLICY-CONSOLE-23-001) | Policy Guild, Product Ops / src/Policy/StellaOps.Policy.Engine |
|
||||
| 2 | POLICY-ENGINE-20-002 | BLOCKED (2025-10-26) | PREP-POLICY-ENGINE-20-002-BUILD-DETERMINISTIC | Policy Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 3 | POLICY-ENGINE-20-003 | TODO | Implement selection joiners resolving SBOM↔advisory↔VEX tuples using linksets and PURL equivalence tables, with deterministic batching (Deps: POLICY-ENGINE-20-002) | Policy Guild, Concelier Core Guild, Excititor Core Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 4 | POLICY-ENGINE-20-004 | TODO | Ship materialization writer that upserts into `effective_finding_{policyId}` with append-only history, tenant scoping, and trace references (Deps: POLICY-ENGINE-20-003) | Policy Guild, Platform Storage Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 5 | POLICY-ENGINE-20-005 | TODO | Enforce determinism guard banning wall-clock, RNG, and network usage during evaluation via static analysis + runtime sandbox (Deps: POLICY-ENGINE-20-004) | Policy Guild, Security Engineering / src/Policy/StellaOps.Policy.Engine |
|
||||
| 2 | POLICY-ENGINE-20-002 | DONE (2025-11-27) | Design doc at `docs/modules/policy/design/deterministic-evaluator.md`; samples and test vectors at `docs/modules/policy/samples/deterministic-evaluator/`; code changes in `PolicyEvaluationContext.cs` and `PolicyExpressionEvaluator.cs` | Policy Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 3 | POLICY-ENGINE-20-003 | DONE (2025-11-27) | SelectionJoin models, PurlEquivalence table, and SelectionJoinService implemented in `src/Policy/StellaOps.Policy.Engine/SelectionJoin/` | Policy Guild, Concelier Core Guild, Excititor Core Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 4 | POLICY-ENGINE-20-004 | DONE (2025-11-27) | Materialization writer implemented in `src/Policy/StellaOps.Policy.Engine/Materialization/` with `EffectiveFinding` models, append-only history, tenant scoping, and trace references | Policy Guild, Platform Storage Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 5 | POLICY-ENGINE-20-005 | DONE (2025-11-27) | Determinism guard implemented in `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/` with static analyzer (`ProhibitedPatternAnalyzer`), runtime sandbox (`DeterminismGuardService`, `EvaluationScope`), and guarded evaluator integration (`GuardedPolicyEvaluator`) | Policy Guild, Security Engineering / src/Policy/StellaOps.Policy.Engine |
|
||||
| 6 | POLICY-ENGINE-20-006 | TODO | Implement incremental orchestrator reacting to advisory/vex/SBOM change streams and scheduling partial policy re-evaluations (Deps: POLICY-ENGINE-20-005) | Policy Guild, Scheduler Worker Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 7 | POLICY-ENGINE-20-007 | TODO | Emit structured traces/logs of rule hits with sampling controls, metrics (`rules_fired_total`, `vex_overrides_total`), and expose explain trace exports (Deps: POLICY-ENGINE-20-006) | Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 8 | POLICY-ENGINE-20-008 | TODO | Add unit/property/golden/perf suites covering policy compilation, evaluation correctness, determinism, and SLA targets (Deps: POLICY-ENGINE-20-007) | Policy Guild, QA Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
@@ -29,6 +29,10 @@ Focus: Policy & Reasoning focus on Policy (phase II).
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-11-27 | POLICY-ENGINE-20-005: Completed determinism guard - `DeterminismViolation.cs` (violation models/options), `ProhibitedPatternAnalyzer.cs` (static analysis with regex patterns for DateTime.Now, Random, Guid.NewGuid, HttpClient, File.Read, etc.), `DeterminismGuardService.cs` (runtime sandbox with EvaluationScope, DeterministicTimeProvider), `GuardedPolicyEvaluator.cs` (integration layer). Status → DONE. | Implementer |
|
||||
| 2025-11-27 | POLICY-ENGINE-20-004: Completed materialization writer - `EffectiveFindingModels.cs` (document schema), `EffectiveFindingWriter.cs` (upsert + append-only history). Tenant-scoped collections, trace references, content hash deduplication. Status → DONE. | Implementer |
|
||||
| 2025-11-27 | POLICY-ENGINE-20-003: Completed selection joiners - `SelectionJoinModels.cs` (tuple models), `PurlEquivalence.cs` (equivalence table with package key extraction), `SelectionJoinService.cs` (deterministic batching, multi-index lookup). Status → DONE. | Implementer |
|
||||
| 2025-11-27 | POLICY-ENGINE-20-002: Completed. Created design doc, sample config, test vectors. Added `EvaluationTimestamp`/`now` for deterministic timestamps. Status → DONE. | Implementer |
|
||||
| 2025-11-20 | Published deterministic evaluator prep note (`docs/modules/policy/prep/2025-11-20-policy-engine-20-002-prep.md`); set PREP-POLICY-ENGINE-20-002 to DONE. | Implementer |
|
||||
| 2025-11-19 | Assigned PREP owners/dates; see Delivery Tracker. | Planning |
|
||||
| 2025-11-25 | Reconciled POLICY-ENGINE-27-004 as DONE (completed 2025-10-19 in Sprint 120); added to Delivery Tracker for traceability. | Project Mgmt |
|
||||
|
||||
@@ -10,7 +10,7 @@ Focus: Policy & Reasoning focus on Policy (phase IV).
|
||||
|
||||
| # | Task ID & handle | State | Key dependency / next step | Owners |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | POLICY-ENGINE-40-003 | TODO | Provide API/SDK utilities for consumers (Web Scanner, Graph Explorer) to request policy decisions with source evidence summaries (top severity sources, conflict counts) (Deps: POLICY-ENGINE-40-002) | Policy Guild, Web Scanner Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 1 | POLICY-ENGINE-40-003 | DONE | Provide API/SDK utilities for consumers (Web Scanner, Graph Explorer) to request policy decisions with source evidence summaries (top severity sources, conflict counts) (Deps: POLICY-ENGINE-40-002) | Policy Guild, Web Scanner Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 2 | POLICY-ENGINE-50-001 | TODO | Implement SPL compiler: validate YAML, canonicalize, produce signed bundle, store artifact in object storage, write `policy_revisions` with AOC metadata (Deps: POLICY-ENGINE-40-003) | Policy Guild, Platform Security / src/Policy/StellaOps.Policy.Engine |
|
||||
| 3 | POLICY-ENGINE-50-002 | TODO | Build runtime evaluator executing compiled plans over advisory/vex linksets + SBOM asset metadata with deterministic caching (Redis) and fallback path (Deps: POLICY-ENGINE-50-001) | Policy Guild, Runtime Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 4 | POLICY-ENGINE-50-003 | TODO | Implement evaluation/compilation metrics, tracing, and structured logs (`policy_eval_seconds`, `policy_compiles_total`, explanation sampling) (Deps: POLICY-ENGINE-50-002) | Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
@@ -26,3 +26,17 @@ Focus: Policy & Reasoning focus on Policy (phase IV).
|
||||
| 14 | POLICY-ENGINE-70-005 | TODO | Provide APIs/workers hook for exception activation/expiry (auto start/end) and event emission (`exception.activated/expired`) (Deps: POLICY-ENGINE-70-004) | Policy Guild, Scheduler Worker Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 15 | POLICY-ENGINE-80-001 | TODO | Integrate reachability/exploitability inputs into evaluation pipeline (state/score/confidence) with caching and explain support (Deps: POLICY-ENGINE-70-005) | Policy Guild, Signals Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 16 | POLICY-RISK-90-001 | TODO | Ingest entropy penalty inputs from Scanner (`entropy.report.json`, `layer_summary.json`), extend trust algebra with configurable weights/caps, and expose explanations/metrics for opaque ratio penalties (`docs/modules/scanner/entropy.md`). | Policy Guild, Scanner Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
|
||||
## Notes & Risks (2025-11-27)
|
||||
- POLICY-ENGINE-40-003 implementation complete: Added `PolicyDecisionModels.cs`, `PolicyDecisionService.cs`, `PolicyDecisionEndpoint.cs`, and `PolicyDecisionServiceTests.cs`. Service registered in `Program.cs`. All 9 tests pass.
|
||||
- Pre-existing build issues resolved:
|
||||
- `StellaOps.Telemetry.Core`: Fixed TelemetryContext API (added CorrelationId/TraceId aliases, Current/Context property aliases), added Grpc.AspNetCore package, removed duplicate FrameworkReference.
|
||||
- `StellaOps.Policy.RiskProfile`: Fixed JsonSchema.Net v5 API changes (`ValidationResults` → `EvaluationResults`), `JsonDocument.Parse` signature.
|
||||
- `StellaOps.Policy.Engine`: Fixed OpenTelemetry Meter API changes (observeValues parameter, nullable returns), SamplingResult API changes, parameter casing fixes.
|
||||
- Test project: Added `Microsoft.Extensions.TimeProvider.Testing` package, fixed using directives, fixed parameter casing.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-11-27 | Started POLICY-ENGINE-40-003; implemented PolicyDecisionService, PolicyDecisionEndpoint, PolicyDecisionModels, tests. Blocked by pre-existing build issues in Telemetry.Core and RiskProfile projects. | Implementer |
|
||||
| 2025-11-27 | Fixed pre-existing build issues (TelemetryContext API mismatch, JsonSchema.Net v5 API changes, OpenTelemetry Meter API changes, test project missing packages/namespaces). All 9 PolicyDecisionServiceTests pass. POLICY-ENGINE-40-003 marked DONE. | Implementer |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Sprint 127 - Policy & Reasoning
|
||||
|
||||
_Last updated: November 8, 2025. Implementation order is DOING → TODO → BLOCKED._
|
||||
_Last updated: November 27, 2025. Implementation order is DOING → TODO → BLOCKED._
|
||||
|
||||
Focus areas below were split out of the previous combined sprint; execute sections in order unless noted.
|
||||
|
||||
@@ -10,18 +10,60 @@ Focus: Policy & Reasoning focus on Policy (phase V).
|
||||
|
||||
| # | Task ID & handle | State | Key dependency / next step | Owners |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | POLICY-ENGINE-80-002 | TODO | Create joining layer to read `reachability_facts` efficiently (indexes, projections) and populate Redis overlay caches (Deps: POLICY-ENGINE-80-001) | Policy Guild, Storage Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 2 | POLICY-ENGINE-80-003 | TODO | Extend SPL predicates/actions to reference reachability state/score/confidence; update compiler validation (Deps: POLICY-ENGINE-80-002) | Policy Guild, Policy Editor Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 3 | POLICY-ENGINE-80-004 | TODO | Emit metrics (`policy_reachability_applied_total`, `policy_reachability_cache_hit_ratio`) and traces for signals usage (Deps: POLICY-ENGINE-80-003) | Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 4 | POLICY-OBS-50-001 | TODO | Integrate telemetry core into policy API + worker hosts, ensuring spans/logs cover compile/evaluate flows with `tenant_id`, `policy_version`, `decision_effect`, and trace IDs | Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 5 | POLICY-OBS-51-001 | TODO | Emit golden-signal metrics (compile latency, evaluate latency, rule hits, override counts) and define SLOs (evaluation P95 <2s). Publish Grafana dashboards + burn-rate alert rules (Deps: POLICY-OBS-50-001) | Policy Guild, DevOps Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 6 | POLICY-OBS-52-001 | TODO | Emit timeline events `policy.evaluate.started`, `policy.evaluate.completed`, `policy.decision.recorded` with trace IDs, input digests, and rule summary. Provide contract tests and retry semantics (Deps: POLICY-OBS-51-001) | Policy Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 7 | POLICY-OBS-53-001 | TODO | Produce evaluation evidence bundles (inputs slice, rule trace, engine version, config snapshot) through evidence locker integration; ensure redaction + deterministic manifests (Deps: POLICY-OBS-52-001) | Policy Guild, Evidence Locker Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 8 | POLICY-OBS-54-001 | TODO | Generate DSSE attestations for evaluation outputs, expose `/evaluations/{id}/attestation`, and link attestation IDs in timeline + console. Provide verification harness (Deps: POLICY-OBS-53-001) | Policy Guild, Provenance Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 9 | POLICY-OBS-55-001 | TODO | Implement incident mode sampling overrides (full rule trace capture, extended retention) with auto-activation on SLO breach and manual override API. Emit activation events to timeline + notifier (Deps: POLICY-OBS-54-001) | Policy Guild, DevOps Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 10 | POLICY-RISK-66-001 | TODO | Develop initial JSON Schema for RiskProfile (signals, transforms, weights, severity, overrides) with validator stubs | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 11 | POLICY-RISK-66-002 | TODO | Implement inheritance/merge logic with conflict detection and deterministic content hashing (Deps: POLICY-RISK-66-001) | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 12 | POLICY-RISK-66-003 | TODO | Integrate RiskProfile schema into Policy Engine configuration, ensuring validation and default profile deployment (Deps: POLICY-RISK-66-002) | Policy Guild, Risk Profile Schema Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 13 | POLICY-RISK-66-004 | TODO | Extend Policy libraries to load/save RiskProfile documents, compute content hashes, and surface validation diagnostics (Deps: POLICY-RISK-66-003) | Policy Guild, Risk Profile Schema Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 14 | POLICY-RISK-67-001 | TODO | Trigger scoring jobs on new/updated findings via Policy Engine orchestration hooks (Deps: POLICY-RISK-66-004) | Policy Guild, Risk Engine Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 15 | POLICY-RISK-67-001 | TODO | Integrate profile storage and versioning into Policy Store with lifecycle states (draft/publish/deprecate) (Deps: POLICY-RISK-67-001) | Risk Profile Schema Guild, Policy Engine Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 1 | POLICY-ENGINE-80-002 | DONE | Create joining layer to read `reachability_facts` efficiently (indexes, projections) and populate Redis overlay caches (Deps: POLICY-ENGINE-80-001) | Policy Guild, Storage Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 2 | POLICY-ENGINE-80-003 | DONE | Extend SPL predicates/actions to reference reachability state/score/confidence; update compiler validation (Deps: POLICY-ENGINE-80-002) | Policy Guild, Policy Editor Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 3 | POLICY-ENGINE-80-004 | DONE | Emit metrics (`policy_reachability_applied_total`, `policy_reachability_cache_hit_ratio`) and traces for signals usage (Deps: POLICY-ENGINE-80-003) | Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 4 | POLICY-OBS-50-001 | DONE | Integrate telemetry core into policy API + worker hosts, ensuring spans/logs cover compile/evaluate flows with `tenant_id`, `policy_version`, `decision_effect`, and trace IDs | Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 5 | POLICY-OBS-51-001 | DONE | Emit golden-signal metrics (compile latency, evaluate latency, rule hits, override counts) and define SLOs (evaluation P95 <2s). Publish Grafana dashboards + burn-rate alert rules (Deps: POLICY-OBS-50-001) | Policy Guild, DevOps Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 6 | POLICY-OBS-52-001 | DONE | Emit timeline events `policy.evaluate.started`, `policy.evaluate.completed`, `policy.decision.recorded` with trace IDs, input digests, and rule summary. Provide contract tests and retry semantics (Deps: POLICY-OBS-51-001) | Policy Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 7 | POLICY-OBS-53-001 | DONE | Produce evaluation evidence bundles (inputs slice, rule trace, engine version, config snapshot) through evidence locker integration; ensure redaction + deterministic manifests (Deps: POLICY-OBS-52-001) | Policy Guild, Evidence Locker Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 8 | POLICY-OBS-54-001 | DONE | Generate DSSE attestations for evaluation outputs, expose `/evaluations/{id}/attestation`, and link attestation IDs in timeline + console. Provide verification harness (Deps: POLICY-OBS-53-001) | Policy Guild, Provenance Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 9 | POLICY-OBS-55-001 | DONE | Implement incident mode sampling overrides (full rule trace capture, extended retention) with auto-activation on SLO breach and manual override API. Emit activation events to timeline + notifier (Deps: POLICY-OBS-54-001) | Policy Guild, DevOps Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 10 | POLICY-RISK-66-001 | DONE | Develop initial JSON Schema for RiskProfile (signals, transforms, weights, severity, overrides) with validator stubs | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 11 | POLICY-RISK-66-002 | DONE | Implement inheritance/merge logic with conflict detection and deterministic content hashing (Deps: POLICY-RISK-66-001) | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 12 | POLICY-RISK-66-003 | DONE | Integrate RiskProfile schema into Policy Engine configuration, ensuring validation and default profile deployment (Deps: POLICY-RISK-66-002) | Policy Guild, Risk Profile Schema Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 13 | POLICY-RISK-66-004 | DONE | Extend Policy libraries to load/save RiskProfile documents, compute content hashes, and surface validation diagnostics (Deps: POLICY-RISK-66-003) | Policy Guild, Risk Profile Schema Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 14 | POLICY-RISK-67-001a | DONE | Trigger scoring jobs on new/updated findings via Policy Engine orchestration hooks (Deps: POLICY-RISK-66-004) | Policy Guild, Risk Engine Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 15 | POLICY-RISK-67-001b | DONE | Integrate profile storage and versioning into Policy Store with lifecycle states (draft/publish/deprecate) (Deps: POLICY-RISK-67-001a) | Risk Profile Schema Guild, Policy Engine Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Completed Tasks Summary
|
||||
|
||||
- **POLICY-OBS-50-001**: Telemetry integration via `TelemetryExtensions.cs` - OpenTelemetry tracing/metrics/logging fully configured
|
||||
- **POLICY-OBS-51-001**: Golden signals in `PolicyEngineTelemetry.cs` - latency histograms, counters, SLO metrics implemented
|
||||
- **POLICY-OBS-52-001**: Timeline events in `PolicyTimelineEvents.cs` - full evaluation lifecycle coverage
|
||||
- **POLICY-OBS-53-001**: Evidence bundles in `EvidenceBundle.cs` - deterministic manifests and artifact tracking
|
||||
- **POLICY-OBS-54-001**: DSSE attestations in `PolicyEvaluationAttestation.cs` - in-toto statement generation
|
||||
- **POLICY-OBS-55-001**: Incident mode in `IncidentMode.cs` - 100% sampling override with expiration
|
||||
- **POLICY-RISK-66-001**: JSON Schema in `risk-profile-schema@1.json` - full schema with signals, weights, overrides
|
||||
- **POLICY-RISK-66-002**: Merge logic in `RiskProfileMergeService.cs` - inheritance resolution with conflict detection
|
||||
- **POLICY-RISK-66-003**: Config integration in `RiskProfileConfigurationService.cs` - profile loading and caching
|
||||
- **POLICY-RISK-66-004**: Hashing in `RiskProfileHasher.cs` - deterministic content hashing
|
||||
- **POLICY-RISK-67-001a**: Scoring triggers in `RiskScoringTriggerService.cs` - finding change event handling
|
||||
- **POLICY-RISK-67-001b**: Lifecycle in `RiskProfileLifecycleService.cs` - draft/active/deprecated/archived states
|
||||
|
||||
### Reachability Integration (POLICY-ENGINE-80-00X)
|
||||
|
||||
- **POLICY-ENGINE-80-002**: Joining layer implemented in `ReachabilityFacts/` directory:
|
||||
- `ReachabilityFactsModels.cs` - Data models for reachability facts with state, confidence, score
|
||||
- `ReachabilityFactsStore.cs` - Store interface with InMemory implementation and MongoDB index definitions
|
||||
- `ReachabilityFactsOverlayCache.cs` - In-memory overlay cache with TTL eviction
|
||||
- `ReachabilityFactsJoiningService.cs` - Batch lookup service with cache-first strategy
|
||||
|
||||
- **POLICY-ENGINE-80-003**: SPL predicates extended in `Evaluation/`:
|
||||
- `PolicyEvaluationContext.cs` - Added `PolicyEvaluationReachability` record with state/confidence/score
|
||||
- `PolicyExpressionEvaluator.cs` - Added `ReachabilityScope` for SPL expressions like:
|
||||
- `reachability.state == "reachable"`
|
||||
- `reachability.confidence >= 0.8`
|
||||
- `reachability.is_high_confidence`
|
||||
|
||||
- **POLICY-ENGINE-80-004**: Metrics emitted via `PolicyEngineTelemetry.cs`:
|
||||
- `policy_reachability_applied_total{state}` - Facts applied during evaluation
|
||||
- `policy_reachability_cache_hits_total` / `policy_reachability_cache_misses_total`
|
||||
- `policy_reachability_cache_hit_ratio` - Observable gauge
|
||||
- `policy_reachability_lookups_total{outcome}` / `policy_reachability_lookup_seconds`
|
||||
|
||||
### Sprint Status
|
||||
|
||||
All 15 tasks in Sprint 127 are now DONE.
|
||||
|
||||
@@ -10,18 +10,18 @@ Focus: Policy & Reasoning focus on Policy (phase VI).
|
||||
|
||||
| # | Task ID & handle | State | Key dependency / next step | Owners |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | POLICY-RISK-67-002 | TODO | Implement profile lifecycle APIs (`/risk/profiles` create/publish/deprecate) and scope attachment logic (Deps: POLICY-RISK-67-001) | Policy Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 2 | POLICY-RISK-67-002 | TODO | Publish `.well-known/risk-profile-schema` endpoint and CLI validation tooling (Deps: POLICY-RISK-67-002) | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 3 | POLICY-RISK-67-003 | TODO | Provide policy-layer APIs to trigger risk simulations and return distributions/contribution breakdowns (Deps: POLICY-RISK-67-002) | Policy Guild, Risk Engine Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 4 | POLICY-RISK-68-001 | TODO | Provide simulation API bridging Policy Studio with risk engine; returns distributions and top movers (Deps: POLICY-RISK-67-003) | Policy Guild, Policy Studio Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 5 | POLICY-RISK-68-001 | TODO | Implement scope selectors, precedence rules, and Authority attachment APIs (Deps: POLICY-RISK-68-001) | Risk Profile Schema Guild, Authority Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 6 | POLICY-RISK-68-002 | TODO | Add override/adjustment support with audit metadata and validation for conflicting rules (Deps: POLICY-RISK-68-001) | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 7 | POLICY-RISK-68-002 | TODO | Enable exporting/importing RiskProfiles with signatures via policy tooling (CLI + API) (Deps: POLICY-RISK-68-002) | Policy Guild, Export Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 8 | POLICY-RISK-69-001 | TODO | Emit events/notifications on profile publish, deprecate, and severity threshold changes (Deps: POLICY-RISK-68-002) | Policy Guild, Notifications Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 9 | POLICY-RISK-70-001 | TODO | Support exporting/importing profiles with signatures for air-gapped bundles (Deps: POLICY-RISK-69-001) | Policy Guild, Export Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 10 | POLICY-SPL-23-001 | TODO | Define SPL v1 YAML + JSON Schema, including advisory rules, VEX precedence, severity mapping, exceptions, and layering metadata. Publish schema resources and validation fixtures | Policy Guild, Language Infrastructure Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 11 | POLICY-SPL-23-002 | TODO | Implement canonicalizer that normalizes policy packs (ordering, defaults), computes content hash, and prepares bundle metadata for AOC/signing (Deps: POLICY-SPL-23-001) | Policy Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 12 | POLICY-SPL-23-003 | TODO | Build policy layering/override engine (global/org/project/env/exception) with field-level precedence matrices; add unit/property tests (Deps: POLICY-SPL-23-002) | Policy Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 13 | POLICY-SPL-23-004 | TODO | Design explanation tree model (rule hits, inputs, decisions) and persistence structures reused by runtime, UI, and CLI (Deps: POLICY-SPL-23-003) | Policy Guild, Audit Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 14 | POLICY-SPL-23-005 | TODO | Create migration tool to snapshot existing behavior into baseline SPL packs (`org.core.baseline`), including policy docs and sample bundles (Deps: POLICY-SPL-23-004) | Policy Guild, DevEx Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 15 | POLICY-SPL-24-001 | TODO | Extend SPL schema to expose reachability/exploitability predicates and weighting functions; update documentation and fixtures (Deps: POLICY-SPL-23-005) | Policy Guild, Signals Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 1 | POLICY-RISK-67-002 | DONE | Implement profile lifecycle APIs (`/risk/profiles` create/publish/deprecate) and scope attachment logic (Deps: POLICY-RISK-67-001) | Policy Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 2 | POLICY-RISK-67-002 | DONE | Publish `.well-known/risk-profile-schema` endpoint and CLI validation tooling (Deps: POLICY-RISK-67-002) | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 3 | POLICY-RISK-67-003 | DONE | Provide policy-layer APIs to trigger risk simulations and return distributions/contribution breakdowns (Deps: POLICY-RISK-67-002) | Policy Guild, Risk Engine Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 4 | POLICY-RISK-68-001 | DONE | Provide simulation API bridging Policy Studio with risk engine; returns distributions and top movers (Deps: POLICY-RISK-67-003) | Policy Guild, Policy Studio Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 5 | POLICY-RISK-68-001 | DONE | Implement scope selectors, precedence rules, and Authority attachment APIs (Deps: POLICY-RISK-68-001) | Risk Profile Schema Guild, Authority Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 6 | POLICY-RISK-68-002 | DONE | Add override/adjustment support with audit metadata and validation for conflicting rules (Deps: POLICY-RISK-68-001) | Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile |
|
||||
| 7 | POLICY-RISK-68-002 | DONE | Enable exporting/importing RiskProfiles with signatures via policy tooling (CLI + API) (Deps: POLICY-RISK-68-002) | Policy Guild, Export Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 8 | POLICY-RISK-69-001 | DONE | Emit events/notifications on profile publish, deprecate, and severity threshold changes (Deps: POLICY-RISK-68-002) | Policy Guild, Notifications Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 9 | POLICY-RISK-70-001 | DONE | Support exporting/importing profiles with signatures for air-gapped bundles (Deps: POLICY-RISK-69-001) | Policy Guild, Export Guild / src/Policy/StellaOps.Policy.Engine |
|
||||
| 10 | POLICY-SPL-23-001 | DONE | Define SPL v1 YAML + JSON Schema, including advisory rules, VEX precedence, severity mapping, exceptions, and layering metadata. Publish schema resources and validation fixtures | Policy Guild, Language Infrastructure Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 11 | POLICY-SPL-23-002 | DONE | Implement canonicalizer that normalizes policy packs (ordering, defaults), computes content hash, and prepares bundle metadata for AOC/signing (Deps: POLICY-SPL-23-001) | Policy Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 12 | POLICY-SPL-23-003 | DONE | Build policy layering/override engine (global/org/project/env/exception) with field-level precedence matrices; add unit/property tests (Deps: POLICY-SPL-23-002) | Policy Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 13 | POLICY-SPL-23-004 | DONE | Design explanation tree model (rule hits, inputs, decisions) and persistence structures reused by runtime, UI, and CLI (Deps: POLICY-SPL-23-003) | Policy Guild, Audit Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 14 | POLICY-SPL-23-005 | DONE | Create migration tool to snapshot existing behavior into baseline SPL packs (`org.core.baseline`), including policy docs and sample bundles (Deps: POLICY-SPL-23-004) | Policy Guild, DevEx Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
| 15 | POLICY-SPL-24-001 | DONE | Extend SPL schema to expose reachability/exploitability predicates and weighting functions; update documentation and fixtures (Deps: POLICY-SPL-23-005) | Policy Guild, Signals Guild / src/Policy/__Libraries/StellaOps.Policy |
|
||||
|
||||
@@ -7,22 +7,57 @@ Dependency: Sprint 131 - 2. Scanner.II — Scanner & Surface focus on Scanner (p
|
||||
|
||||
| Task ID | State | Summary | Owner / Source | Depends On |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `SCANNER-ANALYZERS-LANG-11-002` | TODO | Implement static analyzer (IL + reflection heuristics) capturing AssemblyRef, ModuleRef/PInvoke, DynamicDependency, reflection literals, DI patterns, and custom AssemblyLoadContext probing hints. Emit dependency edges with reason codes and confidence. | StellaOps.Scanner EPDR Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-001 |
|
||||
| `SCANNER-ANALYZERS-LANG-11-003` | TODO | Ingest optional runtime evidence (AssemblyLoad, Resolving, P/Invoke) via event listener harness; merge runtime edges with static/declared ones and attach reason codes/confidence. | StellaOps.Scanner EPDR Guild, Signals Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-002 |
|
||||
| `SCANNER-ANALYZERS-LANG-11-004` | TODO | Produce normalized observation export to Scanner writer: entrypoints + dependency edges + environment profiles (AOC compliant). Wire to SBOM service entrypoint tagging. | StellaOps.Scanner EPDR Guild, SBOM Service Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-003 |
|
||||
| `SCANNER-ANALYZERS-LANG-11-005` | TODO | Add comprehensive fixtures/benchmarks covering framework-dependent, self-contained, single-file, trimmed, NativeAOT, multi-RID scenarios; include explain traces and perf benchmarks vs previous analyzer. | StellaOps.Scanner EPDR Guild, QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-004 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-001` | TODO | Implement format detector and binary identity model supporting ELF, PE/COFF, and Mach-O (including fat slices). Capture arch, OS, build-id/UUID, interpreter metadata. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | — |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-002` | TODO | Parse ELF dynamic sections: `DT_NEEDED`, `DT_RPATH`, `DT_RUNPATH`, symbol versions, interpreter, and note build-id. Emit declared dependency records with reason `elf-dtneeded` and attach version needs. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-001 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-003` | TODO | Parse PE imports, delay-load tables, manifests/SxS metadata, and subsystem flags. Emit edges with reasons `pe-import` and `pe-delayimport`, plus SxS policy metadata. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-002 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-004` | TODO | Parse Mach-O load commands (`LC_LOAD_DYLIB`, `LC_REEXPORT_DYLIB`, `LC_RPATH`, `LC_UUID`, fat headers). Handle `@rpath/@loader_path` placeholders and slice separation. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-003 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-005` | TODO | Implement resolver engine modeling loader search order for ELF (rpath/runpath/cache/default), PE (SafeDll search + SxS), and Mach-O (`@rpath` expansion). Works against virtual image roots, producing explain traces. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-004 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-006` | TODO | Build heuristic scanner for `dlopen`/`LoadLibrary` strings, plugin ecosystem configs, and Go/Rust static hints. Emit edges with `reason_code` (`string-dlopen`, `config-plugin`, `ecosystem-heuristic`) and confidence levels. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-005 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-007` | TODO | Serialize AOC-compliant observations: entrypoints + dependency edges + environment profiles (search paths, interpreter, loader metadata). Integrate with Scanner writer API. | Native Analyzer Guild, SBOM Service Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-006 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-008` | TODO | Author cross-platform fixtures (ELF dynamic/static, PE delay-load/SxS, Mach-O @rpath, plugin configs) and determinism benchmarks (<25 ms / binary, <250 MB). | Native Analyzer Guild, QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-007 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-009` | TODO | Provide optional runtime capture adapters (Linux eBPF `dlopen`, Windows ETW ImageLoad, macOS dyld interpose) writing append-only runtime evidence. Include redaction/sandbox guidance. | Native Analyzer Guild, Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-008 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-010` | TODO | Package native analyzer as restart-time plug-in with manifest/DI registration; update Offline Kit bundle + documentation. | Native Analyzer Guild, DevOps Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-009 |
|
||||
| `SCANNER-ANALYZERS-LANG-11-002` | BLOCKED | Implement static analyzer (IL + reflection heuristics) capturing AssemblyRef, ModuleRef/PInvoke, DynamicDependency, reflection literals, DI patterns, and custom AssemblyLoadContext probing hints. Emit dependency edges with reason codes and confidence. | StellaOps.Scanner EPDR Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-001 |
|
||||
| `SCANNER-ANALYZERS-LANG-11-003` | BLOCKED | Ingest optional runtime evidence (AssemblyLoad, Resolving, P/Invoke) via event listener harness; merge runtime edges with static/declared ones and attach reason codes/confidence. | StellaOps.Scanner EPDR Guild, Signals Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-002 |
|
||||
| `SCANNER-ANALYZERS-LANG-11-004` | BLOCKED | Produce normalized observation export to Scanner writer: entrypoints + dependency edges + environment profiles (AOC compliant). Wire to SBOM service entrypoint tagging. | StellaOps.Scanner EPDR Guild, SBOM Service Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-003 |
|
||||
| `SCANNER-ANALYZERS-LANG-11-005` | BLOCKED | Add comprehensive fixtures/benchmarks covering framework-dependent, self-contained, single-file, trimmed, NativeAOT, multi-RID scenarios; include explain traces and perf benchmarks vs previous analyzer. | StellaOps.Scanner EPDR Guild, QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | SCANNER-ANALYZERS-LANG-11-004 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-001` | DONE | Implement format detector and binary identity model supporting ELF, PE/COFF, and Mach-O (including fat slices). Capture arch, OS, build-id/UUID, interpreter metadata. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | — |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-002` | DONE | Parse ELF dynamic sections: `DT_NEEDED`, `DT_RPATH`, `DT_RUNPATH`, symbol versions, interpreter, and note build-id. Emit declared dependency records with reason `elf-dtneeded` and attach version needs. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-001 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-003` | DONE | Parse PE imports, delay-load tables, manifests/SxS metadata, and subsystem flags. Emit edges with reasons `pe-import` and `pe-delayimport`, plus SxS policy metadata. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-002 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-004` | DONE | Parse Mach-O load commands (`LC_LOAD_DYLIB`, `LC_REEXPORT_DYLIB`, `LC_RPATH`, `LC_UUID`, fat headers). Handle `@rpath/@loader_path` placeholders and slice separation. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-003 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-005` | DONE | Implement resolver engine modeling loader search order for ELF (rpath/runpath/cache/default), PE (SafeDll search + SxS), and Mach-O (`@rpath` expansion). Works against virtual image roots, producing explain traces. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-004 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-006` | DONE | Build heuristic scanner for `dlopen`/`LoadLibrary` strings, plugin ecosystem configs, and Go/Rust static hints. Emit edges with `reason_code` (`string-dlopen`, `config-plugin`, `ecosystem-heuristic`) and confidence levels. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-005 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-007` | DONE | Serialize AOC-compliant observations: entrypoints + dependency edges + environment profiles (search paths, interpreter, loader metadata). Integrate with Scanner writer API. | Native Analyzer Guild, SBOM Service Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-006 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-008` | DONE | Author cross-platform fixtures (ELF dynamic/static, PE delay-load/SxS, Mach-O @rpath, plugin configs) and determinism benchmarks (<25 ms / binary, <250 MB). | Native Analyzer Guild, QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-007 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-009` | DONE | Provide optional runtime capture adapters (Linux eBPF `dlopen`, Windows ETW ImageLoad, macOS dyld interpose) writing append-only runtime evidence. Include redaction/sandbox guidance. | Native Analyzer Guild, Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-008 |
|
||||
| `SCANNER-ANALYZERS-NATIVE-20-010` | DONE | Package native analyzer as restart-time plug-in with manifest/DI registration; update Offline Kit bundle + documentation. | Native Analyzer Guild, DevOps Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | SCANNER-ANALYZERS-NATIVE-20-009 |
|
||||
| `SCANNER-ANALYZERS-NODE-22-001` | TODO | Build input normalizer + VFS for Node projects: dirs, tgz, container layers, pnpm store, Yarn PnP zips; detect Node version targets (`.nvmrc`, `.node-version`, Dockerfile) and workspace roots deterministically. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | — |
|
||||
| `SCANNER-ANALYZERS-NODE-22-002` | TODO | Implement entrypoint discovery (bin/main/module/exports/imports, workers, electron, shebang scripts) and condition set builder per entrypoint. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | SCANNER-ANALYZERS-NODE-22-001 |
|
||||
| `SCANNER-ANALYZERS-NODE-22-003` | TODO | Parse JS/TS sources for static `import`, `require`, `import()` and string concat cases; flag dynamic patterns with confidence levels; support source map de-bundling. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | SCANNER-ANALYZERS-NODE-22-002 |
|
||||
| `SCANNER-ANALYZERS-NODE-22-004` | TODO | Implement Node resolver engine for CJS + ESM (core modules, exports/imports maps, conditions, extension priorities, self-references) parameterised by node_version. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | SCANNER-ANALYZERS-NODE-22-003 |
|
||||
| `SCANNER-ANALYZERS-NODE-22-005` | TODO | Add package manager adapters: Yarn PnP (.pnp.data/.pnp.cjs), pnpm virtual store, npm/Yarn classic hoists; operate entirely in virtual FS. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | SCANNER-ANALYZERS-NODE-22-004 |
|
||||
|
||||
## Status Notes (2025-11-27)
|
||||
|
||||
### Native Analyzer (NATIVE-20-xxx): DONE
|
||||
All 10 tasks completed. Implementation verified with 165 passing tests.
|
||||
|
||||
**Implemented components:**
|
||||
- `NativeFormatDetector.cs` - Format detection for ELF/PE/Mach-O with binary identity
|
||||
- `ElfDynamicSectionParser.cs` - ELF dynamic sections, DT_NEEDED, rpath/runpath
|
||||
- `PeImportParser.cs` - PE imports, delay-load, manifests, subsystem flags
|
||||
- `MachOLoadCommandParser.cs` - Mach-O load commands, @rpath, fat binaries
|
||||
- `NativeResolver.cs` - Cross-platform loader search order modeling
|
||||
- `HeuristicScanner.cs` - dlopen/LoadLibrary string detection, plugin configs
|
||||
- `Observations/` - AOC-compliant observation builder and serializer
|
||||
- `RuntimeCapture/` - Linux eBPF, Windows ETW, macOS dyld adapters
|
||||
- `Plugin/` - Plugin packaging with DI registration
|
||||
|
||||
### DotNet Analyzer (LANG-11-xxx): BLOCKED
|
||||
Tasks 11-002 through 11-005 are blocked pending SCANNER-ANALYZERS-LANG-11-001 from Sprint 131.
|
||||
|
||||
**Blocker:** SCANNER-ANALYZERS-LANG-11-001 (not in this sprint) must implement the foundation for IL analysis before static analyzer heuristics can be built.
|
||||
|
||||
### Node Analyzer (NODE-22-xxx): TODO
|
||||
Tasks 22-001 through 22-005 remain TODO. Existing infrastructure provides partial coverage:
|
||||
- `NodePackageCollector` - handles dirs, tgz, Yarn PnP cache
|
||||
- `NodeVersionDetector` - detects .nvmrc, .node-version, Dockerfile
|
||||
- `NodeWorkspaceIndex` - workspace root detection
|
||||
- `NodeImportWalker` - basic import/require parsing
|
||||
|
||||
**Missing components for Sprint 132:**
|
||||
- Full VFS abstraction for container layers and pnpm store (22-001)
|
||||
- Exports/imports map handling and condition set builder (22-002)
|
||||
- Dynamic pattern confidence levels and source map support (22-003)
|
||||
- Complete Node resolver engine for CJS+ESM (22-004)
|
||||
- pnpm virtual store adapter (22-005)
|
||||
|
||||
@@ -14,10 +14,10 @@ Dependency: Sprint 132 - 3. Scanner.III — Scanner & Surface focus on Scanner (
|
||||
| `SCANNER-ANALYZERS-NODE-22-010` | TODO | Implement optional runtime evidence hooks (ESM loader, CJS require hook) with path scrubbing and loader ID hashing; emit runtime-* edges. | Node Analyzer Guild, Signals Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | SCANNER-ANALYZERS-NODE-22-009 |
|
||||
| `SCANNER-ANALYZERS-NODE-22-011` | TODO | Package updated analyzer as restart-time plug-in, expose Scanner CLI (`stella node *`) commands, refresh Offline Kit documentation. | Node Analyzer Guild, DevOps Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | SCANNER-ANALYZERS-NODE-22-010 |
|
||||
| `SCANNER-ANALYZERS-NODE-22-012` | TODO | Integrate container filesystem adapter (OCI layers, Dockerfile hints) and record NODE_OPTIONS/env warnings. | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | SCANNER-ANALYZERS-NODE-22-011 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-001` | TODO | Build input normalizer & VFS for PHP projects: merge source trees, composer manifests, vendor/, php.ini/conf.d, `.htaccess`, FPM configs, container layers. Detect framework/CMS fingerprints deterministically. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | — |
|
||||
| `SCANNER-ANALYZERS-PHP-27-002` | TODO | Composer/Autoload analyzer: parse composer.json/lock/installed.json, generate package nodes, autoload edges (psr-4/0/classmap/files), bin entrypoints, composer plugins. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-001 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-003` | TODO | Include/require graph builder: resolve static includes, capture dynamic include patterns, bootstrap chains, merge with autoload edges. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-002 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-004` | TODO | Runtime capability scanner: detect exec/fs/net/env/serialization/crypto/database usage, stream wrappers, uploads; record evidence snippets. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-003 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-005` | TODO | PHAR/Archive inspector: parse phar manifests/stubs, hash files, detect embedded vendor trees and phar:// usage. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-004 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-006` | TODO | Framework/CMS surface mapper: extract routes, controllers, middleware, CLI/cron entrypoints for Laravel/Symfony/Slim/WordPress/Drupal/Magento. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-005 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-007` | TODO | Container & extension detector: parse php.ini/conf.d, map extensions to .so/.dll, collect web server/FPM settings, upload limits, disable_functions. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-006 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-001` | DONE | Build input normalizer & VFS for PHP projects: merge source trees, composer manifests, vendor/, php.ini/conf.d, `.htaccess`, FPM configs, container layers. Detect framework/CMS fingerprints deterministically. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | — |
|
||||
| `SCANNER-ANALYZERS-PHP-27-002` | DONE | Composer/Autoload analyzer: parse composer.json/lock/installed.json, generate package nodes, autoload edges (psr-4/0/classmap/files), bin entrypoints, composer plugins. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-001 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-003` | DONE | Include/require graph builder: resolve static includes, capture dynamic include patterns, bootstrap chains, merge with autoload edges. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-002 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-004` | DONE | Runtime capability scanner: detect exec/fs/net/env/serialization/crypto/database usage, stream wrappers, uploads; record evidence snippets. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-003 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-005` | DONE | PHAR/Archive inspector: parse phar manifests/stubs, hash files, detect embedded vendor trees and phar:// usage. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-004 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-006` | DONE | Framework/CMS surface mapper: extract routes, controllers, middleware, CLI/cron entrypoints for Laravel/Symfony/Slim/WordPress/Drupal/Magento. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-005 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-007` | DONE | Container & extension detector: parse php.ini/conf.d, map extensions to .so/.dll, collect web server/FPM settings, upload limits, disable_functions. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-006 |
|
||||
|
||||
@@ -7,14 +7,14 @@ Dependency: Sprint 133 - 4. Scanner.IV — Scanner & Surface focus on Scanner (p
|
||||
|
||||
| Task ID | State | Summary | Owner / Source | Depends On |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `SCANNER-ANALYZERS-PHP-27-009` | TODO | Fixture suite + performance benchmarks (Laravel, Symfony, WordPress, legacy, PHAR, container) with golden outputs. | PHP Analyzer Guild, QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-007 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-010` | TODO | Optional runtime evidence hooks (if provided) to ingest audit logs or opcode cache stats with path hashing. | PHP Analyzer Guild, Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-009 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-011` | TODO | Package analyzer plug-in, add CLI (`stella php inspect`), refresh Offline Kit documentation. | PHP Analyzer Guild, DevOps Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-010 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-012` | TODO | Policy signal emitter: extension requirements/presence, dangerous constructs counters, stream wrapper usage, capability summaries. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-011 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-008` | TODO | Produce AOC-compliant observations: entrypoints, packages, extensions, modules, edges (require/autoload), capabilities, routes, configs. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-002 |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-001` | TODO | Build input normalizer & virtual filesystem for wheels, sdists, editable installs, zipapps, site-packages trees, and container roots. Detect Python version targets (`pyproject.toml`, `runtime.txt`, Dockerfile) + virtualenv layout deterministically. | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | — |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-002` | TODO | Entrypoint discovery: module `__main__`, console_scripts entry points, `scripts`, zipapp main, `manage.py`/gunicorn/celery patterns. Capture invocation context (module vs package, argv wrappers). | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-001 |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-003` | TODO | Static import graph builder using AST and bytecode fallback. Support `import`, `from ... import`, relative imports, `importlib.import_module`, `__import__` with literal args, `pkgutil.extend_path`. | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-002 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-009` | BLOCKED | Fixture suite + performance benchmarks (Laravel, Symfony, WordPress, legacy, PHAR, container) with golden outputs. | PHP Analyzer Guild, QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-007 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-010` | BLOCKED | Optional runtime evidence hooks (if provided) to ingest audit logs or opcode cache stats with path hashing. | PHP Analyzer Guild, Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-009 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-011` | BLOCKED | Package analyzer plug-in, add CLI (`stella php inspect`), refresh Offline Kit documentation. | PHP Analyzer Guild, DevOps Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-010 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-012` | BLOCKED | Policy signal emitter: extension requirements/presence, dangerous constructs counters, stream wrapper usage, capability summaries. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-011 |
|
||||
| `SCANNER-ANALYZERS-PHP-27-008` | BLOCKED | Produce AOC-compliant observations: entrypoints, packages, extensions, modules, edges (require/autoload), capabilities, routes, configs. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | SCANNER-ANALYZERS-PHP-27-002 |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-001` | DONE | Build input normalizer & virtual filesystem for wheels, sdists, editable installs, zipapps, site-packages trees, and container roots. Detect Python version targets (`pyproject.toml`, `runtime.txt`, Dockerfile) + virtualenv layout deterministically. | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | — |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-002` | DONE | Entrypoint discovery: module `__main__`, console_scripts entry points, `scripts`, zipapp main, `manage.py`/gunicorn/celery patterns. Capture invocation context (module vs package, argv wrappers). | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-001 |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-003` | DONE | Static import graph builder using AST and bytecode fallback. Support `import`, `from ... import`, relative imports, `importlib.import_module`, `__import__` with literal args, `pkgutil.extend_path`. | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-002 |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-004` | TODO | Python resolver engine (importlib semantics) handling namespace packages (PEP 420), package discovery order, `.pth` files, `sys.path` composition, zipimport, and site-packages precedence across virtualenv/container roots. | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-003 |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-005` | TODO | Packaging adapters: pip editable (`.egg-link`), Poetry/Flit layout, Conda prefix, `.dist-info/RECORD` cross-check, container layer overlays. | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-004 |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-006` | TODO | Detect native extensions (`*.so`, `*.pyd`), CFFI modules, ctypes loaders, embedded WASM, and runtime capability signals (subprocess, multiprocessing, ctypes, eval). | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-005 |
|
||||
|
||||
@@ -8,17 +8,17 @@ Dependency: Sprint 134 - 5. Scanner.V — Scanner & Surface focus on Scanner (ph
|
||||
| Task ID | State | Summary | Owner / Source | Depends On |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `SCANNER-ANALYZERS-PYTHON-23-012` | TODO | Container/zipapp adapter enhancements: parse OCI layers for Python runtime, detect `PYTHONPATH`/`PYTHONHOME` env, record warnings for sitecustomize/startup hooks. | Python Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python) | SCANNER-ANALYZERS-PYTHON-23-011 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-001` | TODO | Build input normalizer & VFS for Ruby projects: merge source trees, Gemfile/Gemfile.lock, vendor/bundle, .gem archives, `.bundle/config`, Rack configs, containers. Detect framework/job fingerprints deterministically. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | — |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-002` | TODO | Gem & Bundler analyzer: parse Gemfile/Gemfile.lock, vendor specs, .gem archives, produce package nodes (PURLs), dependency edges, bin scripts, Bundler group metadata. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-001 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-003` | TODO | Require/autoload graph builder: resolve static/dynamic require, require_relative, load; infer Zeitwerk autoload paths and Rack boot chain. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-002 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-004` | TODO | Framework surface mapper: extract routes/controllers/middleware for Rails/Rack/Sinatra/Grape/Hanami; inventory jobs/schedulers (Sidekiq, Resque, ActiveJob, whenever, clockwork). | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-003 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-005` | TODO | Capability analyzer: detect os-exec, filesystem, network, serialization, crypto, DB usage, TLS posture, dynamic eval; record evidence snippets with file/line. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-004 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-006` | TODO | Rake task & scheduler analyzer: parse Rakefiles/lib/tasks, capture task names/prereqs/shell commands; parse Sidekiq/whenever/clockwork configs into schedules. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-005 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-007` | TODO | Container/runtime scanner: detect Ruby version, installed gems, native extensions, web server configs in OCI layers. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-006 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-008` | TODO | Produce AOC-compliant observations: entrypoints, packages, modules, edges (require/autoload), routes, jobs, tasks, capabilities, configs, warnings. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-007 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-009` | TODO | Fixture suite + performance benchmarks (Rails, Rack, Sinatra, Sidekiq, legacy, .gem, container) with golden outputs. | Ruby Analyzer Guild, QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-008 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-010` | TODO | Optional runtime evidence integration (if provided logs/metrics) with path hashing, without altering static precedence. | Ruby Analyzer Guild, Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-009 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-011` | TODO | Package analyzer plug-in, add CLI (`stella ruby inspect`), refresh Offline Kit documentation. | Ruby Analyzer Guild, DevOps Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-010 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-001` | DONE | Build input normalizer & VFS for Ruby projects: merge source trees, Gemfile/Gemfile.lock, vendor/bundle, .gem archives, `.bundle/config`, Rack configs, containers. Detect framework/job fingerprints deterministically. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | — |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-002` | DONE | Gem & Bundler analyzer: parse Gemfile/Gemfile.lock, vendor specs, .gem archives, produce package nodes (PURLs), dependency edges, bin scripts, Bundler group metadata. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-001 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-003` | DONE | Require/autoload graph builder: resolve static/dynamic require, require_relative, load; infer Zeitwerk autoload paths and Rack boot chain. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-002 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-004` | DONE | Framework surface mapper: extract routes/controllers/middleware for Rails/Rack/Sinatra/Grape/Hanami; inventory jobs/schedulers (Sidekiq, Resque, ActiveJob, whenever, clockwork). | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-003 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-005` | DONE | Capability analyzer: detect os-exec, filesystem, network, serialization, crypto, DB usage, TLS posture, dynamic eval; record evidence snippets with file/line. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-004 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-006` | DONE | Rake task & scheduler analyzer: parse Rakefiles/lib/tasks, capture task names/prereqs/shell commands; parse Sidekiq/whenever/clockwork configs into schedules. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-005 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-007` | DONE | Container/runtime scanner: detect Ruby version, installed gems, native extensions, web server configs in OCI layers. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-006 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-008` | DONE | Produce AOC-compliant observations: entrypoints, packages, modules, edges (require/autoload), routes, jobs, tasks, capabilities, configs, warnings. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-007 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-009` | DONE | Fixture suite + performance benchmarks (Rails, Rack, Sinatra, Sidekiq, legacy, .gem, container) with golden outputs. | Ruby Analyzer Guild, QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-008 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-010` | DONE | Optional runtime evidence integration (if provided logs/metrics) with path hashing, without altering static precedence. | Ruby Analyzer Guild, Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-009 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-011` | DONE | Package analyzer plug-in, add CLI (`stella ruby inspect`), refresh Offline Kit documentation. | Ruby Analyzer Guild, DevOps Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-010 |
|
||||
| `SCANNER-ANALYZERS-RUBY-28-012` | TODO | Policy signal emitter: rubygems drift, native extension flags, dangerous constructs counts, TLS verify posture, dynamic require eval warnings. | Ruby Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby) | SCANNER-ANALYZERS-RUBY-28-011 |
|
||||
| `SCANNER-ENTRYTRACE-18-502` | TODO | Expand chain walker with init shim/user-switch/supervisor recognition plus env/workdir accumulation and guarded edges. | EntryTrace Guild (src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace) | SCANNER-ENTRYTRACE-18-508 |
|
||||
| `SCANNER-ENTRYTRACE-18-503` | TODO | Introduce target classifier + EntryPlan handoff with confidence scoring for ELF/Java/.NET/Node/Python and user/workdir context. | EntryTrace Guild (src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace) | SCANNER-ENTRYTRACE-18-502 |
|
||||
|
||||
@@ -11,12 +11,12 @@ Dependency: Sprint 135 - 6. Scanner.VI — Scanner & Surface focus on Scanner (p
|
||||
| `SCANNER-ENTRYTRACE-18-505` | TODO | Implement process-tree replay (ProcGraph) to reconcile `/proc` exec chains with static EntryTrace results, collapsing wrappers and emitting agreement/conflict diagnostics. | EntryTrace Guild (src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace) | SCANNER-ENTRYTRACE-18-504 |
|
||||
| `SCANNER-ENTRYTRACE-18-506` | TODO | Surface EntryTrace graph + confidence via Scanner.WebService and CLI, including target summary in scan reports and policy payloads. | EntryTrace Guild, Scanner WebService Guild (src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace) | SCANNER-ENTRYTRACE-18-505 |
|
||||
| `SCANNER-ENV-01` | DONE (2025-11-18) | Worker already wired to `AddSurfaceEnvironment`/`ISurfaceEnvironment` for cache roots + CAS endpoints; no remaining ad-hoc env reads. | Scanner Worker Guild (src/Scanner/StellaOps.Scanner.Worker) | — |
|
||||
| `SCANNER-ENV-02` | TODO (2025-11-06) | Wire Surface.Env helpers into WebService hosting (cache roots, feature flags) and document configuration. | Scanner WebService Guild, Ops Guild (src/Scanner/StellaOps.Scanner.WebService) | SCANNER-ENV-01 |
|
||||
| `SCANNER-ENV-03` | DOING (2025-11-23) | Surface.Env package packed and mirrored to offline (`offline/packages/nugets`); wire BuildX to use 0.1.0-alpha.20251123 and update restore feeds. | BuildX Plugin Guild (src/Scanner/StellaOps.Scanner.Sbomer.BuildXPlugin) | SCANNER-ENV-02 |
|
||||
| `SCANNER-ENV-02` | DONE (2025-11-27) | Wire Surface.Env helpers into WebService hosting (cache roots, feature flags) and document configuration. | Scanner WebService Guild, Ops Guild (src/Scanner/StellaOps.Scanner.WebService) | SCANNER-ENV-01 |
|
||||
| `SCANNER-ENV-03` | DONE (2025-11-27) | Surface.Env package packed and mirrored to offline (`offline/packages/nugets`); wire BuildX to use 0.1.0-alpha.20251123 and update restore feeds. | BuildX Plugin Guild (src/Scanner/StellaOps.Scanner.Sbomer.BuildXPlugin) | SCANNER-ENV-02 |
|
||||
| `SURFACE-ENV-01` | DONE (2025-11-13) | Draft `surface-env.md` enumerating environment variables, defaults, and air-gap behaviour for Surface consumers. | Scanner Guild, Zastava Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Env) | — |
|
||||
| `SURFACE-ENV-02` | DONE (2025-11-18) | Strongly-typed env accessors implemented; validation covers required endpoint, bounds, TLS cert path; regression tests passing. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Env) | SURFACE-ENV-01 |
|
||||
| `SURFACE-ENV-03` | TODO | Adopt the env helper across Scanner Worker/WebService/BuildX plug-ins. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Env) | SURFACE-ENV-02 |
|
||||
| `SURFACE-ENV-04` | TODO | Wire env helper into Zastava Observer/Webhook containers. | Zastava Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Env) | SURFACE-ENV-02 |
|
||||
| `SURFACE-ENV-03` | DONE (2025-11-27) | Adopt the env helper across Scanner Worker/WebService/BuildX plug-ins. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Env) | SURFACE-ENV-02 |
|
||||
| `SURFACE-ENV-04` | DONE (2025-11-27) | Wire env helper into Zastava Observer/Webhook containers. | Zastava Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Env) | SURFACE-ENV-02 |
|
||||
| `SURFACE-ENV-05` | TODO | Update Helm/Compose/offline kit templates with new env knobs and documentation. | Ops Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Env) | SURFACE-ENV-03, SURFACE-ENV-04 |
|
||||
| `SCANNER-EVENTS-16-301` | BLOCKED (2025-10-26) | Emit orchestrator-compatible envelopes (`scanner.event.*`) and update integration tests to verify Notifier ingestion (no Redis queue coupling). | Scanner WebService Guild (src/Scanner/StellaOps.Scanner.WebService) | — |
|
||||
| `SCANNER-GRAPH-21-001` | TODO | Provide webhook/REST endpoint for Cartographer to request policy overlays and runtime evidence for graph nodes, ensuring determinism and tenant scoping. | Scanner WebService Guild, Cartographer Guild (src/Scanner/StellaOps.Scanner.WebService) | — |
|
||||
@@ -25,10 +25,10 @@ Dependency: Sprint 135 - 6. Scanner.VI — Scanner & Surface focus on Scanner (p
|
||||
| `SCANNER-SECRETS-03` | TODO | Use Surface.Secrets to retrieve registry credentials when interacting with CAS/referrers. | BuildX Plugin Guild, Security Guild (src/Scanner/StellaOps.Scanner.Sbomer.BuildXPlugin) | SCANNER-SECRETS-02 |
|
||||
| `SURFACE-SECRETS-01` | DONE (2025-11-23) | Security-approved schema published at `docs/modules/scanner/design/surface-secrets-schema.md`; proceed to provider wiring. | Scanner Guild, Security Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | — |
|
||||
| `SURFACE-SECRETS-02` | DONE (2025-11-23) | Provider chain implemented (primary + fallback) with DI wiring; tests updated (`StellaOps.Scanner.Surface.Secrets.Tests`). | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-01 |
|
||||
| `SURFACE-SECRETS-03` | TODO | Add Kubernetes/File/Offline backends with deterministic caching and audit hooks. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-02 |
|
||||
| `SURFACE-SECRETS-04` | TODO | Integrate Surface.Secrets into Scanner Worker/WebService/BuildX for registry + CAS creds. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-02 |
|
||||
| `SURFACE-SECRETS-05` | TODO | Invoke Surface.Secrets from Zastava Observer/Webhook for CAS & attestation secrets. | Zastava Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-02 |
|
||||
| `SURFACE-SECRETS-06` | TODO | Update deployment manifests/offline kit bundles to provision secret references instead of raw values. | Ops Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-03 |
|
||||
| `SURFACE-SECRETS-03` | DONE (2025-11-27) | Add Kubernetes/File/Offline backends with deterministic caching and audit hooks. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-02 |
|
||||
| `SURFACE-SECRETS-04` | DONE (2025-11-27) | Integrate Surface.Secrets into Scanner Worker/WebService/BuildX for registry + CAS creds. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-02 |
|
||||
| `SURFACE-SECRETS-05` | DONE (2025-11-27) | Invoke Surface.Secrets from Zastava Observer/Webhook for CAS & attestation secrets. | Zastava Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-02 |
|
||||
| `SURFACE-SECRETS-06` | BLOCKED (2025-11-27) | Update deployment manifests/offline kit bundles to provision secret references instead of raw values. Requires Ops Guild input on Helm/Compose patterns for Surface.Secrets provider configuration. | Ops Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets) | SURFACE-SECRETS-03 |
|
||||
| `SCANNER-ENG-0020` | TODO | Implement Homebrew collector & fragment mapper per `design/macos-analyzer.md` §3.1. | Scanner Guild (docs/modules/scanner) | — |
|
||||
| `SCANNER-ENG-0021` | TODO | Implement pkgutil receipt collector per `design/macos-analyzer.md` §3.2. | Scanner Guild (docs/modules/scanner) | — |
|
||||
| `SCANNER-ENG-0022` | TODO | Implement macOS bundle inspector & capability overlays per `design/macos-analyzer.md` §3.3. | Scanner Guild, Policy Guild (docs/modules/scanner) | — |
|
||||
@@ -50,12 +50,21 @@ Dependency: Sprint 135 - 6. Scanner.VI — Scanner & Surface focus on Scanner (p
|
||||
| `SURFACE-VAL-01` | DONE (2025-11-23) | Validation framework doc aligned with Surface.Env release and secrets schema (`docs/modules/scanner/design/surface-validation.md` v1.1). | Scanner Guild, Security Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Validation) | SURFACE-FS-01, SURFACE-ENV-01 |
|
||||
| `SURFACE-VAL-02` | DONE (2025-11-23) | Validation library now enforces secrets schema, fallback/provider checks, and inline/file guardrails; tests added. | Scanner Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Validation) | SURFACE-VAL-01, SURFACE-ENV-02, SURFACE-FS-02 |
|
||||
| `SURFACE-VAL-03` | DONE (2025-11-23) | Validation runner wired into Worker/WebService startup and pre-analyzer paths (OS, language, EntryTrace). | Scanner Guild, Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Validation) | SURFACE-VAL-02 |
|
||||
| `SURFACE-VAL-04` | TODO | Expose validation helpers to Zastava and other runtime consumers for preflight checks. | Scanner Guild, Zastava Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Validation) | SURFACE-VAL-02 |
|
||||
| `SURFACE-VAL-04` | DONE (2025-11-27) | Expose validation helpers to Zastava and other runtime consumers for preflight checks. | Scanner Guild, Zastava Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Validation) | SURFACE-VAL-02 |
|
||||
| `SURFACE-VAL-05` | TODO | Document validation extensibility, registration, and customization in scanner-engine guides. | Docs Guild (src/Scanner/__Libraries/StellaOps.Scanner.Surface.Validation) | SURFACE-VAL-02 |
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-11-27 | Added missing package references to BuildX plugin (Configuration.EnvironmentVariables, DependencyInjection, Logging); refactored to use public AddSurfaceEnvironment API instead of internal SurfaceEnvironmentFactory; build passes. SCANNER-ENV-03 DONE. | Implementer |
|
||||
| 2025-11-27 | Created SurfaceFeatureFlagsConfigurator to merge Surface.Env feature flags into WebService FeatureFlagOptions.Experimental dictionary; registered configurator in Program.cs. Cache roots and feature flags now wired from Surface.Env. SCANNER-ENV-02 DONE. | Implementer |
|
||||
| 2025-11-27 | Verified SURFACE-ENV-03: Scanner Worker (SCANNER-ENV-01), WebService (SCANNER-ENV-02), and BuildX (SCANNER-ENV-03) all wire Surface.Env helpers; task complete. SURFACE-ENV-03 DONE. | Implementer |
|
||||
| 2025-11-27 | Added CachingSurfaceSecretProvider (deterministic TTL cache), AuditingSurfaceSecretProvider (structured audit logging), and OfflineSurfaceSecretProvider (integrity-verified offline kit support); wired into ServiceCollectionExtensions with configurable options. SURFACE-SECRETS-03 DONE. | Implementer |
|
||||
| 2025-11-27 | Added Surface.Validation project references to Zastava Observer and Webhook; wired AddSurfaceValidation() in service extensions for preflight checks. SURFACE-VAL-04 DONE. | Implementer |
|
||||
| 2025-11-27 | Verified Zastava Observer and Webhook already have AddSurfaceEnvironment() wired with ZASTAVA prefixes; SURFACE-ENV-04 DONE. | Implementer |
|
||||
| 2025-11-27 | Added Surface.Secrets project reference to BuildX plugin; implemented TryResolveAttestationToken() to fetch attestation secrets from Surface.Secrets; Worker/WebService already had configurators for CAS/registry/attestation secrets. SURFACE-SECRETS-04 DONE. | Implementer |
|
||||
| 2025-11-27 | Verified Zastava Observer/Webhook already have ObserverSurfaceSecrets/WebhookSurfaceSecrets classes using ISurfaceSecretProvider for CAS and attestation secrets. SURFACE-SECRETS-05 DONE. | Implementer |
|
||||
| 2025-11-27 | SURFACE-SECRETS-06 marked BLOCKED: requires Ops Guild input on Helm/Compose patterns for Surface.Secrets provider configuration (kubernetes/file/inline). Added to Decisions & Risks. | Implementer |
|
||||
| 2025-11-23 | Published Security-approved Surface.Secrets schema (`docs/modules/scanner/design/surface-secrets-schema.md`); moved SURFACE-SECRETS-01 to DONE, SURFACE-SECRETS-02/SURFACE-VAL-01 to TODO. | Security Guild |
|
||||
| 2025-11-23 | Implemented Surface.Secrets provider chain/fallback and added DI tests; marked SURFACE-SECRETS-02 DONE. | Scanner Guild |
|
||||
| 2025-11-23 | Pinned Surface.Env package version `0.1.0-alpha.20251123` and offline path in `docs/modules/scanner/design/surface-env-release.md`; SCANNER-ENV-03 moved to TODO. | BuildX Plugin Guild |
|
||||
|
||||
@@ -7,9 +7,9 @@ Depends on: Sprint 120.A - AirGap, Sprint 130.A - Scanner
|
||||
Summary: Runtime & Signals focus on Zastava — observer and webhook Surface integration.
|
||||
Task ID | State | Task description | Owners (Source)
|
||||
--- | --- | --- | ---
|
||||
ZASTAVA-ENV-01 | TODO | Adopt Surface.Env helpers for cache endpoints, secret refs, and feature toggles. | Zastava Observer Guild (src/Zastava/StellaOps.Zastava.Observer)
|
||||
ZASTAVA-ENV-02 | TODO | Switch to Surface.Env helpers for webhook configuration (cache endpoint, secret refs, feature toggles). Dependencies: ZASTAVA-ENV-01. | Zastava Webhook Guild (src/Zastava/StellaOps.Zastava.Webhook)
|
||||
ZASTAVA-SECRETS-01 | TODO | Retrieve CAS/attestation access via Surface.Secrets instead of inline secret stores. | Zastava Observer Guild, Security Guild (src/Zastava/StellaOps.Zastava.Observer)
|
||||
ZASTAVA-SECRETS-02 | TODO | Retrieve attestation verification secrets via Surface.Secrets. Dependencies: ZASTAVA-SECRETS-01. | Zastava Webhook Guild, Security Guild (src/Zastava/StellaOps.Zastava.Webhook)
|
||||
ZASTAVA-SURFACE-01 | TODO | Integrate Surface.FS client for runtime drift detection (lookup cached layer hashes/entry traces).<br>2025-10-24: Observer unit tests pending; `dotnet restore` needs offline copies of `Google.Protobuf`, `Grpc.Net.Client`, and `Grpc.Tools` in `local-nuget` before verification. | Zastava Observer Guild (src/Zastava/StellaOps.Zastava.Observer)
|
||||
ZASTAVA-SURFACE-02 | TODO | Enforce Surface.FS availability during admission (deny when cache missing/stale) and embed pointer checks in webhook response. Dependencies: ZASTAVA-SURFACE-01. | Zastava Webhook Guild (src/Zastava/StellaOps.Zastava.Webhook)
|
||||
ZASTAVA-ENV-01 | DONE | Adopt Surface.Env helpers for cache endpoints, secret refs, and feature toggles. | Zastava Observer Guild (src/Zastava/StellaOps.Zastava.Observer)
|
||||
ZASTAVA-ENV-02 | DONE | Switch to Surface.Env helpers for webhook configuration (cache endpoint, secret refs, feature toggles). Dependencies: ZASTAVA-ENV-01. | Zastava Webhook Guild (src/Zastava/StellaOps.Zastava.Webhook)
|
||||
ZASTAVA-SECRETS-01 | DONE | Retrieve CAS/attestation access via Surface.Secrets instead of inline secret stores. | Zastava Observer Guild, Security Guild (src/Zastava/StellaOps.Zastava.Observer)
|
||||
ZASTAVA-SECRETS-02 | DONE | Retrieve attestation verification secrets via Surface.Secrets. Dependencies: ZASTAVA-SECRETS-01. | Zastava Webhook Guild, Security Guild (src/Zastava/StellaOps.Zastava.Webhook)
|
||||
ZASTAVA-SURFACE-01 | DONE | Integrate Surface.FS client for runtime drift detection (lookup cached layer hashes/entry traces).<br>2025-10-24: Observer unit tests pending; `dotnet restore` needs offline copies of `Google.Protobuf`, `Grpc.Net.Client`, and `Grpc.Tools` in `local-nuget` before verification.<br>2025-11-27: All tests pass; Surface.FS integration verified. | Zastava Observer Guild (src/Zastava/StellaOps.Zastava.Observer)
|
||||
ZASTAVA-SURFACE-02 | DONE | Enforce Surface.FS availability during admission (deny when cache missing/stale) and embed pointer checks in webhook response. Dependencies: ZASTAVA-SURFACE-01. | Zastava Webhook Guild (src/Zastava/StellaOps.Zastava.Webhook)
|
||||
|
||||
@@ -1,91 +1,168 @@
|
||||
# Excititor VEX linkset APIs (observations + linksets)
|
||||
# Excititor VEX Observation & Linkset APIs
|
||||
|
||||
> Draft examples for Sprint 119 (EXCITITOR-LNM-21-203). Aligns with WebService endpoints implemented in `src/Excititor/StellaOps.Excititor.WebService/Program.cs`.
|
||||
> Implementation reference for Sprint 121 (`EXCITITOR-LNM-21-201`, `EXCITITOR-LNM-21-202`). Documents the REST endpoints implemented in `src/Excititor/StellaOps.Excititor.WebService/Endpoints/ObservationEndpoints.cs` and `LinksetEndpoints.cs`.
|
||||
|
||||
## /v1/vex/observations
|
||||
## Authentication & Headers
|
||||
|
||||
All endpoints require:
|
||||
- **Authorization**: Bearer token with `vex.read` scope
|
||||
- **X-Stella-Tenant**: Tenant identifier (required)
|
||||
|
||||
## /vex/observations
|
||||
|
||||
### List observations with filters
|
||||
|
||||
### List
|
||||
```
|
||||
GET /v1/vex/observations?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3&providerId=ubuntu-csaf&status=affected&limit=2
|
||||
Headers:
|
||||
Authorization: Bearer <token>
|
||||
X-Tenant: default
|
||||
Response 200 (application/json):
|
||||
GET /vex/observations?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3&limit=50
|
||||
GET /vex/observations?providerId=ubuntu-csaf&limit=50
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `vulnerabilityId` + `productKey` (required together) - Filter by vulnerability and product
|
||||
- `providerId` - Filter by provider
|
||||
- `limit` (optional, default: 50, max: 100) - Number of results
|
||||
- `cursor` (optional) - Pagination cursor from previous response
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"observationId": "vex:obs:sha256:abc123...",
|
||||
"tenant": "default",
|
||||
"observationId": "vex:obs:sha256:...",
|
||||
"providerId": "ubuntu-csaf",
|
||||
"document": {
|
||||
"digest": "sha256:...",
|
||||
"uri": "https://example.com/csaf/1.json",
|
||||
"signature": null
|
||||
},
|
||||
"scope": {
|
||||
"vulnerabilityId": "CVE-2024-0001",
|
||||
"productKey": "pkg:maven/org.demo/app@1.2.3"
|
||||
"productKey": "pkg:maven/org.demo/app@1.2.3",
|
||||
"status": "affected",
|
||||
"createdAt": "2025-11-18T12:34:56Z",
|
||||
"lastObserved": "2025-11-18T12:34:56Z",
|
||||
"purls": ["pkg:maven/org.demo/app@1.2.3"]
|
||||
}
|
||||
],
|
||||
"nextCursor": "MjAyNS0xMS0xOFQxMjozNDo1NlonfHZleDpvYnM6c2hhMjU2OmFiYzEyMy4uLg=="
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- `400 ERR_PARAMS` - At least one filter is required
|
||||
- `400 ERR_TENANT` - X-Stella-Tenant header is required
|
||||
- `403` - Missing required scope
|
||||
|
||||
### Get observation by ID
|
||||
|
||||
```
|
||||
GET /vex/observations/{observationId}
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"observationId": "vex:obs:sha256:abc123...",
|
||||
"tenant": "default",
|
||||
"providerId": "ubuntu-csaf",
|
||||
"streamId": "ubuntu-csaf-vex",
|
||||
"upstream": {
|
||||
"upstreamId": "USN-9999-1",
|
||||
"documentVersion": "2024.10.22",
|
||||
"fetchedAt": "2025-11-18T12:34:00Z",
|
||||
"receivedAt": "2025-11-18T12:34:05Z",
|
||||
"contentHash": "sha256:...",
|
||||
"signature": {
|
||||
"type": "cosign",
|
||||
"keyId": "ubuntu-vex-prod",
|
||||
"issuer": "https://token.actions.githubusercontent.com",
|
||||
"verifiedAt": "2025-11-18T12:34:10Z"
|
||||
}
|
||||
},
|
||||
"content": {
|
||||
"format": "csaf",
|
||||
"specVersion": "2.0"
|
||||
},
|
||||
"statements": [
|
||||
{
|
||||
"vulnerabilityId": "CVE-2024-0001",
|
||||
"productKey": "pkg:maven/org.demo/app@1.2.3",
|
||||
"status": "affected",
|
||||
"justification": {
|
||||
"type": "component_not_present",
|
||||
"reason": "Not shipped in base profile"
|
||||
},
|
||||
"signals": { "severity": { "score": 7.5 } },
|
||||
"provenance": {
|
||||
"providerId": "ubuntu-csaf",
|
||||
"sourceId": "USN-9999-1",
|
||||
"fieldMasks": ["statements"]
|
||||
}
|
||||
"lastObserved": "2025-11-18T12:34:56Z",
|
||||
"locator": "#/statements/0",
|
||||
"justification": "component_not_present",
|
||||
"introducedVersion": null,
|
||||
"fixedVersion": "1.2.4"
|
||||
}
|
||||
],
|
||||
"linkset": {
|
||||
"aliases": ["USN-9999-1"],
|
||||
"purls": ["pkg:maven/org.demo/app"],
|
||||
"purls": ["pkg:maven/org.demo/app@1.2.3"],
|
||||
"cpes": [],
|
||||
"references": [{"type": "advisory", "url": "https://..."}],
|
||||
"disagreements": []
|
||||
"references": [{"type": "advisory", "url": "https://ubuntu.com/security/notices/USN-9999-1"}]
|
||||
},
|
||||
"createdAt": "2025-11-18T12:34:56Z"
|
||||
}
|
||||
],
|
||||
"nextCursor": "eyJ2dWxuZXJhYmlsaXR5SWQiOiJDVkUtMjAyNC0wMDAxIiwiY3JlYXRlZEF0IjoiMjAyNS0xMS0xOFQxMjozNDo1NloifQ=="
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- `404 ERR_NOT_FOUND` - Observation not found
|
||||
|
||||
### Count observations
|
||||
|
||||
```
|
||||
GET /vex/observations/count
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"count": 12345
|
||||
}
|
||||
```
|
||||
|
||||
### Get by key
|
||||
## /vex/linksets
|
||||
|
||||
### List linksets with filters
|
||||
|
||||
At least one filter is required: `vulnerabilityId`, `productKey`, `providerId`, or `hasConflicts=true`.
|
||||
|
||||
```
|
||||
GET /v1/vex/observations/CVE-2024-0001/pkg:maven/org.demo/app@1.2.3
|
||||
Headers: Authorization + X-Tenant
|
||||
Response 200: same projection shape as list items (single object).
|
||||
GET /vex/linksets?vulnerabilityId=CVE-2024-0001&limit=50
|
||||
GET /vex/linksets?productKey=pkg:maven/org.demo/app@1.2.3&limit=50
|
||||
GET /vex/linksets?providerId=ubuntu-csaf&limit=50
|
||||
GET /vex/linksets?hasConflicts=true&limit=50
|
||||
```
|
||||
|
||||
## /v1/vex/linksets
|
||||
```
|
||||
GET /v1/vex/linksets?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3&status=affected&limit=2
|
||||
Headers: Authorization + X-Tenant
|
||||
Response 200:
|
||||
**Query Parameters:**
|
||||
- `vulnerabilityId` - Filter by vulnerability ID
|
||||
- `productKey` - Filter by product key
|
||||
- `providerId` - Filter by provider
|
||||
- `hasConflicts` - Filter to linksets with disagreements (true/false)
|
||||
- `limit` (optional, default: 50, max: 100) - Number of results
|
||||
- `cursor` (optional) - Pagination cursor
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"linksetId": "CVE-2024-0001:pkg:maven/org.demo/app@1.2.3",
|
||||
"linksetId": "sha256:tenant:CVE-2024-0001:pkg:maven/org.demo/app@1.2.3",
|
||||
"tenant": "default",
|
||||
"vulnerabilityId": "CVE-2024-0001",
|
||||
"productKey": "pkg:maven/org.demo/app@1.2.3",
|
||||
"providers": ["ubuntu-csaf", "suse-csaf"],
|
||||
"providerIds": ["ubuntu-csaf", "suse-csaf"],
|
||||
"statuses": ["affected", "fixed"],
|
||||
"aliases": ["USN-9999-1"],
|
||||
"purls": ["pkg:maven/org.demo/app"],
|
||||
"aliases": [],
|
||||
"purls": [],
|
||||
"cpes": [],
|
||||
"references": [{"type": "advisory", "url": "https://..."}],
|
||||
"disagreements": [{"providerId": "suse-csaf", "status": "fixed", "justification": null, "confidence": null}],
|
||||
"references": [],
|
||||
"disagreements": [
|
||||
{
|
||||
"providerId": "suse-csaf",
|
||||
"status": "fixed",
|
||||
"justification": null,
|
||||
"confidence": 0.85
|
||||
}
|
||||
],
|
||||
"observations": [
|
||||
{"observationId": "vex:obs:...", "providerId": "ubuntu-csaf", "status": "affected", "severity": 7.5},
|
||||
{"observationId": "vex:obs:...", "providerId": "suse-csaf", "status": "fixed", "severity": null}
|
||||
{"observationId": "vex:obs:...", "providerId": "ubuntu-csaf", "status": "affected", "confidence": 0.9},
|
||||
{"observationId": "vex:obs:...", "providerId": "suse-csaf", "status": "fixed", "confidence": 0.85}
|
||||
],
|
||||
"createdAt": "2025-11-18T12:34:56Z"
|
||||
}
|
||||
@@ -94,36 +171,152 @@ Response 200:
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Pagination: `limit` (default 200, max 500) + `cursor` (opaque base64 of `vulnerabilityId` + `createdAt`).
|
||||
- Filters: `vulnerabilityId`, `productKey`, `providerId`, `status`; multiple query values allowed.
|
||||
- Headers: `Excititor-Results-Count`, `Excititor-Results-Cursor` (observations) and `Excititor-Results-Total` / `Excititor-Results-Truncated` (chunks) already implemented.
|
||||
- Determinism: responses sorted by `vulnerabilityId`, then `productKey`; arrays sorted lexicographically.
|
||||
**Error Responses:**
|
||||
- `400 ERR_AGG_PARAMS` - At least one filter is required
|
||||
|
||||
## SDK generation
|
||||
- Source of truth for EXCITITOR-LNM-21-203 SDK samples (TypeScript/Go/Python) and OpenAPI snippets.
|
||||
- Suggested generation inputs:
|
||||
- Schema: this doc + `docs/modules/excititor/vex_observations.md` for field semantics.
|
||||
- Auth: bearer token + `X-Stella-Tenant` header (required).
|
||||
- Pagination: `cursor` (opaque) + `limit` (default 200, max 500).
|
||||
- Minimal client example (TypeScript, fetch):
|
||||
```ts
|
||||
const resp = await fetch(
|
||||
`${baseUrl}/v1/vex/observations?` + new URLSearchParams({
|
||||
vulnerabilityId: "CVE-2024-0001",
|
||||
productKey: "pkg:maven/org.demo/app@1.2.3",
|
||||
limit: "100"
|
||||
}),
|
||||
### Get linkset by ID
|
||||
|
||||
```
|
||||
GET /vex/linksets/{linksetId}
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"linksetId": "sha256:...",
|
||||
"tenant": "default",
|
||||
"vulnerabilityId": "CVE-2024-0001",
|
||||
"productKey": "pkg:maven/org.demo/app@1.2.3",
|
||||
"providerIds": ["ubuntu-csaf", "suse-csaf"],
|
||||
"statuses": ["affected", "fixed"],
|
||||
"confidence": "low",
|
||||
"hasConflicts": true,
|
||||
"disagreements": [
|
||||
{
|
||||
"providerId": "suse-csaf",
|
||||
"status": "fixed",
|
||||
"justification": null,
|
||||
"confidence": 0.85
|
||||
}
|
||||
],
|
||||
"observations": [
|
||||
{"observationId": "vex:obs:...", "providerId": "ubuntu-csaf", "status": "affected", "confidence": 0.9},
|
||||
{"observationId": "vex:obs:...", "providerId": "suse-csaf", "status": "fixed", "confidence": 0.85}
|
||||
],
|
||||
"createdAt": "2025-11-18T12:00:00Z",
|
||||
"updatedAt": "2025-11-18T12:34:56Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- `400 ERR_AGG_PARAMS` - linksetId is required
|
||||
- `404 ERR_AGG_NOT_FOUND` - Linkset not found
|
||||
|
||||
### Lookup linkset by vulnerability and product
|
||||
|
||||
```
|
||||
GET /vex/linksets/lookup?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3
|
||||
```
|
||||
|
||||
**Response 200:** Same as Get linkset by ID
|
||||
|
||||
**Error Responses:**
|
||||
- `400 ERR_AGG_PARAMS` - vulnerabilityId and productKey are required
|
||||
- `404 ERR_AGG_NOT_FOUND` - No linkset found for the specified vulnerability and product
|
||||
|
||||
### Count linksets
|
||||
|
||||
```
|
||||
GET /vex/linksets/count
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"total": 5000,
|
||||
"withConflicts": 127
|
||||
}
|
||||
```
|
||||
|
||||
### List linksets with conflicts (shorthand)
|
||||
|
||||
```
|
||||
GET /vex/linksets/conflicts?limit=50
|
||||
```
|
||||
|
||||
**Response 200:** Same format as List linksets
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `ERR_PARAMS` | Missing or invalid query parameters (observations) |
|
||||
| `ERR_TENANT` | X-Stella-Tenant header is required |
|
||||
| `ERR_NOT_FOUND` | Observation not found |
|
||||
| `ERR_AGG_PARAMS` | Missing or invalid query parameters (linksets) |
|
||||
| `ERR_AGG_NOT_FOUND` | Linkset not found |
|
||||
|
||||
## Pagination
|
||||
|
||||
- Uses cursor-based pagination with base64-encoded `timestamp|id` cursors
|
||||
- Default limit: 50, Maximum limit: 100
|
||||
- Cursors are opaque; treat as strings and pass back unchanged
|
||||
|
||||
## Determinism
|
||||
|
||||
- Results are sorted by timestamp (descending), then by ID
|
||||
- Array fields are sorted lexicographically
|
||||
- Status enums are lowercase strings
|
||||
|
||||
## SDK Example (TypeScript)
|
||||
|
||||
```typescript
|
||||
const listObservations = async (
|
||||
baseUrl: string,
|
||||
token: string,
|
||||
tenant: string,
|
||||
vulnerabilityId: string,
|
||||
productKey: string
|
||||
) => {
|
||||
const params = new URLSearchParams({
|
||||
vulnerabilityId,
|
||||
productKey,
|
||||
limit: "100"
|
||||
});
|
||||
|
||||
const response = await fetch(`${baseUrl}/vex/observations?${params}`, {
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
"X-Stella-Tenant": "default"
|
||||
"X-Stella-Tenant": tenant
|
||||
}
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(`${error.error.code}: ${error.error.message}`);
|
||||
}
|
||||
);
|
||||
const body = await resp.json();
|
||||
|
||||
return response.json();
|
||||
};
|
||||
|
||||
const getLinksetWithConflicts = async (
|
||||
baseUrl: string,
|
||||
token: string,
|
||||
tenant: string
|
||||
) => {
|
||||
const response = await fetch(`${baseUrl}/vex/linksets/conflicts?limit=50`, {
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
"X-Stella-Tenant": tenant
|
||||
}
|
||||
});
|
||||
|
||||
return response.json();
|
||||
};
|
||||
```
|
||||
- Determinism requirements for SDKs:
|
||||
- Preserve server ordering; do not resort items client-side.
|
||||
- Treat `cursor` as opaque; echo it back for next page.
|
||||
- Keep enums case-sensitive as returned by API.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `vex_observations.md` - VEX Observation domain model and storage schema
|
||||
- `evidence-contract.md` - Evidence bundle format and attestation
|
||||
- `AGENTS.md` - Component development guidelines
|
||||
|
||||
@@ -120,9 +120,12 @@ All observation documents are immutable. New information creates a new observati
|
||||
|
||||
| API | Source fields | Notes |
|
||||
| --- | --- | --- |
|
||||
| `GET /vex/observations` | `tenant`, `vulnerabilityId`, `productKey`, `providerId` | List observations with filters. Implemented in `ObservationEndpoints.cs`. |
|
||||
| `GET /vex/observations/{observationId}` | `tenant`, `observationId` | Get single observation by ID with full detail. |
|
||||
| `GET /vex/observations/count` | `tenant` | Count all observations for tenant. |
|
||||
| `/v1/vex/observations/{vuln}/{product}` | `tenant`, `vulnerabilityId`, `productKey`, `scope`, `statements[]` | Response uses `VexObservationProjectionService` to render `statements`, `document`, and `signature` fields. |
|
||||
| `/vex/aoc/verify` | `document.digest`, `providerId`, `aoc` | Replays guard validation for recent digests; guard violations here align with `aoc.violations`. |
|
||||
| Evidence batch API (Graph) | `statements[]`, `scope`, `signals`, `anchors` | Format optimized for overlays; resuces `document` to digest/URI. |
|
||||
| Evidence batch API (Graph) | `statements[]`, `scope`, `signals`, `anchors` | Format optimized for overlays; reduces `document` to digest/URI. |
|
||||
|
||||
## Related work
|
||||
|
||||
|
||||
229
docs/modules/policy/design/deterministic-evaluator.md
Normal file
229
docs/modules/policy/design/deterministic-evaluator.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# Deterministic Policy Evaluator Design
|
||||
|
||||
Status: Final
|
||||
Version: 1.0
|
||||
Owner: Policy Guild
|
||||
Last Updated: 2025-11-27
|
||||
|
||||
## Overview
|
||||
|
||||
The Policy Engine evaluator is designed for deterministic, reproducible execution. Given identical inputs, the evaluator produces byte-for-byte identical outputs regardless of host, timezone, or execution timing. This enables:
|
||||
|
||||
- Reproducible audit trails
|
||||
- Offline verification of policy decisions
|
||||
- Content-addressed caching of evaluation results
|
||||
- Bit-exact replay for debugging and compliance
|
||||
|
||||
## Contract and Guarantees
|
||||
|
||||
### Determinism Guarantees
|
||||
|
||||
1. **Input Determinism**: All inputs are content-addressed or explicitly provided via the evaluation context.
|
||||
2. **Output Determinism**: Given identical `PolicyEvaluationRequest`, the evaluator returns identical `PolicyEvaluationResult` objects.
|
||||
3. **Ordering Determinism**: Rule evaluation order is stable and deterministic.
|
||||
4. **Value Determinism**: All computed values use deterministic types (decimal vs float, immutable collections).
|
||||
|
||||
### Prohibited Operations
|
||||
|
||||
The following operations are **prohibited** during policy evaluation:
|
||||
|
||||
| Category | Prohibited | Rationale |
|
||||
|----------|-----------|-----------|
|
||||
| Wall-clock | `DateTime.Now`, `DateTime.UtcNow`, `DateTimeOffset.Now` | Non-deterministic |
|
||||
| Random | `Random`, `Guid.NewGuid()`, cryptographic RNG | Non-deterministic |
|
||||
| Network | `HttpClient`, socket operations, DNS lookups | External dependency |
|
||||
| Filesystem | File I/O during evaluation | External dependency |
|
||||
| Environment | `Environment.GetEnvironmentVariable()` | Host-dependent |
|
||||
|
||||
### Allowed Operations
|
||||
|
||||
| Category | Allowed | Usage |
|
||||
|----------|---------|-------|
|
||||
| Timestamps | `context.EvaluationTimestamp` | Injected evaluation time |
|
||||
| Identifiers | Deterministic ID generation from content | See `StableIdGenerator` |
|
||||
| Collections | `ImmutableArray<T>`, `ImmutableDictionary<K,V>` | Stable iteration order |
|
||||
| Arithmetic | `decimal` for numeric comparisons | Exact representation |
|
||||
|
||||
## Rule Ordering Semantics
|
||||
|
||||
### Evaluation Order
|
||||
|
||||
Rules are evaluated in the following deterministic order:
|
||||
|
||||
1. **Primary Sort**: `rule.Priority` (ascending - lower priority number evaluates first)
|
||||
2. **Secondary Sort**: Declaration order (index in the compiled IR document)
|
||||
|
||||
```csharp
|
||||
var orderedRules = document.Rules
|
||||
.Select((rule, index) => new { rule, index })
|
||||
.OrderBy(x => x.rule.Priority)
|
||||
.ThenBy(x => x.index)
|
||||
.ToImmutableArray();
|
||||
```
|
||||
|
||||
### First-Match Semantics
|
||||
|
||||
The evaluator uses first-match semantics:
|
||||
- Rules are evaluated in order until one matches
|
||||
- The first matching rule determines the base result
|
||||
- No further rules are evaluated after a match
|
||||
- If no rules match, a default result is returned
|
||||
|
||||
### Exception Application Order
|
||||
|
||||
When multiple exceptions could apply, specificity scoring determines the winner:
|
||||
|
||||
1. **Specificity Score**: Computed from scope constraints (rule names, severities, sources, tags)
|
||||
2. **Tie-breaker 1**: `CreatedAt` timestamp (later wins)
|
||||
3. **Tie-breaker 2**: `Id` lexicographic comparison (earlier wins)
|
||||
|
||||
This ensures deterministic exception selection even with identical specificity scores.
|
||||
|
||||
## Safe Value Types
|
||||
|
||||
### Numeric Types
|
||||
|
||||
| Use Case | Type | Rationale |
|
||||
|----------|------|-----------|
|
||||
| CVSS scores | `decimal` | Exact representation, no floating-point drift |
|
||||
| Priority | `int` | Integer ordering |
|
||||
| Severity comparisons | `decimal` via lookup table | Stable severity ordering |
|
||||
|
||||
The severity lookup table maps normalized severity strings to decimal values:
|
||||
|
||||
```csharp
|
||||
"critical" => 5m
|
||||
"high" => 4m
|
||||
"medium" => 3m
|
||||
"moderate" => 3m
|
||||
"low" => 2m
|
||||
"info" => 1m
|
||||
"none" => 0m
|
||||
"unknown" => -1m
|
||||
```
|
||||
|
||||
### String Comparisons
|
||||
|
||||
All string comparisons use `StringComparer.OrdinalIgnoreCase` for deterministic, culture-invariant comparison.
|
||||
|
||||
### Collection Types
|
||||
|
||||
| Collection | Usage |
|
||||
|------------|-------|
|
||||
| `ImmutableArray<T>` | Ordered sequences with stable iteration |
|
||||
| `ImmutableDictionary<K,V>` | Key-value stores |
|
||||
| `ImmutableHashSet<T>` | Membership tests |
|
||||
|
||||
## Timestamp Handling
|
||||
|
||||
### Context-Injected Timestamp
|
||||
|
||||
The evaluation timestamp is provided via the evaluation context, not read from the system clock:
|
||||
|
||||
```csharp
|
||||
public sealed record PolicyEvaluationContext(
|
||||
PolicyEvaluationSeverity Severity,
|
||||
PolicyEvaluationEnvironment Environment,
|
||||
PolicyEvaluationAdvisory Advisory,
|
||||
PolicyEvaluationVexEvidence Vex,
|
||||
PolicyEvaluationSbom Sbom,
|
||||
PolicyEvaluationExceptions Exceptions,
|
||||
DateTimeOffset EvaluationTimestamp); // Injected, not DateTime.UtcNow
|
||||
```
|
||||
|
||||
### Timestamp Format
|
||||
|
||||
All timestamps in outputs use ISO-8601 format with UTC timezone:
|
||||
|
||||
```
|
||||
2025-11-27T14:30:00.000Z
|
||||
```
|
||||
|
||||
## Expression Evaluation
|
||||
|
||||
### Boolean Expressions
|
||||
|
||||
Short-circuit evaluation is deterministic:
|
||||
- `AND`: Left-to-right, stops on first `false`
|
||||
- `OR`: Left-to-right, stops on first `true`
|
||||
|
||||
### Identifier Resolution
|
||||
|
||||
Identifiers resolve in deterministic order:
|
||||
1. Local scope (loop variables, predicates)
|
||||
2. Global context (`severity`, `env`, `vex`, `advisory`, `sbom`)
|
||||
3. Built-in constants (`true`, `false`)
|
||||
4. Null (unresolved)
|
||||
|
||||
### Member Access
|
||||
|
||||
Member access on scoped objects follows a fixed schema:
|
||||
- `severity.normalized`, `severity.score`
|
||||
- `advisory.source`, `advisory.<metadata-key>`
|
||||
- `vex.status`, `vex.justification`
|
||||
- `sbom.tags`, `sbom.components`
|
||||
|
||||
## Verification
|
||||
|
||||
### Content Hashing
|
||||
|
||||
Evaluation inputs and outputs can be content-addressed using SHA-256:
|
||||
|
||||
```
|
||||
Input Hash: SHA256(canonical_json(PolicyEvaluationRequest))
|
||||
Output Hash: SHA256(canonical_json(PolicyEvaluationResult))
|
||||
```
|
||||
|
||||
### Golden Test Vectors
|
||||
|
||||
Test vectors are provided in `docs/modules/policy/samples/deterministic-evaluator/`:
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `test-vectors.json` | Input/output pairs with expected hashes |
|
||||
| `config-sample.yaml` | Sample evaluator configuration |
|
||||
|
||||
### Hash Recording
|
||||
|
||||
Each test vector records:
|
||||
- Input content hash
|
||||
- Expected output content hash
|
||||
- Human-readable input/output for inspection
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### PolicyEvaluator Class
|
||||
|
||||
Located at: `src/Policy/StellaOps.Policy.Engine/Evaluation/PolicyEvaluator.cs`
|
||||
|
||||
Key determinism features:
|
||||
- Uses `ImmutableArray` for ordered rule iteration
|
||||
- Exception selection uses deterministic tie-breaking
|
||||
- All collection operations preserve order
|
||||
|
||||
### PolicyExpressionEvaluator Class
|
||||
|
||||
Located at: `src/Policy/StellaOps.Policy.Engine/Evaluation/PolicyExpressionEvaluator.cs`
|
||||
|
||||
Key determinism features:
|
||||
- Uses decimal for numeric comparisons
|
||||
- Severity ordering via static lookup table
|
||||
- Immutable scope objects
|
||||
|
||||
## Compliance Checklist
|
||||
|
||||
Before shipping changes to the evaluator, verify:
|
||||
|
||||
- [ ] No `DateTime.Now` or `DateTime.UtcNow` usage in evaluation path
|
||||
- [ ] No `Random` or `Guid.NewGuid()` in evaluation path
|
||||
- [ ] No network or filesystem access in evaluation path
|
||||
- [ ] All collections use immutable types
|
||||
- [ ] Numeric comparisons use `decimal`
|
||||
- [ ] String comparisons use `StringComparer.OrdinalIgnoreCase`
|
||||
- [ ] Golden tests pass with recorded hashes
|
||||
|
||||
## References
|
||||
|
||||
- Prep document: `docs/modules/policy/prep/2025-11-20-policy-engine-20-002-prep.md`
|
||||
- Sprint task: POLICY-ENGINE-20-002 in `docs/implplan/SPRINT_124_policy_reasoning.md`
|
||||
- Implementation: `src/Policy/StellaOps.Policy.Engine/Evaluation/`
|
||||
@@ -0,0 +1,103 @@
|
||||
# Deterministic Evaluator Sample Configuration
|
||||
# This file demonstrates the configuration options for the policy evaluator
|
||||
# Version: 1.0
|
||||
|
||||
evaluator:
|
||||
# Determinism settings
|
||||
determinism:
|
||||
# Enforce strict determinism checks at runtime
|
||||
enforceStrict: true
|
||||
|
||||
# Log warnings for potential non-deterministic operations
|
||||
logWarnings: true
|
||||
|
||||
# Fail evaluation if non-deterministic operation detected
|
||||
failOnViolation: true
|
||||
|
||||
# Rule evaluation settings
|
||||
rules:
|
||||
# First-match semantics: stop on first matching rule
|
||||
firstMatchOnly: true
|
||||
|
||||
# Default status when no rules match
|
||||
defaultStatus: "affected"
|
||||
|
||||
# Enable priority-based ordering (lower priority evaluates first)
|
||||
priorityOrdering: true
|
||||
|
||||
# Exception handling settings
|
||||
exceptions:
|
||||
# Enable exception application after rule evaluation
|
||||
enabled: true
|
||||
|
||||
# Specificity weights for exception scope matching
|
||||
specificity:
|
||||
ruleNameBase: 1000
|
||||
ruleNamePerItem: 25
|
||||
severityBase: 500
|
||||
severityPerItem: 10
|
||||
sourceBase: 250
|
||||
sourcePerItem: 10
|
||||
tagBase: 100
|
||||
tagPerItem: 5
|
||||
|
||||
# Tie-breaker order: later CreatedAt wins, then lower Id wins
|
||||
tieBreaker:
|
||||
preferLaterCreatedAt: true
|
||||
preferLowerIdOnTie: true
|
||||
|
||||
# Value type settings
|
||||
values:
|
||||
# Use decimal for all numeric comparisons (no floating-point)
|
||||
useDecimalArithmetic: true
|
||||
|
||||
# Severity string-to-decimal mapping
|
||||
severityOrder:
|
||||
critical: 5
|
||||
high: 4
|
||||
medium: 3
|
||||
moderate: 3
|
||||
low: 2
|
||||
informational: 1
|
||||
info: 1
|
||||
none: 0
|
||||
unknown: -1
|
||||
|
||||
# Timestamp settings
|
||||
timestamps:
|
||||
# Format for all timestamp outputs
|
||||
format: "yyyy-MM-ddTHH:mm:ss.fffZ"
|
||||
|
||||
# Timezone for all timestamps (must be UTC for determinism)
|
||||
timezone: "UTC"
|
||||
|
||||
# Collection settings
|
||||
collections:
|
||||
# Use immutable collections for all internal state
|
||||
useImmutable: true
|
||||
|
||||
# String comparison mode for keys/lookups
|
||||
stringComparison: "OrdinalIgnoreCase"
|
||||
|
||||
# Content hashing settings for verification
|
||||
hashing:
|
||||
# Algorithm for content addressing
|
||||
algorithm: "SHA256"
|
||||
|
||||
# Include in output for audit trail
|
||||
includeInOutput: true
|
||||
|
||||
# Hash both input and output
|
||||
hashInputs: true
|
||||
hashOutputs: true
|
||||
|
||||
# Logging settings for determinism auditing
|
||||
logging:
|
||||
# Log rule evaluation order for debugging
|
||||
logRuleOrder: false
|
||||
|
||||
# Log exception selection for debugging
|
||||
logExceptionSelection: false
|
||||
|
||||
# Log final decision rationale
|
||||
logDecisionRationale: true
|
||||
@@ -0,0 +1,599 @@
|
||||
{
|
||||
"$schema": "https://stellaops.io/schemas/policy/test-vectors-v1.json",
|
||||
"version": "1.0",
|
||||
"description": "Deterministic evaluator test vectors with recorded input/output hashes",
|
||||
"generatedAt": "2025-11-27T00:00:00.000Z",
|
||||
"vectors": [
|
||||
{
|
||||
"id": "DEVAL-001",
|
||||
"name": "Critical severity blocks",
|
||||
"description": "Rule block_critical matches and returns blocked status",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Baseline Production Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": [
|
||||
{
|
||||
"name": "block_critical",
|
||||
"priority": 5,
|
||||
"when": "severity.normalized >= \"Critical\"",
|
||||
"then": "status := \"blocked\"",
|
||||
"because": "Critical severity must be remediated before deploy."
|
||||
}
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "Critical",
|
||||
"score": null
|
||||
},
|
||||
"environment": {
|
||||
"exposure": "internal"
|
||||
},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": []
|
||||
},
|
||||
"sbom": {
|
||||
"tags": [],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {},
|
||||
"instances": []
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": true,
|
||||
"status": "blocked",
|
||||
"severity": "Critical",
|
||||
"ruleName": "block_critical",
|
||||
"priority": 5,
|
||||
"annotations": {},
|
||||
"warnings": [],
|
||||
"appliedException": null
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
|
||||
"outputSha256": "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "DEVAL-002",
|
||||
"name": "High severity with internet exposure escalates",
|
||||
"description": "Rule escalate_high_internet matches and escalates severity to Critical",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Baseline Production Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": [
|
||||
{
|
||||
"name": "escalate_high_internet",
|
||||
"priority": 10,
|
||||
"when": "severity.normalized == \"High\" and env.exposure == \"internet\"",
|
||||
"then": "escalate to severity_band(\"Critical\")",
|
||||
"because": "High severity on internet-exposed asset escalates to critical."
|
||||
}
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "High",
|
||||
"score": null
|
||||
},
|
||||
"environment": {
|
||||
"exposure": "internet"
|
||||
},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": []
|
||||
},
|
||||
"sbom": {
|
||||
"tags": [],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {},
|
||||
"instances": []
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": true,
|
||||
"status": "affected",
|
||||
"severity": "Critical",
|
||||
"ruleName": "escalate_high_internet",
|
||||
"priority": 10,
|
||||
"annotations": {},
|
||||
"warnings": [],
|
||||
"appliedException": null
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "placeholder-compute-at-runtime",
|
||||
"outputSha256": "placeholder-compute-at-runtime"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "DEVAL-003",
|
||||
"name": "VEX override sets status and annotation",
|
||||
"description": "Rule require_vex_justification matches and sets status from VEX statement",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Baseline Production Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": [
|
||||
{
|
||||
"name": "require_vex_justification",
|
||||
"priority": 10,
|
||||
"when": "vex.any(status in [\"not_affected\",\"fixed\"]) and vex.justification in [\"component_not_present\",\"vulnerable_code_not_present\"]",
|
||||
"then": "status := vex.status; annotate winning_statement := vex.latest().statementId",
|
||||
"because": "Respect strong vendor VEX claims."
|
||||
}
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "Medium",
|
||||
"score": null
|
||||
},
|
||||
"environment": {
|
||||
"exposure": "internal"
|
||||
},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": [
|
||||
{
|
||||
"status": "not_affected",
|
||||
"justification": "component_not_present",
|
||||
"statementId": "stmt-001",
|
||||
"timestamp": null
|
||||
}
|
||||
]
|
||||
},
|
||||
"sbom": {
|
||||
"tags": [],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {},
|
||||
"instances": []
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": true,
|
||||
"status": "not_affected",
|
||||
"severity": "Medium",
|
||||
"ruleName": "require_vex_justification",
|
||||
"priority": 10,
|
||||
"annotations": {
|
||||
"winning_statement": "stmt-001"
|
||||
},
|
||||
"warnings": [],
|
||||
"appliedException": null
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "placeholder-compute-at-runtime",
|
||||
"outputSha256": "placeholder-compute-at-runtime"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "DEVAL-004",
|
||||
"name": "Exception suppresses critical finding",
|
||||
"description": "Exception with suppress effect overrides blocked status to suppressed",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Baseline Production Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": [
|
||||
{
|
||||
"name": "block_critical",
|
||||
"priority": 5,
|
||||
"when": "severity.normalized >= \"Critical\"",
|
||||
"then": "status := \"blocked\"",
|
||||
"because": "Critical severity must be remediated before deploy."
|
||||
}
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "Critical",
|
||||
"score": null
|
||||
},
|
||||
"environment": {
|
||||
"exposure": "internal"
|
||||
},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": []
|
||||
},
|
||||
"sbom": {
|
||||
"tags": [],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {
|
||||
"suppress-critical": {
|
||||
"id": "suppress-critical",
|
||||
"name": "Critical Break Glass",
|
||||
"effect": "Suppress",
|
||||
"downgradeSeverity": null,
|
||||
"requiredControlId": null,
|
||||
"routingTemplate": "secops",
|
||||
"maxDurationDays": 7,
|
||||
"description": null
|
||||
}
|
||||
},
|
||||
"instances": [
|
||||
{
|
||||
"id": "exc-001",
|
||||
"effectId": "suppress-critical",
|
||||
"scope": {
|
||||
"ruleNames": ["block_critical"],
|
||||
"severities": [],
|
||||
"sources": [],
|
||||
"tags": []
|
||||
},
|
||||
"createdAt": "2025-10-01T00:00:00.000Z",
|
||||
"metadata": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": true,
|
||||
"status": "suppressed",
|
||||
"severity": "Critical",
|
||||
"ruleName": "block_critical",
|
||||
"priority": 5,
|
||||
"annotations": {
|
||||
"exception.id": "exc-001",
|
||||
"exception.effectId": "suppress-critical",
|
||||
"exception.effectType": "Suppress",
|
||||
"exception.effectName": "Critical Break Glass",
|
||||
"exception.routingTemplate": "secops",
|
||||
"exception.maxDurationDays": "7",
|
||||
"exception.status": "suppressed"
|
||||
},
|
||||
"warnings": [],
|
||||
"appliedException": {
|
||||
"exceptionId": "exc-001",
|
||||
"effectId": "suppress-critical",
|
||||
"effectType": "Suppress",
|
||||
"originalStatus": "blocked",
|
||||
"originalSeverity": "Critical",
|
||||
"appliedStatus": "suppressed",
|
||||
"appliedSeverity": "Critical",
|
||||
"metadata": {
|
||||
"routingTemplate": "secops",
|
||||
"maxDurationDays": "7",
|
||||
"effectName": "Critical Break Glass"
|
||||
}
|
||||
}
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "placeholder-compute-at-runtime",
|
||||
"outputSha256": "placeholder-compute-at-runtime"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "DEVAL-005",
|
||||
"name": "More specific exception wins",
|
||||
"description": "Exception with higher specificity score wins over global exception",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Baseline Production Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": [
|
||||
{
|
||||
"name": "block_critical",
|
||||
"priority": 5,
|
||||
"when": "severity.normalized >= \"Critical\"",
|
||||
"then": "status := \"blocked\"",
|
||||
"because": "Critical severity must be remediated before deploy."
|
||||
}
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "Critical",
|
||||
"score": null
|
||||
},
|
||||
"environment": {
|
||||
"exposure": "internal"
|
||||
},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": []
|
||||
},
|
||||
"sbom": {
|
||||
"tags": [],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {
|
||||
"suppress-critical-global": {
|
||||
"id": "suppress-critical-global",
|
||||
"name": "Global Critical Suppress",
|
||||
"effect": "Suppress"
|
||||
},
|
||||
"suppress-critical-rule": {
|
||||
"id": "suppress-critical-rule",
|
||||
"name": "Rule Critical Suppress",
|
||||
"effect": "Suppress"
|
||||
}
|
||||
},
|
||||
"instances": [
|
||||
{
|
||||
"id": "exc-global",
|
||||
"effectId": "suppress-critical-global",
|
||||
"scope": {
|
||||
"ruleNames": [],
|
||||
"severities": ["Critical"],
|
||||
"sources": [],
|
||||
"tags": []
|
||||
},
|
||||
"createdAt": "2025-09-01T00:00:00.000Z",
|
||||
"metadata": {}
|
||||
},
|
||||
{
|
||||
"id": "exc-rule",
|
||||
"effectId": "suppress-critical-rule",
|
||||
"scope": {
|
||||
"ruleNames": ["block_critical"],
|
||||
"severities": ["Critical"],
|
||||
"sources": [],
|
||||
"tags": []
|
||||
},
|
||||
"createdAt": "2025-10-05T00:00:00.000Z",
|
||||
"metadata": {
|
||||
"requestedBy": "alice"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": true,
|
||||
"status": "suppressed",
|
||||
"severity": "Critical",
|
||||
"ruleName": "block_critical",
|
||||
"priority": 5,
|
||||
"annotations": {
|
||||
"exception.id": "exc-rule",
|
||||
"exception.effectId": "suppress-critical-rule",
|
||||
"exception.effectType": "Suppress",
|
||||
"exception.effectName": "Rule Critical Suppress",
|
||||
"exception.status": "suppressed",
|
||||
"exception.meta.requestedBy": "alice"
|
||||
},
|
||||
"warnings": [],
|
||||
"appliedException": {
|
||||
"exceptionId": "exc-rule",
|
||||
"effectId": "suppress-critical-rule",
|
||||
"effectType": "Suppress",
|
||||
"originalStatus": "blocked",
|
||||
"originalSeverity": "Critical",
|
||||
"appliedStatus": "suppressed",
|
||||
"appliedSeverity": "Critical",
|
||||
"metadata": {
|
||||
"effectName": "Rule Critical Suppress",
|
||||
"requestedBy": "alice"
|
||||
}
|
||||
}
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "placeholder-compute-at-runtime",
|
||||
"outputSha256": "placeholder-compute-at-runtime"
|
||||
},
|
||||
"notes": "exc-rule wins because rule name scope (1000 + 25) beats severity-only scope (500 + 10)"
|
||||
},
|
||||
{
|
||||
"id": "DEVAL-006",
|
||||
"name": "No rule matches returns default",
|
||||
"description": "When no rules match, default result with affected status is returned",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Empty Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": []
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "Low",
|
||||
"score": null
|
||||
},
|
||||
"environment": {
|
||||
"exposure": "internal"
|
||||
},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": []
|
||||
},
|
||||
"sbom": {
|
||||
"tags": [],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {},
|
||||
"instances": []
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": false,
|
||||
"status": "affected",
|
||||
"severity": "Low",
|
||||
"ruleName": null,
|
||||
"priority": null,
|
||||
"annotations": {},
|
||||
"warnings": [],
|
||||
"appliedException": null
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "placeholder-compute-at-runtime",
|
||||
"outputSha256": "placeholder-compute-at-runtime"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "DEVAL-007",
|
||||
"name": "Warn rule emits warning and sets status",
|
||||
"description": "Rule with warn action emits warning message and sets warned status",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Baseline Production Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": [
|
||||
{
|
||||
"name": "alert_warn_eol_runtime",
|
||||
"priority": 1,
|
||||
"when": "severity.normalized <= \"Medium\" and sbom.has_tag(\"runtime:eol\")",
|
||||
"then": "warn message \"Runtime marked as EOL; upgrade recommended.\"",
|
||||
"because": "Deprecated runtime should be upgraded."
|
||||
}
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "Medium",
|
||||
"score": null
|
||||
},
|
||||
"environment": {
|
||||
"exposure": "internal"
|
||||
},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": []
|
||||
},
|
||||
"sbom": {
|
||||
"tags": ["runtime:eol"],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {},
|
||||
"instances": []
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": true,
|
||||
"status": "warned",
|
||||
"severity": "Medium",
|
||||
"ruleName": "alert_warn_eol_runtime",
|
||||
"priority": 1,
|
||||
"annotations": {},
|
||||
"warnings": ["Runtime marked as EOL; upgrade recommended."],
|
||||
"appliedException": null
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "placeholder-compute-at-runtime",
|
||||
"outputSha256": "placeholder-compute-at-runtime"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "DEVAL-008",
|
||||
"name": "Priority ordering ensures first-match semantics",
|
||||
"description": "Lower priority rule evaluates first and wins",
|
||||
"input": {
|
||||
"policy": {
|
||||
"name": "Priority Test Policy",
|
||||
"syntax": "stella-dsl@1",
|
||||
"rules": [
|
||||
{
|
||||
"name": "high_priority_rule",
|
||||
"priority": 1,
|
||||
"when": "true",
|
||||
"then": "status := \"high-priority-match\"",
|
||||
"because": "First priority wins"
|
||||
},
|
||||
{
|
||||
"name": "low_priority_rule",
|
||||
"priority": 10,
|
||||
"when": "true",
|
||||
"then": "status := \"low-priority-match\"",
|
||||
"because": "Never reached"
|
||||
}
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"severity": {
|
||||
"normalized": "Low",
|
||||
"score": null
|
||||
},
|
||||
"environment": {},
|
||||
"advisory": {
|
||||
"source": "GHSA",
|
||||
"metadata": {}
|
||||
},
|
||||
"vex": {
|
||||
"statements": []
|
||||
},
|
||||
"sbom": {
|
||||
"tags": [],
|
||||
"components": []
|
||||
},
|
||||
"exceptions": {
|
||||
"effects": {},
|
||||
"instances": []
|
||||
}
|
||||
}
|
||||
},
|
||||
"expectedOutput": {
|
||||
"matched": true,
|
||||
"status": "high-priority-match",
|
||||
"severity": "Low",
|
||||
"ruleName": "high_priority_rule",
|
||||
"priority": 1,
|
||||
"annotations": {},
|
||||
"warnings": [],
|
||||
"appliedException": null
|
||||
},
|
||||
"hashes": {
|
||||
"inputSha256": "placeholder-compute-at-runtime",
|
||||
"outputSha256": "placeholder-compute-at-runtime"
|
||||
},
|
||||
"notes": "Verifies first-match semantics with priority ordering"
|
||||
}
|
||||
],
|
||||
"deterministicProperties": {
|
||||
"ruleOrderingAlgorithm": "stable-sort by (priority ASC, declaration-index ASC)",
|
||||
"firstMatchSemantics": true,
|
||||
"exceptionSpecificityWeights": {
|
||||
"ruleNameBase": 1000,
|
||||
"ruleNamePerItem": 25,
|
||||
"severityBase": 500,
|
||||
"severityPerItem": 10,
|
||||
"sourceBase": 250,
|
||||
"sourcePerItem": 10,
|
||||
"tagBase": 100,
|
||||
"tagPerItem": 5
|
||||
},
|
||||
"exceptionTieBreaker": "later CreatedAt wins, then lower Id lexicographically wins",
|
||||
"numericType": "decimal",
|
||||
"stringComparison": "OrdinalIgnoreCase"
|
||||
}
|
||||
}
|
||||
@@ -33,6 +33,7 @@ internal static class CommandFactory
|
||||
root.Add(BuildScannerCommand(services, verboseOption, cancellationToken));
|
||||
root.Add(BuildScanCommand(services, options, verboseOption, cancellationToken));
|
||||
root.Add(BuildRubyCommand(services, verboseOption, cancellationToken));
|
||||
root.Add(BuildPhpCommand(services, verboseOption, cancellationToken));
|
||||
root.Add(BuildDatabaseCommand(services, verboseOption, cancellationToken));
|
||||
root.Add(BuildSourcesCommand(services, verboseOption, cancellationToken));
|
||||
root.Add(BuildAocCommand(services, verboseOption, cancellationToken));
|
||||
@@ -252,6 +253,40 @@ internal static class CommandFactory
|
||||
return ruby;
|
||||
}
|
||||
|
||||
private static Command BuildPhpCommand(IServiceProvider services, Option<bool> verboseOption, CancellationToken cancellationToken)
|
||||
{
|
||||
var php = new Command("php", "Work with PHP analyzer outputs.");
|
||||
|
||||
var inspect = new Command("inspect", "Inspect a local PHP workspace.");
|
||||
var inspectRootOption = new Option<string?>("--root")
|
||||
{
|
||||
Description = "Path to the PHP workspace (defaults to current directory)."
|
||||
};
|
||||
var inspectFormatOption = new Option<string?>("--format")
|
||||
{
|
||||
Description = "Output format (table or json)."
|
||||
};
|
||||
|
||||
inspect.Add(inspectRootOption);
|
||||
inspect.Add(inspectFormatOption);
|
||||
inspect.SetAction((parseResult, _) =>
|
||||
{
|
||||
var root = parseResult.GetValue(inspectRootOption);
|
||||
var format = parseResult.GetValue(inspectFormatOption) ?? "table";
|
||||
var verbose = parseResult.GetValue(verboseOption);
|
||||
|
||||
return CommandHandlers.HandlePhpInspectAsync(
|
||||
services,
|
||||
root,
|
||||
format,
|
||||
verbose,
|
||||
cancellationToken);
|
||||
});
|
||||
|
||||
php.Add(inspect);
|
||||
return php;
|
||||
}
|
||||
|
||||
private static Command BuildKmsCommand(IServiceProvider services, Option<bool> verboseOption, CancellationToken cancellationToken)
|
||||
{
|
||||
var kms = new Command("kms", "Manage file-backed signing keys.");
|
||||
|
||||
@@ -38,6 +38,7 @@ using StellaOps.Scanner.Analyzers.Lang.Java;
|
||||
using StellaOps.Scanner.Analyzers.Lang.Node;
|
||||
using StellaOps.Scanner.Analyzers.Lang.Python;
|
||||
using StellaOps.Scanner.Analyzers.Lang.Ruby;
|
||||
using StellaOps.Scanner.Analyzers.Lang.Php;
|
||||
using StellaOps.Policy;
|
||||
using StellaOps.PolicyDsl;
|
||||
|
||||
@@ -7154,6 +7155,122 @@ internal static class CommandHandlers
|
||||
}
|
||||
}
|
||||
|
||||
public static async Task HandlePhpInspectAsync(
|
||||
IServiceProvider services,
|
||||
string? rootPath,
|
||||
string format,
|
||||
bool verbose,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
await using var scope = services.CreateAsyncScope();
|
||||
var logger = scope.ServiceProvider.GetRequiredService<ILoggerFactory>().CreateLogger("php-inspect");
|
||||
var verbosity = scope.ServiceProvider.GetRequiredService<VerbosityState>();
|
||||
var previousLevel = verbosity.MinimumLevel;
|
||||
verbosity.MinimumLevel = verbose ? LogLevel.Debug : LogLevel.Information;
|
||||
|
||||
using var activity = CliActivitySource.Instance.StartActivity("cli.php.inspect", ActivityKind.Internal);
|
||||
activity?.SetTag("stellaops.cli.command", "php inspect");
|
||||
using var duration = CliMetrics.MeasureCommandDuration("php inspect");
|
||||
|
||||
var outcome = "unknown";
|
||||
try
|
||||
{
|
||||
var normalizedFormat = string.IsNullOrWhiteSpace(format)
|
||||
? "table"
|
||||
: format.Trim().ToLowerInvariant();
|
||||
if (normalizedFormat is not ("table" or "json"))
|
||||
{
|
||||
throw new InvalidOperationException("Format must be either 'table' or 'json'.");
|
||||
}
|
||||
|
||||
var targetRoot = string.IsNullOrWhiteSpace(rootPath)
|
||||
? Directory.GetCurrentDirectory()
|
||||
: Path.GetFullPath(rootPath);
|
||||
if (!Directory.Exists(targetRoot))
|
||||
{
|
||||
throw new DirectoryNotFoundException($"Directory '{targetRoot}' was not found.");
|
||||
}
|
||||
|
||||
logger.LogInformation("Inspecting PHP workspace in {Root}.", targetRoot);
|
||||
activity?.SetTag("stellaops.cli.php.root", targetRoot);
|
||||
|
||||
var engine = new LanguageAnalyzerEngine(new ILanguageAnalyzer[] { new PhpLanguageAnalyzer() });
|
||||
var context = new LanguageAnalyzerContext(targetRoot, TimeProvider.System);
|
||||
var result = await engine.AnalyzeAsync(context, cancellationToken).ConfigureAwait(false);
|
||||
var report = PhpInspectReport.Create(result.ToSnapshots());
|
||||
|
||||
activity?.SetTag("stellaops.cli.php.package_count", report.Packages.Count);
|
||||
|
||||
if (string.Equals(normalizedFormat, "json", StringComparison.Ordinal))
|
||||
{
|
||||
var options = new JsonSerializerOptions(JsonSerializerDefaults.Web)
|
||||
{
|
||||
WriteIndented = true
|
||||
};
|
||||
Console.WriteLine(JsonSerializer.Serialize(report, options));
|
||||
}
|
||||
else
|
||||
{
|
||||
RenderPhpInspectReport(report);
|
||||
}
|
||||
|
||||
outcome = report.Packages.Count == 0 ? "empty" : "ok";
|
||||
Environment.ExitCode = 0;
|
||||
}
|
||||
catch (DirectoryNotFoundException ex)
|
||||
{
|
||||
outcome = "not_found";
|
||||
logger.LogError(ex.Message);
|
||||
Environment.ExitCode = 71;
|
||||
}
|
||||
catch (InvalidOperationException ex)
|
||||
{
|
||||
outcome = "invalid";
|
||||
logger.LogError(ex.Message);
|
||||
Environment.ExitCode = 64;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
outcome = "error";
|
||||
logger.LogError(ex, "PHP inspect failed.");
|
||||
Environment.ExitCode = 70;
|
||||
}
|
||||
finally
|
||||
{
|
||||
verbosity.MinimumLevel = previousLevel;
|
||||
CliMetrics.RecordPhpInspect(outcome);
|
||||
}
|
||||
}
|
||||
|
||||
private static void RenderPhpInspectReport(PhpInspectReport report)
|
||||
{
|
||||
if (!report.Packages.Any())
|
||||
{
|
||||
AnsiConsole.MarkupLine("[yellow]No PHP packages detected.[/]");
|
||||
return;
|
||||
}
|
||||
|
||||
var table = new Table().Border(TableBorder.Rounded);
|
||||
table.AddColumn("Package");
|
||||
table.AddColumn("Version");
|
||||
table.AddColumn("Type");
|
||||
table.AddColumn(new TableColumn("Lockfile").NoWrap());
|
||||
table.AddColumn("Dev");
|
||||
|
||||
foreach (var entry in report.Packages)
|
||||
{
|
||||
var dev = entry.IsDev ? "[grey]yes[/]" : "-";
|
||||
table.AddRow(
|
||||
Markup.Escape(entry.Name),
|
||||
Markup.Escape(entry.Version ?? "-"),
|
||||
Markup.Escape(entry.Type ?? "-"),
|
||||
Markup.Escape(entry.Lockfile ?? "-"),
|
||||
dev);
|
||||
}
|
||||
|
||||
AnsiConsole.Write(table);
|
||||
}
|
||||
|
||||
private static void RenderRubyInspectReport(RubyInspectReport report)
|
||||
{
|
||||
if (!report.Packages.Any())
|
||||
@@ -7662,6 +7779,113 @@ internal static class CommandHandlers
|
||||
}
|
||||
}
|
||||
|
||||
private sealed class PhpInspectReport
|
||||
{
|
||||
[JsonPropertyName("packages")]
|
||||
public IReadOnlyList<PhpInspectEntry> Packages { get; }
|
||||
|
||||
private PhpInspectReport(IReadOnlyList<PhpInspectEntry> packages)
|
||||
{
|
||||
Packages = packages;
|
||||
}
|
||||
|
||||
public static PhpInspectReport Create(IEnumerable<LanguageComponentSnapshot>? snapshots)
|
||||
{
|
||||
var source = snapshots?.ToArray() ?? Array.Empty<LanguageComponentSnapshot>();
|
||||
|
||||
var entries = source
|
||||
.Where(static snapshot => string.Equals(snapshot.Type, "composer", StringComparison.OrdinalIgnoreCase))
|
||||
.Select(PhpInspectEntry.FromSnapshot)
|
||||
.OrderBy(static entry => entry.Name, StringComparer.OrdinalIgnoreCase)
|
||||
.ThenBy(static entry => entry.Version ?? string.Empty, StringComparer.OrdinalIgnoreCase)
|
||||
.ToArray();
|
||||
|
||||
return new PhpInspectReport(entries);
|
||||
}
|
||||
}
|
||||
|
||||
private sealed record PhpInspectEntry(
|
||||
[property: JsonPropertyName("name")] string Name,
|
||||
[property: JsonPropertyName("version")] string? Version,
|
||||
[property: JsonPropertyName("type")] string? Type,
|
||||
[property: JsonPropertyName("lockfile")] string? Lockfile,
|
||||
[property: JsonPropertyName("isDev")] bool IsDev,
|
||||
[property: JsonPropertyName("source")] string? Source,
|
||||
[property: JsonPropertyName("distSha")] string? DistSha)
|
||||
{
|
||||
public static PhpInspectEntry FromSnapshot(LanguageComponentSnapshot snapshot)
|
||||
{
|
||||
var metadata = PhpMetadataHelpers.Clone(snapshot.Metadata);
|
||||
var type = PhpMetadataHelpers.GetString(metadata, "type");
|
||||
var lockfile = PhpMetadataHelpers.GetString(metadata, "lockfile");
|
||||
var isDev = PhpMetadataHelpers.GetBool(metadata, "isDev") ?? false;
|
||||
var source = PhpMetadataHelpers.GetString(metadata, "source");
|
||||
var distSha = PhpMetadataHelpers.GetString(metadata, "distSha");
|
||||
|
||||
return new PhpInspectEntry(
|
||||
snapshot.Name,
|
||||
snapshot.Version,
|
||||
type,
|
||||
lockfile,
|
||||
isDev,
|
||||
source,
|
||||
distSha);
|
||||
}
|
||||
}
|
||||
|
||||
private static class PhpMetadataHelpers
|
||||
{
|
||||
public static IDictionary<string, string?> Clone(IDictionary<string, string?>? metadata)
|
||||
{
|
||||
if (metadata is null || metadata.Count == 0)
|
||||
{
|
||||
return new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
|
||||
}
|
||||
|
||||
var clone = new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
|
||||
foreach (var pair in metadata)
|
||||
{
|
||||
clone[pair.Key] = pair.Value;
|
||||
}
|
||||
|
||||
return clone;
|
||||
}
|
||||
|
||||
public static string? GetString(IDictionary<string, string?> metadata, string key)
|
||||
{
|
||||
if (metadata.TryGetValue(key, out var value))
|
||||
{
|
||||
return value;
|
||||
}
|
||||
|
||||
foreach (var pair in metadata)
|
||||
{
|
||||
if (string.Equals(pair.Key, key, StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return pair.Value;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
public static bool? GetBool(IDictionary<string, string?> metadata, string key)
|
||||
{
|
||||
var value = GetString(metadata, key);
|
||||
if (string.IsNullOrWhiteSpace(value))
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
if (bool.TryParse(value, out var parsed))
|
||||
{
|
||||
return parsed;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
private sealed record LockValidationEntry(
|
||||
[property: JsonPropertyName("name")] string Name,
|
||||
[property: JsonPropertyName("version")] string? Version,
|
||||
|
||||
@@ -52,6 +52,7 @@
|
||||
<ProjectReference Include="../../Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Python/StellaOps.Scanner.Analyzers.Lang.Python.csproj" />
|
||||
<ProjectReference Include="../../Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Ruby/StellaOps.Scanner.Analyzers.Lang.Ruby.csproj" />
|
||||
<ProjectReference Include="../../Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java/StellaOps.Scanner.Analyzers.Lang.Java.csproj" />
|
||||
<ProjectReference Include="../../Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Php/StellaOps.Scanner.Analyzers.Lang.Php.csproj" />
|
||||
<ProjectReference Include="../../Scanner/__Libraries/StellaOps.Scanner.Surface.Env/StellaOps.Scanner.Surface.Env.csproj" />
|
||||
<ProjectReference Include="../../Scanner/__Libraries/StellaOps.Scanner.Surface.Validation/StellaOps.Scanner.Surface.Validation.csproj" />
|
||||
<ProjectReference Include="../../Policy/StellaOps.PolicyDsl/StellaOps.PolicyDsl.csproj" />
|
||||
|
||||
@@ -26,6 +26,7 @@ internal static class CliMetrics
|
||||
private static readonly Counter<long> JavaLockValidateCounter = Meter.CreateCounter<long>("stellaops.cli.java.lock_validate.count");
|
||||
private static readonly Counter<long> RubyInspectCounter = Meter.CreateCounter<long>("stellaops.cli.ruby.inspect.count");
|
||||
private static readonly Counter<long> RubyResolveCounter = Meter.CreateCounter<long>("stellaops.cli.ruby.resolve.count");
|
||||
private static readonly Counter<long> PhpInspectCounter = Meter.CreateCounter<long>("stellaops.cli.php.inspect.count");
|
||||
private static readonly Histogram<double> CommandDurationHistogram = Meter.CreateHistogram<double>("stellaops.cli.command.duration.ms");
|
||||
|
||||
public static void RecordScannerDownload(string channel, bool fromCache)
|
||||
@@ -143,6 +144,12 @@ internal static class CliMetrics
|
||||
new("outcome", string.IsNullOrWhiteSpace(outcome) ? "unknown" : outcome)
|
||||
});
|
||||
|
||||
public static void RecordPhpInspect(string outcome)
|
||||
=> PhpInspectCounter.Add(1, new KeyValuePair<string, object?>[]
|
||||
{
|
||||
new("outcome", string.IsNullOrWhiteSpace(outcome) ? "unknown" : outcome)
|
||||
});
|
||||
|
||||
public static IDisposable MeasureCommandDuration(string command)
|
||||
{
|
||||
var start = DateTime.UtcNow;
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Contracts;
|
||||
|
||||
/// <summary>
|
||||
/// Response for /attestations/vex/{attestationId} endpoint.
|
||||
/// </summary>
|
||||
public sealed record VexAttestationDetailResponse(
|
||||
[property: JsonPropertyName("attestationId")] string AttestationId,
|
||||
[property: JsonPropertyName("tenant")] string Tenant,
|
||||
[property: JsonPropertyName("createdAt")] DateTimeOffset CreatedAt,
|
||||
[property: JsonPropertyName("predicateType")] string PredicateType,
|
||||
[property: JsonPropertyName("subject")] VexAttestationSubject Subject,
|
||||
[property: JsonPropertyName("builder")] VexAttestationBuilderIdentity Builder,
|
||||
[property: JsonPropertyName("verification")] VexAttestationVerificationState Verification,
|
||||
[property: JsonPropertyName("chainOfCustody")] IReadOnlyList<VexAttestationCustodyLink> ChainOfCustody,
|
||||
[property: JsonPropertyName("metadata")] IReadOnlyDictionary<string, string> Metadata);
|
||||
|
||||
/// <summary>
|
||||
/// Subject of the attestation (what was signed).
|
||||
/// </summary>
|
||||
public sealed record VexAttestationSubject(
|
||||
[property: JsonPropertyName("digest")] string Digest,
|
||||
[property: JsonPropertyName("digestAlgorithm")] string DigestAlgorithm,
|
||||
[property: JsonPropertyName("name")] string? Name,
|
||||
[property: JsonPropertyName("uri")] string? Uri);
|
||||
|
||||
/// <summary>
|
||||
/// Builder identity for the attestation.
|
||||
/// </summary>
|
||||
public sealed record VexAttestationBuilderIdentity(
|
||||
[property: JsonPropertyName("id")] string Id,
|
||||
[property: JsonPropertyName("version")] string? Version,
|
||||
[property: JsonPropertyName("builderId")] string? BuilderId,
|
||||
[property: JsonPropertyName("invocationId")] string? InvocationId);
|
||||
|
||||
/// <summary>
|
||||
/// DSSE verification state.
|
||||
/// </summary>
|
||||
public sealed record VexAttestationVerificationState(
|
||||
[property: JsonPropertyName("valid")] bool Valid,
|
||||
[property: JsonPropertyName("verifiedAt")] DateTimeOffset? VerifiedAt,
|
||||
[property: JsonPropertyName("signatureType")] string? SignatureType,
|
||||
[property: JsonPropertyName("keyId")] string? KeyId,
|
||||
[property: JsonPropertyName("issuer")] string? Issuer,
|
||||
[property: JsonPropertyName("envelopeDigest")] string? EnvelopeDigest,
|
||||
[property: JsonPropertyName("diagnostics")] IReadOnlyDictionary<string, string> Diagnostics);
|
||||
|
||||
/// <summary>
|
||||
/// Chain-of-custody link in the attestation provenance.
|
||||
/// </summary>
|
||||
public sealed record VexAttestationCustodyLink(
|
||||
[property: JsonPropertyName("step")] int Step,
|
||||
[property: JsonPropertyName("actor")] string Actor,
|
||||
[property: JsonPropertyName("action")] string Action,
|
||||
[property: JsonPropertyName("timestamp")] DateTimeOffset Timestamp,
|
||||
[property: JsonPropertyName("reference")] string? Reference);
|
||||
|
||||
/// <summary>
|
||||
/// Response for /attestations/vex/list endpoint.
|
||||
/// </summary>
|
||||
public sealed record VexAttestationListResponse(
|
||||
[property: JsonPropertyName("items")] IReadOnlyList<VexAttestationListItem> Items,
|
||||
[property: JsonPropertyName("cursor")] string? Cursor,
|
||||
[property: JsonPropertyName("hasMore")] bool HasMore,
|
||||
[property: JsonPropertyName("total")] int Total);
|
||||
|
||||
/// <summary>
|
||||
/// Summary item for attestation list.
|
||||
/// </summary>
|
||||
public sealed record VexAttestationListItem(
|
||||
[property: JsonPropertyName("attestationId")] string AttestationId,
|
||||
[property: JsonPropertyName("tenant")] string Tenant,
|
||||
[property: JsonPropertyName("createdAt")] DateTimeOffset CreatedAt,
|
||||
[property: JsonPropertyName("predicateType")] string PredicateType,
|
||||
[property: JsonPropertyName("subjectDigest")] string SubjectDigest,
|
||||
[property: JsonPropertyName("valid")] bool Valid,
|
||||
[property: JsonPropertyName("builderId")] string? BuilderId);
|
||||
|
||||
/// <summary>
|
||||
/// Response for /attestations/vex/lookup endpoint.
|
||||
/// </summary>
|
||||
public sealed record VexAttestationLookupResponse(
|
||||
[property: JsonPropertyName("subjectDigest")] string SubjectDigest,
|
||||
[property: JsonPropertyName("attestations")] IReadOnlyList<VexAttestationListItem> Attestations,
|
||||
[property: JsonPropertyName("queriedAt")] DateTimeOffset QueriedAt);
|
||||
@@ -0,0 +1,141 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Contracts;
|
||||
|
||||
/// <summary>
|
||||
/// Response for /evidence/vex/bundle/{bundleId} endpoint.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceBundleResponse(
|
||||
[property: JsonPropertyName("bundleId")] string BundleId,
|
||||
[property: JsonPropertyName("tenant")] string Tenant,
|
||||
[property: JsonPropertyName("createdAt")] DateTimeOffset CreatedAt,
|
||||
[property: JsonPropertyName("contentHash")] string ContentHash,
|
||||
[property: JsonPropertyName("format")] string Format,
|
||||
[property: JsonPropertyName("itemCount")] int ItemCount,
|
||||
[property: JsonPropertyName("verification")] VexEvidenceVerificationMetadata? Verification,
|
||||
[property: JsonPropertyName("metadata")] IReadOnlyDictionary<string, string> Metadata);
|
||||
|
||||
/// <summary>
|
||||
/// Verification metadata for evidence bundles.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceVerificationMetadata(
|
||||
[property: JsonPropertyName("verified")] bool Verified,
|
||||
[property: JsonPropertyName("verifiedAt")] DateTimeOffset? VerifiedAt,
|
||||
[property: JsonPropertyName("signatureType")] string? SignatureType,
|
||||
[property: JsonPropertyName("keyId")] string? KeyId,
|
||||
[property: JsonPropertyName("issuer")] string? Issuer,
|
||||
[property: JsonPropertyName("transparencyRef")] string? TransparencyRef);
|
||||
|
||||
/// <summary>
|
||||
/// Response for /evidence/vex/list endpoint.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceListResponse(
|
||||
[property: JsonPropertyName("items")] IReadOnlyList<VexEvidenceListItem> Items,
|
||||
[property: JsonPropertyName("cursor")] string? Cursor,
|
||||
[property: JsonPropertyName("hasMore")] bool HasMore,
|
||||
[property: JsonPropertyName("total")] int Total);
|
||||
|
||||
/// <summary>
|
||||
/// Summary item for evidence list.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceListItem(
|
||||
[property: JsonPropertyName("bundleId")] string BundleId,
|
||||
[property: JsonPropertyName("tenant")] string Tenant,
|
||||
[property: JsonPropertyName("createdAt")] DateTimeOffset CreatedAt,
|
||||
[property: JsonPropertyName("contentHash")] string ContentHash,
|
||||
[property: JsonPropertyName("format")] string Format,
|
||||
[property: JsonPropertyName("itemCount")] int ItemCount,
|
||||
[property: JsonPropertyName("verified")] bool Verified);
|
||||
|
||||
/// <summary>
|
||||
/// Response for /evidence/vex/lookup endpoint.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceLookupResponse(
|
||||
[property: JsonPropertyName("vulnerabilityId")] string VulnerabilityId,
|
||||
[property: JsonPropertyName("productKey")] string ProductKey,
|
||||
[property: JsonPropertyName("evidenceItems")] IReadOnlyList<VexEvidenceItem> EvidenceItems,
|
||||
[property: JsonPropertyName("queriedAt")] DateTimeOffset QueriedAt);
|
||||
|
||||
/// <summary>
|
||||
/// Individual evidence item for a vuln/product pair.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceItem(
|
||||
[property: JsonPropertyName("observationId")] string ObservationId,
|
||||
[property: JsonPropertyName("providerId")] string ProviderId,
|
||||
[property: JsonPropertyName("status")] string Status,
|
||||
[property: JsonPropertyName("justification")] string? Justification,
|
||||
[property: JsonPropertyName("firstSeen")] DateTimeOffset FirstSeen,
|
||||
[property: JsonPropertyName("lastSeen")] DateTimeOffset LastSeen,
|
||||
[property: JsonPropertyName("documentDigest")] string DocumentDigest,
|
||||
[property: JsonPropertyName("verification")] VexEvidenceVerificationMetadata? Verification);
|
||||
|
||||
/// <summary>
|
||||
/// Response for /vuln/evidence/vex/{advisory_key} endpoint.
|
||||
/// Returns tenant-scoped raw statements for Vuln Explorer evidence tabs.
|
||||
/// </summary>
|
||||
public sealed record VexAdvisoryEvidenceResponse(
|
||||
[property: JsonPropertyName("advisoryKey")] string AdvisoryKey,
|
||||
[property: JsonPropertyName("canonicalKey")] string CanonicalKey,
|
||||
[property: JsonPropertyName("scope")] string Scope,
|
||||
[property: JsonPropertyName("aliases")] IReadOnlyList<VexAdvisoryLinkResponse> Aliases,
|
||||
[property: JsonPropertyName("statements")] IReadOnlyList<VexAdvisoryStatementResponse> Statements,
|
||||
[property: JsonPropertyName("queriedAt")] DateTimeOffset QueriedAt,
|
||||
[property: JsonPropertyName("totalCount")] int TotalCount);
|
||||
|
||||
/// <summary>
|
||||
/// Advisory link for traceability (CVE, GHSA, RHSA, etc.).
|
||||
/// </summary>
|
||||
public sealed record VexAdvisoryLinkResponse(
|
||||
[property: JsonPropertyName("identifier")] string Identifier,
|
||||
[property: JsonPropertyName("type")] string Type,
|
||||
[property: JsonPropertyName("isOriginal")] bool IsOriginal);
|
||||
|
||||
/// <summary>
|
||||
/// Raw VEX statement for an advisory with provenance and attestation metadata.
|
||||
/// </summary>
|
||||
public sealed record VexAdvisoryStatementResponse(
|
||||
[property: JsonPropertyName("statementId")] string StatementId,
|
||||
[property: JsonPropertyName("providerId")] string ProviderId,
|
||||
[property: JsonPropertyName("product")] VexAdvisoryProductResponse Product,
|
||||
[property: JsonPropertyName("status")] string Status,
|
||||
[property: JsonPropertyName("justification")] string? Justification,
|
||||
[property: JsonPropertyName("detail")] string? Detail,
|
||||
[property: JsonPropertyName("firstSeen")] DateTimeOffset FirstSeen,
|
||||
[property: JsonPropertyName("lastSeen")] DateTimeOffset LastSeen,
|
||||
[property: JsonPropertyName("provenance")] VexAdvisoryProvenanceResponse Provenance,
|
||||
[property: JsonPropertyName("attestation")] VexAdvisoryAttestationResponse? Attestation);
|
||||
|
||||
/// <summary>
|
||||
/// Product information for an advisory statement.
|
||||
/// </summary>
|
||||
public sealed record VexAdvisoryProductResponse(
|
||||
[property: JsonPropertyName("key")] string Key,
|
||||
[property: JsonPropertyName("name")] string? Name,
|
||||
[property: JsonPropertyName("version")] string? Version,
|
||||
[property: JsonPropertyName("purl")] string? Purl,
|
||||
[property: JsonPropertyName("cpe")] string? Cpe);
|
||||
|
||||
/// <summary>
|
||||
/// Provenance metadata for a VEX statement.
|
||||
/// </summary>
|
||||
public sealed record VexAdvisoryProvenanceResponse(
|
||||
[property: JsonPropertyName("documentDigest")] string DocumentDigest,
|
||||
[property: JsonPropertyName("documentFormat")] string DocumentFormat,
|
||||
[property: JsonPropertyName("sourceUri")] string SourceUri,
|
||||
[property: JsonPropertyName("revision")] string? Revision,
|
||||
[property: JsonPropertyName("insertedAt")] DateTimeOffset InsertedAt);
|
||||
|
||||
/// <summary>
|
||||
/// Attestation metadata for signature verification.
|
||||
/// </summary>
|
||||
public sealed record VexAdvisoryAttestationResponse(
|
||||
[property: JsonPropertyName("signatureType")] string SignatureType,
|
||||
[property: JsonPropertyName("issuer")] string? Issuer,
|
||||
[property: JsonPropertyName("subject")] string? Subject,
|
||||
[property: JsonPropertyName("keyId")] string? KeyId,
|
||||
[property: JsonPropertyName("verifiedAt")] DateTimeOffset? VerifiedAt,
|
||||
[property: JsonPropertyName("transparencyLogRef")] string? TransparencyLogRef,
|
||||
[property: JsonPropertyName("trustWeight")] decimal? TrustWeight,
|
||||
[property: JsonPropertyName("trustTier")] string? TrustTier);
|
||||
@@ -0,0 +1,347 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Globalization;
|
||||
using System.Linq;
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.AspNetCore.Http;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using Microsoft.Extensions.Options;
|
||||
using MongoDB.Bson;
|
||||
using MongoDB.Driver;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.WebService.Contracts;
|
||||
using StellaOps.Excititor.WebService.Services;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Endpoints;
|
||||
|
||||
/// <summary>
|
||||
/// Attestation API endpoints (WEB-OBS-54-001).
|
||||
/// Exposes /attestations/vex/* endpoints returning DSSE verification state,
|
||||
/// builder identity, and chain-of-custody links.
|
||||
/// </summary>
|
||||
public static class AttestationEndpoints
|
||||
{
|
||||
public static void MapAttestationEndpoints(this WebApplication app)
|
||||
{
|
||||
// GET /attestations/vex/list - List attestations
|
||||
app.MapGet("/attestations/vex/list", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IMongoDatabase database,
|
||||
TimeProvider timeProvider,
|
||||
[FromQuery] int? limit,
|
||||
[FromQuery] string? cursor,
|
||||
[FromQuery] string? vulnerabilityId,
|
||||
[FromQuery] string? productKey,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(50), 1, 200);
|
||||
var collection = database.GetCollection<BsonDocument>(VexMongoCollectionNames.Attestations);
|
||||
var builder = Builders<BsonDocument>.Filter;
|
||||
var filters = new List<FilterDefinition<BsonDocument>>();
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(vulnerabilityId))
|
||||
{
|
||||
filters.Add(builder.Eq("VulnerabilityId", vulnerabilityId.Trim().ToUpperInvariant()));
|
||||
}
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(productKey))
|
||||
{
|
||||
filters.Add(builder.Eq("ProductKey", productKey.Trim().ToLowerInvariant()));
|
||||
}
|
||||
|
||||
// Parse cursor if provided
|
||||
if (!string.IsNullOrWhiteSpace(cursor) && TryDecodeCursor(cursor, out var cursorTime, out var cursorId))
|
||||
{
|
||||
var ltTime = builder.Lt("IssuedAt", cursorTime);
|
||||
var eqTimeLtId = builder.And(
|
||||
builder.Eq("IssuedAt", cursorTime),
|
||||
builder.Lt("_id", cursorId));
|
||||
filters.Add(builder.Or(ltTime, eqTimeLtId));
|
||||
}
|
||||
|
||||
var filter = filters.Count == 0 ? builder.Empty : builder.And(filters);
|
||||
var sort = Builders<BsonDocument>.Sort.Descending("IssuedAt").Descending("_id");
|
||||
|
||||
var documents = await collection
|
||||
.Find(filter)
|
||||
.Sort(sort)
|
||||
.Limit(take)
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
var items = documents.Select(doc => ToListItem(doc, tenant, timeProvider)).ToList();
|
||||
|
||||
string? nextCursor = null;
|
||||
var hasMore = documents.Count == take;
|
||||
if (hasMore && documents.Count > 0)
|
||||
{
|
||||
var last = documents[^1];
|
||||
var lastTime = last.GetValue("IssuedAt", BsonNull.Value).ToUniversalTime();
|
||||
var lastId = last.GetValue("_id", BsonNull.Value).AsString;
|
||||
nextCursor = EncodeCursor(lastTime, lastId);
|
||||
}
|
||||
|
||||
var response = new VexAttestationListResponse(items, nextCursor, hasMore, items.Count);
|
||||
return Results.Ok(response);
|
||||
}).WithName("ListVexAttestations");
|
||||
|
||||
// GET /attestations/vex/{attestationId} - Get attestation details
|
||||
app.MapGet("/attestations/vex/{attestationId}", async (
|
||||
HttpContext context,
|
||||
string attestationId,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexAttestationLinkStore attestationStore,
|
||||
TimeProvider timeProvider,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(attestationId))
|
||||
{
|
||||
return Results.BadRequest(new { error = new { code = "ERR_ATTESTATION_ID", message = "attestationId is required" } });
|
||||
}
|
||||
|
||||
var attestation = await attestationStore.FindAsync(attestationId.Trim(), cancellationToken).ConfigureAwait(false);
|
||||
if (attestation is null)
|
||||
{
|
||||
return Results.NotFound(new { error = new { code = "ERR_NOT_FOUND", message = $"Attestation '{attestationId}' not found" } });
|
||||
}
|
||||
|
||||
// Build subject from observation context
|
||||
var subjectDigest = attestation.Metadata.TryGetValue("digest", out var dig) ? dig : attestation.ObservationId;
|
||||
var subject = new VexAttestationSubject(
|
||||
Digest: subjectDigest,
|
||||
DigestAlgorithm: "sha256",
|
||||
Name: $"{attestation.VulnerabilityId}/{attestation.ProductKey}",
|
||||
Uri: null);
|
||||
|
||||
var builder = new VexAttestationBuilderIdentity(
|
||||
Id: attestation.SupplierId,
|
||||
Version: null,
|
||||
BuilderId: attestation.SupplierId,
|
||||
InvocationId: attestation.ObservationId);
|
||||
|
||||
// Get verification state from metadata
|
||||
var isValid = attestation.Metadata.TryGetValue("verified", out var verified) && verified == "true";
|
||||
DateTimeOffset? verifiedAt = null;
|
||||
if (attestation.Metadata.TryGetValue("verifiedAt", out var verifiedAtStr) &&
|
||||
DateTimeOffset.TryParse(verifiedAtStr, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out var parsedVerifiedAt))
|
||||
{
|
||||
verifiedAt = parsedVerifiedAt;
|
||||
}
|
||||
|
||||
var verification = new VexAttestationVerificationState(
|
||||
Valid: isValid,
|
||||
VerifiedAt: verifiedAt,
|
||||
SignatureType: attestation.Metadata.GetValueOrDefault("signatureType", "dsse"),
|
||||
KeyId: attestation.Metadata.GetValueOrDefault("keyId"),
|
||||
Issuer: attestation.Metadata.GetValueOrDefault("issuer"),
|
||||
EnvelopeDigest: attestation.Metadata.GetValueOrDefault("envelopeDigest"),
|
||||
Diagnostics: attestation.Metadata);
|
||||
|
||||
var custodyLinks = new List<VexAttestationCustodyLink>
|
||||
{
|
||||
new(
|
||||
Step: 1,
|
||||
Actor: attestation.SupplierId,
|
||||
Action: "created",
|
||||
Timestamp: attestation.IssuedAt,
|
||||
Reference: attestation.AttestationId)
|
||||
};
|
||||
|
||||
// Add linkset link
|
||||
custodyLinks.Add(new VexAttestationCustodyLink(
|
||||
Step: 2,
|
||||
Actor: "excititor",
|
||||
Action: "linked_to_observation",
|
||||
Timestamp: attestation.IssuedAt,
|
||||
Reference: attestation.LinksetId));
|
||||
|
||||
var metadata = new Dictionary<string, string>(StringComparer.Ordinal)
|
||||
{
|
||||
["observationId"] = attestation.ObservationId,
|
||||
["linksetId"] = attestation.LinksetId,
|
||||
["vulnerabilityId"] = attestation.VulnerabilityId,
|
||||
["productKey"] = attestation.ProductKey
|
||||
};
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(attestation.JustificationSummary))
|
||||
{
|
||||
metadata["justificationSummary"] = attestation.JustificationSummary;
|
||||
}
|
||||
|
||||
var response = new VexAttestationDetailResponse(
|
||||
AttestationId: attestation.AttestationId,
|
||||
Tenant: tenant,
|
||||
CreatedAt: attestation.IssuedAt,
|
||||
PredicateType: attestation.Metadata.GetValueOrDefault("predicateType", "https://in-toto.io/attestation/v1"),
|
||||
Subject: subject,
|
||||
Builder: builder,
|
||||
Verification: verification,
|
||||
ChainOfCustody: custodyLinks,
|
||||
Metadata: metadata);
|
||||
|
||||
return Results.Ok(response);
|
||||
}).WithName("GetVexAttestation");
|
||||
|
||||
// GET /attestations/vex/lookup - Lookup attestations by linkset or observation
|
||||
app.MapGet("/attestations/vex/lookup", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IMongoDatabase database,
|
||||
TimeProvider timeProvider,
|
||||
[FromQuery] string? linksetId,
|
||||
[FromQuery] string? observationId,
|
||||
[FromQuery] int? limit,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(linksetId) && string.IsNullOrWhiteSpace(observationId))
|
||||
{
|
||||
return Results.BadRequest(new { error = new { code = "ERR_PARAMS", message = "Either linksetId or observationId is required" } });
|
||||
}
|
||||
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(50), 1, 100);
|
||||
var collection = database.GetCollection<BsonDocument>(VexMongoCollectionNames.Attestations);
|
||||
var builder = Builders<BsonDocument>.Filter;
|
||||
|
||||
FilterDefinition<BsonDocument> filter;
|
||||
if (!string.IsNullOrWhiteSpace(linksetId))
|
||||
{
|
||||
filter = builder.Eq("LinksetId", linksetId.Trim());
|
||||
}
|
||||
else
|
||||
{
|
||||
filter = builder.Eq("ObservationId", observationId!.Trim());
|
||||
}
|
||||
|
||||
var sort = Builders<BsonDocument>.Sort.Descending("IssuedAt");
|
||||
|
||||
var documents = await collection
|
||||
.Find(filter)
|
||||
.Sort(sort)
|
||||
.Limit(take)
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
var items = documents.Select(doc => ToListItem(doc, tenant, timeProvider)).ToList();
|
||||
|
||||
var response = new VexAttestationLookupResponse(
|
||||
SubjectDigest: linksetId ?? observationId ?? string.Empty,
|
||||
Attestations: items,
|
||||
QueriedAt: timeProvider.GetUtcNow());
|
||||
|
||||
return Results.Ok(response);
|
||||
}).WithName("LookupVexAttestations");
|
||||
}
|
||||
|
||||
private static VexAttestationListItem ToListItem(BsonDocument doc, string tenant, TimeProvider timeProvider)
|
||||
{
|
||||
return new VexAttestationListItem(
|
||||
AttestationId: doc.GetValue("_id", BsonNull.Value).AsString ?? string.Empty,
|
||||
Tenant: tenant,
|
||||
CreatedAt: doc.GetValue("IssuedAt", BsonNull.Value).IsBsonDateTime
|
||||
? new DateTimeOffset(doc["IssuedAt"].ToUniversalTime(), TimeSpan.Zero)
|
||||
: timeProvider.GetUtcNow(),
|
||||
PredicateType: "https://in-toto.io/attestation/v1",
|
||||
SubjectDigest: doc.GetValue("ObservationId", BsonNull.Value).AsString ?? string.Empty,
|
||||
Valid: doc.Contains("Metadata") && !doc["Metadata"].IsBsonNull &&
|
||||
doc["Metadata"].AsBsonDocument.Contains("verified") &&
|
||||
doc["Metadata"]["verified"].AsString == "true",
|
||||
BuilderId: doc.GetValue("SupplierId", BsonNull.Value).AsString);
|
||||
}
|
||||
|
||||
private static bool TryResolveTenant(HttpContext context, VexMongoStorageOptions options, out string tenant, out IResult? problem)
|
||||
{
|
||||
tenant = options.DefaultTenant;
|
||||
problem = null;
|
||||
|
||||
if (context.Request.Headers.TryGetValue("X-Stella-Tenant", out var headerValues) && headerValues.Count > 0)
|
||||
{
|
||||
var requestedTenant = headerValues[0]?.Trim();
|
||||
if (string.IsNullOrEmpty(requestedTenant))
|
||||
{
|
||||
problem = Results.BadRequest(new { error = new { code = "ERR_TENANT", message = "X-Stella-Tenant header must not be empty" } });
|
||||
return false;
|
||||
}
|
||||
|
||||
if (!string.Equals(requestedTenant, options.DefaultTenant, StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
problem = Results.Json(
|
||||
new { error = new { code = "ERR_TENANT_FORBIDDEN", message = $"Tenant '{requestedTenant}' is not allowed" } },
|
||||
statusCode: StatusCodes.Status403Forbidden);
|
||||
return false;
|
||||
}
|
||||
|
||||
tenant = requestedTenant;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private static bool TryDecodeCursor(string cursor, out DateTime timestamp, out string id)
|
||||
{
|
||||
timestamp = default;
|
||||
id = string.Empty;
|
||||
try
|
||||
{
|
||||
var payload = System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(cursor));
|
||||
var parts = payload.Split('|');
|
||||
if (parts.Length != 2)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
if (!DateTimeOffset.TryParse(parts[0], CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out var parsed))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
timestamp = parsed.UtcDateTime;
|
||||
id = parts[1];
|
||||
return true;
|
||||
}
|
||||
catch
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
private static string EncodeCursor(DateTime timestamp, string id)
|
||||
{
|
||||
var payload = FormattableString.Invariant($"{timestamp:O}|{id}");
|
||||
return Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(payload));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,311 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Collections.Immutable;
|
||||
using System.Globalization;
|
||||
using System.Linq;
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.AspNetCore.Http;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using Microsoft.Extensions.Options;
|
||||
using MongoDB.Bson;
|
||||
using MongoDB.Driver;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Canonicalization;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.WebService.Contracts;
|
||||
using StellaOps.Excititor.WebService.Services;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Endpoints;
|
||||
|
||||
/// <summary>
|
||||
/// Evidence API endpoints (WEB-OBS-53-001).
|
||||
/// Exposes /evidence/vex/* endpoints that fetch locker bundles, enforce scopes,
|
||||
/// and surface verification metadata without synthesizing verdicts.
|
||||
/// </summary>
|
||||
public static class EvidenceEndpoints
|
||||
{
|
||||
public static void MapEvidenceEndpoints(this WebApplication app)
|
||||
{
|
||||
// GET /evidence/vex/list - List evidence exports
|
||||
app.MapGet("/evidence/vex/list", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IMongoDatabase database,
|
||||
TimeProvider timeProvider,
|
||||
[FromQuery] int? limit,
|
||||
[FromQuery] string? cursor,
|
||||
[FromQuery] string? format,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(50), 1, 200);
|
||||
var collection = database.GetCollection<BsonDocument>(VexMongoCollectionNames.Exports);
|
||||
var builder = Builders<BsonDocument>.Filter;
|
||||
var filters = new List<FilterDefinition<BsonDocument>>();
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(format))
|
||||
{
|
||||
filters.Add(builder.Eq("Format", format.Trim().ToLowerInvariant()));
|
||||
}
|
||||
|
||||
// Parse cursor if provided (base64-encoded timestamp|id)
|
||||
if (!string.IsNullOrWhiteSpace(cursor) && TryDecodeCursor(cursor, out var cursorTime, out var cursorId))
|
||||
{
|
||||
var ltTime = builder.Lt("CreatedAt", cursorTime);
|
||||
var eqTimeLtId = builder.And(
|
||||
builder.Eq("CreatedAt", cursorTime),
|
||||
builder.Lt("_id", cursorId));
|
||||
filters.Add(builder.Or(ltTime, eqTimeLtId));
|
||||
}
|
||||
|
||||
var filter = filters.Count == 0 ? builder.Empty : builder.And(filters);
|
||||
var sort = Builders<BsonDocument>.Sort.Descending("CreatedAt").Descending("_id");
|
||||
|
||||
var documents = await collection
|
||||
.Find(filter)
|
||||
.Sort(sort)
|
||||
.Limit(take)
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
var items = documents.Select(doc => new VexEvidenceListItem(
|
||||
BundleId: doc.GetValue("ExportId", BsonNull.Value).AsString ?? doc.GetValue("_id", BsonNull.Value).AsString,
|
||||
Tenant: tenant,
|
||||
CreatedAt: doc.GetValue("CreatedAt", BsonNull.Value).IsBsonDateTime
|
||||
? new DateTimeOffset(doc["CreatedAt"].ToUniversalTime(), TimeSpan.Zero)
|
||||
: timeProvider.GetUtcNow(),
|
||||
ContentHash: doc.GetValue("ArtifactDigest", BsonNull.Value).AsString ?? string.Empty,
|
||||
Format: doc.GetValue("Format", BsonNull.Value).AsString ?? "json",
|
||||
ItemCount: doc.GetValue("ClaimCount", BsonNull.Value).IsInt32 ? doc["ClaimCount"].AsInt32 : 0,
|
||||
Verified: doc.Contains("Attestation") && !doc["Attestation"].IsBsonNull)).ToList();
|
||||
|
||||
string? nextCursor = null;
|
||||
var hasMore = documents.Count == take;
|
||||
if (hasMore && documents.Count > 0)
|
||||
{
|
||||
var last = documents[^1];
|
||||
var lastTime = last.GetValue("CreatedAt", BsonNull.Value).ToUniversalTime();
|
||||
var lastId = last.GetValue("_id", BsonNull.Value).AsString;
|
||||
nextCursor = EncodeCursor(lastTime, lastId);
|
||||
}
|
||||
|
||||
var response = new VexEvidenceListResponse(items, nextCursor, hasMore, items.Count);
|
||||
return Results.Ok(response);
|
||||
}).WithName("ListVexEvidence");
|
||||
|
||||
// GET /evidence/vex/bundle/{bundleId} - Get evidence bundle details
|
||||
app.MapGet("/evidence/vex/bundle/{bundleId}", async (
|
||||
HttpContext context,
|
||||
string bundleId,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IMongoDatabase database,
|
||||
TimeProvider timeProvider,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(bundleId))
|
||||
{
|
||||
return Results.BadRequest(new { error = new { code = "ERR_BUNDLE_ID", message = "bundleId is required" } });
|
||||
}
|
||||
|
||||
var collection = database.GetCollection<BsonDocument>(VexMongoCollectionNames.Exports);
|
||||
var filter = Builders<BsonDocument>.Filter.Or(
|
||||
Builders<BsonDocument>.Filter.Eq("_id", bundleId.Trim()),
|
||||
Builders<BsonDocument>.Filter.Eq("ExportId", bundleId.Trim()));
|
||||
|
||||
var doc = await collection.Find(filter).FirstOrDefaultAsync(cancellationToken).ConfigureAwait(false);
|
||||
if (doc is null)
|
||||
{
|
||||
return Results.NotFound(new { error = new { code = "ERR_NOT_FOUND", message = $"Evidence bundle '{bundleId}' not found" } });
|
||||
}
|
||||
|
||||
VexEvidenceVerificationMetadata? verification = null;
|
||||
if (doc.Contains("Attestation") && !doc["Attestation"].IsBsonNull)
|
||||
{
|
||||
var att = doc["Attestation"].AsBsonDocument;
|
||||
verification = new VexEvidenceVerificationMetadata(
|
||||
Verified: true,
|
||||
VerifiedAt: att.Contains("SignedAt") && att["SignedAt"].IsBsonDateTime
|
||||
? new DateTimeOffset(att["SignedAt"].ToUniversalTime(), TimeSpan.Zero)
|
||||
: null,
|
||||
SignatureType: "dsse",
|
||||
KeyId: att.GetValue("KeyId", BsonNull.Value).AsString,
|
||||
Issuer: att.GetValue("Issuer", BsonNull.Value).AsString,
|
||||
TransparencyRef: att.Contains("Rekor") && !att["Rekor"].IsBsonNull
|
||||
? att["Rekor"].AsBsonDocument.GetValue("Location", BsonNull.Value).AsString
|
||||
: null);
|
||||
}
|
||||
|
||||
var metadata = new Dictionary<string, string>(StringComparer.Ordinal);
|
||||
if (doc.Contains("SourceProviders") && doc["SourceProviders"].IsBsonArray)
|
||||
{
|
||||
metadata["sourceProviders"] = string.Join(",", doc["SourceProviders"].AsBsonArray.Select(v => v.AsString));
|
||||
}
|
||||
if (doc.Contains("PolicyRevisionId") && !doc["PolicyRevisionId"].IsBsonNull)
|
||||
{
|
||||
metadata["policyRevisionId"] = doc["PolicyRevisionId"].AsString;
|
||||
}
|
||||
|
||||
var response = new VexEvidenceBundleResponse(
|
||||
BundleId: doc.GetValue("ExportId", BsonNull.Value).AsString ?? bundleId.Trim(),
|
||||
Tenant: tenant,
|
||||
CreatedAt: doc.GetValue("CreatedAt", BsonNull.Value).IsBsonDateTime
|
||||
? new DateTimeOffset(doc["CreatedAt"].ToUniversalTime(), TimeSpan.Zero)
|
||||
: timeProvider.GetUtcNow(),
|
||||
ContentHash: doc.GetValue("ArtifactDigest", BsonNull.Value).AsString ?? string.Empty,
|
||||
Format: doc.GetValue("Format", BsonNull.Value).AsString ?? "json",
|
||||
ItemCount: doc.GetValue("ClaimCount", BsonNull.Value).IsInt32 ? doc["ClaimCount"].AsInt32 : 0,
|
||||
Verification: verification,
|
||||
Metadata: metadata);
|
||||
|
||||
return Results.Ok(response);
|
||||
}).WithName("GetVexEvidenceBundle");
|
||||
|
||||
// GET /evidence/vex/lookup - Lookup evidence for vuln/product pair
|
||||
app.MapGet("/evidence/vex/lookup", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexObservationProjectionService projectionService,
|
||||
TimeProvider timeProvider,
|
||||
[FromQuery] string vulnerabilityId,
|
||||
[FromQuery] string productKey,
|
||||
[FromQuery] int? limit,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(vulnerabilityId) || string.IsNullOrWhiteSpace(productKey))
|
||||
{
|
||||
return Results.BadRequest(new { error = new { code = "ERR_PARAMS", message = "vulnerabilityId and productKey are required" } });
|
||||
}
|
||||
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(100), 1, 500);
|
||||
var request = new VexObservationProjectionRequest(
|
||||
tenant,
|
||||
vulnerabilityId.Trim(),
|
||||
productKey.Trim(),
|
||||
ImmutableHashSet<string>.Empty,
|
||||
ImmutableHashSet<VexClaimStatus>.Empty,
|
||||
null,
|
||||
take);
|
||||
|
||||
var result = await projectionService.QueryAsync(request, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
var items = result.Statements.Select(s => new VexEvidenceItem(
|
||||
ObservationId: s.ObservationId,
|
||||
ProviderId: s.ProviderId,
|
||||
Status: s.Status.ToString().ToLowerInvariant(),
|
||||
Justification: s.Justification?.ToString().ToLowerInvariant(),
|
||||
FirstSeen: s.FirstSeen,
|
||||
LastSeen: s.LastSeen,
|
||||
DocumentDigest: s.Document.Digest,
|
||||
Verification: s.Signature is null ? null : new VexEvidenceVerificationMetadata(
|
||||
Verified: s.Signature.VerifiedAt.HasValue,
|
||||
VerifiedAt: s.Signature.VerifiedAt,
|
||||
SignatureType: s.Signature.Type,
|
||||
KeyId: s.Signature.KeyId,
|
||||
Issuer: s.Signature.Issuer,
|
||||
TransparencyRef: null))).ToList();
|
||||
|
||||
var response = new VexEvidenceLookupResponse(
|
||||
VulnerabilityId: vulnerabilityId.Trim(),
|
||||
ProductKey: productKey.Trim(),
|
||||
EvidenceItems: items,
|
||||
QueriedAt: timeProvider.GetUtcNow());
|
||||
|
||||
return Results.Ok(response);
|
||||
}).WithName("LookupVexEvidence");
|
||||
}
|
||||
|
||||
private static bool TryResolveTenant(HttpContext context, VexMongoStorageOptions options, out string tenant, out IResult? problem)
|
||||
{
|
||||
tenant = options.DefaultTenant;
|
||||
problem = null;
|
||||
|
||||
if (context.Request.Headers.TryGetValue("X-Stella-Tenant", out var headerValues) && headerValues.Count > 0)
|
||||
{
|
||||
var requestedTenant = headerValues[0]?.Trim();
|
||||
if (string.IsNullOrEmpty(requestedTenant))
|
||||
{
|
||||
problem = Results.BadRequest(new { error = new { code = "ERR_TENANT", message = "X-Stella-Tenant header must not be empty" } });
|
||||
return false;
|
||||
}
|
||||
|
||||
if (!string.Equals(requestedTenant, options.DefaultTenant, StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
problem = Results.Json(
|
||||
new { error = new { code = "ERR_TENANT_FORBIDDEN", message = $"Tenant '{requestedTenant}' is not allowed" } },
|
||||
statusCode: StatusCodes.Status403Forbidden);
|
||||
return false;
|
||||
}
|
||||
|
||||
tenant = requestedTenant;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private static bool TryDecodeCursor(string cursor, out DateTime timestamp, out string id)
|
||||
{
|
||||
timestamp = default;
|
||||
id = string.Empty;
|
||||
try
|
||||
{
|
||||
var payload = System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(cursor));
|
||||
var parts = payload.Split('|');
|
||||
if (parts.Length != 2)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
if (!DateTimeOffset.TryParse(parts[0], CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out var parsed))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
timestamp = parsed.UtcDateTime;
|
||||
id = parts[1];
|
||||
return true;
|
||||
}
|
||||
catch
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
private static string EncodeCursor(DateTime timestamp, string id)
|
||||
{
|
||||
var payload = FormattableString.Invariant($"{timestamp:O}|{id}");
|
||||
return Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(payload));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,366 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Diagnostics;
|
||||
using System.Linq;
|
||||
using System.Text.Json.Serialization;
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.AspNetCore.Http;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using Microsoft.Extensions.Options;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.WebService.Contracts;
|
||||
using StellaOps.Excititor.WebService.Services;
|
||||
using StellaOps.Excititor.WebService.Telemetry;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Endpoints;
|
||||
|
||||
/// <summary>
|
||||
/// Linkset API endpoints (EXCITITOR-LNM-21-202).
|
||||
/// Exposes /vex/linksets/* endpoints that surface alias mappings, conflict markers,
|
||||
/// and provenance proofs exactly as stored. Errors map to ERR_AGG_* codes.
|
||||
/// </summary>
|
||||
public static class LinksetEndpoints
|
||||
{
|
||||
public static void MapLinksetEndpoints(this WebApplication app)
|
||||
{
|
||||
var group = app.MapGroup("/vex/linksets");
|
||||
|
||||
// GET /vex/linksets - List linksets with filters
|
||||
group.MapGet("", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexLinksetStore linksetStore,
|
||||
[FromQuery] int? limit,
|
||||
[FromQuery] string? cursor,
|
||||
[FromQuery] string? vulnerabilityId,
|
||||
[FromQuery] string? productKey,
|
||||
[FromQuery] string? providerId,
|
||||
[FromQuery] bool? hasConflicts,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(50), 1, 100);
|
||||
|
||||
IReadOnlyList<VexLinkset> linksets;
|
||||
|
||||
// Route to appropriate query method based on filters
|
||||
if (hasConflicts == true)
|
||||
{
|
||||
linksets = await linksetStore
|
||||
.FindWithConflictsAsync(tenant, take, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
else if (!string.IsNullOrWhiteSpace(vulnerabilityId))
|
||||
{
|
||||
linksets = await linksetStore
|
||||
.FindByVulnerabilityAsync(tenant, vulnerabilityId.Trim(), take, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
else if (!string.IsNullOrWhiteSpace(productKey))
|
||||
{
|
||||
linksets = await linksetStore
|
||||
.FindByProductKeyAsync(tenant, productKey.Trim(), take, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
else if (!string.IsNullOrWhiteSpace(providerId))
|
||||
{
|
||||
linksets = await linksetStore
|
||||
.FindByProviderAsync(tenant, providerId.Trim(), take, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
else
|
||||
{
|
||||
return Results.BadRequest(new
|
||||
{
|
||||
error = new
|
||||
{
|
||||
code = "ERR_AGG_PARAMS",
|
||||
message = "At least one filter is required: vulnerabilityId, productKey, providerId, or hasConflicts=true"
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
var items = linksets
|
||||
.Take(take)
|
||||
.Select(ToListItem)
|
||||
.ToList();
|
||||
|
||||
// Record conflict metrics (EXCITITOR-OBS-51-001)
|
||||
foreach (var linkset in linksets.Take(take))
|
||||
{
|
||||
if (linkset.HasConflicts)
|
||||
{
|
||||
LinksetTelemetry.RecordLinksetDisagreements(tenant, linkset);
|
||||
}
|
||||
}
|
||||
|
||||
var hasMore = linksets.Count > take;
|
||||
string? nextCursor = null;
|
||||
if (hasMore && items.Count > 0)
|
||||
{
|
||||
var last = linksets[items.Count - 1];
|
||||
nextCursor = EncodeCursor(last.UpdatedAt.UtcDateTime, last.LinksetId);
|
||||
}
|
||||
|
||||
var response = new VexLinksetListResponse(items, nextCursor);
|
||||
return Results.Ok(response);
|
||||
}).WithName("ListVexLinksets");
|
||||
|
||||
// GET /vex/linksets/{linksetId} - Get linkset by ID
|
||||
group.MapGet("/{linksetId}", async (
|
||||
HttpContext context,
|
||||
string linksetId,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexLinksetStore linksetStore,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(linksetId))
|
||||
{
|
||||
return Results.BadRequest(new
|
||||
{
|
||||
error = new { code = "ERR_AGG_PARAMS", message = "linksetId is required" }
|
||||
});
|
||||
}
|
||||
|
||||
var linkset = await linksetStore
|
||||
.GetByIdAsync(tenant, linksetId.Trim(), cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
if (linkset is null)
|
||||
{
|
||||
return Results.NotFound(new
|
||||
{
|
||||
error = new { code = "ERR_AGG_NOT_FOUND", message = $"Linkset '{linksetId}' not found" }
|
||||
});
|
||||
}
|
||||
|
||||
var response = ToDetailResponse(linkset);
|
||||
return Results.Ok(response);
|
||||
}).WithName("GetVexLinkset");
|
||||
|
||||
// GET /vex/linksets/lookup - Lookup linkset by vulnerability and product
|
||||
group.MapGet("/lookup", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexLinksetStore linksetStore,
|
||||
[FromQuery] string? vulnerabilityId,
|
||||
[FromQuery] string? productKey,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(vulnerabilityId) || string.IsNullOrWhiteSpace(productKey))
|
||||
{
|
||||
return Results.BadRequest(new
|
||||
{
|
||||
error = new { code = "ERR_AGG_PARAMS", message = "vulnerabilityId and productKey are required" }
|
||||
});
|
||||
}
|
||||
|
||||
var linksetId = VexLinkset.CreateLinksetId(tenant, vulnerabilityId.Trim(), productKey.Trim());
|
||||
var linkset = await linksetStore
|
||||
.GetByIdAsync(tenant, linksetId, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
if (linkset is null)
|
||||
{
|
||||
return Results.NotFound(new
|
||||
{
|
||||
error = new { code = "ERR_AGG_NOT_FOUND", message = "No linkset found for the specified vulnerability and product" }
|
||||
});
|
||||
}
|
||||
|
||||
var response = ToDetailResponse(linkset);
|
||||
return Results.Ok(response);
|
||||
}).WithName("LookupVexLinkset");
|
||||
|
||||
// GET /vex/linksets/count - Get linkset counts for tenant
|
||||
group.MapGet("/count", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexLinksetStore linksetStore,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
var total = await linksetStore
|
||||
.CountAsync(tenant, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
var withConflicts = await linksetStore
|
||||
.CountWithConflictsAsync(tenant, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return Results.Ok(new LinksetCountResponse(total, withConflicts));
|
||||
}).WithName("CountVexLinksets");
|
||||
|
||||
// GET /vex/linksets/conflicts - List linksets with conflicts (shorthand)
|
||||
group.MapGet("/conflicts", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexLinksetStore linksetStore,
|
||||
[FromQuery] int? limit,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(50), 1, 100);
|
||||
|
||||
var linksets = await linksetStore
|
||||
.FindWithConflictsAsync(tenant, take, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
var items = linksets.Select(ToListItem).ToList();
|
||||
var response = new VexLinksetListResponse(items, null);
|
||||
return Results.Ok(response);
|
||||
}).WithName("ListVexLinksetConflicts");
|
||||
}
|
||||
|
||||
private static VexLinksetListItem ToListItem(VexLinkset linkset)
|
||||
{
|
||||
return new VexLinksetListItem(
|
||||
LinksetId: linkset.LinksetId,
|
||||
Tenant: linkset.Tenant,
|
||||
VulnerabilityId: linkset.VulnerabilityId,
|
||||
ProductKey: linkset.ProductKey,
|
||||
ProviderIds: linkset.ProviderIds.ToList(),
|
||||
Statuses: linkset.Statuses.ToList(),
|
||||
Aliases: Array.Empty<string>(), // Aliases are in observations, not linksets
|
||||
Purls: Array.Empty<string>(),
|
||||
Cpes: Array.Empty<string>(),
|
||||
References: Array.Empty<VexLinksetReference>(),
|
||||
Disagreements: linkset.Disagreements
|
||||
.Select(d => new VexLinksetDisagreement(d.ProviderId, d.Status, d.Justification, d.Confidence))
|
||||
.ToList(),
|
||||
Observations: linkset.Observations
|
||||
.Select(o => new VexLinksetObservationRef(o.ObservationId, o.ProviderId, o.Status, o.Confidence))
|
||||
.ToList(),
|
||||
CreatedAt: linkset.CreatedAt);
|
||||
}
|
||||
|
||||
private static VexLinksetDetailResponse ToDetailResponse(VexLinkset linkset)
|
||||
{
|
||||
return new VexLinksetDetailResponse(
|
||||
LinksetId: linkset.LinksetId,
|
||||
Tenant: linkset.Tenant,
|
||||
VulnerabilityId: linkset.VulnerabilityId,
|
||||
ProductKey: linkset.ProductKey,
|
||||
ProviderIds: linkset.ProviderIds.ToList(),
|
||||
Statuses: linkset.Statuses.ToList(),
|
||||
Confidence: linkset.Confidence.ToString().ToLowerInvariant(),
|
||||
HasConflicts: linkset.HasConflicts,
|
||||
Disagreements: linkset.Disagreements
|
||||
.Select(d => new VexLinksetDisagreement(d.ProviderId, d.Status, d.Justification, d.Confidence))
|
||||
.ToList(),
|
||||
Observations: linkset.Observations
|
||||
.Select(o => new VexLinksetObservationRef(o.ObservationId, o.ProviderId, o.Status, o.Confidence))
|
||||
.ToList(),
|
||||
CreatedAt: linkset.CreatedAt,
|
||||
UpdatedAt: linkset.UpdatedAt);
|
||||
}
|
||||
|
||||
private static bool TryResolveTenant(
|
||||
HttpContext context,
|
||||
VexMongoStorageOptions options,
|
||||
out string tenant,
|
||||
out IResult? problem)
|
||||
{
|
||||
problem = null;
|
||||
tenant = string.Empty;
|
||||
|
||||
var headerTenant = context.Request.Headers["X-Stella-Tenant"].FirstOrDefault();
|
||||
if (!string.IsNullOrWhiteSpace(headerTenant))
|
||||
{
|
||||
tenant = headerTenant.Trim().ToLowerInvariant();
|
||||
}
|
||||
else if (!string.IsNullOrWhiteSpace(options.DefaultTenant))
|
||||
{
|
||||
tenant = options.DefaultTenant.Trim().ToLowerInvariant();
|
||||
}
|
||||
else
|
||||
{
|
||||
problem = Results.BadRequest(new
|
||||
{
|
||||
error = new { code = "ERR_TENANT", message = "X-Stella-Tenant header is required" }
|
||||
});
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private static string EncodeCursor(DateTime timestamp, string id)
|
||||
{
|
||||
var raw = $"{timestamp:O}|{id}";
|
||||
return Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(raw));
|
||||
}
|
||||
}
|
||||
|
||||
// Detail response for single linkset
|
||||
public sealed record VexLinksetDetailResponse(
|
||||
[property: JsonPropertyName("linksetId")] string LinksetId,
|
||||
[property: JsonPropertyName("tenant")] string Tenant,
|
||||
[property: JsonPropertyName("vulnerabilityId")] string VulnerabilityId,
|
||||
[property: JsonPropertyName("productKey")] string ProductKey,
|
||||
[property: JsonPropertyName("providerIds")] IReadOnlyList<string> ProviderIds,
|
||||
[property: JsonPropertyName("statuses")] IReadOnlyList<string> Statuses,
|
||||
[property: JsonPropertyName("confidence")] string Confidence,
|
||||
[property: JsonPropertyName("hasConflicts")] bool HasConflicts,
|
||||
[property: JsonPropertyName("disagreements")] IReadOnlyList<VexLinksetDisagreement> Disagreements,
|
||||
[property: JsonPropertyName("observations")] IReadOnlyList<VexLinksetObservationRef> Observations,
|
||||
[property: JsonPropertyName("createdAt")] DateTimeOffset CreatedAt,
|
||||
[property: JsonPropertyName("updatedAt")] DateTimeOffset UpdatedAt);
|
||||
|
||||
// Count response
|
||||
public sealed record LinksetCountResponse(
|
||||
[property: JsonPropertyName("total")] long Total,
|
||||
[property: JsonPropertyName("withConflicts")] long WithConflicts);
|
||||
@@ -0,0 +1,310 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Linq;
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.AspNetCore.Http;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using Microsoft.Extensions.Options;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.WebService.Contracts;
|
||||
using StellaOps.Excititor.WebService.Services;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Endpoints;
|
||||
|
||||
/// <summary>
|
||||
/// Observation API endpoints (EXCITITOR-LNM-21-201).
|
||||
/// Exposes /vex/observations/* endpoints with filters for advisory/product/provider,
|
||||
/// strict RBAC, and deterministic pagination (no derived verdict fields).
|
||||
/// </summary>
|
||||
public static class ObservationEndpoints
|
||||
{
|
||||
public static void MapObservationEndpoints(this WebApplication app)
|
||||
{
|
||||
var group = app.MapGroup("/vex/observations");
|
||||
|
||||
// GET /vex/observations - List observations with filters
|
||||
group.MapGet("", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexObservationStore observationStore,
|
||||
TimeProvider timeProvider,
|
||||
[FromQuery] int? limit,
|
||||
[FromQuery] string? cursor,
|
||||
[FromQuery] string? vulnerabilityId,
|
||||
[FromQuery] string? productKey,
|
||||
[FromQuery] string? providerId,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(50), 1, 100);
|
||||
|
||||
IReadOnlyList<VexObservation> observations;
|
||||
|
||||
// Route to appropriate query method based on filters
|
||||
if (!string.IsNullOrWhiteSpace(vulnerabilityId) && !string.IsNullOrWhiteSpace(productKey))
|
||||
{
|
||||
observations = await observationStore
|
||||
.FindByVulnerabilityAndProductAsync(tenant, vulnerabilityId.Trim(), productKey.Trim(), cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
else if (!string.IsNullOrWhiteSpace(providerId))
|
||||
{
|
||||
observations = await observationStore
|
||||
.FindByProviderAsync(tenant, providerId.Trim(), take, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
else
|
||||
{
|
||||
// No filter - return empty for now (full list requires pagination infrastructure)
|
||||
return Results.BadRequest(new
|
||||
{
|
||||
error = new
|
||||
{
|
||||
code = "ERR_PARAMS",
|
||||
message = "At least one filter is required: vulnerabilityId+productKey or providerId"
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
var items = observations
|
||||
.Take(take)
|
||||
.Select(obs => ToListItem(obs))
|
||||
.ToList();
|
||||
|
||||
var hasMore = observations.Count > take;
|
||||
string? nextCursor = null;
|
||||
if (hasMore && items.Count > 0)
|
||||
{
|
||||
var last = observations[items.Count - 1];
|
||||
nextCursor = EncodeCursor(last.CreatedAt.UtcDateTime, last.ObservationId);
|
||||
}
|
||||
|
||||
var response = new VexObservationListResponse(items, nextCursor);
|
||||
return Results.Ok(response);
|
||||
}).WithName("ListVexObservations");
|
||||
|
||||
// GET /vex/observations/{observationId} - Get observation by ID
|
||||
group.MapGet("/{observationId}", async (
|
||||
HttpContext context,
|
||||
string observationId,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexObservationStore observationStore,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(observationId))
|
||||
{
|
||||
return Results.BadRequest(new
|
||||
{
|
||||
error = new { code = "ERR_PARAMS", message = "observationId is required" }
|
||||
});
|
||||
}
|
||||
|
||||
var observation = await observationStore
|
||||
.GetByIdAsync(tenant, observationId.Trim(), cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
if (observation is null)
|
||||
{
|
||||
return Results.NotFound(new
|
||||
{
|
||||
error = new { code = "ERR_NOT_FOUND", message = $"Observation '{observationId}' not found" }
|
||||
});
|
||||
}
|
||||
|
||||
var response = ToDetailResponse(observation);
|
||||
return Results.Ok(response);
|
||||
}).WithName("GetVexObservation");
|
||||
|
||||
// GET /vex/observations/count - Get observation count for tenant
|
||||
group.MapGet("/count", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexObservationStore observationStore,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, "vex.read");
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!TryResolveTenant(context, storageOptions.Value, out var tenant, out var tenantError))
|
||||
{
|
||||
return tenantError;
|
||||
}
|
||||
|
||||
var count = await observationStore
|
||||
.CountAsync(tenant, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return Results.Ok(new { count });
|
||||
}).WithName("CountVexObservations");
|
||||
}
|
||||
|
||||
private static VexObservationListItem ToListItem(VexObservation obs)
|
||||
{
|
||||
var firstStatement = obs.Statements.FirstOrDefault();
|
||||
return new VexObservationListItem(
|
||||
ObservationId: obs.ObservationId,
|
||||
Tenant: obs.Tenant,
|
||||
ProviderId: obs.ProviderId,
|
||||
VulnerabilityId: firstStatement?.VulnerabilityId ?? string.Empty,
|
||||
ProductKey: firstStatement?.ProductKey ?? string.Empty,
|
||||
Status: firstStatement?.Status.ToString().ToLowerInvariant() ?? "unknown",
|
||||
CreatedAt: obs.CreatedAt,
|
||||
LastObserved: firstStatement?.LastObserved,
|
||||
Purls: obs.Linkset.Purls.ToList());
|
||||
}
|
||||
|
||||
private static VexObservationDetailResponse ToDetailResponse(VexObservation obs)
|
||||
{
|
||||
var upstream = new VexObservationUpstreamResponse(
|
||||
obs.Upstream.UpstreamId,
|
||||
obs.Upstream.DocumentVersion,
|
||||
obs.Upstream.FetchedAt,
|
||||
obs.Upstream.ReceivedAt,
|
||||
obs.Upstream.ContentHash,
|
||||
obs.Upstream.Signature.Present
|
||||
? new VexObservationSignatureResponse(
|
||||
obs.Upstream.Signature.Format ?? "dsse",
|
||||
obs.Upstream.Signature.KeyId,
|
||||
Issuer: null,
|
||||
VerifiedAtUtc: null)
|
||||
: null);
|
||||
|
||||
var content = new VexObservationContentResponse(
|
||||
obs.Content.Format,
|
||||
obs.Content.SpecVersion);
|
||||
|
||||
var statements = obs.Statements
|
||||
.Select(stmt => new VexObservationStatementItem(
|
||||
stmt.VulnerabilityId,
|
||||
stmt.ProductKey,
|
||||
stmt.Status.ToString().ToLowerInvariant(),
|
||||
stmt.LastObserved,
|
||||
stmt.Locator,
|
||||
stmt.Justification?.ToString().ToLowerInvariant(),
|
||||
stmt.IntroducedVersion,
|
||||
stmt.FixedVersion))
|
||||
.ToList();
|
||||
|
||||
var linkset = new VexObservationLinksetResponse(
|
||||
obs.Linkset.Aliases.ToList(),
|
||||
obs.Linkset.Purls.ToList(),
|
||||
obs.Linkset.Cpes.ToList(),
|
||||
obs.Linkset.References.Select(r => new VexObservationReferenceItem(r.Type, r.Url)).ToList());
|
||||
|
||||
return new VexObservationDetailResponse(
|
||||
obs.ObservationId,
|
||||
obs.Tenant,
|
||||
obs.ProviderId,
|
||||
obs.StreamId,
|
||||
upstream,
|
||||
content,
|
||||
statements,
|
||||
linkset,
|
||||
obs.CreatedAt);
|
||||
}
|
||||
|
||||
private static bool TryResolveTenant(
|
||||
HttpContext context,
|
||||
VexMongoStorageOptions options,
|
||||
out string tenant,
|
||||
out IResult? problem)
|
||||
{
|
||||
problem = null;
|
||||
tenant = string.Empty;
|
||||
|
||||
var headerTenant = context.Request.Headers["X-Stella-Tenant"].FirstOrDefault();
|
||||
if (!string.IsNullOrWhiteSpace(headerTenant))
|
||||
{
|
||||
tenant = headerTenant.Trim().ToLowerInvariant();
|
||||
}
|
||||
else if (!string.IsNullOrWhiteSpace(options.DefaultTenant))
|
||||
{
|
||||
tenant = options.DefaultTenant.Trim().ToLowerInvariant();
|
||||
}
|
||||
else
|
||||
{
|
||||
problem = Results.BadRequest(new
|
||||
{
|
||||
error = new { code = "ERR_TENANT", message = "X-Stella-Tenant header is required" }
|
||||
});
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private static string EncodeCursor(DateTime timestamp, string id)
|
||||
{
|
||||
var raw = $"{timestamp:O}|{id}";
|
||||
return Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(raw));
|
||||
}
|
||||
}
|
||||
|
||||
// Additional response DTOs for observation detail
|
||||
public sealed record VexObservationUpstreamResponse(
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("upstreamId")] string UpstreamId,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("documentVersion")] string? DocumentVersion,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("fetchedAt")] DateTimeOffset FetchedAt,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("receivedAt")] DateTimeOffset ReceivedAt,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("contentHash")] string ContentHash,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("signature")] VexObservationSignatureResponse? Signature);
|
||||
|
||||
public sealed record VexObservationContentResponse(
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("format")] string Format,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("specVersion")] string? SpecVersion);
|
||||
|
||||
public sealed record VexObservationStatementItem(
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("vulnerabilityId")] string VulnerabilityId,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("productKey")] string ProductKey,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("status")] string Status,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("lastObserved")] DateTimeOffset? LastObserved,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("locator")] string? Locator,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("justification")] string? Justification,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("introducedVersion")] string? IntroducedVersion,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("fixedVersion")] string? FixedVersion);
|
||||
|
||||
public sealed record VexObservationLinksetResponse(
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("aliases")] IReadOnlyList<string> Aliases,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("purls")] IReadOnlyList<string> Purls,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("cpes")] IReadOnlyList<string> Cpes,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("references")] IReadOnlyList<VexObservationReferenceItem> References);
|
||||
|
||||
public sealed record VexObservationReferenceItem(
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("type")] string Type,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("url")] string Url);
|
||||
|
||||
public sealed record VexObservationDetailResponse(
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("observationId")] string ObservationId,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("tenant")] string Tenant,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("providerId")] string ProviderId,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("streamId")] string StreamId,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("upstream")] VexObservationUpstreamResponse Upstream,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("content")] VexObservationContentResponse Content,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("statements")] IReadOnlyList<VexObservationStatementItem> Statements,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("linkset")] VexObservationLinksetResponse Linkset,
|
||||
[property: System.Text.Json.Serialization.JsonPropertyName("createdAt")] DateTimeOffset CreatedAt);
|
||||
@@ -66,6 +66,7 @@ internal static class TelemetryExtensions
|
||||
metrics
|
||||
.AddMeter(IngestionTelemetry.MeterName)
|
||||
.AddMeter(EvidenceTelemetry.MeterName)
|
||||
.AddMeter(LinksetTelemetry.MeterName)
|
||||
.AddAspNetCoreInstrumentation()
|
||||
.AddHttpClientInstrumentation()
|
||||
.AddRuntimeInstrumentation();
|
||||
|
||||
@@ -76,6 +76,14 @@ services.AddRedHatCsafConnector();
|
||||
services.Configure<MirrorDistributionOptions>(configuration.GetSection(MirrorDistributionOptions.SectionName));
|
||||
services.AddSingleton<MirrorRateLimiter>();
|
||||
services.TryAddSingleton(TimeProvider.System);
|
||||
|
||||
// CRYPTO-90-001: Crypto provider abstraction for pluggable hashing algorithms (GOST/SM support)
|
||||
services.AddSingleton<IVexHashingService>(sp =>
|
||||
{
|
||||
// When ICryptoProviderRegistry is available, use it for pluggable algorithms
|
||||
var registry = sp.GetService<StellaOps.Cryptography.ICryptoProviderRegistry>();
|
||||
return new VexHashingService(registry);
|
||||
});
|
||||
services.AddSingleton<IVexObservationProjectionService, VexObservationProjectionService>();
|
||||
services.AddScoped<IVexObservationQueryService, VexObservationQueryService>();
|
||||
|
||||
@@ -387,6 +395,471 @@ app.MapGet("/openapi/excititor.json", () =>
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
// WEB-OBS-53-001: Evidence API endpoints
|
||||
["/evidence/vex/list"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "List VEX evidence exports",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false },
|
||||
new { name = "limit", @in = "query", schema = new { type = "integer", minimum = 1, maximum = 100 }, required = false },
|
||||
new { name = "cursor", @in = "query", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Evidence list response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["evidence-list"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
items = new[] {
|
||||
new {
|
||||
bundleId = "vex-bundle-2025-11-24-001",
|
||||
tenant = "acme",
|
||||
format = "openvex",
|
||||
createdAt = "2025-11-24T00:00:00Z",
|
||||
itemCount = 42,
|
||||
merkleRoot = "sha256:abc123...",
|
||||
sealed_ = false
|
||||
}
|
||||
},
|
||||
nextCursor = (string?)null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["/evidence/vex/bundle/{bundleId}"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "Get VEX evidence bundle details",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "bundleId", @in = "path", schema = new { type = "string" }, required = true },
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Bundle detail response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["bundle-detail"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
bundleId = "vex-bundle-2025-11-24-001",
|
||||
tenant = "acme",
|
||||
format = "openvex",
|
||||
specVersion = "0.2.0",
|
||||
createdAt = "2025-11-24T00:00:00Z",
|
||||
itemCount = 42,
|
||||
merkleRoot = "sha256:abc123...",
|
||||
sealed_ = false,
|
||||
metadata = new { source = "excititor" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["404"] = new
|
||||
{
|
||||
description = "Bundle not found",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
schema = new { @ref = "#/components/schemas/Error" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["/evidence/vex/lookup"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "Lookup evidence for vulnerability/product pair",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "vulnerabilityId", @in = "query", schema = new { type = "string" }, required = true, example = "CVE-2024-12345" },
|
||||
new { name = "productKey", @in = "query", schema = new { type = "string" }, required = true, example = "pkg:npm/lodash@4.17.21" },
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Evidence lookup response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["lookup-result"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
vulnerabilityId = "CVE-2024-12345",
|
||||
productKey = "pkg:npm/lodash@4.17.21",
|
||||
evidence = new[] {
|
||||
new { bundleId = "vex-bundle-001", observationId = "obs-001" }
|
||||
},
|
||||
queriedAt = "2025-11-24T12:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
// WEB-OBS-54-001: Attestation API endpoints
|
||||
["/attestations/vex/list"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "List VEX attestations",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "limit", @in = "query", schema = new { type = "integer", minimum = 1, maximum = 200 }, required = false },
|
||||
new { name = "cursor", @in = "query", schema = new { type = "string" }, required = false },
|
||||
new { name = "vulnerabilityId", @in = "query", schema = new { type = "string" }, required = false },
|
||||
new { name = "productKey", @in = "query", schema = new { type = "string" }, required = false },
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Attestation list response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["attestation-list"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
items = new[] {
|
||||
new {
|
||||
attestationId = "att-2025-001",
|
||||
tenant = "acme",
|
||||
createdAt = "2025-11-24T00:00:00Z",
|
||||
predicateType = "https://in-toto.io/attestation/v1",
|
||||
subjectDigest = "sha256:abc123...",
|
||||
valid = true,
|
||||
builderId = "excititor:redhat"
|
||||
}
|
||||
},
|
||||
nextCursor = (string?)null,
|
||||
hasMore = false,
|
||||
count = 1
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["/attestations/vex/{attestationId}"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "Get VEX attestation details with DSSE verification state",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "attestationId", @in = "path", schema = new { type = "string" }, required = true },
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Attestation detail response with chain-of-custody",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["attestation-detail"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
attestationId = "att-2025-001",
|
||||
tenant = "acme",
|
||||
createdAt = "2025-11-24T00:00:00Z",
|
||||
predicateType = "https://in-toto.io/attestation/v1",
|
||||
subject = new { digest = "sha256:abc123...", name = "CVE-2024-12345/pkg:npm/lodash@4.17.21" },
|
||||
builder = new { id = "excititor:redhat", builderId = "excititor:redhat" },
|
||||
verification = new { valid = true, verifiedAt = "2025-11-24T00:00:00Z", signatureType = "dsse" },
|
||||
chainOfCustody = new[] {
|
||||
new { step = 1, actor = "excititor:redhat", action = "created", timestamp = "2025-11-24T00:00:00Z" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["404"] = new
|
||||
{
|
||||
description = "Attestation not found",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
schema = new { @ref = "#/components/schemas/Error" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["/attestations/vex/lookup"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "Lookup attestations by linkset or observation",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "linksetId", @in = "query", schema = new { type = "string" }, required = false },
|
||||
new { name = "observationId", @in = "query", schema = new { type = "string" }, required = false },
|
||||
new { name = "limit", @in = "query", schema = new { type = "integer", minimum = 1, maximum = 100 }, required = false },
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Attestation lookup response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["lookup-result"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
subjectDigest = "linkset-001",
|
||||
attestations = new[] {
|
||||
new { attestationId = "att-001", valid = true }
|
||||
},
|
||||
queriedAt = "2025-11-24T12:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["400"] = new
|
||||
{
|
||||
description = "Missing required parameter",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
schema = new { @ref = "#/components/schemas/Error" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
// EXCITITOR-LNM-21-201: Observation API endpoints
|
||||
["/vex/observations"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "List VEX observations with filters",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "limit", @in = "query", schema = new { type = "integer", minimum = 1, maximum = 100 }, required = false },
|
||||
new { name = "cursor", @in = "query", schema = new { type = "string" }, required = false },
|
||||
new { name = "vulnerabilityId", @in = "query", schema = new { type = "string" }, required = false, example = "CVE-2024-12345" },
|
||||
new { name = "productKey", @in = "query", schema = new { type = "string" }, required = false, example = "pkg:npm/lodash@4.17.21" },
|
||||
new { name = "providerId", @in = "query", schema = new { type = "string" }, required = false, example = "excititor:redhat" },
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Observation list response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["observation-list"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
items = new[] {
|
||||
new {
|
||||
observationId = "obs-2025-001",
|
||||
tenant = "acme",
|
||||
providerId = "excititor:redhat",
|
||||
vulnerabilityId = "CVE-2024-12345",
|
||||
productKey = "pkg:npm/lodash@4.17.21",
|
||||
status = "not_affected",
|
||||
createdAt = "2025-11-24T00:00:00Z"
|
||||
}
|
||||
},
|
||||
nextCursor = (string?)null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["400"] = new
|
||||
{
|
||||
description = "Missing required filter",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
schema = new { @ref = "#/components/schemas/Error" },
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["missing-filter"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
error = new
|
||||
{
|
||||
code = "ERR_PARAMS",
|
||||
message = "At least one filter is required: vulnerabilityId+productKey or providerId"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["/vex/observations/{observationId}"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "Get VEX observation by ID",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "observationId", @in = "path", schema = new { type = "string" }, required = true },
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Observation detail response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["observation-detail"] = new
|
||||
{
|
||||
value = new
|
||||
{
|
||||
observationId = "obs-2025-001",
|
||||
tenant = "acme",
|
||||
providerId = "excititor:redhat",
|
||||
streamId = "stream-001",
|
||||
upstream = new { upstreamId = "RHSA-2024:001", fetchedAt = "2025-11-24T00:00:00Z" },
|
||||
content = new { format = "csaf", specVersion = "2.0" },
|
||||
statements = new[] {
|
||||
new { vulnerabilityId = "CVE-2024-12345", productKey = "pkg:npm/lodash@4.17.21", status = "not_affected" }
|
||||
},
|
||||
linkset = new { aliases = new[] { "CVE-2024-12345" }, purls = new[] { "pkg:npm/lodash@4.17.21" } },
|
||||
createdAt = "2025-11-24T00:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["404"] = new
|
||||
{
|
||||
description = "Observation not found",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
schema = new { @ref = "#/components/schemas/Error" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
["/vex/observations/count"] = new
|
||||
{
|
||||
get = new
|
||||
{
|
||||
summary = "Get observation count for tenant",
|
||||
parameters = new object[]
|
||||
{
|
||||
new { name = "X-Stella-Tenant", @in = "header", schema = new { type = "string" }, required = false }
|
||||
},
|
||||
responses = new Dictionary<string, object>
|
||||
{
|
||||
["200"] = new
|
||||
{
|
||||
description = "Count response",
|
||||
content = new Dictionary<string, object>
|
||||
{
|
||||
["application/json"] = new
|
||||
{
|
||||
examples = new Dictionary<string, object>
|
||||
{
|
||||
["count"] = new
|
||||
{
|
||||
value = new { count = 1234 }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
components = new
|
||||
@@ -451,6 +924,8 @@ app.MapPost("/airgap/v1/vex/import", async (
|
||||
[FromServices] AirgapSignerTrustService trustService,
|
||||
[FromServices] AirgapModeEnforcer modeEnforcer,
|
||||
[FromServices] IAirgapImportStore store,
|
||||
[FromServices] IVexTimelineEventEmitter timelineEmitter,
|
||||
[FromServices] IVexHashingService hashingService,
|
||||
[FromServices] ILoggerFactory loggerFactory,
|
||||
[FromServices] TimeProvider timeProvider,
|
||||
[FromBody] AirgapImportRequest request,
|
||||
@@ -465,6 +940,7 @@ app.MapPost("/airgap/v1/vex/import", async (
|
||||
? (int?)null
|
||||
: (int)Math.Round((nowUtc - request.SignedAt.Value).TotalSeconds);
|
||||
|
||||
var traceId = Activity.Current?.TraceId.ToString();
|
||||
var timeline = new List<AirgapTimelineEntry>();
|
||||
void RecordEvent(string eventType, string? code = null, string? message = null)
|
||||
{
|
||||
@@ -481,6 +957,54 @@ app.MapPost("/airgap/v1/vex/import", async (
|
||||
};
|
||||
timeline.Add(entry);
|
||||
logger.LogInformation("Airgap timeline event {EventType} bundle={BundleId} gen={Gen} tenant={Tenant} code={Code}", eventType, entry.BundleId, entry.MirrorGeneration, tenantId, code);
|
||||
|
||||
// WEB-AIRGAP-58-001: Emit timeline event to persistent store for SSE streaming
|
||||
_ = EmitTimelineEventAsync(eventType, code, message);
|
||||
}
|
||||
|
||||
async Task EmitTimelineEventAsync(string eventType, string? code, string? message)
|
||||
{
|
||||
try
|
||||
{
|
||||
var attributes = new Dictionary<string, string>(StringComparer.Ordinal)
|
||||
{
|
||||
["bundle_id"] = request.BundleId ?? string.Empty,
|
||||
["mirror_generation"] = request.MirrorGeneration ?? string.Empty
|
||||
};
|
||||
if (stalenessSeconds.HasValue)
|
||||
{
|
||||
attributes["staleness_seconds"] = stalenessSeconds.Value.ToString(CultureInfo.InvariantCulture);
|
||||
}
|
||||
if (!string.IsNullOrEmpty(code))
|
||||
{
|
||||
attributes["error_code"] = code;
|
||||
}
|
||||
if (!string.IsNullOrEmpty(message))
|
||||
{
|
||||
attributes["message"] = message;
|
||||
}
|
||||
|
||||
var eventId = $"airgap-{request.BundleId}-{request.MirrorGeneration}-{nowUtc:yyyyMMddHHmmssfff}";
|
||||
var streamId = $"airgap:{request.BundleId}:{request.MirrorGeneration}";
|
||||
var evt = new TimelineEvent(
|
||||
eventId,
|
||||
tenantId,
|
||||
"airgap-import",
|
||||
streamId,
|
||||
eventType,
|
||||
traceId ?? Guid.NewGuid().ToString("N"),
|
||||
justificationSummary: message ?? string.Empty,
|
||||
nowUtc,
|
||||
evidenceHash: null,
|
||||
payloadHash: request.PayloadHash,
|
||||
attributes.ToImmutableDictionary());
|
||||
|
||||
await timelineEmitter.EmitAsync(evt, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
logger.LogWarning(ex, "Failed to emit timeline event {EventType} for bundle {BundleId}", eventType, request.BundleId);
|
||||
}
|
||||
}
|
||||
|
||||
RecordEvent("airgap.import.started");
|
||||
@@ -528,7 +1052,8 @@ app.MapPost("/airgap/v1/vex/import", async (
|
||||
|
||||
var manifestPath = $"mirror/{request.BundleId}/{request.MirrorGeneration}/manifest.json";
|
||||
var evidenceLockerPath = $"evidence/{request.BundleId}/{request.MirrorGeneration}/bundle.ndjson";
|
||||
var manifestHash = ComputeSha256($"{request.BundleId}:{request.MirrorGeneration}:{request.PayloadHash}");
|
||||
// CRYPTO-90-001: Use IVexHashingService for pluggable crypto algorithms
|
||||
var manifestHash = hashingService.ComputeHash($"{request.BundleId}:{request.MirrorGeneration}:{request.PayloadHash}");
|
||||
|
||||
RecordEvent("airgap.import.completed");
|
||||
|
||||
@@ -578,12 +1103,7 @@ app.MapPost("/airgap/v1/vex/import", async (
|
||||
});
|
||||
});
|
||||
|
||||
static string ComputeSha256(string value)
|
||||
{
|
||||
var bytes = Encoding.UTF8.GetBytes(value);
|
||||
var hash = System.Security.Cryptography.SHA256.HashData(bytes);
|
||||
return "sha256:" + Convert.ToHexString(hash).ToLowerInvariant();
|
||||
}
|
||||
// CRYPTO-90-001: ComputeSha256 removed - now using IVexHashingService for pluggable crypto
|
||||
|
||||
app.MapPost("/v1/attestations/verify", async (
|
||||
[FromServices] IVexAttestationClient attestationClient,
|
||||
@@ -1666,10 +2186,13 @@ app.MapGet("/obs/excititor/health", async (
|
||||
app.MapGet("/obs/excititor/timeline", async (
|
||||
HttpContext context,
|
||||
IOptions<VexMongoStorageOptions> storageOptions,
|
||||
[FromServices] IVexTimelineEventStore timelineStore,
|
||||
TimeProvider timeProvider,
|
||||
ILoggerFactory loggerFactory,
|
||||
[FromQuery] string? cursor,
|
||||
[FromQuery] int? limit,
|
||||
[FromQuery] string? eventType,
|
||||
[FromQuery] string? providerId,
|
||||
CancellationToken cancellationToken) =>
|
||||
{
|
||||
if (!TryResolveTenant(context, storageOptions.Value, requireHeader: true, out var tenant, out var tenantError))
|
||||
@@ -1680,44 +2203,71 @@ app.MapGet("/obs/excititor/timeline", async (
|
||||
var logger = loggerFactory.CreateLogger("ExcititorTimeline");
|
||||
var take = Math.Clamp(limit.GetValueOrDefault(10), 1, 100);
|
||||
|
||||
var startId = 0;
|
||||
// Parse cursor as ISO-8601 timestamp or Last-Event-ID header
|
||||
DateTimeOffset? cursorTimestamp = null;
|
||||
var candidateCursor = cursor ?? context.Request.Headers["Last-Event-ID"].FirstOrDefault();
|
||||
if (!string.IsNullOrWhiteSpace(candidateCursor) && !int.TryParse(candidateCursor, NumberStyles.Integer, CultureInfo.InvariantCulture, out startId))
|
||||
if (!string.IsNullOrWhiteSpace(candidateCursor))
|
||||
{
|
||||
return Results.BadRequest(new { error = "cursor must be integer" });
|
||||
if (DateTimeOffset.TryParse(candidateCursor, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out var parsed))
|
||||
{
|
||||
cursorTimestamp = parsed;
|
||||
}
|
||||
else
|
||||
{
|
||||
return Results.BadRequest(new { error = new { code = "ERR_CURSOR", message = "cursor must be ISO-8601 timestamp" } });
|
||||
}
|
||||
}
|
||||
|
||||
context.Response.Headers.CacheControl = "no-store";
|
||||
context.Response.Headers["X-Accel-Buffering"] = "no";
|
||||
context.Response.Headers["Link"] = "</openapi/excititor.json>; rel=\"describedby\"; type=\"application/json\"";
|
||||
context.Response.ContentType = "text/event-stream";
|
||||
await context.Response.WriteAsync("retry: 5000\n\n", cancellationToken).ConfigureAwait(false);
|
||||
|
||||
// Fetch real timeline events from the store
|
||||
IReadOnlyList<TimelineEvent> events;
|
||||
var now = timeProvider.GetUtcNow();
|
||||
var events = Enumerable.Range(startId, take)
|
||||
.Select(id => new ExcititorTimelineEvent(
|
||||
Type: "evidence.update",
|
||||
Tenant: tenant,
|
||||
Source: "vex-runtime",
|
||||
Count: 0,
|
||||
Errors: 0,
|
||||
TraceId: null,
|
||||
OccurredAt: now.ToString("O", CultureInfo.InvariantCulture)))
|
||||
.ToList();
|
||||
|
||||
foreach (var (evt, idx) in events.Select((e, i) => (e, i)))
|
||||
if (!string.IsNullOrWhiteSpace(eventType))
|
||||
{
|
||||
events = await timelineStore.FindByEventTypeAsync(tenant, eventType, take, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
else if (!string.IsNullOrWhiteSpace(providerId))
|
||||
{
|
||||
events = await timelineStore.FindByProviderAsync(tenant, providerId, take, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
else if (cursorTimestamp.HasValue)
|
||||
{
|
||||
// Get events after the cursor timestamp
|
||||
events = await timelineStore.FindByTimeRangeAsync(tenant, cursorTimestamp.Value, now, take, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
else
|
||||
{
|
||||
events = await timelineStore.GetRecentAsync(tenant, take, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
foreach (var evt in events)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
var id = startId + idx;
|
||||
await context.Response.WriteAsync($"id: {id}\n", cancellationToken).ConfigureAwait(false);
|
||||
await context.Response.WriteAsync($"event: {evt.Type}\n", cancellationToken).ConfigureAwait(false);
|
||||
await context.Response.WriteAsync($"data: {JsonSerializer.Serialize(evt)}\n\n", cancellationToken).ConfigureAwait(false);
|
||||
var sseEvent = new ExcititorTimelineEvent(
|
||||
Type: evt.EventType,
|
||||
Tenant: evt.Tenant,
|
||||
Source: evt.ProviderId,
|
||||
Count: evt.Attributes.TryGetValue("observation_count", out var countStr) && int.TryParse(countStr, out var count) ? count : 1,
|
||||
Errors: evt.Attributes.TryGetValue("error_count", out var errStr) && int.TryParse(errStr, out var errCount) ? errCount : 0,
|
||||
TraceId: evt.TraceId,
|
||||
OccurredAt: evt.CreatedAt.ToString("O", CultureInfo.InvariantCulture));
|
||||
|
||||
await context.Response.WriteAsync($"id: {evt.CreatedAt:O}\n", cancellationToken).ConfigureAwait(false);
|
||||
await context.Response.WriteAsync($"event: {evt.EventType}\n", cancellationToken).ConfigureAwait(false);
|
||||
await context.Response.WriteAsync($"data: {JsonSerializer.Serialize(sseEvent)}\n\n", cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
await context.Response.Body.FlushAsync(cancellationToken).ConfigureAwait(false);
|
||||
|
||||
var nextCursor = startId + events.Count;
|
||||
context.Response.Headers["X-Next-Cursor"] = nextCursor.ToString(CultureInfo.InvariantCulture);
|
||||
logger.LogInformation("obs excititor timeline emitted {Count} events for tenant {Tenant} start {Start} next {Next}", events.Count, tenant, startId, nextCursor);
|
||||
var nextCursor = events.Count > 0 ? events[^1].CreatedAt.ToString("O", CultureInfo.InvariantCulture) : now.ToString("O", CultureInfo.InvariantCulture);
|
||||
context.Response.Headers["X-Next-Cursor"] = nextCursor;
|
||||
logger.LogInformation("obs excititor timeline emitted {Count} events for tenant {Tenant} cursor {Cursor} next {Next}", events.Count, tenant, candidateCursor, nextCursor);
|
||||
|
||||
return Results.Empty;
|
||||
}).WithName("GetExcititorTimeline");
|
||||
@@ -1726,11 +2276,13 @@ IngestEndpoints.MapIngestEndpoints(app);
|
||||
ResolveEndpoint.MapResolveEndpoint(app);
|
||||
MirrorEndpoints.MapMirrorEndpoints(app);
|
||||
|
||||
app.MapGet("/v1/vex/observations", async (HttpContext _, CancellationToken __) =>
|
||||
Results.StatusCode(StatusCodes.Status501NotImplemented));
|
||||
// Evidence and Attestation APIs (WEB-OBS-53-001, WEB-OBS-54-001)
|
||||
EvidenceEndpoints.MapEvidenceEndpoints(app);
|
||||
AttestationEndpoints.MapAttestationEndpoints(app);
|
||||
|
||||
app.MapGet("/v1/vex/linksets", async (HttpContext _, CancellationToken __) =>
|
||||
Results.StatusCode(StatusCodes.Status501NotImplemented));
|
||||
// Observation and Linkset APIs (EXCITITOR-LNM-21-201, EXCITITOR-LNM-21-202)
|
||||
ObservationEndpoints.MapObservationEndpoints(app);
|
||||
LinksetEndpoints.MapLinksetEndpoints(app);
|
||||
|
||||
app.Run();
|
||||
|
||||
|
||||
@@ -0,0 +1,112 @@
|
||||
using System;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
using StellaOps.Cryptography;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Services;
|
||||
|
||||
/// <summary>
|
||||
/// Service interface for hashing operations in Excititor (CRYPTO-90-001).
|
||||
/// Abstracts hashing implementation to support GOST/SM algorithms via ICryptoProviderRegistry.
|
||||
/// </summary>
|
||||
public interface IVexHashingService
|
||||
{
|
||||
/// <summary>
|
||||
/// Compute hash of a UTF-8 encoded string.
|
||||
/// </summary>
|
||||
string ComputeHash(string value, string algorithm = "sha256");
|
||||
|
||||
/// <summary>
|
||||
/// Compute hash of raw bytes.
|
||||
/// </summary>
|
||||
string ComputeHash(ReadOnlySpan<byte> data, string algorithm = "sha256");
|
||||
|
||||
/// <summary>
|
||||
/// Try to compute hash of raw bytes with stack-allocated buffer optimization.
|
||||
/// </summary>
|
||||
bool TryComputeHash(ReadOnlySpan<byte> data, Span<byte> destination, out int bytesWritten, string algorithm = "sha256");
|
||||
|
||||
/// <summary>
|
||||
/// Format a hash digest with algorithm prefix.
|
||||
/// </summary>
|
||||
string FormatDigest(string algorithm, ReadOnlySpan<byte> digest);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Default implementation of <see cref="IVexHashingService"/> that uses ICryptoProviderRegistry
|
||||
/// when available, falling back to System.Security.Cryptography for SHA-256.
|
||||
/// </summary>
|
||||
public sealed class VexHashingService : IVexHashingService
|
||||
{
|
||||
private readonly ICryptoProviderRegistry? _registry;
|
||||
|
||||
public VexHashingService(ICryptoProviderRegistry? registry = null)
|
||||
{
|
||||
_registry = registry;
|
||||
}
|
||||
|
||||
public string ComputeHash(string value, string algorithm = "sha256")
|
||||
{
|
||||
if (string.IsNullOrEmpty(value))
|
||||
{
|
||||
return string.Empty;
|
||||
}
|
||||
|
||||
var bytes = Encoding.UTF8.GetBytes(value);
|
||||
return ComputeHash(bytes, algorithm);
|
||||
}
|
||||
|
||||
public string ComputeHash(ReadOnlySpan<byte> data, string algorithm = "sha256")
|
||||
{
|
||||
Span<byte> buffer = stackalloc byte[64]; // Large enough for SHA-512 and GOST
|
||||
if (!TryComputeHash(data, buffer, out var written, algorithm))
|
||||
{
|
||||
throw new InvalidOperationException($"Failed to compute {algorithm} hash.");
|
||||
}
|
||||
|
||||
return FormatDigest(algorithm, buffer[..written]);
|
||||
}
|
||||
|
||||
public bool TryComputeHash(ReadOnlySpan<byte> data, Span<byte> destination, out int bytesWritten, string algorithm = "sha256")
|
||||
{
|
||||
bytesWritten = 0;
|
||||
|
||||
// Try to use crypto provider registry first for pluggable algorithms
|
||||
if (_registry is not null)
|
||||
{
|
||||
try
|
||||
{
|
||||
var resolution = _registry.ResolveHasher(algorithm);
|
||||
var hasher = resolution.Hasher;
|
||||
var result = hasher.ComputeHash(data);
|
||||
if (result.Length <= destination.Length)
|
||||
{
|
||||
result.CopyTo(destination);
|
||||
bytesWritten = result.Length;
|
||||
return true;
|
||||
}
|
||||
}
|
||||
catch
|
||||
{
|
||||
// Fall through to built-in implementation
|
||||
}
|
||||
}
|
||||
|
||||
// Fall back to System.Security.Cryptography for standard algorithms
|
||||
var normalizedAlgorithm = algorithm.ToLowerInvariant().Replace("-", string.Empty);
|
||||
return normalizedAlgorithm switch
|
||||
{
|
||||
"sha256" => SHA256.TryHashData(data, destination, out bytesWritten),
|
||||
"sha384" => SHA384.TryHashData(data, destination, out bytesWritten),
|
||||
"sha512" => SHA512.TryHashData(data, destination, out bytesWritten),
|
||||
_ => throw new NotSupportedException($"Unsupported hash algorithm: {algorithm}")
|
||||
};
|
||||
}
|
||||
|
||||
public string FormatDigest(string algorithm, ReadOnlySpan<byte> digest)
|
||||
{
|
||||
var normalizedAlgorithm = algorithm.ToLowerInvariant().Replace("-", string.Empty);
|
||||
var hexDigest = Convert.ToHexString(digest).ToLowerInvariant();
|
||||
return $"{normalizedAlgorithm}:{hexDigest}";
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,250 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Diagnostics.Metrics;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Telemetry;
|
||||
|
||||
/// <summary>
|
||||
/// Telemetry metrics for VEX linkset and observation store operations (EXCITITOR-OBS-51-001).
|
||||
/// Tracks ingest latency, scope resolution success, conflict rate, and signature verification
|
||||
/// to support SLO burn alerts for AOC "evidence freshness" mission.
|
||||
/// </summary>
|
||||
internal static class LinksetTelemetry
|
||||
{
|
||||
public const string MeterName = "StellaOps.Excititor.WebService.Linksets";
|
||||
|
||||
private static readonly Meter Meter = new(MeterName);
|
||||
|
||||
// Ingest latency metrics
|
||||
private static readonly Histogram<double> IngestLatencyHistogram =
|
||||
Meter.CreateHistogram<double>(
|
||||
"excititor.vex.ingest.latency_seconds",
|
||||
unit: "s",
|
||||
description: "Latency distribution for VEX observation and linkset store operations.");
|
||||
|
||||
private static readonly Counter<long> IngestOperationCounter =
|
||||
Meter.CreateCounter<long>(
|
||||
"excititor.vex.ingest.operations_total",
|
||||
unit: "operations",
|
||||
description: "Total count of VEX ingest operations by outcome.");
|
||||
|
||||
// Scope resolution metrics
|
||||
private static readonly Counter<long> ScopeResolutionCounter =
|
||||
Meter.CreateCounter<long>(
|
||||
"excititor.vex.scope.resolution_total",
|
||||
unit: "resolutions",
|
||||
description: "Count of scope resolution attempts by outcome (success/failure).");
|
||||
|
||||
private static readonly Histogram<int> ScopeMatchCountHistogram =
|
||||
Meter.CreateHistogram<int>(
|
||||
"excititor.vex.scope.match_count",
|
||||
unit: "matches",
|
||||
description: "Distribution of matched scopes per resolution request.");
|
||||
|
||||
// Conflict/disagreement metrics
|
||||
private static readonly Counter<long> LinksetConflictCounter =
|
||||
Meter.CreateCounter<long>(
|
||||
"excititor.vex.linkset.conflicts_total",
|
||||
unit: "conflicts",
|
||||
description: "Total count of linksets with provider disagreements detected.");
|
||||
|
||||
private static readonly Histogram<int> DisagreementCountHistogram =
|
||||
Meter.CreateHistogram<int>(
|
||||
"excititor.vex.linkset.disagreement_count",
|
||||
unit: "disagreements",
|
||||
description: "Distribution of disagreement count per linkset.");
|
||||
|
||||
private static readonly Counter<long> DisagreementByStatusCounter =
|
||||
Meter.CreateCounter<long>(
|
||||
"excititor.vex.linkset.disagreement_by_status",
|
||||
unit: "disagreements",
|
||||
description: "Disagreement counts broken down by conflicting status values.");
|
||||
|
||||
// Observation store metrics
|
||||
private static readonly Counter<long> ObservationStoreCounter =
|
||||
Meter.CreateCounter<long>(
|
||||
"excititor.vex.observation.store_operations_total",
|
||||
unit: "operations",
|
||||
description: "Total observation store operations by type and outcome.");
|
||||
|
||||
private static readonly Histogram<int> ObservationBatchSizeHistogram =
|
||||
Meter.CreateHistogram<int>(
|
||||
"excititor.vex.observation.batch_size",
|
||||
unit: "observations",
|
||||
description: "Distribution of observation batch sizes for store operations.");
|
||||
|
||||
// Linkset store metrics
|
||||
private static readonly Counter<long> LinksetStoreCounter =
|
||||
Meter.CreateCounter<long>(
|
||||
"excititor.vex.linkset.store_operations_total",
|
||||
unit: "operations",
|
||||
description: "Total linkset store operations by type and outcome.");
|
||||
|
||||
// Confidence metrics
|
||||
private static readonly Histogram<double> LinksetConfidenceHistogram =
|
||||
Meter.CreateHistogram<double>(
|
||||
"excititor.vex.linkset.confidence_score",
|
||||
unit: "score",
|
||||
description: "Distribution of linkset confidence scores (0.0-1.0).");
|
||||
|
||||
/// <summary>
|
||||
/// Records latency for a VEX ingest operation.
|
||||
/// </summary>
|
||||
public static void RecordIngestLatency(string? tenant, string operation, string outcome, double latencySeconds)
|
||||
{
|
||||
var tags = BuildBaseTags(tenant, operation, outcome);
|
||||
IngestLatencyHistogram.Record(latencySeconds, tags);
|
||||
IngestOperationCounter.Add(1, tags);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Records a scope resolution attempt and its outcome.
|
||||
/// </summary>
|
||||
public static void RecordScopeResolution(string? tenant, string outcome, int matchCount = 0)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var tags = new[]
|
||||
{
|
||||
new KeyValuePair<string, object?>("tenant", normalizedTenant),
|
||||
new KeyValuePair<string, object?>("outcome", outcome),
|
||||
};
|
||||
|
||||
ScopeResolutionCounter.Add(1, tags);
|
||||
|
||||
if (string.Equals(outcome, "success", StringComparison.OrdinalIgnoreCase) && matchCount > 0)
|
||||
{
|
||||
ScopeMatchCountHistogram.Record(matchCount, tags);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Records conflict detection for a linkset.
|
||||
/// </summary>
|
||||
public static void RecordLinksetConflict(string? tenant, bool hasConflicts, int disagreementCount = 0)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
|
||||
if (hasConflicts)
|
||||
{
|
||||
var conflictTags = new[]
|
||||
{
|
||||
new KeyValuePair<string, object?>("tenant", normalizedTenant),
|
||||
};
|
||||
LinksetConflictCounter.Add(1, conflictTags);
|
||||
|
||||
if (disagreementCount > 0)
|
||||
{
|
||||
DisagreementCountHistogram.Record(disagreementCount, conflictTags);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Records a linkset with detailed disagreement breakdown.
|
||||
/// </summary>
|
||||
public static void RecordLinksetDisagreements(string? tenant, VexLinkset linkset)
|
||||
{
|
||||
if (linkset is null || !linkset.HasConflicts)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
RecordLinksetConflict(normalizedTenant, true, linkset.Disagreements.Length);
|
||||
|
||||
// Record disagreements by status
|
||||
foreach (var disagreement in linkset.Disagreements)
|
||||
{
|
||||
var statusTags = new[]
|
||||
{
|
||||
new KeyValuePair<string, object?>("tenant", normalizedTenant),
|
||||
new KeyValuePair<string, object?>("status", disagreement.Status.ToLowerInvariant()),
|
||||
new KeyValuePair<string, object?>("provider", disagreement.ProviderId),
|
||||
};
|
||||
DisagreementByStatusCounter.Add(1, statusTags);
|
||||
}
|
||||
|
||||
// Record confidence score
|
||||
var confidenceScore = linkset.Confidence switch
|
||||
{
|
||||
VexLinksetConfidence.High => 0.9,
|
||||
VexLinksetConfidence.Medium => 0.7,
|
||||
VexLinksetConfidence.Low => 0.4,
|
||||
_ => 0.5
|
||||
};
|
||||
|
||||
var confidenceTags = new[]
|
||||
{
|
||||
new KeyValuePair<string, object?>("tenant", normalizedTenant),
|
||||
new KeyValuePair<string, object?>("has_conflicts", linkset.HasConflicts),
|
||||
};
|
||||
LinksetConfidenceHistogram.Record(confidenceScore, confidenceTags);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Records an observation store operation.
|
||||
/// </summary>
|
||||
public static void RecordObservationStoreOperation(
|
||||
string? tenant,
|
||||
string operation,
|
||||
string outcome,
|
||||
int batchSize = 1)
|
||||
{
|
||||
var tags = BuildBaseTags(tenant, operation, outcome);
|
||||
ObservationStoreCounter.Add(1, tags);
|
||||
|
||||
if (batchSize > 0 && string.Equals(outcome, "success", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
var batchTags = new[]
|
||||
{
|
||||
new KeyValuePair<string, object?>("tenant", NormalizeTenant(tenant)),
|
||||
new KeyValuePair<string, object?>("operation", operation),
|
||||
};
|
||||
ObservationBatchSizeHistogram.Record(batchSize, batchTags);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Records a linkset store operation.
|
||||
/// </summary>
|
||||
public static void RecordLinksetStoreOperation(string? tenant, string operation, string outcome)
|
||||
{
|
||||
var tags = BuildBaseTags(tenant, operation, outcome);
|
||||
LinksetStoreCounter.Add(1, tags);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Records linkset confidence score distribution.
|
||||
/// </summary>
|
||||
public static void RecordLinksetConfidence(string? tenant, VexLinksetConfidence confidence, bool hasConflicts)
|
||||
{
|
||||
var score = confidence switch
|
||||
{
|
||||
VexLinksetConfidence.High => 0.9,
|
||||
VexLinksetConfidence.Medium => 0.7,
|
||||
VexLinksetConfidence.Low => 0.4,
|
||||
_ => 0.5
|
||||
};
|
||||
|
||||
var tags = new[]
|
||||
{
|
||||
new KeyValuePair<string, object?>("tenant", NormalizeTenant(tenant)),
|
||||
new KeyValuePair<string, object?>("has_conflicts", hasConflicts),
|
||||
new KeyValuePair<string, object?>("confidence_level", confidence.ToString().ToLowerInvariant()),
|
||||
};
|
||||
|
||||
LinksetConfidenceHistogram.Record(score, tags);
|
||||
}
|
||||
|
||||
private static string NormalizeTenant(string? tenant)
|
||||
=> string.IsNullOrWhiteSpace(tenant) ? "default" : tenant;
|
||||
|
||||
private static KeyValuePair<string, object?>[] BuildBaseTags(string? tenant, string operation, string outcome)
|
||||
=> new[]
|
||||
{
|
||||
new KeyValuePair<string, object?>("tenant", NormalizeTenant(tenant)),
|
||||
new KeyValuePair<string, object?>("operation", operation),
|
||||
new KeyValuePair<string, object?>("outcome", outcome),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
using System;
|
||||
|
||||
namespace StellaOps.Excititor.Worker.Options;
|
||||
|
||||
/// <summary>
|
||||
/// Configuration options for the orchestrator worker SDK integration.
|
||||
/// </summary>
|
||||
public sealed class VexWorkerOrchestratorOptions
|
||||
{
|
||||
/// <summary>
|
||||
/// Whether orchestrator integration is enabled.
|
||||
/// </summary>
|
||||
public bool Enabled { get; set; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// Interval between heartbeat emissions during job execution.
|
||||
/// </summary>
|
||||
public TimeSpan HeartbeatInterval { get; set; } = TimeSpan.FromSeconds(30);
|
||||
|
||||
/// <summary>
|
||||
/// Minimum heartbeat interval (safety floor).
|
||||
/// </summary>
|
||||
public TimeSpan MinHeartbeatInterval { get; set; } = TimeSpan.FromSeconds(5);
|
||||
|
||||
/// <summary>
|
||||
/// Maximum heartbeat interval (safety cap).
|
||||
/// </summary>
|
||||
public TimeSpan MaxHeartbeatInterval { get; set; } = TimeSpan.FromMinutes(2);
|
||||
|
||||
/// <summary>
|
||||
/// Enable verbose logging for heartbeat/artifact events.
|
||||
/// </summary>
|
||||
public bool EnableVerboseLogging { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Maximum number of artifact hashes to retain in state.
|
||||
/// </summary>
|
||||
public int MaxArtifactHashes { get; set; } = 1000;
|
||||
|
||||
/// <summary>
|
||||
/// Default tenant for worker jobs when not specified.
|
||||
/// </summary>
|
||||
public string DefaultTenant { get; set; } = "default";
|
||||
}
|
||||
@@ -0,0 +1,152 @@
|
||||
using System;
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Microsoft.Extensions.Options;
|
||||
using StellaOps.Excititor.Core.Orchestration;
|
||||
using StellaOps.Excititor.Worker.Options;
|
||||
|
||||
namespace StellaOps.Excititor.Worker.Orchestration;
|
||||
|
||||
/// <summary>
|
||||
/// Background service that emits periodic heartbeats during job execution.
|
||||
/// </summary>
|
||||
internal sealed class VexWorkerHeartbeatService
|
||||
{
|
||||
private readonly IVexWorkerOrchestratorClient _orchestratorClient;
|
||||
private readonly IOptions<VexWorkerOrchestratorOptions> _options;
|
||||
private readonly TimeProvider _timeProvider;
|
||||
private readonly ILogger<VexWorkerHeartbeatService> _logger;
|
||||
|
||||
public VexWorkerHeartbeatService(
|
||||
IVexWorkerOrchestratorClient orchestratorClient,
|
||||
IOptions<VexWorkerOrchestratorOptions> options,
|
||||
TimeProvider timeProvider,
|
||||
ILogger<VexWorkerHeartbeatService> logger)
|
||||
{
|
||||
_orchestratorClient = orchestratorClient ?? throw new ArgumentNullException(nameof(orchestratorClient));
|
||||
_options = options ?? throw new ArgumentNullException(nameof(options));
|
||||
_timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
|
||||
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Runs the heartbeat loop for the given job context.
|
||||
/// Call this in a background task while the job is running.
|
||||
/// </summary>
|
||||
public async Task RunAsync(
|
||||
VexWorkerJobContext context,
|
||||
Func<VexWorkerHeartbeatStatus> statusProvider,
|
||||
Func<int?> progressProvider,
|
||||
Func<string?> lastArtifactHashProvider,
|
||||
Func<string?> lastArtifactKindProvider,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
ArgumentNullException.ThrowIfNull(statusProvider);
|
||||
|
||||
if (!_options.Value.Enabled)
|
||||
{
|
||||
_logger.LogDebug("Orchestrator heartbeat service disabled; skipping heartbeat loop.");
|
||||
return;
|
||||
}
|
||||
|
||||
var interval = ComputeInterval();
|
||||
_logger.LogDebug(
|
||||
"Starting heartbeat loop for job {RunId} with interval {Interval}",
|
||||
context.RunId,
|
||||
interval);
|
||||
|
||||
await Task.Yield();
|
||||
|
||||
try
|
||||
{
|
||||
using var timer = new PeriodicTimer(interval);
|
||||
|
||||
// Send initial heartbeat
|
||||
await SendHeartbeatAsync(
|
||||
context,
|
||||
statusProvider(),
|
||||
progressProvider?.Invoke(),
|
||||
lastArtifactHashProvider?.Invoke(),
|
||||
lastArtifactKindProvider?.Invoke(),
|
||||
cancellationToken).ConfigureAwait(false);
|
||||
|
||||
while (await timer.WaitForNextTickAsync(cancellationToken).ConfigureAwait(false))
|
||||
{
|
||||
if (cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
break;
|
||||
}
|
||||
|
||||
await SendHeartbeatAsync(
|
||||
context,
|
||||
statusProvider(),
|
||||
progressProvider?.Invoke(),
|
||||
lastArtifactHashProvider?.Invoke(),
|
||||
lastArtifactKindProvider?.Invoke(),
|
||||
cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
_logger.LogDebug("Heartbeat loop cancelled for job {RunId}", context.RunId);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogWarning(
|
||||
ex,
|
||||
"Heartbeat loop error for job {RunId}: {Message}",
|
||||
context.RunId,
|
||||
ex.Message);
|
||||
}
|
||||
}
|
||||
|
||||
private async Task SendHeartbeatAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerHeartbeatStatus status,
|
||||
int? progress,
|
||||
string? lastArtifactHash,
|
||||
string? lastArtifactKind,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
try
|
||||
{
|
||||
var heartbeat = new VexWorkerHeartbeat(
|
||||
status,
|
||||
progress,
|
||||
QueueDepth: null,
|
||||
lastArtifactHash,
|
||||
lastArtifactKind,
|
||||
ErrorCode: null,
|
||||
RetryAfterSeconds: null);
|
||||
|
||||
await _orchestratorClient.SendHeartbeatAsync(context, heartbeat, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogWarning(
|
||||
ex,
|
||||
"Failed to send heartbeat for job {RunId}: {Message}",
|
||||
context.RunId,
|
||||
ex.Message);
|
||||
}
|
||||
}
|
||||
|
||||
private TimeSpan ComputeInterval()
|
||||
{
|
||||
var opts = _options.Value;
|
||||
var interval = opts.HeartbeatInterval;
|
||||
|
||||
if (interval < opts.MinHeartbeatInterval)
|
||||
{
|
||||
interval = opts.MinHeartbeatInterval;
|
||||
}
|
||||
else if (interval > opts.MaxHeartbeatInterval)
|
||||
{
|
||||
interval = opts.MaxHeartbeatInterval;
|
||||
}
|
||||
|
||||
return interval;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,328 @@
|
||||
using System;
|
||||
using System.Collections.Immutable;
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Microsoft.Extensions.Options;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Orchestration;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.Worker.Options;
|
||||
|
||||
namespace StellaOps.Excititor.Worker.Orchestration;
|
||||
|
||||
/// <summary>
|
||||
/// Default implementation of <see cref="IVexWorkerOrchestratorClient"/>.
|
||||
/// Stores heartbeats and artifacts locally and emits them to the orchestrator registry when configured.
|
||||
/// </summary>
|
||||
internal sealed class VexWorkerOrchestratorClient : IVexWorkerOrchestratorClient
|
||||
{
|
||||
private readonly IVexConnectorStateRepository _stateRepository;
|
||||
private readonly TimeProvider _timeProvider;
|
||||
private readonly IOptions<VexWorkerOrchestratorOptions> _options;
|
||||
private readonly ILogger<VexWorkerOrchestratorClient> _logger;
|
||||
|
||||
public VexWorkerOrchestratorClient(
|
||||
IVexConnectorStateRepository stateRepository,
|
||||
TimeProvider timeProvider,
|
||||
IOptions<VexWorkerOrchestratorOptions> options,
|
||||
ILogger<VexWorkerOrchestratorClient> logger)
|
||||
{
|
||||
_stateRepository = stateRepository ?? throw new ArgumentNullException(nameof(stateRepository));
|
||||
_timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
|
||||
_options = options ?? throw new ArgumentNullException(nameof(options));
|
||||
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
|
||||
}
|
||||
|
||||
public ValueTask<VexWorkerJobContext> StartJobAsync(
|
||||
string tenant,
|
||||
string connectorId,
|
||||
string? checkpoint,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
var runId = Guid.NewGuid();
|
||||
var startedAt = _timeProvider.GetUtcNow();
|
||||
var context = new VexWorkerJobContext(tenant, connectorId, runId, checkpoint, startedAt);
|
||||
|
||||
_logger.LogInformation(
|
||||
"Orchestrator job started: tenant={Tenant} connector={ConnectorId} runId={RunId} checkpoint={Checkpoint}",
|
||||
tenant,
|
||||
connectorId,
|
||||
runId,
|
||||
checkpoint ?? "(none)");
|
||||
|
||||
return ValueTask.FromResult(context);
|
||||
}
|
||||
|
||||
public async ValueTask SendHeartbeatAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerHeartbeat heartbeat,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
ArgumentNullException.ThrowIfNull(heartbeat);
|
||||
|
||||
var sequence = context.NextSequence();
|
||||
var timestamp = _timeProvider.GetUtcNow();
|
||||
|
||||
// Update state with heartbeat info
|
||||
var state = await _stateRepository.GetAsync(context.ConnectorId, cancellationToken).ConfigureAwait(false)
|
||||
?? new VexConnectorState(context.ConnectorId, null, ImmutableArray<string>.Empty);
|
||||
|
||||
var updated = state with
|
||||
{
|
||||
LastHeartbeatAt = timestamp,
|
||||
LastHeartbeatStatus = heartbeat.Status.ToString()
|
||||
};
|
||||
|
||||
await _stateRepository.SaveAsync(updated, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
if (_options.Value.EnableVerboseLogging)
|
||||
{
|
||||
_logger.LogDebug(
|
||||
"Orchestrator heartbeat: runId={RunId} seq={Sequence} status={Status} progress={Progress} artifact={ArtifactHash}",
|
||||
context.RunId,
|
||||
sequence,
|
||||
heartbeat.Status,
|
||||
heartbeat.Progress,
|
||||
heartbeat.LastArtifactHash);
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask RecordArtifactAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerArtifact artifact,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
ArgumentNullException.ThrowIfNull(artifact);
|
||||
|
||||
// Track artifact hash in connector state for determinism verification
|
||||
var state = await _stateRepository.GetAsync(context.ConnectorId, cancellationToken).ConfigureAwait(false)
|
||||
?? new VexConnectorState(context.ConnectorId, null, ImmutableArray<string>.Empty);
|
||||
|
||||
var digests = state.DocumentDigests.IsDefault
|
||||
? ImmutableArray<string>.Empty
|
||||
: state.DocumentDigests;
|
||||
|
||||
// Add artifact hash if not already tracked (cap to avoid unbounded growth)
|
||||
const int maxDigests = 1000;
|
||||
if (!digests.Contains(artifact.Hash))
|
||||
{
|
||||
digests = digests.Length >= maxDigests
|
||||
? digests.RemoveAt(0).Add(artifact.Hash)
|
||||
: digests.Add(artifact.Hash);
|
||||
}
|
||||
|
||||
var updated = state with
|
||||
{
|
||||
DocumentDigests = digests,
|
||||
LastArtifactHash = artifact.Hash,
|
||||
LastArtifactKind = artifact.Kind
|
||||
};
|
||||
|
||||
await _stateRepository.SaveAsync(updated, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
_logger.LogDebug(
|
||||
"Orchestrator artifact recorded: runId={RunId} hash={Hash} kind={Kind} provider={Provider}",
|
||||
context.RunId,
|
||||
artifact.Hash,
|
||||
artifact.Kind,
|
||||
artifact.ProviderId);
|
||||
}
|
||||
|
||||
public async ValueTask CompleteJobAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerJobResult result,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
ArgumentNullException.ThrowIfNull(result);
|
||||
|
||||
var state = await _stateRepository.GetAsync(context.ConnectorId, cancellationToken).ConfigureAwait(false)
|
||||
?? new VexConnectorState(context.ConnectorId, null, ImmutableArray<string>.Empty);
|
||||
|
||||
var updated = state with
|
||||
{
|
||||
LastUpdated = result.CompletedAt,
|
||||
LastSuccessAt = result.CompletedAt,
|
||||
LastHeartbeatAt = result.CompletedAt,
|
||||
LastHeartbeatStatus = VexWorkerHeartbeatStatus.Succeeded.ToString(),
|
||||
LastArtifactHash = result.LastArtifactHash,
|
||||
LastCheckpoint = result.LastCheckpoint,
|
||||
FailureCount = 0,
|
||||
NextEligibleRun = null,
|
||||
LastFailureReason = null
|
||||
};
|
||||
|
||||
await _stateRepository.SaveAsync(updated, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
var duration = result.CompletedAt - context.StartedAt;
|
||||
_logger.LogInformation(
|
||||
"Orchestrator job completed: runId={RunId} connector={ConnectorId} documents={Documents} claims={Claims} duration={Duration}",
|
||||
context.RunId,
|
||||
context.ConnectorId,
|
||||
result.DocumentsProcessed,
|
||||
result.ClaimsGenerated,
|
||||
duration);
|
||||
}
|
||||
|
||||
public async ValueTask FailJobAsync(
|
||||
VexWorkerJobContext context,
|
||||
string errorCode,
|
||||
string? errorMessage,
|
||||
int? retryAfterSeconds,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
|
||||
var now = _timeProvider.GetUtcNow();
|
||||
var state = await _stateRepository.GetAsync(context.ConnectorId, cancellationToken).ConfigureAwait(false)
|
||||
?? new VexConnectorState(context.ConnectorId, null, ImmutableArray<string>.Empty);
|
||||
|
||||
var failureCount = state.FailureCount + 1;
|
||||
var nextEligible = retryAfterSeconds.HasValue
|
||||
? now.AddSeconds(retryAfterSeconds.Value)
|
||||
: (DateTimeOffset?)null;
|
||||
|
||||
var updated = state with
|
||||
{
|
||||
LastHeartbeatAt = now,
|
||||
LastHeartbeatStatus = VexWorkerHeartbeatStatus.Failed.ToString(),
|
||||
FailureCount = failureCount,
|
||||
NextEligibleRun = nextEligible,
|
||||
LastFailureReason = Truncate($"{errorCode}: {errorMessage}", 512)
|
||||
};
|
||||
|
||||
await _stateRepository.SaveAsync(updated, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
_logger.LogWarning(
|
||||
"Orchestrator job failed: runId={RunId} connector={ConnectorId} error={ErrorCode} retryAfter={RetryAfter}s",
|
||||
context.RunId,
|
||||
context.ConnectorId,
|
||||
errorCode,
|
||||
retryAfterSeconds);
|
||||
}
|
||||
|
||||
public ValueTask FailJobAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerError error,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(error);
|
||||
|
||||
_logger.LogDebug(
|
||||
"Orchestrator job failed with classified error: runId={RunId} code={Code} category={Category} retryable={Retryable}",
|
||||
context.RunId,
|
||||
error.Code,
|
||||
error.Category,
|
||||
error.Retryable);
|
||||
|
||||
return FailJobAsync(
|
||||
context,
|
||||
error.Code,
|
||||
error.Message,
|
||||
error.Retryable ? error.RetryAfterSeconds : null,
|
||||
cancellationToken);
|
||||
}
|
||||
|
||||
public ValueTask<VexWorkerCommand?> GetPendingCommandAsync(
|
||||
VexWorkerJobContext context,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
|
||||
// In this local implementation, commands are not externally sourced.
|
||||
// Return Continue to indicate normal processing should continue.
|
||||
// A full orchestrator integration would poll a command queue here.
|
||||
if (!_options.Value.Enabled)
|
||||
{
|
||||
return ValueTask.FromResult<VexWorkerCommand?>(null);
|
||||
}
|
||||
|
||||
// No pending commands in local mode
|
||||
return ValueTask.FromResult<VexWorkerCommand?>(null);
|
||||
}
|
||||
|
||||
public ValueTask AcknowledgeCommandAsync(
|
||||
VexWorkerJobContext context,
|
||||
long commandSequence,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
|
||||
_logger.LogDebug(
|
||||
"Orchestrator command acknowledged: runId={RunId} sequence={Sequence}",
|
||||
context.RunId,
|
||||
commandSequence);
|
||||
|
||||
// In local mode, acknowledgment is a no-op
|
||||
return ValueTask.CompletedTask;
|
||||
}
|
||||
|
||||
public async ValueTask SaveCheckpointAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerCheckpoint checkpoint,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
ArgumentNullException.ThrowIfNull(checkpoint);
|
||||
|
||||
var now = _timeProvider.GetUtcNow();
|
||||
var state = await _stateRepository.GetAsync(context.ConnectorId, cancellationToken).ConfigureAwait(false)
|
||||
?? new VexConnectorState(context.ConnectorId, null, ImmutableArray<string>.Empty);
|
||||
|
||||
var updated = state with
|
||||
{
|
||||
LastCheckpoint = checkpoint.Cursor,
|
||||
LastUpdated = checkpoint.LastProcessedAt ?? now,
|
||||
DocumentDigests = checkpoint.ProcessedDigests.IsDefault
|
||||
? ImmutableArray<string>.Empty
|
||||
: checkpoint.ProcessedDigests,
|
||||
ResumeTokens = checkpoint.ResumeTokens.IsEmpty
|
||||
? ImmutableDictionary<string, string>.Empty
|
||||
: checkpoint.ResumeTokens
|
||||
};
|
||||
|
||||
await _stateRepository.SaveAsync(updated, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
_logger.LogDebug(
|
||||
"Orchestrator checkpoint saved: runId={RunId} connector={ConnectorId} cursor={Cursor} digests={DigestCount}",
|
||||
context.RunId,
|
||||
context.ConnectorId,
|
||||
checkpoint.Cursor ?? "(none)",
|
||||
checkpoint.ProcessedDigests.Length);
|
||||
}
|
||||
|
||||
public async ValueTask<VexWorkerCheckpoint?> LoadCheckpointAsync(
|
||||
string connectorId,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(connectorId);
|
||||
|
||||
var state = await _stateRepository.GetAsync(connectorId, cancellationToken).ConfigureAwait(false);
|
||||
if (state is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
return new VexWorkerCheckpoint(
|
||||
connectorId,
|
||||
state.LastCheckpoint,
|
||||
state.LastUpdated,
|
||||
state.DocumentDigests.IsDefault ? ImmutableArray<string>.Empty : state.DocumentDigests,
|
||||
state.ResumeTokens.IsEmpty ? ImmutableDictionary<string, string>.Empty : state.ResumeTokens);
|
||||
}
|
||||
|
||||
private static string Truncate(string? value, int maxLength)
|
||||
{
|
||||
if (string.IsNullOrEmpty(value))
|
||||
{
|
||||
return string.Empty;
|
||||
}
|
||||
|
||||
return value.Length <= maxLength
|
||||
? value
|
||||
: value[..maxLength];
|
||||
}
|
||||
}
|
||||
@@ -8,12 +8,14 @@ using StellaOps.Plugin;
|
||||
using StellaOps.Excititor.Connectors.RedHat.CSAF.DependencyInjection;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Aoc;
|
||||
using StellaOps.Excititor.Core.Orchestration;
|
||||
using StellaOps.Excititor.Formats.CSAF;
|
||||
using StellaOps.Excititor.Formats.CycloneDX;
|
||||
using StellaOps.Excititor.Formats.OpenVEX;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.Worker.Auth;
|
||||
using StellaOps.Excititor.Worker.Options;
|
||||
using StellaOps.Excititor.Worker.Orchestration;
|
||||
using StellaOps.Excititor.Worker.Scheduling;
|
||||
using StellaOps.Excititor.Worker.Signature;
|
||||
using StellaOps.Excititor.Attestation.Extensions;
|
||||
@@ -103,6 +105,13 @@ services.AddSingleton<PluginCatalog>(provider =>
|
||||
return catalog;
|
||||
});
|
||||
|
||||
// Orchestrator worker SDK integration
|
||||
services.AddOptions<VexWorkerOrchestratorOptions>()
|
||||
.Bind(configuration.GetSection("Excititor:Worker:Orchestrator"))
|
||||
.ValidateOnStart();
|
||||
services.AddSingleton<IVexWorkerOrchestratorClient, VexWorkerOrchestratorClient>();
|
||||
services.AddSingleton<VexWorkerHeartbeatService>();
|
||||
|
||||
services.AddSingleton<IVexProviderRunner, DefaultVexProviderRunner>();
|
||||
services.AddHostedService<VexWorkerHostedService>();
|
||||
if (!workerConfigSnapshot.DisableConsensus)
|
||||
|
||||
@@ -9,8 +9,10 @@ using MongoDB.Driver;
|
||||
using StellaOps.Plugin;
|
||||
using StellaOps.Excititor.Connectors.Abstractions;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Orchestration;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.Worker.Options;
|
||||
using StellaOps.Excititor.Worker.Orchestration;
|
||||
using StellaOps.Excititor.Worker.Signature;
|
||||
|
||||
namespace StellaOps.Excititor.Worker.Scheduling;
|
||||
@@ -19,19 +21,27 @@ internal sealed class DefaultVexProviderRunner : IVexProviderRunner
|
||||
{
|
||||
private readonly IServiceProvider _serviceProvider;
|
||||
private readonly PluginCatalog _pluginCatalog;
|
||||
private readonly IVexWorkerOrchestratorClient _orchestratorClient;
|
||||
private readonly VexWorkerHeartbeatService _heartbeatService;
|
||||
private readonly ILogger<DefaultVexProviderRunner> _logger;
|
||||
private readonly TimeProvider _timeProvider;
|
||||
private readonly VexWorkerRetryOptions _retryOptions;
|
||||
private readonly VexWorkerOrchestratorOptions _orchestratorOptions;
|
||||
|
||||
public DefaultVexProviderRunner(
|
||||
IServiceProvider serviceProvider,
|
||||
PluginCatalog pluginCatalog,
|
||||
IVexWorkerOrchestratorClient orchestratorClient,
|
||||
VexWorkerHeartbeatService heartbeatService,
|
||||
ILogger<DefaultVexProviderRunner> logger,
|
||||
TimeProvider timeProvider,
|
||||
IOptions<VexWorkerOptions> workerOptions)
|
||||
IOptions<VexWorkerOptions> workerOptions,
|
||||
IOptions<VexWorkerOrchestratorOptions> orchestratorOptions)
|
||||
{
|
||||
_serviceProvider = serviceProvider ?? throw new ArgumentNullException(nameof(serviceProvider));
|
||||
_pluginCatalog = pluginCatalog ?? throw new ArgumentNullException(nameof(pluginCatalog));
|
||||
_orchestratorClient = orchestratorClient ?? throw new ArgumentNullException(nameof(orchestratorClient));
|
||||
_heartbeatService = heartbeatService ?? throw new ArgumentNullException(nameof(heartbeatService));
|
||||
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
|
||||
_timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
|
||||
if (workerOptions is null)
|
||||
@@ -40,6 +50,7 @@ internal sealed class DefaultVexProviderRunner : IVexProviderRunner
|
||||
}
|
||||
|
||||
_retryOptions = workerOptions.Value?.Retry ?? throw new InvalidOperationException("VexWorkerOptions.Retry must be configured.");
|
||||
_orchestratorOptions = orchestratorOptions?.Value ?? new VexWorkerOrchestratorOptions();
|
||||
}
|
||||
|
||||
public async ValueTask RunAsync(VexWorkerSchedule schedule, CancellationToken cancellationToken)
|
||||
@@ -118,7 +129,7 @@ internal sealed class DefaultVexProviderRunner : IVexProviderRunner
|
||||
|
||||
var verifyingSink = new VerifyingVexRawDocumentSink(rawStore, signatureVerifier);
|
||||
|
||||
var context = new VexConnectorContext(
|
||||
var connectorContext = new VexConnectorContext(
|
||||
Since: stateBeforeRun?.LastUpdated,
|
||||
Settings: effectiveSettings,
|
||||
RawSink: verifyingSink,
|
||||
@@ -127,33 +138,128 @@ internal sealed class DefaultVexProviderRunner : IVexProviderRunner
|
||||
Services: scopeProvider,
|
||||
ResumeTokens: stateBeforeRun?.ResumeTokens ?? ImmutableDictionary<string, string>.Empty);
|
||||
|
||||
// Start orchestrator job for heartbeat/progress tracking
|
||||
var jobContext = await _orchestratorClient.StartJobAsync(
|
||||
_orchestratorOptions.DefaultTenant,
|
||||
connector.Id,
|
||||
stateBeforeRun?.LastCheckpoint,
|
||||
cancellationToken).ConfigureAwait(false);
|
||||
|
||||
var documentCount = 0;
|
||||
string? lastArtifactHash = null;
|
||||
string? lastArtifactKind = null;
|
||||
var currentStatus = VexWorkerHeartbeatStatus.Running;
|
||||
|
||||
// Start heartbeat loop in background
|
||||
using var heartbeatCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
|
||||
var heartbeatTask = _heartbeatService.RunAsync(
|
||||
jobContext,
|
||||
() => currentStatus,
|
||||
() => null, // Progress not tracked at document level
|
||||
() => lastArtifactHash,
|
||||
() => lastArtifactKind,
|
||||
heartbeatCts.Token);
|
||||
|
||||
try
|
||||
{
|
||||
await foreach (var document in connector.FetchAsync(context, cancellationToken).ConfigureAwait(false))
|
||||
await foreach (var document in connector.FetchAsync(connectorContext, cancellationToken).ConfigureAwait(false))
|
||||
{
|
||||
documentCount++;
|
||||
lastArtifactHash = document.Digest;
|
||||
lastArtifactKind = "vex-raw-document";
|
||||
|
||||
// Record artifact for determinism tracking
|
||||
if (_orchestratorOptions.Enabled)
|
||||
{
|
||||
var artifact = new VexWorkerArtifact(
|
||||
document.Digest,
|
||||
"vex-raw-document",
|
||||
connector.Id,
|
||||
document.Digest,
|
||||
_timeProvider.GetUtcNow());
|
||||
|
||||
await _orchestratorClient.RecordArtifactAsync(jobContext, artifact, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
|
||||
// Stop heartbeat loop
|
||||
currentStatus = VexWorkerHeartbeatStatus.Succeeded;
|
||||
await heartbeatCts.CancelAsync().ConfigureAwait(false);
|
||||
await SafeWaitForTaskAsync(heartbeatTask).ConfigureAwait(false);
|
||||
|
||||
_logger.LogInformation(
|
||||
"Connector {ConnectorId} persisted {DocumentCount} raw document(s) this run.",
|
||||
connector.Id,
|
||||
documentCount);
|
||||
|
||||
await UpdateSuccessStateAsync(stateRepository, descriptor.Id, _timeProvider.GetUtcNow(), cancellationToken).ConfigureAwait(false);
|
||||
// Complete orchestrator job
|
||||
var completedAt = _timeProvider.GetUtcNow();
|
||||
var result = new VexWorkerJobResult(
|
||||
documentCount,
|
||||
ClaimsGenerated: 0, // Claims generated in separate normalization pass
|
||||
lastArtifactHash,
|
||||
lastArtifactHash,
|
||||
completedAt);
|
||||
|
||||
await _orchestratorClient.CompleteJobAsync(jobContext, result, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
await UpdateSuccessStateAsync(stateRepository, descriptor.Id, completedAt, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
currentStatus = VexWorkerHeartbeatStatus.Failed;
|
||||
await heartbeatCts.CancelAsync().ConfigureAwait(false);
|
||||
await SafeWaitForTaskAsync(heartbeatTask).ConfigureAwait(false);
|
||||
|
||||
var error = VexWorkerError.Cancelled("Operation cancelled by host");
|
||||
await _orchestratorClient.FailJobAsync(jobContext, error, CancellationToken.None).ConfigureAwait(false);
|
||||
|
||||
throw;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
await UpdateFailureStateAsync(stateRepository, descriptor.Id, _timeProvider.GetUtcNow(), ex, cancellationToken).ConfigureAwait(false);
|
||||
currentStatus = VexWorkerHeartbeatStatus.Failed;
|
||||
await heartbeatCts.CancelAsync().ConfigureAwait(false);
|
||||
await SafeWaitForTaskAsync(heartbeatTask).ConfigureAwait(false);
|
||||
|
||||
// Classify the error for appropriate retry handling
|
||||
var classifiedError = VexWorkerError.FromException(ex, stage: "fetch");
|
||||
|
||||
// Apply backoff delay for retryable errors
|
||||
var retryDelay = classifiedError.Retryable
|
||||
? (int)CalculateDelayWithJitter(1).TotalSeconds
|
||||
: (int?)null;
|
||||
|
||||
var errorWithRetry = classifiedError.Retryable && retryDelay.HasValue
|
||||
? new VexWorkerError(
|
||||
classifiedError.Code,
|
||||
classifiedError.Category,
|
||||
classifiedError.Message,
|
||||
classifiedError.Retryable,
|
||||
retryDelay,
|
||||
classifiedError.Stage,
|
||||
classifiedError.Details)
|
||||
: classifiedError;
|
||||
|
||||
await _orchestratorClient.FailJobAsync(jobContext, errorWithRetry, CancellationToken.None).ConfigureAwait(false);
|
||||
|
||||
await UpdateFailureStateAsync(stateRepository, descriptor.Id, _timeProvider.GetUtcNow(), ex, classifiedError.Retryable, cancellationToken).ConfigureAwait(false);
|
||||
throw;
|
||||
}
|
||||
}
|
||||
|
||||
private static async Task SafeWaitForTaskAsync(Task task)
|
||||
{
|
||||
try
|
||||
{
|
||||
await task.ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
// Expected when cancellation is requested
|
||||
}
|
||||
}
|
||||
|
||||
private async Task UpdateSuccessStateAsync(
|
||||
IVexConnectorStateRepository stateRepository,
|
||||
string connectorId,
|
||||
@@ -179,14 +285,20 @@ internal sealed class DefaultVexProviderRunner : IVexProviderRunner
|
||||
string connectorId,
|
||||
DateTimeOffset failureTime,
|
||||
Exception exception,
|
||||
bool retryable,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var current = await stateRepository.GetAsync(connectorId, cancellationToken).ConfigureAwait(false)
|
||||
?? new VexConnectorState(connectorId, null, ImmutableArray<string>.Empty);
|
||||
|
||||
var failureCount = current.FailureCount + 1;
|
||||
DateTimeOffset? nextEligible;
|
||||
|
||||
if (retryable)
|
||||
{
|
||||
// Apply exponential backoff for retryable errors
|
||||
var delay = CalculateDelayWithJitter(failureCount);
|
||||
var nextEligible = failureTime + delay;
|
||||
nextEligible = failureTime + delay;
|
||||
|
||||
if (failureCount >= _retryOptions.FailureThreshold)
|
||||
{
|
||||
@@ -207,6 +319,12 @@ internal sealed class DefaultVexProviderRunner : IVexProviderRunner
|
||||
{
|
||||
nextEligible = failureTime;
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
// Non-retryable errors: apply quarantine immediately
|
||||
nextEligible = failureTime + _retryOptions.QuarantineDuration;
|
||||
}
|
||||
|
||||
var updated = current with
|
||||
{
|
||||
@@ -219,9 +337,10 @@ internal sealed class DefaultVexProviderRunner : IVexProviderRunner
|
||||
|
||||
_logger.LogWarning(
|
||||
exception,
|
||||
"Connector {ConnectorId} failed (attempt {Attempt}). Next eligible run at {NextEligible:O}.",
|
||||
"Connector {ConnectorId} failed (attempt {Attempt}, retryable={Retryable}). Next eligible run at {NextEligible:O}.",
|
||||
connectorId,
|
||||
failureCount,
|
||||
retryable,
|
||||
nextEligible);
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,247 @@
|
||||
using System;
|
||||
using System.Collections.Immutable;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization;
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using StellaOps.Excititor.Attestation.Dsse;
|
||||
using StellaOps.Excititor.Attestation.Signing;
|
||||
using StellaOps.Excititor.Core.Evidence;
|
||||
|
||||
namespace StellaOps.Excititor.Attestation.Evidence;
|
||||
|
||||
/// <summary>
|
||||
/// Default implementation of <see cref="IVexEvidenceAttestor"/> that creates DSSE attestations for evidence manifests.
|
||||
/// </summary>
|
||||
public sealed class VexEvidenceAttestor : IVexEvidenceAttestor
|
||||
{
|
||||
internal const string PayloadType = "application/vnd.in-toto+json";
|
||||
|
||||
private readonly IVexSigner _signer;
|
||||
private readonly TimeProvider _timeProvider;
|
||||
private readonly ILogger<VexEvidenceAttestor> _logger;
|
||||
private readonly JsonSerializerOptions _serializerOptions;
|
||||
|
||||
public VexEvidenceAttestor(
|
||||
IVexSigner signer,
|
||||
ILogger<VexEvidenceAttestor> logger,
|
||||
TimeProvider? timeProvider = null)
|
||||
{
|
||||
_signer = signer ?? throw new ArgumentNullException(nameof(signer));
|
||||
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
|
||||
_timeProvider = timeProvider ?? TimeProvider.System;
|
||||
_serializerOptions = new JsonSerializerOptions
|
||||
{
|
||||
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
|
||||
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
|
||||
WriteIndented = false,
|
||||
};
|
||||
_serializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase));
|
||||
}
|
||||
|
||||
public async ValueTask<VexEvidenceAttestationResult> AttestManifestAsync(
|
||||
VexLockerManifest manifest,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(manifest);
|
||||
|
||||
var attestedAt = _timeProvider.GetUtcNow();
|
||||
var attestationId = CreateAttestationId(manifest, attestedAt);
|
||||
|
||||
// Build in-toto statement
|
||||
var predicate = VexEvidenceAttestationPredicate.FromManifest(manifest);
|
||||
var subject = new VexEvidenceInTotoSubject(
|
||||
manifest.ManifestId,
|
||||
ImmutableDictionary<string, string>.Empty.Add("sha256", manifest.MerkleRoot.Replace("sha256:", "")));
|
||||
|
||||
var statement = new InTotoStatementDto
|
||||
{
|
||||
Type = VexEvidenceInTotoStatement.InTotoStatementType,
|
||||
PredicateType = VexEvidenceInTotoStatement.EvidenceLockerPredicateType,
|
||||
Subject = new[] { new InTotoSubjectDto { Name = subject.Name, Digest = subject.Digest } },
|
||||
Predicate = new InTotoPredicateDto
|
||||
{
|
||||
ManifestId = predicate.ManifestId,
|
||||
Tenant = predicate.Tenant,
|
||||
MerkleRoot = predicate.MerkleRoot,
|
||||
ItemCount = predicate.ItemCount,
|
||||
CreatedAt = predicate.CreatedAt,
|
||||
Metadata = predicate.Metadata.Count > 0 ? predicate.Metadata : null
|
||||
}
|
||||
};
|
||||
|
||||
// Serialize and sign
|
||||
var payloadBytes = JsonSerializer.SerializeToUtf8Bytes(statement, _serializerOptions);
|
||||
var signatureResult = await _signer.SignAsync(payloadBytes, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
// Build DSSE envelope
|
||||
var envelope = new DsseEnvelope(
|
||||
Convert.ToBase64String(payloadBytes),
|
||||
PayloadType,
|
||||
new[] { new DsseSignature(signatureResult.Signature, signatureResult.KeyId) });
|
||||
|
||||
var envelopeJson = JsonSerializer.Serialize(envelope, _serializerOptions);
|
||||
var envelopeHash = ComputeHash(envelopeJson);
|
||||
|
||||
// Create signed manifest
|
||||
var signedManifest = manifest.WithSignature(signatureResult.Signature);
|
||||
|
||||
_logger.LogDebug(
|
||||
"Evidence attestation created for manifest {ManifestId}: attestation={AttestationId} hash={Hash}",
|
||||
manifest.ManifestId,
|
||||
attestationId,
|
||||
envelopeHash);
|
||||
|
||||
return new VexEvidenceAttestationResult(
|
||||
signedManifest,
|
||||
envelopeJson,
|
||||
envelopeHash,
|
||||
attestationId,
|
||||
attestedAt);
|
||||
}
|
||||
|
||||
public ValueTask<VexEvidenceVerificationResult> VerifyAttestationAsync(
|
||||
VexLockerManifest manifest,
|
||||
string dsseEnvelopeJson,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(manifest);
|
||||
if (string.IsNullOrWhiteSpace(dsseEnvelopeJson))
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure("DSSE envelope is required."));
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
var envelope = JsonSerializer.Deserialize<DsseEnvelope>(dsseEnvelopeJson, _serializerOptions);
|
||||
if (envelope is null)
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure("Invalid DSSE envelope format."));
|
||||
}
|
||||
|
||||
// Decode payload and verify it matches the manifest
|
||||
var payloadBytes = Convert.FromBase64String(envelope.Payload);
|
||||
var statement = JsonSerializer.Deserialize<InTotoStatementDto>(payloadBytes, _serializerOptions);
|
||||
if (statement is null)
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure("Invalid in-toto statement format."));
|
||||
}
|
||||
|
||||
// Verify statement type
|
||||
if (statement.Type != VexEvidenceInTotoStatement.InTotoStatementType)
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure(
|
||||
$"Invalid statement type: expected {VexEvidenceInTotoStatement.InTotoStatementType}, got {statement.Type}"));
|
||||
}
|
||||
|
||||
// Verify predicate type
|
||||
if (statement.PredicateType != VexEvidenceInTotoStatement.EvidenceLockerPredicateType)
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure(
|
||||
$"Invalid predicate type: expected {VexEvidenceInTotoStatement.EvidenceLockerPredicateType}, got {statement.PredicateType}"));
|
||||
}
|
||||
|
||||
// Verify manifest ID matches
|
||||
if (statement.Predicate?.ManifestId != manifest.ManifestId)
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure(
|
||||
$"Manifest ID mismatch: expected {manifest.ManifestId}, got {statement.Predicate?.ManifestId}"));
|
||||
}
|
||||
|
||||
// Verify Merkle root matches
|
||||
if (statement.Predicate?.MerkleRoot != manifest.MerkleRoot)
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure(
|
||||
$"Merkle root mismatch: expected {manifest.MerkleRoot}, got {statement.Predicate?.MerkleRoot}"));
|
||||
}
|
||||
|
||||
// Verify item count matches
|
||||
if (statement.Predicate?.ItemCount != manifest.Items.Length)
|
||||
{
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure(
|
||||
$"Item count mismatch: expected {manifest.Items.Length}, got {statement.Predicate?.ItemCount}"));
|
||||
}
|
||||
|
||||
var diagnostics = ImmutableDictionary.CreateBuilder<string, string>();
|
||||
diagnostics.Add("envelope_hash", ComputeHash(dsseEnvelopeJson));
|
||||
diagnostics.Add("verified_at", _timeProvider.GetUtcNow().ToString("O"));
|
||||
|
||||
_logger.LogDebug("Evidence attestation verified for manifest {ManifestId}", manifest.ManifestId);
|
||||
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Success(diagnostics.ToImmutable()));
|
||||
}
|
||||
catch (JsonException ex)
|
||||
{
|
||||
_logger.LogWarning(ex, "Failed to parse DSSE envelope for manifest {ManifestId}", manifest.ManifestId);
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure($"JSON parse error: {ex.Message}"));
|
||||
}
|
||||
catch (FormatException ex)
|
||||
{
|
||||
_logger.LogWarning(ex, "Failed to decode base64 payload for manifest {ManifestId}", manifest.ManifestId);
|
||||
return ValueTask.FromResult(VexEvidenceVerificationResult.Failure($"Base64 decode error: {ex.Message}"));
|
||||
}
|
||||
}
|
||||
|
||||
private static string CreateAttestationId(VexLockerManifest manifest, DateTimeOffset timestamp)
|
||||
{
|
||||
var normalized = manifest.Tenant.ToLowerInvariant();
|
||||
var date = timestamp.ToString("yyyyMMddHHmmssfff");
|
||||
return $"attest:evidence:{normalized}:{date}";
|
||||
}
|
||||
|
||||
private static string ComputeHash(string content)
|
||||
{
|
||||
var bytes = Encoding.UTF8.GetBytes(content);
|
||||
var hash = SHA256.HashData(bytes);
|
||||
return "sha256:" + Convert.ToHexString(hash).ToLowerInvariant();
|
||||
}
|
||||
|
||||
// DTOs for JSON serialization
|
||||
private sealed record InTotoStatementDto
|
||||
{
|
||||
[JsonPropertyName("_type")]
|
||||
public string? Type { get; init; }
|
||||
|
||||
[JsonPropertyName("predicateType")]
|
||||
public string? PredicateType { get; init; }
|
||||
|
||||
[JsonPropertyName("subject")]
|
||||
public InTotoSubjectDto[]? Subject { get; init; }
|
||||
|
||||
[JsonPropertyName("predicate")]
|
||||
public InTotoPredicateDto? Predicate { get; init; }
|
||||
}
|
||||
|
||||
private sealed record InTotoSubjectDto
|
||||
{
|
||||
[JsonPropertyName("name")]
|
||||
public string? Name { get; init; }
|
||||
|
||||
[JsonPropertyName("digest")]
|
||||
public ImmutableDictionary<string, string>? Digest { get; init; }
|
||||
}
|
||||
|
||||
private sealed record InTotoPredicateDto
|
||||
{
|
||||
[JsonPropertyName("manifestId")]
|
||||
public string? ManifestId { get; init; }
|
||||
|
||||
[JsonPropertyName("tenant")]
|
||||
public string? Tenant { get; init; }
|
||||
|
||||
[JsonPropertyName("merkleRoot")]
|
||||
public string? MerkleRoot { get; init; }
|
||||
|
||||
[JsonPropertyName("itemCount")]
|
||||
public int? ItemCount { get; init; }
|
||||
|
||||
[JsonPropertyName("createdAt")]
|
||||
public DateTimeOffset? CreatedAt { get; init; }
|
||||
|
||||
[JsonPropertyName("metadata")]
|
||||
public ImmutableDictionary<string, string>? Metadata { get; init; }
|
||||
}
|
||||
}
|
||||
@@ -1,8 +1,10 @@
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using StellaOps.Excititor.Attestation.Dsse;
|
||||
using StellaOps.Excititor.Attestation.Evidence;
|
||||
using StellaOps.Excititor.Attestation.Transparency;
|
||||
using StellaOps.Excititor.Attestation.Verification;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Evidence;
|
||||
|
||||
namespace StellaOps.Excititor.Attestation.Extensions;
|
||||
|
||||
@@ -14,6 +16,7 @@ public static class VexAttestationServiceCollectionExtensions
|
||||
services.AddSingleton<VexAttestationMetrics>();
|
||||
services.AddSingleton<IVexAttestationVerifier, VexAttestationVerifier>();
|
||||
services.AddSingleton<IVexAttestationClient, VexAttestationClient>();
|
||||
services.AddSingleton<IVexEvidenceAttestor, VexEvidenceAttestor>();
|
||||
return services;
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,314 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Text.RegularExpressions;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Canonicalization;
|
||||
|
||||
/// <summary>
|
||||
/// Canonicalizes advisory and vulnerability identifiers to a stable <see cref="VexCanonicalAdvisoryKey"/>.
|
||||
/// Preserves original identifiers in the Links collection for traceability.
|
||||
/// </summary>
|
||||
public sealed class VexAdvisoryKeyCanonicalizer
|
||||
{
|
||||
private static readonly Regex CvePattern = new(
|
||||
@"^CVE-\d{4}-\d{4,}$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
private static readonly Regex GhsaPattern = new(
|
||||
@"^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
private static readonly Regex RhsaPattern = new(
|
||||
@"^RH[A-Z]{2}-\d{4}:\d+$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
private static readonly Regex DsaPattern = new(
|
||||
@"^DSA-\d+(-\d+)?$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
private static readonly Regex UsnPattern = new(
|
||||
@"^USN-\d+(-\d+)?$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
private static readonly Regex MsrcPattern = new(
|
||||
@"^(ADV|CVE)-\d{4}-\d+$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
/// <summary>
|
||||
/// Canonicalizes an advisory identifier and extracts scope metadata.
|
||||
/// </summary>
|
||||
/// <param name="originalId">The original advisory/vulnerability identifier.</param>
|
||||
/// <param name="aliases">Optional alias identifiers to include in links.</param>
|
||||
/// <returns>A canonical advisory key with preserved original links.</returns>
|
||||
public VexCanonicalAdvisoryKey Canonicalize(string originalId, IEnumerable<string>? aliases = null)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(originalId);
|
||||
|
||||
var normalized = originalId.Trim().ToUpperInvariant();
|
||||
var scope = DetermineScope(normalized);
|
||||
var canonicalKey = BuildCanonicalKey(normalized, scope);
|
||||
|
||||
var linksBuilder = ImmutableArray.CreateBuilder<VexAdvisoryLink>();
|
||||
|
||||
// Add the original identifier as a link
|
||||
linksBuilder.Add(new VexAdvisoryLink(
|
||||
originalId.Trim(),
|
||||
DetermineIdType(normalized),
|
||||
isOriginal: true));
|
||||
|
||||
// Add aliases as links
|
||||
if (aliases is not null)
|
||||
{
|
||||
var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { normalized };
|
||||
foreach (var alias in aliases)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(alias))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
var normalizedAlias = alias.Trim();
|
||||
if (!seen.Add(normalizedAlias.ToUpperInvariant()))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
linksBuilder.Add(new VexAdvisoryLink(
|
||||
normalizedAlias,
|
||||
DetermineIdType(normalizedAlias.ToUpperInvariant()),
|
||||
isOriginal: false));
|
||||
}
|
||||
}
|
||||
|
||||
return new VexCanonicalAdvisoryKey(
|
||||
canonicalKey,
|
||||
scope,
|
||||
linksBuilder.ToImmutable());
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extracts CVE identifier from aliases if the original is not a CVE.
|
||||
/// </summary>
|
||||
public string? ExtractCveFromAliases(IEnumerable<string>? aliases)
|
||||
{
|
||||
if (aliases is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
foreach (var alias in aliases)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(alias))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
var normalized = alias.Trim().ToUpperInvariant();
|
||||
if (CvePattern.IsMatch(normalized))
|
||||
{
|
||||
return normalized;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
private static VexAdvisoryScope DetermineScope(string normalizedId)
|
||||
{
|
||||
if (CvePattern.IsMatch(normalizedId))
|
||||
{
|
||||
return VexAdvisoryScope.Global;
|
||||
}
|
||||
|
||||
if (GhsaPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return VexAdvisoryScope.Ecosystem;
|
||||
}
|
||||
|
||||
if (RhsaPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return VexAdvisoryScope.Vendor;
|
||||
}
|
||||
|
||||
if (DsaPattern.IsMatch(normalizedId) || UsnPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return VexAdvisoryScope.Distribution;
|
||||
}
|
||||
|
||||
if (MsrcPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return VexAdvisoryScope.Vendor;
|
||||
}
|
||||
|
||||
return VexAdvisoryScope.Unknown;
|
||||
}
|
||||
|
||||
private static string BuildCanonicalKey(string normalizedId, VexAdvisoryScope scope)
|
||||
{
|
||||
// CVE is the most authoritative global identifier
|
||||
if (CvePattern.IsMatch(normalizedId))
|
||||
{
|
||||
return normalizedId;
|
||||
}
|
||||
|
||||
// For non-CVE identifiers, prefix with scope indicator for disambiguation
|
||||
var prefix = scope switch
|
||||
{
|
||||
VexAdvisoryScope.Ecosystem => "ECO",
|
||||
VexAdvisoryScope.Vendor => "VND",
|
||||
VexAdvisoryScope.Distribution => "DST",
|
||||
_ => "UNK",
|
||||
};
|
||||
|
||||
return $"{prefix}:{normalizedId}";
|
||||
}
|
||||
|
||||
private static string DetermineIdType(string normalizedId)
|
||||
{
|
||||
if (CvePattern.IsMatch(normalizedId))
|
||||
{
|
||||
return "cve";
|
||||
}
|
||||
|
||||
if (GhsaPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return "ghsa";
|
||||
}
|
||||
|
||||
if (RhsaPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return "rhsa";
|
||||
}
|
||||
|
||||
if (DsaPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return "dsa";
|
||||
}
|
||||
|
||||
if (UsnPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return "usn";
|
||||
}
|
||||
|
||||
if (MsrcPattern.IsMatch(normalizedId))
|
||||
{
|
||||
return "msrc";
|
||||
}
|
||||
|
||||
return "other";
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Represents a canonicalized advisory key with preserved original identifiers.
|
||||
/// </summary>
|
||||
public sealed record VexCanonicalAdvisoryKey
|
||||
{
|
||||
public VexCanonicalAdvisoryKey(
|
||||
string advisoryKey,
|
||||
VexAdvisoryScope scope,
|
||||
ImmutableArray<VexAdvisoryLink> links)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(advisoryKey))
|
||||
{
|
||||
throw new ArgumentException("Advisory key must be provided.", nameof(advisoryKey));
|
||||
}
|
||||
|
||||
AdvisoryKey = advisoryKey.Trim();
|
||||
Scope = scope;
|
||||
Links = links.IsDefault ? ImmutableArray<VexAdvisoryLink>.Empty : links;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The canonical advisory key used for correlation and storage.
|
||||
/// </summary>
|
||||
public string AdvisoryKey { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The scope/authority level of the advisory.
|
||||
/// </summary>
|
||||
public VexAdvisoryScope Scope { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Original and alias identifiers preserved for traceability.
|
||||
/// </summary>
|
||||
public ImmutableArray<VexAdvisoryLink> Links { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Returns the original identifier if available.
|
||||
/// </summary>
|
||||
public string? OriginalId => Links.FirstOrDefault(l => l.IsOriginal)?.Identifier;
|
||||
|
||||
/// <summary>
|
||||
/// Returns all non-original alias identifiers.
|
||||
/// </summary>
|
||||
public IEnumerable<string> Aliases => Links.Where(l => !l.IsOriginal).Select(l => l.Identifier);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Represents a link to an original or alias advisory identifier.
|
||||
/// </summary>
|
||||
public sealed record VexAdvisoryLink
|
||||
{
|
||||
public VexAdvisoryLink(string identifier, string type, bool isOriginal)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(identifier))
|
||||
{
|
||||
throw new ArgumentException("Identifier must be provided.", nameof(identifier));
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(type))
|
||||
{
|
||||
throw new ArgumentException("Type must be provided.", nameof(type));
|
||||
}
|
||||
|
||||
Identifier = identifier.Trim();
|
||||
Type = type.Trim().ToLowerInvariant();
|
||||
IsOriginal = isOriginal;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The advisory identifier value.
|
||||
/// </summary>
|
||||
public string Identifier { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The type of identifier (cve, ghsa, rhsa, dsa, usn, msrc, other).
|
||||
/// </summary>
|
||||
public string Type { get; }
|
||||
|
||||
/// <summary>
|
||||
/// True if this is the original identifier provided at ingest time.
|
||||
/// </summary>
|
||||
public bool IsOriginal { get; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The scope/authority level of an advisory.
|
||||
/// </summary>
|
||||
public enum VexAdvisoryScope
|
||||
{
|
||||
/// <summary>
|
||||
/// Unknown or unclassified scope.
|
||||
/// </summary>
|
||||
Unknown = 0,
|
||||
|
||||
/// <summary>
|
||||
/// Global identifiers (e.g., CVE).
|
||||
/// </summary>
|
||||
Global = 1,
|
||||
|
||||
/// <summary>
|
||||
/// Ecosystem-specific identifiers (e.g., GHSA).
|
||||
/// </summary>
|
||||
Ecosystem = 2,
|
||||
|
||||
/// <summary>
|
||||
/// Vendor-specific identifiers (e.g., RHSA, MSRC).
|
||||
/// </summary>
|
||||
Vendor = 3,
|
||||
|
||||
/// <summary>
|
||||
/// Distribution-specific identifiers (e.g., DSA, USN).
|
||||
/// </summary>
|
||||
Distribution = 4,
|
||||
}
|
||||
@@ -0,0 +1,479 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Text.RegularExpressions;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Canonicalization;
|
||||
|
||||
/// <summary>
|
||||
/// Canonicalizes product identifiers (PURL, CPE, OS package names) to a stable <see cref="VexCanonicalProductKey"/>.
|
||||
/// Preserves original identifiers in the Links collection for traceability.
|
||||
/// </summary>
|
||||
public sealed class VexProductKeyCanonicalizer
|
||||
{
|
||||
private static readonly Regex PurlPattern = new(
|
||||
@"^pkg:[a-z0-9]+/",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
private static readonly Regex CpePattern = new(
|
||||
@"^cpe:(2\.3:|/)",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
// RPM NEVRA format: name-[epoch:]version-release.arch
|
||||
// Release can contain dots (e.g., 1.el9), so we match until the last dot before arch
|
||||
private static readonly Regex RpmNevraPattern = new(
|
||||
@"^(?<name>[a-zA-Z0-9_+-]+)-(?<epoch>\d+:)?(?<version>[^-]+)-(?<release>.+)\.(?<arch>x86_64|i686|noarch|aarch64|s390x|ppc64le|armv7hl|src)$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
// Debian packages use underscores as separators: name_version_arch or name_version
|
||||
// Must have at least one underscore to be considered a Debian package
|
||||
private static readonly Regex DebianPackagePattern = new(
|
||||
@"^(?<name>[a-z0-9][a-z0-9.+-]+)_(?<version>[^_]+)(_(?<arch>[a-z0-9-]+))?$",
|
||||
RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
|
||||
|
||||
/// <summary>
|
||||
/// Canonicalizes a product identifier and extracts scope metadata.
|
||||
/// </summary>
|
||||
/// <param name="originalKey">The original product key/identifier.</param>
|
||||
/// <param name="purl">Optional PURL for the product.</param>
|
||||
/// <param name="cpe">Optional CPE for the product.</param>
|
||||
/// <param name="componentIdentifiers">Optional additional component identifiers.</param>
|
||||
/// <returns>A canonical product key with preserved original links.</returns>
|
||||
public VexCanonicalProductKey Canonicalize(
|
||||
string originalKey,
|
||||
string? purl = null,
|
||||
string? cpe = null,
|
||||
IEnumerable<string>? componentIdentifiers = null)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(originalKey);
|
||||
|
||||
// Check component identifiers for PURL if not provided directly
|
||||
var effectivePurl = purl ?? ExtractPurlFromIdentifiers(componentIdentifiers);
|
||||
var effectiveCpe = cpe ?? ExtractCpeFromIdentifiers(componentIdentifiers);
|
||||
|
||||
var keyType = DetermineKeyType(originalKey.Trim());
|
||||
var scope = DetermineScope(originalKey.Trim(), effectivePurl, effectiveCpe);
|
||||
var canonicalKey = BuildCanonicalKey(originalKey.Trim(), effectivePurl, effectiveCpe, keyType);
|
||||
|
||||
var linksBuilder = ImmutableArray.CreateBuilder<VexProductLink>();
|
||||
|
||||
// Add the original key as a link
|
||||
linksBuilder.Add(new VexProductLink(
|
||||
originalKey.Trim(),
|
||||
keyType.ToString().ToLowerInvariant(),
|
||||
isOriginal: true));
|
||||
|
||||
var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { originalKey.Trim() };
|
||||
|
||||
// Add PURL if different from original
|
||||
if (!string.IsNullOrWhiteSpace(purl) && seen.Add(purl.Trim()))
|
||||
{
|
||||
linksBuilder.Add(new VexProductLink(
|
||||
purl.Trim(),
|
||||
"purl",
|
||||
isOriginal: false));
|
||||
}
|
||||
|
||||
// Add CPE if different from original
|
||||
if (!string.IsNullOrWhiteSpace(cpe) && seen.Add(cpe.Trim()))
|
||||
{
|
||||
linksBuilder.Add(new VexProductLink(
|
||||
cpe.Trim(),
|
||||
"cpe",
|
||||
isOriginal: false));
|
||||
}
|
||||
|
||||
// Add component identifiers
|
||||
if (componentIdentifiers is not null)
|
||||
{
|
||||
foreach (var identifier in componentIdentifiers)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(identifier))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
var normalizedId = identifier.Trim();
|
||||
if (!seen.Add(normalizedId))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
var idType = DetermineKeyType(normalizedId);
|
||||
linksBuilder.Add(new VexProductLink(
|
||||
normalizedId,
|
||||
idType.ToString().ToLowerInvariant(),
|
||||
isOriginal: false));
|
||||
}
|
||||
}
|
||||
|
||||
return new VexCanonicalProductKey(
|
||||
canonicalKey,
|
||||
scope,
|
||||
keyType,
|
||||
linksBuilder.ToImmutable());
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extracts PURL from component identifiers if available.
|
||||
/// </summary>
|
||||
public string? ExtractPurlFromIdentifiers(IEnumerable<string>? identifiers)
|
||||
{
|
||||
if (identifiers is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
foreach (var id in identifiers)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(id))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (PurlPattern.IsMatch(id.Trim()))
|
||||
{
|
||||
return id.Trim();
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extracts CPE from component identifiers if available.
|
||||
/// </summary>
|
||||
public string? ExtractCpeFromIdentifiers(IEnumerable<string>? identifiers)
|
||||
{
|
||||
if (identifiers is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
foreach (var id in identifiers)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(id))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (CpePattern.IsMatch(id.Trim()))
|
||||
{
|
||||
return id.Trim();
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
private static VexProductKeyType DetermineKeyType(string key)
|
||||
{
|
||||
if (PurlPattern.IsMatch(key))
|
||||
{
|
||||
return VexProductKeyType.Purl;
|
||||
}
|
||||
|
||||
if (CpePattern.IsMatch(key))
|
||||
{
|
||||
return VexProductKeyType.Cpe;
|
||||
}
|
||||
|
||||
if (RpmNevraPattern.IsMatch(key))
|
||||
{
|
||||
return VexProductKeyType.RpmNevra;
|
||||
}
|
||||
|
||||
if (DebianPackagePattern.IsMatch(key))
|
||||
{
|
||||
return VexProductKeyType.DebianPackage;
|
||||
}
|
||||
|
||||
if (key.StartsWith("oci:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return VexProductKeyType.OciImage;
|
||||
}
|
||||
|
||||
if (key.StartsWith("platform:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return VexProductKeyType.Platform;
|
||||
}
|
||||
|
||||
return VexProductKeyType.Other;
|
||||
}
|
||||
|
||||
private static VexProductScope DetermineScope(string key, string? purl, string? cpe)
|
||||
{
|
||||
// PURL is the most authoritative
|
||||
if (!string.IsNullOrWhiteSpace(purl) || PurlPattern.IsMatch(key))
|
||||
{
|
||||
return VexProductScope.Package;
|
||||
}
|
||||
|
||||
// CPE is next
|
||||
if (!string.IsNullOrWhiteSpace(cpe) || CpePattern.IsMatch(key))
|
||||
{
|
||||
return VexProductScope.Component;
|
||||
}
|
||||
|
||||
// OS packages
|
||||
if (RpmNevraPattern.IsMatch(key) || DebianPackagePattern.IsMatch(key))
|
||||
{
|
||||
return VexProductScope.OsPackage;
|
||||
}
|
||||
|
||||
// OCI images
|
||||
if (key.StartsWith("oci:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return VexProductScope.Container;
|
||||
}
|
||||
|
||||
// Platforms
|
||||
if (key.StartsWith("platform:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return VexProductScope.Platform;
|
||||
}
|
||||
|
||||
return VexProductScope.Unknown;
|
||||
}
|
||||
|
||||
private static string BuildCanonicalKey(string key, string? purl, string? cpe, VexProductKeyType keyType)
|
||||
{
|
||||
// Prefer PURL as canonical key
|
||||
if (!string.IsNullOrWhiteSpace(purl))
|
||||
{
|
||||
return NormalizePurl(purl.Trim());
|
||||
}
|
||||
|
||||
if (PurlPattern.IsMatch(key))
|
||||
{
|
||||
return NormalizePurl(key);
|
||||
}
|
||||
|
||||
// Fall back to CPE
|
||||
if (!string.IsNullOrWhiteSpace(cpe))
|
||||
{
|
||||
return NormalizeCpe(cpe.Trim());
|
||||
}
|
||||
|
||||
if (CpePattern.IsMatch(key))
|
||||
{
|
||||
return NormalizeCpe(key);
|
||||
}
|
||||
|
||||
// For types that already have their prefix, return as-is
|
||||
if (keyType == VexProductKeyType.OciImage && key.StartsWith("oci:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return key;
|
||||
}
|
||||
|
||||
if (keyType == VexProductKeyType.Platform && key.StartsWith("platform:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return key;
|
||||
}
|
||||
|
||||
// For other types, prefix for disambiguation
|
||||
var prefix = keyType switch
|
||||
{
|
||||
VexProductKeyType.RpmNevra => "rpm",
|
||||
VexProductKeyType.DebianPackage => "deb",
|
||||
VexProductKeyType.OciImage => "oci",
|
||||
VexProductKeyType.Platform => "platform",
|
||||
_ => "product",
|
||||
};
|
||||
|
||||
return $"{prefix}:{key}";
|
||||
}
|
||||
|
||||
private static string NormalizePurl(string purl)
|
||||
{
|
||||
// Ensure lowercase scheme
|
||||
if (purl.StartsWith("PKG:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return "pkg:" + purl.Substring(4);
|
||||
}
|
||||
|
||||
return purl;
|
||||
}
|
||||
|
||||
private static string NormalizeCpe(string cpe)
|
||||
{
|
||||
// Ensure lowercase scheme
|
||||
if (cpe.StartsWith("CPE:", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return "cpe:" + cpe.Substring(4);
|
||||
}
|
||||
|
||||
return cpe;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Represents a canonicalized product key with preserved original identifiers.
|
||||
/// </summary>
|
||||
public sealed record VexCanonicalProductKey
|
||||
{
|
||||
public VexCanonicalProductKey(
|
||||
string productKey,
|
||||
VexProductScope scope,
|
||||
VexProductKeyType keyType,
|
||||
ImmutableArray<VexProductLink> links)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(productKey))
|
||||
{
|
||||
throw new ArgumentException("Product key must be provided.", nameof(productKey));
|
||||
}
|
||||
|
||||
ProductKey = productKey.Trim();
|
||||
Scope = scope;
|
||||
KeyType = keyType;
|
||||
Links = links.IsDefault ? ImmutableArray<VexProductLink>.Empty : links;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The canonical product key used for correlation and storage.
|
||||
/// </summary>
|
||||
public string ProductKey { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The scope/authority level of the product identifier.
|
||||
/// </summary>
|
||||
public VexProductScope Scope { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The type of the canonical key.
|
||||
/// </summary>
|
||||
public VexProductKeyType KeyType { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Original and alias identifiers preserved for traceability.
|
||||
/// </summary>
|
||||
public ImmutableArray<VexProductLink> Links { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Returns the original identifier if available.
|
||||
/// </summary>
|
||||
public string? OriginalKey => Links.FirstOrDefault(l => l.IsOriginal)?.Identifier;
|
||||
|
||||
/// <summary>
|
||||
/// Returns the PURL link if available.
|
||||
/// </summary>
|
||||
public string? Purl => Links.FirstOrDefault(l => l.Type == "purl")?.Identifier;
|
||||
|
||||
/// <summary>
|
||||
/// Returns the CPE link if available.
|
||||
/// </summary>
|
||||
public string? Cpe => Links.FirstOrDefault(l => l.Type == "cpe")?.Identifier;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Represents a link to an original or alias product identifier.
|
||||
/// </summary>
|
||||
public sealed record VexProductLink
|
||||
{
|
||||
public VexProductLink(string identifier, string type, bool isOriginal)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(identifier))
|
||||
{
|
||||
throw new ArgumentException("Identifier must be provided.", nameof(identifier));
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(type))
|
||||
{
|
||||
throw new ArgumentException("Type must be provided.", nameof(type));
|
||||
}
|
||||
|
||||
Identifier = identifier.Trim();
|
||||
Type = type.Trim().ToLowerInvariant();
|
||||
IsOriginal = isOriginal;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The product identifier value.
|
||||
/// </summary>
|
||||
public string Identifier { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The type of identifier (purl, cpe, rpm, deb, oci, platform, other).
|
||||
/// </summary>
|
||||
public string Type { get; }
|
||||
|
||||
/// <summary>
|
||||
/// True if this is the original identifier provided at ingest time.
|
||||
/// </summary>
|
||||
public bool IsOriginal { get; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The scope/authority level of a product identifier.
|
||||
/// </summary>
|
||||
public enum VexProductScope
|
||||
{
|
||||
/// <summary>
|
||||
/// Unknown or unclassified scope.
|
||||
/// </summary>
|
||||
Unknown = 0,
|
||||
|
||||
/// <summary>
|
||||
/// Package-level identifier (PURL).
|
||||
/// </summary>
|
||||
Package = 1,
|
||||
|
||||
/// <summary>
|
||||
/// Component-level identifier (CPE).
|
||||
/// </summary>
|
||||
Component = 2,
|
||||
|
||||
/// <summary>
|
||||
/// OS package identifier (RPM, DEB).
|
||||
/// </summary>
|
||||
OsPackage = 3,
|
||||
|
||||
/// <summary>
|
||||
/// Container image identifier.
|
||||
/// </summary>
|
||||
Container = 4,
|
||||
|
||||
/// <summary>
|
||||
/// Platform-level identifier.
|
||||
/// </summary>
|
||||
Platform = 5,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The type of product key identifier.
|
||||
/// </summary>
|
||||
public enum VexProductKeyType
|
||||
{
|
||||
/// <summary>
|
||||
/// Other/unknown type.
|
||||
/// </summary>
|
||||
Other = 0,
|
||||
|
||||
/// <summary>
|
||||
/// Package URL (PURL).
|
||||
/// </summary>
|
||||
Purl = 1,
|
||||
|
||||
/// <summary>
|
||||
/// Common Platform Enumeration (CPE).
|
||||
/// </summary>
|
||||
Cpe = 2,
|
||||
|
||||
/// <summary>
|
||||
/// RPM NEVRA format.
|
||||
/// </summary>
|
||||
RpmNevra = 3,
|
||||
|
||||
/// <summary>
|
||||
/// Debian package format.
|
||||
/// </summary>
|
||||
DebianPackage = 4,
|
||||
|
||||
/// <summary>
|
||||
/// OCI image reference.
|
||||
/// </summary>
|
||||
OciImage = 5,
|
||||
|
||||
/// <summary>
|
||||
/// Platform identifier.
|
||||
/// </summary>
|
||||
Platform = 6,
|
||||
}
|
||||
@@ -0,0 +1,187 @@
|
||||
using System;
|
||||
using System.Collections.Immutable;
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Evidence;
|
||||
|
||||
/// <summary>
|
||||
/// Service interface for creating and verifying DSSE attestations on evidence locker manifests.
|
||||
/// </summary>
|
||||
public interface IVexEvidenceAttestor
|
||||
{
|
||||
/// <summary>
|
||||
/// Creates a DSSE attestation for the given manifest and returns the signed manifest.
|
||||
/// </summary>
|
||||
ValueTask<VexEvidenceAttestationResult> AttestManifestAsync(
|
||||
VexLockerManifest manifest,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Verifies an attestation for the given manifest.
|
||||
/// </summary>
|
||||
ValueTask<VexEvidenceVerificationResult> VerifyAttestationAsync(
|
||||
VexLockerManifest manifest,
|
||||
string dsseEnvelopeJson,
|
||||
CancellationToken cancellationToken = default);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Result of attesting an evidence manifest.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceAttestationResult
|
||||
{
|
||||
public VexEvidenceAttestationResult(
|
||||
VexLockerManifest signedManifest,
|
||||
string dsseEnvelopeJson,
|
||||
string dsseEnvelopeHash,
|
||||
string attestationId,
|
||||
DateTimeOffset attestedAt)
|
||||
{
|
||||
SignedManifest = signedManifest ?? throw new ArgumentNullException(nameof(signedManifest));
|
||||
DsseEnvelopeJson = EnsureNotNullOrWhiteSpace(dsseEnvelopeJson, nameof(dsseEnvelopeJson));
|
||||
DsseEnvelopeHash = EnsureNotNullOrWhiteSpace(dsseEnvelopeHash, nameof(dsseEnvelopeHash));
|
||||
AttestationId = EnsureNotNullOrWhiteSpace(attestationId, nameof(attestationId));
|
||||
AttestedAt = attestedAt;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The manifest with the attestation signature attached.
|
||||
/// </summary>
|
||||
public VexLockerManifest SignedManifest { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The DSSE envelope as JSON.
|
||||
/// </summary>
|
||||
public string DsseEnvelopeJson { get; }
|
||||
|
||||
/// <summary>
|
||||
/// SHA-256 hash of the DSSE envelope.
|
||||
/// </summary>
|
||||
public string DsseEnvelopeHash { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Unique identifier for this attestation.
|
||||
/// </summary>
|
||||
public string AttestationId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// When the attestation was created.
|
||||
/// </summary>
|
||||
public DateTimeOffset AttestedAt { get; }
|
||||
|
||||
private static string EnsureNotNullOrWhiteSpace(string value, string name)
|
||||
=> string.IsNullOrWhiteSpace(value) ? throw new ArgumentException($"{name} must be provided.", name) : value.Trim();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Result of verifying an evidence attestation.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceVerificationResult
|
||||
{
|
||||
public VexEvidenceVerificationResult(
|
||||
bool isValid,
|
||||
string? failureReason = null,
|
||||
ImmutableDictionary<string, string>? diagnostics = null)
|
||||
{
|
||||
IsValid = isValid;
|
||||
FailureReason = failureReason?.Trim();
|
||||
Diagnostics = diagnostics ?? ImmutableDictionary<string, string>.Empty;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Whether the attestation is valid.
|
||||
/// </summary>
|
||||
public bool IsValid { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Reason for failure if not valid.
|
||||
/// </summary>
|
||||
public string? FailureReason { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Additional diagnostic information.
|
||||
/// </summary>
|
||||
public ImmutableDictionary<string, string> Diagnostics { get; }
|
||||
|
||||
public static VexEvidenceVerificationResult Success(ImmutableDictionary<string, string>? diagnostics = null)
|
||||
=> new(true, null, diagnostics);
|
||||
|
||||
public static VexEvidenceVerificationResult Failure(string reason, ImmutableDictionary<string, string>? diagnostics = null)
|
||||
=> new(false, reason, diagnostics);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// in-toto statement for evidence locker attestations.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceInTotoStatement
|
||||
{
|
||||
public const string InTotoStatementType = "https://in-toto.io/Statement/v1";
|
||||
public const string EvidenceLockerPredicateType = "https://stella-ops.org/attestations/evidence-locker/v1";
|
||||
|
||||
public VexEvidenceInTotoStatement(
|
||||
ImmutableArray<VexEvidenceInTotoSubject> subjects,
|
||||
VexEvidenceAttestationPredicate predicate)
|
||||
{
|
||||
Type = InTotoStatementType;
|
||||
Subjects = subjects;
|
||||
PredicateType = EvidenceLockerPredicateType;
|
||||
Predicate = predicate ?? throw new ArgumentNullException(nameof(predicate));
|
||||
}
|
||||
|
||||
public string Type { get; }
|
||||
public ImmutableArray<VexEvidenceInTotoSubject> Subjects { get; }
|
||||
public string PredicateType { get; }
|
||||
public VexEvidenceAttestationPredicate Predicate { get; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Subject of an evidence locker attestation.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceInTotoSubject(
|
||||
string Name,
|
||||
ImmutableDictionary<string, string> Digest);
|
||||
|
||||
/// <summary>
|
||||
/// Predicate for evidence locker attestations.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceAttestationPredicate
|
||||
{
|
||||
public VexEvidenceAttestationPredicate(
|
||||
string manifestId,
|
||||
string tenant,
|
||||
string merkleRoot,
|
||||
int itemCount,
|
||||
DateTimeOffset createdAt,
|
||||
ImmutableDictionary<string, string>? metadata = null)
|
||||
{
|
||||
ManifestId = EnsureNotNullOrWhiteSpace(manifestId, nameof(manifestId));
|
||||
Tenant = EnsureNotNullOrWhiteSpace(tenant, nameof(tenant));
|
||||
MerkleRoot = EnsureNotNullOrWhiteSpace(merkleRoot, nameof(merkleRoot));
|
||||
ItemCount = itemCount;
|
||||
CreatedAt = createdAt;
|
||||
Metadata = metadata ?? ImmutableDictionary<string, string>.Empty;
|
||||
}
|
||||
|
||||
public string ManifestId { get; }
|
||||
public string Tenant { get; }
|
||||
public string MerkleRoot { get; }
|
||||
public int ItemCount { get; }
|
||||
public DateTimeOffset CreatedAt { get; }
|
||||
public ImmutableDictionary<string, string> Metadata { get; }
|
||||
|
||||
public static VexEvidenceAttestationPredicate FromManifest(VexLockerManifest manifest)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(manifest);
|
||||
return new VexEvidenceAttestationPredicate(
|
||||
manifest.ManifestId,
|
||||
manifest.Tenant,
|
||||
manifest.MerkleRoot,
|
||||
manifest.Items.Length,
|
||||
manifest.CreatedAt,
|
||||
manifest.Metadata);
|
||||
}
|
||||
|
||||
private static string EnsureNotNullOrWhiteSpace(string value, string name)
|
||||
=> string.IsNullOrWhiteSpace(value) ? throw new ArgumentException($"{name} must be provided.", name) : value.Trim();
|
||||
}
|
||||
@@ -0,0 +1,127 @@
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Evidence;
|
||||
|
||||
/// <summary>
|
||||
/// Service interface for building evidence locker payloads and Merkle manifests.
|
||||
/// </summary>
|
||||
public interface IVexEvidenceLockerService
|
||||
{
|
||||
/// <summary>
|
||||
/// Creates an evidence snapshot item from an observation.
|
||||
/// </summary>
|
||||
VexEvidenceSnapshotItem CreateSnapshotItem(
|
||||
VexObservation observation,
|
||||
string linksetId,
|
||||
VexEvidenceProvenance? provenance = null);
|
||||
|
||||
/// <summary>
|
||||
/// Builds a locker manifest from a collection of observations.
|
||||
/// </summary>
|
||||
VexLockerManifest BuildManifest(
|
||||
string tenant,
|
||||
IEnumerable<VexObservation> observations,
|
||||
Func<VexObservation, string> linksetIdSelector,
|
||||
DateTimeOffset? timestamp = null,
|
||||
int sequence = 1,
|
||||
bool isSealed = false);
|
||||
|
||||
/// <summary>
|
||||
/// Builds a locker manifest from pre-built snapshot items.
|
||||
/// </summary>
|
||||
VexLockerManifest BuildManifest(
|
||||
string tenant,
|
||||
IEnumerable<VexEvidenceSnapshotItem> items,
|
||||
DateTimeOffset? timestamp = null,
|
||||
int sequence = 1,
|
||||
bool isSealed = false);
|
||||
|
||||
/// <summary>
|
||||
/// Verifies a manifest's Merkle root against its items.
|
||||
/// </summary>
|
||||
bool VerifyManifest(VexLockerManifest manifest);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Default implementation of <see cref="IVexEvidenceLockerService"/>.
|
||||
/// </summary>
|
||||
public sealed class VexEvidenceLockerService : IVexEvidenceLockerService
|
||||
{
|
||||
private readonly TimeProvider _timeProvider;
|
||||
|
||||
public VexEvidenceLockerService(TimeProvider? timeProvider = null)
|
||||
{
|
||||
_timeProvider = timeProvider ?? TimeProvider.System;
|
||||
}
|
||||
|
||||
public VexEvidenceSnapshotItem CreateSnapshotItem(
|
||||
VexObservation observation,
|
||||
string linksetId,
|
||||
VexEvidenceProvenance? provenance = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(observation);
|
||||
|
||||
if (string.IsNullOrWhiteSpace(linksetId))
|
||||
{
|
||||
throw new ArgumentException("linksetId must be provided.", nameof(linksetId));
|
||||
}
|
||||
|
||||
return new VexEvidenceSnapshotItem(
|
||||
observationId: observation.ObservationId,
|
||||
providerId: observation.ProviderId,
|
||||
contentHash: observation.Upstream.ContentHash,
|
||||
linksetId: linksetId,
|
||||
dsseEnvelopeHash: null, // Populated by OBS-54-001
|
||||
provenance: provenance ?? VexEvidenceProvenance.Empty);
|
||||
}
|
||||
|
||||
public VexLockerManifest BuildManifest(
|
||||
string tenant,
|
||||
IEnumerable<VexObservation> observations,
|
||||
Func<VexObservation, string> linksetIdSelector,
|
||||
DateTimeOffset? timestamp = null,
|
||||
int sequence = 1,
|
||||
bool isSealed = false)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(observations);
|
||||
ArgumentNullException.ThrowIfNull(linksetIdSelector);
|
||||
|
||||
var items = observations
|
||||
.Where(o => o is not null)
|
||||
.Select(o => CreateSnapshotItem(o, linksetIdSelector(o)))
|
||||
.ToList();
|
||||
|
||||
return BuildManifest(tenant, items, timestamp, sequence, isSealed);
|
||||
}
|
||||
|
||||
public VexLockerManifest BuildManifest(
|
||||
string tenant,
|
||||
IEnumerable<VexEvidenceSnapshotItem> items,
|
||||
DateTimeOffset? timestamp = null,
|
||||
int sequence = 1,
|
||||
bool isSealed = false)
|
||||
{
|
||||
var ts = timestamp ?? _timeProvider.GetUtcNow();
|
||||
var manifestId = VexLockerManifest.CreateManifestId(tenant, ts, sequence);
|
||||
|
||||
var metadata = isSealed
|
||||
? System.Collections.Immutable.ImmutableDictionary<string, string>.Empty.Add("sealed", "true")
|
||||
: System.Collections.Immutable.ImmutableDictionary<string, string>.Empty;
|
||||
|
||||
return new VexLockerManifest(
|
||||
tenant: tenant,
|
||||
manifestId: manifestId,
|
||||
createdAt: ts,
|
||||
items: items,
|
||||
signature: null,
|
||||
metadata: metadata);
|
||||
}
|
||||
|
||||
public bool VerifyManifest(VexLockerManifest manifest)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(manifest);
|
||||
|
||||
var expectedRoot = VexLockerManifest.ComputeMerkleRoot(manifest.Items);
|
||||
return string.Equals(manifest.MerkleRoot, expectedRoot, StringComparison.OrdinalIgnoreCase);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,299 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Evidence;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a single evidence item in a locker payload for sealed-mode auditing.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceSnapshotItem
|
||||
{
|
||||
public VexEvidenceSnapshotItem(
|
||||
string observationId,
|
||||
string providerId,
|
||||
string contentHash,
|
||||
string linksetId,
|
||||
string? dsseEnvelopeHash = null,
|
||||
VexEvidenceProvenance? provenance = null)
|
||||
{
|
||||
ObservationId = EnsureNotNullOrWhiteSpace(observationId, nameof(observationId));
|
||||
ProviderId = EnsureNotNullOrWhiteSpace(providerId, nameof(providerId)).ToLowerInvariant();
|
||||
ContentHash = EnsureNotNullOrWhiteSpace(contentHash, nameof(contentHash));
|
||||
LinksetId = EnsureNotNullOrWhiteSpace(linksetId, nameof(linksetId));
|
||||
DsseEnvelopeHash = TrimToNull(dsseEnvelopeHash);
|
||||
Provenance = provenance ?? VexEvidenceProvenance.Empty;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The observation ID this evidence corresponds to.
|
||||
/// </summary>
|
||||
[JsonPropertyName("observationId")]
|
||||
public string ObservationId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The provider that supplied this evidence.
|
||||
/// </summary>
|
||||
[JsonPropertyName("providerId")]
|
||||
public string ProviderId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// SHA-256 hash of the raw observation content.
|
||||
/// </summary>
|
||||
[JsonPropertyName("contentHash")]
|
||||
public string ContentHash { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The linkset ID this evidence relates to.
|
||||
/// </summary>
|
||||
[JsonPropertyName("linksetId")]
|
||||
public string LinksetId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Optional DSSE envelope hash when attestations are enabled.
|
||||
/// </summary>
|
||||
[JsonPropertyName("dsseEnvelopeHash")]
|
||||
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
|
||||
public string? DsseEnvelopeHash { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Provenance information for this evidence.
|
||||
/// </summary>
|
||||
[JsonPropertyName("provenance")]
|
||||
public VexEvidenceProvenance Provenance { get; }
|
||||
|
||||
private static string EnsureNotNullOrWhiteSpace(string value, string name)
|
||||
=> string.IsNullOrWhiteSpace(value) ? throw new ArgumentException($"{name} must be provided.", name) : value.Trim();
|
||||
|
||||
private static string? TrimToNull(string? value)
|
||||
=> string.IsNullOrWhiteSpace(value) ? null : value.Trim();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Provenance information for evidence items.
|
||||
/// </summary>
|
||||
public sealed record VexEvidenceProvenance
|
||||
{
|
||||
public static readonly VexEvidenceProvenance Empty = new("ingest", null, null);
|
||||
|
||||
public VexEvidenceProvenance(
|
||||
string source,
|
||||
int? mirrorGeneration = null,
|
||||
string? exportCenterManifest = null)
|
||||
{
|
||||
Source = EnsureNotNullOrWhiteSpace(source, nameof(source)).ToLowerInvariant();
|
||||
MirrorGeneration = mirrorGeneration;
|
||||
ExportCenterManifest = TrimToNull(exportCenterManifest);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Source type: "mirror" or "ingest".
|
||||
/// </summary>
|
||||
[JsonPropertyName("source")]
|
||||
public string Source { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Mirror generation number when source is "mirror".
|
||||
/// </summary>
|
||||
[JsonPropertyName("mirrorGeneration")]
|
||||
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
|
||||
public int? MirrorGeneration { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Export center manifest hash when available.
|
||||
/// </summary>
|
||||
[JsonPropertyName("exportCenterManifest")]
|
||||
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
|
||||
public string? ExportCenterManifest { get; }
|
||||
|
||||
private static string EnsureNotNullOrWhiteSpace(string value, string name)
|
||||
=> string.IsNullOrWhiteSpace(value) ? throw new ArgumentException($"{name} must be provided.", name) : value.Trim();
|
||||
|
||||
private static string? TrimToNull(string? value)
|
||||
=> string.IsNullOrWhiteSpace(value) ? null : value.Trim();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Locker manifest containing evidence snapshots with Merkle root for verification.
|
||||
/// </summary>
|
||||
public sealed record VexLockerManifest
|
||||
{
|
||||
public VexLockerManifest(
|
||||
string tenant,
|
||||
string manifestId,
|
||||
DateTimeOffset createdAt,
|
||||
IEnumerable<VexEvidenceSnapshotItem> items,
|
||||
string? signature = null,
|
||||
ImmutableDictionary<string, string>? metadata = null)
|
||||
{
|
||||
Tenant = EnsureNotNullOrWhiteSpace(tenant, nameof(tenant)).ToLowerInvariant();
|
||||
ManifestId = EnsureNotNullOrWhiteSpace(manifestId, nameof(manifestId));
|
||||
CreatedAt = createdAt.ToUniversalTime();
|
||||
Items = NormalizeItems(items);
|
||||
MerkleRoot = ComputeMerkleRoot(Items);
|
||||
Signature = TrimToNull(signature);
|
||||
Metadata = NormalizeMetadata(metadata);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Tenant this manifest belongs to.
|
||||
/// </summary>
|
||||
[JsonPropertyName("tenant")]
|
||||
public string Tenant { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Unique manifest identifier.
|
||||
/// </summary>
|
||||
[JsonPropertyName("manifestId")]
|
||||
public string ManifestId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// When this manifest was created.
|
||||
/// </summary>
|
||||
[JsonPropertyName("createdAt")]
|
||||
public DateTimeOffset CreatedAt { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Evidence items in deterministic order.
|
||||
/// </summary>
|
||||
[JsonPropertyName("items")]
|
||||
public ImmutableArray<VexEvidenceSnapshotItem> Items { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Merkle root computed over item content hashes.
|
||||
/// </summary>
|
||||
[JsonPropertyName("merkleRoot")]
|
||||
public string MerkleRoot { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Optional DSSE signature (populated by OBS-54-001).
|
||||
/// </summary>
|
||||
[JsonPropertyName("signature")]
|
||||
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
|
||||
public string? Signature { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Additional metadata (e.g., sealed mode flag).
|
||||
/// </summary>
|
||||
[JsonPropertyName("metadata")]
|
||||
public ImmutableDictionary<string, string> Metadata { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new manifest with an attached signature.
|
||||
/// </summary>
|
||||
public VexLockerManifest WithSignature(string signature)
|
||||
{
|
||||
return new VexLockerManifest(
|
||||
Tenant,
|
||||
ManifestId,
|
||||
CreatedAt,
|
||||
Items,
|
||||
signature,
|
||||
Metadata);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a deterministic manifest ID.
|
||||
/// </summary>
|
||||
public static string CreateManifestId(string tenant, DateTimeOffset timestamp, int sequence)
|
||||
{
|
||||
var normalizedTenant = (tenant ?? "default").Trim().ToLowerInvariant();
|
||||
var date = timestamp.ToUniversalTime().ToString("yyyy-MM-dd");
|
||||
return $"locker:excititor:{normalizedTenant}:{date}:{sequence:D4}";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Computes Merkle root from a list of hashes.
|
||||
/// </summary>
|
||||
public static string ComputeMerkleRoot(ImmutableArray<VexEvidenceSnapshotItem> items)
|
||||
{
|
||||
if (items.Length == 0)
|
||||
{
|
||||
return "sha256:" + Convert.ToHexString(SHA256.HashData(Array.Empty<byte>())).ToLowerInvariant();
|
||||
}
|
||||
|
||||
var hashes = items
|
||||
.Select(i => i.ContentHash.StartsWith("sha256:", StringComparison.OrdinalIgnoreCase)
|
||||
? i.ContentHash[7..]
|
||||
: i.ContentHash)
|
||||
.ToList();
|
||||
|
||||
return ComputeMerkleRootFromHashes(hashes);
|
||||
}
|
||||
|
||||
private static string ComputeMerkleRootFromHashes(List<string> hashes)
|
||||
{
|
||||
if (hashes.Count == 0)
|
||||
{
|
||||
return "sha256:" + Convert.ToHexString(SHA256.HashData(Array.Empty<byte>())).ToLowerInvariant();
|
||||
}
|
||||
|
||||
if (hashes.Count == 1)
|
||||
{
|
||||
return "sha256:" + hashes[0].ToLowerInvariant();
|
||||
}
|
||||
|
||||
// Pad to even number if necessary
|
||||
if (hashes.Count % 2 != 0)
|
||||
{
|
||||
hashes.Add(hashes[^1]);
|
||||
}
|
||||
|
||||
var nextLevel = new List<string>();
|
||||
for (var i = 0; i < hashes.Count; i += 2)
|
||||
{
|
||||
var combined = hashes[i].ToLowerInvariant() + hashes[i + 1].ToLowerInvariant();
|
||||
var bytes = Convert.FromHexString(combined);
|
||||
var hash = SHA256.HashData(bytes);
|
||||
nextLevel.Add(Convert.ToHexString(hash).ToLowerInvariant());
|
||||
}
|
||||
|
||||
return ComputeMerkleRootFromHashes(nextLevel);
|
||||
}
|
||||
|
||||
private static ImmutableArray<VexEvidenceSnapshotItem> NormalizeItems(IEnumerable<VexEvidenceSnapshotItem>? items)
|
||||
{
|
||||
if (items is null)
|
||||
{
|
||||
return ImmutableArray<VexEvidenceSnapshotItem>.Empty;
|
||||
}
|
||||
|
||||
// Sort by observationId, then providerId for deterministic ordering
|
||||
return items
|
||||
.Where(i => i is not null)
|
||||
.OrderBy(i => i.ObservationId, StringComparer.Ordinal)
|
||||
.ThenBy(i => i.ProviderId, StringComparer.OrdinalIgnoreCase)
|
||||
.ToImmutableArray();
|
||||
}
|
||||
|
||||
private static ImmutableDictionary<string, string> NormalizeMetadata(ImmutableDictionary<string, string>? metadata)
|
||||
{
|
||||
if (metadata is null || metadata.Count == 0)
|
||||
{
|
||||
return ImmutableDictionary<string, string>.Empty;
|
||||
}
|
||||
|
||||
var builder = ImmutableDictionary.CreateBuilder<string, string>(StringComparer.Ordinal);
|
||||
foreach (var pair in metadata.OrderBy(kv => kv.Key, StringComparer.Ordinal))
|
||||
{
|
||||
var key = TrimToNull(pair.Key);
|
||||
var value = TrimToNull(pair.Value);
|
||||
if (key is null || value is null)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
builder[key] = value;
|
||||
}
|
||||
|
||||
return builder.ToImmutable();
|
||||
}
|
||||
|
||||
private static string EnsureNotNullOrWhiteSpace(string value, string name)
|
||||
=> string.IsNullOrWhiteSpace(value) ? throw new ArgumentException($"{name} must be provided.", name) : value.Trim();
|
||||
|
||||
private static string? TrimToNull(string? value)
|
||||
=> string.IsNullOrWhiteSpace(value) ? null : value.Trim();
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
namespace StellaOps.Excititor.Core.Observations;
|
||||
|
||||
/// <summary>
|
||||
/// Publishes vex.linkset.updated events to downstream consumers.
|
||||
/// Implementations may persist to MongoDB, publish to NATS, or both.
|
||||
/// </summary>
|
||||
public interface IVexLinksetEventPublisher
|
||||
{
|
||||
/// <summary>
|
||||
/// Publishes a linkset updated event.
|
||||
/// </summary>
|
||||
Task PublishAsync(VexLinksetUpdatedEvent @event, CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Publishes multiple linkset updated events in a batch.
|
||||
/// </summary>
|
||||
Task PublishManyAsync(IEnumerable<VexLinksetUpdatedEvent> events, CancellationToken cancellationToken);
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
namespace StellaOps.Excititor.Core.Observations;
|
||||
|
||||
/// <summary>
|
||||
/// Persistence abstraction for VEX linksets with tenant-isolated operations.
|
||||
/// Linksets correlate observations and capture conflict annotations.
|
||||
/// </summary>
|
||||
public interface IVexLinksetStore
|
||||
{
|
||||
/// <summary>
|
||||
/// Persists a new linkset. Returns true if inserted, false if it already exists.
|
||||
/// </summary>
|
||||
ValueTask<bool> InsertAsync(
|
||||
VexLinkset linkset,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Persists or updates a linkset. Returns true if inserted, false if updated.
|
||||
/// </summary>
|
||||
ValueTask<bool> UpsertAsync(
|
||||
VexLinkset linkset,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves a linkset by tenant and linkset ID.
|
||||
/// </summary>
|
||||
ValueTask<VexLinkset?> GetByIdAsync(
|
||||
string tenant,
|
||||
string linksetId,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves or creates a linkset for the given vulnerability and product key.
|
||||
/// </summary>
|
||||
ValueTask<VexLinkset> GetOrCreateAsync(
|
||||
string tenant,
|
||||
string vulnerabilityId,
|
||||
string productKey,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Finds linksets by vulnerability ID.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<VexLinkset>> FindByVulnerabilityAsync(
|
||||
string tenant,
|
||||
string vulnerabilityId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Finds linksets by product key.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<VexLinkset>> FindByProductKeyAsync(
|
||||
string tenant,
|
||||
string productKey,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Finds linksets that have disagreements (conflicts).
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<VexLinkset>> FindWithConflictsAsync(
|
||||
string tenant,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Finds linksets by provider ID.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<VexLinkset>> FindByProviderAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Deletes a linkset by tenant and linkset ID. Returns true if deleted.
|
||||
/// </summary>
|
||||
ValueTask<bool> DeleteAsync(
|
||||
string tenant,
|
||||
string linksetId,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Returns the count of linksets for the specified tenant.
|
||||
/// </summary>
|
||||
ValueTask<long> CountAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Returns the count of linksets with conflicts for the specified tenant.
|
||||
/// </summary>
|
||||
ValueTask<long> CountWithConflictsAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken);
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
namespace StellaOps.Excititor.Core.Observations;
|
||||
|
||||
/// <summary>
|
||||
/// Persistence abstraction for VEX observations with tenant-isolated write operations.
|
||||
/// </summary>
|
||||
public interface IVexObservationStore
|
||||
{
|
||||
/// <summary>
|
||||
/// Persists a new observation. Returns true if inserted, false if it already exists.
|
||||
/// </summary>
|
||||
ValueTask<bool> InsertAsync(
|
||||
VexObservation observation,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Persists or updates an observation. Returns true if inserted, false if updated.
|
||||
/// </summary>
|
||||
ValueTask<bool> UpsertAsync(
|
||||
VexObservation observation,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Persists multiple observations in a batch. Returns the count of newly inserted observations.
|
||||
/// </summary>
|
||||
ValueTask<int> InsertManyAsync(
|
||||
string tenant,
|
||||
IEnumerable<VexObservation> observations,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves an observation by tenant and observation ID.
|
||||
/// </summary>
|
||||
ValueTask<VexObservation?> GetByIdAsync(
|
||||
string tenant,
|
||||
string observationId,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves observations for a specific vulnerability and product key.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<VexObservation>> FindByVulnerabilityAndProductAsync(
|
||||
string tenant,
|
||||
string vulnerabilityId,
|
||||
string productKey,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves observations by provider.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<VexObservation>> FindByProviderAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Deletes an observation by tenant and observation ID. Returns true if deleted.
|
||||
/// </summary>
|
||||
ValueTask<bool> DeleteAsync(
|
||||
string tenant,
|
||||
string observationId,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Returns the count of observations for the specified tenant.
|
||||
/// </summary>
|
||||
ValueTask<long> CountAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken);
|
||||
}
|
||||
@@ -0,0 +1,129 @@
|
||||
using System.Collections.Immutable;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Observations;
|
||||
|
||||
/// <summary>
|
||||
/// Service interface for emitting timeline events during ingest/linkset operations.
|
||||
/// Implementations should emit events asynchronously without blocking the main operation.
|
||||
/// </summary>
|
||||
public interface IVexTimelineEventEmitter
|
||||
{
|
||||
/// <summary>
|
||||
/// Emits a timeline event for an observation ingest operation.
|
||||
/// </summary>
|
||||
ValueTask EmitObservationIngestAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
string streamId,
|
||||
string traceId,
|
||||
string observationId,
|
||||
string evidenceHash,
|
||||
string justificationSummary,
|
||||
ImmutableDictionary<string, string>? attributes = null,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Emits a timeline event for a linkset update operation.
|
||||
/// </summary>
|
||||
ValueTask EmitLinksetUpdateAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
string streamId,
|
||||
string traceId,
|
||||
string linksetId,
|
||||
string vulnerabilityId,
|
||||
string productKey,
|
||||
string payloadHash,
|
||||
string justificationSummary,
|
||||
ImmutableDictionary<string, string>? attributes = null,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Emits a timeline event for a generic operation.
|
||||
/// </summary>
|
||||
ValueTask EmitAsync(
|
||||
TimelineEvent evt,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Emits multiple timeline events in a batch.
|
||||
/// </summary>
|
||||
ValueTask EmitBatchAsync(
|
||||
string tenant,
|
||||
IEnumerable<TimelineEvent> events,
|
||||
CancellationToken cancellationToken = default);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Well-known timeline event types for Excititor operations.
|
||||
/// </summary>
|
||||
public static class VexTimelineEventTypes
|
||||
{
|
||||
/// <summary>
|
||||
/// An observation was ingested.
|
||||
/// </summary>
|
||||
public const string ObservationIngested = "vex.observation.ingested";
|
||||
|
||||
/// <summary>
|
||||
/// An observation was updated.
|
||||
/// </summary>
|
||||
public const string ObservationUpdated = "vex.observation.updated";
|
||||
|
||||
/// <summary>
|
||||
/// An observation was superseded by another.
|
||||
/// </summary>
|
||||
public const string ObservationSuperseded = "vex.observation.superseded";
|
||||
|
||||
/// <summary>
|
||||
/// A linkset was created.
|
||||
/// </summary>
|
||||
public const string LinksetCreated = "vex.linkset.created";
|
||||
|
||||
/// <summary>
|
||||
/// A linkset was updated with new observations.
|
||||
/// </summary>
|
||||
public const string LinksetUpdated = "vex.linkset.updated";
|
||||
|
||||
/// <summary>
|
||||
/// A linkset conflict was detected.
|
||||
/// </summary>
|
||||
public const string LinksetConflictDetected = "vex.linkset.conflict_detected";
|
||||
|
||||
/// <summary>
|
||||
/// A linkset conflict was resolved.
|
||||
/// </summary>
|
||||
public const string LinksetConflictResolved = "vex.linkset.conflict_resolved";
|
||||
|
||||
/// <summary>
|
||||
/// Evidence was sealed to the locker.
|
||||
/// </summary>
|
||||
public const string EvidenceSealed = "vex.evidence.sealed";
|
||||
|
||||
/// <summary>
|
||||
/// An attestation was attached.
|
||||
/// </summary>
|
||||
public const string AttestationAttached = "vex.attestation.attached";
|
||||
|
||||
/// <summary>
|
||||
/// An attestation was verified.
|
||||
/// </summary>
|
||||
public const string AttestationVerified = "vex.attestation.verified";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Well-known attribute keys for timeline events.
|
||||
/// </summary>
|
||||
public static class VexTimelineEventAttributes
|
||||
{
|
||||
public const string ObservationId = "observation_id";
|
||||
public const string LinksetId = "linkset_id";
|
||||
public const string VulnerabilityId = "vulnerability_id";
|
||||
public const string ProductKey = "product_key";
|
||||
public const string Status = "status";
|
||||
public const string ConflictType = "conflict_type";
|
||||
public const string AttestationId = "attestation_id";
|
||||
public const string SupersededBy = "superseded_by";
|
||||
public const string Supersedes = "supersedes";
|
||||
public const string ObservationCount = "observation_count";
|
||||
public const string ConflictCount = "conflict_count";
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
namespace StellaOps.Excititor.Core.Observations;
|
||||
|
||||
/// <summary>
|
||||
/// Persistence abstraction for VEX timeline events.
|
||||
/// Timeline events capture ingest/linkset changes with trace IDs, justification summaries,
|
||||
/// and evidence hashes so downstream systems can replay raw facts chronologically.
|
||||
/// </summary>
|
||||
public interface IVexTimelineEventStore
|
||||
{
|
||||
/// <summary>
|
||||
/// Persists a new timeline event. Returns the event ID if successful.
|
||||
/// </summary>
|
||||
ValueTask<string> InsertAsync(
|
||||
TimelineEvent evt,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Persists multiple timeline events in a batch. Returns the count of successfully inserted events.
|
||||
/// </summary>
|
||||
ValueTask<int> InsertManyAsync(
|
||||
string tenant,
|
||||
IEnumerable<TimelineEvent> events,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves timeline events for a tenant within a time range.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<TimelineEvent>> FindByTimeRangeAsync(
|
||||
string tenant,
|
||||
DateTimeOffset from,
|
||||
DateTimeOffset to,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves timeline events by trace ID for correlation.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<TimelineEvent>> FindByTraceIdAsync(
|
||||
string tenant,
|
||||
string traceId,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves timeline events by provider ID.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<TimelineEvent>> FindByProviderAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves timeline events by event type.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<TimelineEvent>> FindByEventTypeAsync(
|
||||
string tenant,
|
||||
string eventType,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves the most recent timeline events for a tenant.
|
||||
/// </summary>
|
||||
ValueTask<IReadOnlyList<TimelineEvent>> GetRecentAsync(
|
||||
string tenant,
|
||||
int limit,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Retrieves a single timeline event by ID.
|
||||
/// </summary>
|
||||
ValueTask<TimelineEvent?> GetByIdAsync(
|
||||
string tenant,
|
||||
string eventId,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Returns the count of timeline events for the specified tenant.
|
||||
/// </summary>
|
||||
ValueTask<long> CountAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Returns the count of timeline events for the specified tenant within a time range.
|
||||
/// </summary>
|
||||
ValueTask<long> CountInRangeAsync(
|
||||
string tenant,
|
||||
DateTimeOffset from,
|
||||
DateTimeOffset to,
|
||||
CancellationToken cancellationToken);
|
||||
}
|
||||
@@ -0,0 +1,298 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Observations;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a VEX linkset correlating multiple observations for a specific
|
||||
/// vulnerability and product key. Linksets capture disagreements (conflicts)
|
||||
/// between providers without deciding a winner.
|
||||
/// </summary>
|
||||
public sealed record VexLinkset
|
||||
{
|
||||
public VexLinkset(
|
||||
string linksetId,
|
||||
string tenant,
|
||||
string vulnerabilityId,
|
||||
string productKey,
|
||||
IEnumerable<VexLinksetObservationRefModel> observations,
|
||||
IEnumerable<VexObservationDisagreement>? disagreements = null,
|
||||
DateTimeOffset? createdAt = null,
|
||||
DateTimeOffset? updatedAt = null)
|
||||
{
|
||||
LinksetId = VexObservation.EnsureNotNullOrWhiteSpace(linksetId, nameof(linksetId));
|
||||
Tenant = VexObservation.EnsureNotNullOrWhiteSpace(tenant, nameof(tenant)).ToLowerInvariant();
|
||||
VulnerabilityId = VexObservation.EnsureNotNullOrWhiteSpace(vulnerabilityId, nameof(vulnerabilityId));
|
||||
ProductKey = VexObservation.EnsureNotNullOrWhiteSpace(productKey, nameof(productKey));
|
||||
Observations = NormalizeObservations(observations);
|
||||
Disagreements = NormalizeDisagreements(disagreements);
|
||||
CreatedAt = (createdAt ?? DateTimeOffset.UtcNow).ToUniversalTime();
|
||||
UpdatedAt = (updatedAt ?? CreatedAt).ToUniversalTime();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Unique identifier for this linkset. Typically a SHA256 hash over
|
||||
/// (tenant, vulnerabilityId, productKey) for deterministic addressing.
|
||||
/// </summary>
|
||||
public string LinksetId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Tenant identifier (normalized to lowercase).
|
||||
/// </summary>
|
||||
public string Tenant { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The vulnerability identifier (CVE, GHSA, vendor ID).
|
||||
/// </summary>
|
||||
public string VulnerabilityId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Product key (typically a PURL or CPE).
|
||||
/// </summary>
|
||||
public string ProductKey { get; }
|
||||
|
||||
/// <summary>
|
||||
/// References to observations that contribute to this linkset.
|
||||
/// </summary>
|
||||
public ImmutableArray<VexLinksetObservationRefModel> Observations { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Conflict annotations capturing disagreements between providers.
|
||||
/// </summary>
|
||||
public ImmutableArray<VexObservationDisagreement> Disagreements { get; }
|
||||
|
||||
/// <summary>
|
||||
/// When this linkset was first created.
|
||||
/// </summary>
|
||||
public DateTimeOffset CreatedAt { get; }
|
||||
|
||||
/// <summary>
|
||||
/// When this linkset was last updated.
|
||||
/// </summary>
|
||||
public DateTimeOffset UpdatedAt { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Distinct provider IDs contributing to this linkset.
|
||||
/// </summary>
|
||||
public IReadOnlyList<string> ProviderIds =>
|
||||
Observations.Select(o => o.ProviderId)
|
||||
.Distinct(StringComparer.OrdinalIgnoreCase)
|
||||
.OrderBy(p => p, StringComparer.OrdinalIgnoreCase)
|
||||
.ToList();
|
||||
|
||||
/// <summary>
|
||||
/// Distinct statuses observed in this linkset.
|
||||
/// </summary>
|
||||
public IReadOnlyList<string> Statuses =>
|
||||
Observations.Select(o => o.Status)
|
||||
.Distinct(StringComparer.OrdinalIgnoreCase)
|
||||
.OrderBy(s => s, StringComparer.OrdinalIgnoreCase)
|
||||
.ToList();
|
||||
|
||||
/// <summary>
|
||||
/// Whether this linkset contains disagreements (conflicts).
|
||||
/// </summary>
|
||||
public bool HasConflicts => !Disagreements.IsDefaultOrEmpty && Disagreements.Length > 0;
|
||||
|
||||
/// <summary>
|
||||
/// Confidence level based on the linkset state.
|
||||
/// </summary>
|
||||
public VexLinksetConfidence Confidence
|
||||
{
|
||||
get
|
||||
{
|
||||
if (HasConflicts)
|
||||
{
|
||||
return VexLinksetConfidence.Low;
|
||||
}
|
||||
|
||||
if (Observations.Length == 0)
|
||||
{
|
||||
return VexLinksetConfidence.Low;
|
||||
}
|
||||
|
||||
var distinctStatuses = Statuses.Count;
|
||||
if (distinctStatuses > 1)
|
||||
{
|
||||
return VexLinksetConfidence.Low;
|
||||
}
|
||||
|
||||
var distinctProviders = ProviderIds.Count;
|
||||
if (distinctProviders >= 2)
|
||||
{
|
||||
return VexLinksetConfidence.High;
|
||||
}
|
||||
|
||||
return VexLinksetConfidence.Medium;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a deterministic linkset ID from key components.
|
||||
/// </summary>
|
||||
public static string CreateLinksetId(string tenant, string vulnerabilityId, string productKey)
|
||||
{
|
||||
var normalizedTenant = (tenant ?? string.Empty).Trim().ToLowerInvariant();
|
||||
var normalizedVuln = (vulnerabilityId ?? string.Empty).Trim();
|
||||
var normalizedProduct = (productKey ?? string.Empty).Trim();
|
||||
|
||||
var input = $"{normalizedTenant}|{normalizedVuln}|{normalizedProduct}";
|
||||
var hash = SHA256.HashData(Encoding.UTF8.GetBytes(input));
|
||||
return $"sha256:{Convert.ToHexString(hash).ToLowerInvariant()}";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new linkset with updated observations and recomputed disagreements.
|
||||
/// </summary>
|
||||
public VexLinkset WithObservations(
|
||||
IEnumerable<VexLinksetObservationRefModel> observations,
|
||||
IEnumerable<VexObservationDisagreement>? disagreements = null)
|
||||
{
|
||||
return new VexLinkset(
|
||||
LinksetId,
|
||||
Tenant,
|
||||
VulnerabilityId,
|
||||
ProductKey,
|
||||
observations,
|
||||
disagreements,
|
||||
CreatedAt,
|
||||
DateTimeOffset.UtcNow);
|
||||
}
|
||||
|
||||
private static ImmutableArray<VexLinksetObservationRefModel> NormalizeObservations(
|
||||
IEnumerable<VexLinksetObservationRefModel>? observations)
|
||||
{
|
||||
if (observations is null)
|
||||
{
|
||||
return ImmutableArray<VexLinksetObservationRefModel>.Empty;
|
||||
}
|
||||
|
||||
var set = new SortedSet<VexLinksetObservationRefModel>(VexLinksetObservationRefComparer.Instance);
|
||||
foreach (var item in observations)
|
||||
{
|
||||
if (item is null)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
var obsId = VexObservation.TrimToNull(item.ObservationId);
|
||||
var provider = VexObservation.TrimToNull(item.ProviderId);
|
||||
var status = VexObservation.TrimToNull(item.Status);
|
||||
if (obsId is null || provider is null || status is null)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
double? clamped = item.Confidence is null ? null : Math.Clamp(item.Confidence.Value, 0.0, 1.0);
|
||||
set.Add(new VexLinksetObservationRefModel(obsId, provider, status, clamped));
|
||||
}
|
||||
|
||||
return set.Count == 0 ? ImmutableArray<VexLinksetObservationRefModel>.Empty : set.ToImmutableArray();
|
||||
}
|
||||
|
||||
private static ImmutableArray<VexObservationDisagreement> NormalizeDisagreements(
|
||||
IEnumerable<VexObservationDisagreement>? disagreements)
|
||||
{
|
||||
if (disagreements is null)
|
||||
{
|
||||
return ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
}
|
||||
|
||||
var set = new SortedSet<VexObservationDisagreement>(DisagreementComparer.Instance);
|
||||
foreach (var disagreement in disagreements)
|
||||
{
|
||||
if (disagreement is null)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
var normalizedProvider = VexObservation.TrimToNull(disagreement.ProviderId);
|
||||
var normalizedStatus = VexObservation.TrimToNull(disagreement.Status);
|
||||
|
||||
if (normalizedProvider is null || normalizedStatus is null)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
var normalizedJustification = VexObservation.TrimToNull(disagreement.Justification);
|
||||
double? clampedConfidence = disagreement.Confidence is null
|
||||
? null
|
||||
: Math.Clamp(disagreement.Confidence.Value, 0.0, 1.0);
|
||||
|
||||
set.Add(new VexObservationDisagreement(
|
||||
normalizedProvider,
|
||||
normalizedStatus,
|
||||
normalizedJustification,
|
||||
clampedConfidence));
|
||||
}
|
||||
|
||||
return set.Count == 0 ? ImmutableArray<VexObservationDisagreement>.Empty : set.ToImmutableArray();
|
||||
}
|
||||
|
||||
private sealed class DisagreementComparer : IComparer<VexObservationDisagreement>
|
||||
{
|
||||
public static readonly DisagreementComparer Instance = new();
|
||||
|
||||
public int Compare(VexObservationDisagreement? x, VexObservationDisagreement? y)
|
||||
{
|
||||
if (ReferenceEquals(x, y))
|
||||
{
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (x is null)
|
||||
{
|
||||
return -1;
|
||||
}
|
||||
|
||||
if (y is null)
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
|
||||
var providerCompare = StringComparer.OrdinalIgnoreCase.Compare(x.ProviderId, y.ProviderId);
|
||||
if (providerCompare != 0)
|
||||
{
|
||||
return providerCompare;
|
||||
}
|
||||
|
||||
var statusCompare = StringComparer.OrdinalIgnoreCase.Compare(x.Status, y.Status);
|
||||
if (statusCompare != 0)
|
||||
{
|
||||
return statusCompare;
|
||||
}
|
||||
|
||||
var justificationCompare = StringComparer.OrdinalIgnoreCase.Compare(
|
||||
x.Justification ?? string.Empty,
|
||||
y.Justification ?? string.Empty);
|
||||
if (justificationCompare != 0)
|
||||
{
|
||||
return justificationCompare;
|
||||
}
|
||||
|
||||
return Nullable.Compare(x.Confidence, y.Confidence);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Confidence level for a linkset based on agreement between providers.
|
||||
/// </summary>
|
||||
public enum VexLinksetConfidence
|
||||
{
|
||||
/// <summary>
|
||||
/// Low confidence: conflicts exist or insufficient observations.
|
||||
/// </summary>
|
||||
Low,
|
||||
|
||||
/// <summary>
|
||||
/// Medium confidence: single provider or consistent observations.
|
||||
/// </summary>
|
||||
Medium,
|
||||
|
||||
/// <summary>
|
||||
/// High confidence: multiple providers agree.
|
||||
/// </summary>
|
||||
High
|
||||
}
|
||||
@@ -0,0 +1,221 @@
|
||||
using System.Collections.Immutable;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Observations;
|
||||
|
||||
/// <summary>
|
||||
/// Computes disagreements (conflicts) from VEX observations without choosing winners.
|
||||
/// Excititor remains aggregation-only; downstream consumers use disagreements to highlight
|
||||
/// conflicts and apply their own decision rules (AOC-19-002).
|
||||
/// </summary>
|
||||
public sealed class VexLinksetDisagreementService
|
||||
{
|
||||
/// <summary>
|
||||
/// Analyzes observations and returns disagreements where providers report different
|
||||
/// statuses or justifications for the same vulnerability/product combination.
|
||||
/// </summary>
|
||||
public ImmutableArray<VexObservationDisagreement> ComputeDisagreements(
|
||||
IEnumerable<VexObservation> observations)
|
||||
{
|
||||
if (observations is null)
|
||||
{
|
||||
return ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
}
|
||||
|
||||
var observationList = observations
|
||||
.Where(o => o is not null)
|
||||
.ToList();
|
||||
|
||||
if (observationList.Count < 2)
|
||||
{
|
||||
return ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
}
|
||||
|
||||
// Group by (vulnerabilityId, productKey)
|
||||
var groups = observationList
|
||||
.SelectMany(obs => obs.Statements.Select(stmt => (obs, stmt)))
|
||||
.GroupBy(x => new
|
||||
{
|
||||
VulnerabilityId = Normalize(x.stmt.VulnerabilityId),
|
||||
ProductKey = Normalize(x.stmt.ProductKey)
|
||||
});
|
||||
|
||||
var disagreements = new List<VexObservationDisagreement>();
|
||||
|
||||
foreach (var group in groups)
|
||||
{
|
||||
var groupDisagreements = DetectGroupDisagreements(group.ToList());
|
||||
disagreements.AddRange(groupDisagreements);
|
||||
}
|
||||
|
||||
return disagreements
|
||||
.Distinct(DisagreementComparer.Instance)
|
||||
.OrderBy(d => d.ProviderId, StringComparer.OrdinalIgnoreCase)
|
||||
.ThenBy(d => d.Status, StringComparer.OrdinalIgnoreCase)
|
||||
.ToImmutableArray();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Analyzes observations for a specific linkset and returns disagreements.
|
||||
/// </summary>
|
||||
public ImmutableArray<VexObservationDisagreement> ComputeDisagreementsForLinkset(
|
||||
IEnumerable<VexLinksetObservationRefModel> observationRefs)
|
||||
{
|
||||
if (observationRefs is null)
|
||||
{
|
||||
return ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
}
|
||||
|
||||
var refList = observationRefs
|
||||
.Where(r => r is not null)
|
||||
.ToList();
|
||||
|
||||
if (refList.Count < 2)
|
||||
{
|
||||
return ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
}
|
||||
|
||||
// Group by status to detect conflicts
|
||||
var statusGroups = refList
|
||||
.GroupBy(r => Normalize(r.Status))
|
||||
.ToDictionary(g => g.Key, g => g.ToList(), StringComparer.OrdinalIgnoreCase);
|
||||
|
||||
if (statusGroups.Count <= 1)
|
||||
{
|
||||
// All providers agree on status
|
||||
return ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
}
|
||||
|
||||
// Multiple statuses = disagreement
|
||||
// Generate disagreement entries for each provider-status combination
|
||||
var disagreements = refList
|
||||
.Select(r => new VexObservationDisagreement(
|
||||
providerId: r.ProviderId,
|
||||
status: r.Status,
|
||||
justification: null,
|
||||
confidence: ComputeConfidence(r.Status, statusGroups)))
|
||||
.Distinct(DisagreementComparer.Instance)
|
||||
.OrderBy(d => d.ProviderId, StringComparer.OrdinalIgnoreCase)
|
||||
.ThenBy(d => d.Status, StringComparer.OrdinalIgnoreCase)
|
||||
.ToImmutableArray();
|
||||
|
||||
return disagreements;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Updates a linkset with computed disagreements based on its observations.
|
||||
/// Returns a new linkset with updated disagreements.
|
||||
/// </summary>
|
||||
public VexLinkset UpdateLinksetDisagreements(VexLinkset linkset)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(linkset);
|
||||
|
||||
var disagreements = ComputeDisagreementsForLinkset(linkset.Observations);
|
||||
|
||||
return linkset.WithObservations(
|
||||
linkset.Observations,
|
||||
disagreements);
|
||||
}
|
||||
|
||||
private static IEnumerable<VexObservationDisagreement> DetectGroupDisagreements(
|
||||
List<(VexObservation obs, VexObservationStatement stmt)> group)
|
||||
{
|
||||
if (group.Count < 2)
|
||||
{
|
||||
yield break;
|
||||
}
|
||||
|
||||
// Group by provider to get unique provider perspectives
|
||||
var byProvider = group
|
||||
.GroupBy(x => Normalize(x.obs.ProviderId))
|
||||
.Select(g => new
|
||||
{
|
||||
ProviderId = g.Key,
|
||||
Status = Normalize(g.First().stmt.Status.ToString()),
|
||||
Justification = g.First().stmt.Justification?.ToString()
|
||||
})
|
||||
.ToList();
|
||||
|
||||
// Count status frequencies
|
||||
var statusCounts = byProvider
|
||||
.GroupBy(p => p.Status, StringComparer.OrdinalIgnoreCase)
|
||||
.ToDictionary(g => g.Key, g => g.Count(), StringComparer.OrdinalIgnoreCase);
|
||||
|
||||
// If all providers agree on status, no disagreement
|
||||
if (statusCounts.Count <= 1)
|
||||
{
|
||||
yield break;
|
||||
}
|
||||
|
||||
// Multiple statuses = disagreement
|
||||
// Report each provider's position as a disagreement
|
||||
var totalProviders = byProvider.Count;
|
||||
|
||||
foreach (var provider in byProvider)
|
||||
{
|
||||
var statusCount = statusCounts[provider.Status];
|
||||
var confidence = (double)statusCount / totalProviders;
|
||||
|
||||
yield return new VexObservationDisagreement(
|
||||
providerId: provider.ProviderId,
|
||||
status: provider.Status,
|
||||
justification: provider.Justification,
|
||||
confidence: confidence);
|
||||
}
|
||||
}
|
||||
|
||||
private static double ComputeConfidence(
|
||||
string status,
|
||||
Dictionary<string, List<VexLinksetObservationRefModel>> statusGroups)
|
||||
{
|
||||
var totalCount = statusGroups.Values.Sum(g => g.Count);
|
||||
if (totalCount == 0)
|
||||
{
|
||||
return 0.0;
|
||||
}
|
||||
|
||||
if (statusGroups.TryGetValue(status, out var group))
|
||||
{
|
||||
return (double)group.Count / totalCount;
|
||||
}
|
||||
|
||||
return 0.0;
|
||||
}
|
||||
|
||||
private static string Normalize(string value)
|
||||
{
|
||||
return string.IsNullOrWhiteSpace(value)
|
||||
? string.Empty
|
||||
: value.Trim().ToLowerInvariant();
|
||||
}
|
||||
|
||||
private sealed class DisagreementComparer : IEqualityComparer<VexObservationDisagreement>
|
||||
{
|
||||
public static readonly DisagreementComparer Instance = new();
|
||||
|
||||
public bool Equals(VexObservationDisagreement? x, VexObservationDisagreement? y)
|
||||
{
|
||||
if (ReferenceEquals(x, y))
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
if (x is null || y is null)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
return string.Equals(x.ProviderId, y.ProviderId, StringComparison.OrdinalIgnoreCase)
|
||||
&& string.Equals(x.Status, y.Status, StringComparison.OrdinalIgnoreCase)
|
||||
&& string.Equals(x.Justification, y.Justification, StringComparison.OrdinalIgnoreCase);
|
||||
}
|
||||
|
||||
public int GetHashCode(VexObservationDisagreement obj)
|
||||
{
|
||||
var hash = new HashCode();
|
||||
hash.Add(obj.ProviderId, StringComparer.OrdinalIgnoreCase);
|
||||
hash.Add(obj.Status, StringComparer.OrdinalIgnoreCase);
|
||||
hash.Add(obj.Justification, StringComparer.OrdinalIgnoreCase);
|
||||
return hash.ToHashCode();
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,418 @@
|
||||
using System;
|
||||
using System.Collections.Immutable;
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
|
||||
namespace StellaOps.Excititor.Core.Orchestration;
|
||||
|
||||
/// <summary>
|
||||
/// Client interface for the orchestrator worker SDK.
|
||||
/// Emits heartbeats, progress, and artifact hashes for deterministic, restartable ingestion.
|
||||
/// </summary>
|
||||
public interface IVexWorkerOrchestratorClient
|
||||
{
|
||||
/// <summary>
|
||||
/// Creates a new job context for a provider run.
|
||||
/// </summary>
|
||||
ValueTask<VexWorkerJobContext> StartJobAsync(
|
||||
string tenant,
|
||||
string connectorId,
|
||||
string? checkpoint,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Emits a heartbeat for the given job.
|
||||
/// </summary>
|
||||
ValueTask SendHeartbeatAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerHeartbeat heartbeat,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Records an artifact produced during the job.
|
||||
/// </summary>
|
||||
ValueTask RecordArtifactAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerArtifact artifact,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Marks the job as completed successfully.
|
||||
/// </summary>
|
||||
ValueTask CompleteJobAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerJobResult result,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Marks the job as failed.
|
||||
/// </summary>
|
||||
ValueTask FailJobAsync(
|
||||
VexWorkerJobContext context,
|
||||
string errorCode,
|
||||
string? errorMessage,
|
||||
int? retryAfterSeconds,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Marks the job as failed with a classified error.
|
||||
/// </summary>
|
||||
ValueTask FailJobAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerError error,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Polls for pending commands from the orchestrator.
|
||||
/// </summary>
|
||||
ValueTask<VexWorkerCommand?> GetPendingCommandAsync(
|
||||
VexWorkerJobContext context,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Acknowledges that a command has been processed.
|
||||
/// </summary>
|
||||
ValueTask AcknowledgeCommandAsync(
|
||||
VexWorkerJobContext context,
|
||||
long commandSequence,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Saves a checkpoint for resumable ingestion.
|
||||
/// </summary>
|
||||
ValueTask SaveCheckpointAsync(
|
||||
VexWorkerJobContext context,
|
||||
VexWorkerCheckpoint checkpoint,
|
||||
CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Loads the most recent checkpoint for a connector.
|
||||
/// </summary>
|
||||
ValueTask<VexWorkerCheckpoint?> LoadCheckpointAsync(
|
||||
string connectorId,
|
||||
CancellationToken cancellationToken = default);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Context for an active worker job.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerJobContext
|
||||
{
|
||||
public VexWorkerJobContext(
|
||||
string tenant,
|
||||
string connectorId,
|
||||
Guid runId,
|
||||
string? checkpoint,
|
||||
DateTimeOffset startedAt)
|
||||
{
|
||||
Tenant = EnsureNotNullOrWhiteSpace(tenant, nameof(tenant));
|
||||
ConnectorId = EnsureNotNullOrWhiteSpace(connectorId, nameof(connectorId));
|
||||
RunId = runId;
|
||||
Checkpoint = checkpoint?.Trim();
|
||||
StartedAt = startedAt;
|
||||
}
|
||||
|
||||
public string Tenant { get; }
|
||||
public string ConnectorId { get; }
|
||||
public Guid RunId { get; }
|
||||
public string? Checkpoint { get; }
|
||||
public DateTimeOffset StartedAt { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Current sequence number for heartbeats.
|
||||
/// </summary>
|
||||
public long Sequence { get; private set; }
|
||||
|
||||
/// <summary>
|
||||
/// Increments and returns the next sequence number.
|
||||
/// </summary>
|
||||
public long NextSequence() => ++Sequence;
|
||||
|
||||
private static string EnsureNotNullOrWhiteSpace(string value, string name)
|
||||
=> string.IsNullOrWhiteSpace(value) ? throw new ArgumentException($"{name} must be provided.", name) : value.Trim();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Heartbeat status for orchestrator reporting.
|
||||
/// </summary>
|
||||
public enum VexWorkerHeartbeatStatus
|
||||
{
|
||||
Starting,
|
||||
Running,
|
||||
Paused,
|
||||
Throttled,
|
||||
Backfill,
|
||||
Failed,
|
||||
Succeeded
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Heartbeat payload for orchestrator.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerHeartbeat(
|
||||
VexWorkerHeartbeatStatus Status,
|
||||
int? Progress,
|
||||
int? QueueDepth,
|
||||
string? LastArtifactHash,
|
||||
string? LastArtifactKind,
|
||||
string? ErrorCode,
|
||||
int? RetryAfterSeconds);
|
||||
|
||||
/// <summary>
|
||||
/// Artifact produced during ingestion.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerArtifact(
|
||||
string Hash,
|
||||
string Kind,
|
||||
string? ProviderId,
|
||||
string? DocumentId,
|
||||
DateTimeOffset CreatedAt,
|
||||
ImmutableDictionary<string, string>? Metadata = null);
|
||||
|
||||
/// <summary>
|
||||
/// Result of a completed worker job.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerJobResult(
|
||||
int DocumentsProcessed,
|
||||
int ClaimsGenerated,
|
||||
string? LastCheckpoint,
|
||||
string? LastArtifactHash,
|
||||
DateTimeOffset CompletedAt,
|
||||
ImmutableDictionary<string, string>? Metadata = null);
|
||||
|
||||
/// <summary>
|
||||
/// Commands issued by the orchestrator to control worker behavior.
|
||||
/// </summary>
|
||||
public enum VexWorkerCommandKind
|
||||
{
|
||||
/// <summary>
|
||||
/// Continue normal processing.
|
||||
/// </summary>
|
||||
Continue,
|
||||
|
||||
/// <summary>
|
||||
/// Pause processing until resumed.
|
||||
/// </summary>
|
||||
Pause,
|
||||
|
||||
/// <summary>
|
||||
/// Resume after a pause.
|
||||
/// </summary>
|
||||
Resume,
|
||||
|
||||
/// <summary>
|
||||
/// Apply throttling constraints.
|
||||
/// </summary>
|
||||
Throttle,
|
||||
|
||||
/// <summary>
|
||||
/// Retry the current operation.
|
||||
/// </summary>
|
||||
Retry,
|
||||
|
||||
/// <summary>
|
||||
/// Abort the current job.
|
||||
/// </summary>
|
||||
Abort
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Command received from the orchestrator.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerCommand(
|
||||
VexWorkerCommandKind Kind,
|
||||
long Sequence,
|
||||
DateTimeOffset IssuedAt,
|
||||
DateTimeOffset? ExpiresAt,
|
||||
VexWorkerThrottleParams? Throttle,
|
||||
string? Reason);
|
||||
|
||||
/// <summary>
|
||||
/// Throttle parameters issued with a throttle command.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerThrottleParams(
|
||||
int? RequestsPerMinute,
|
||||
int? BurstLimit,
|
||||
int? CooldownSeconds);
|
||||
|
||||
/// <summary>
|
||||
/// Classification of errors for orchestrator reporting.
|
||||
/// </summary>
|
||||
public enum VexWorkerErrorCategory
|
||||
{
|
||||
/// <summary>
|
||||
/// Unknown or unclassified error.
|
||||
/// </summary>
|
||||
Unknown,
|
||||
|
||||
/// <summary>
|
||||
/// Transient network or connectivity issues.
|
||||
/// </summary>
|
||||
Network,
|
||||
|
||||
/// <summary>
|
||||
/// Authentication or authorization failure.
|
||||
/// </summary>
|
||||
Authorization,
|
||||
|
||||
/// <summary>
|
||||
/// Rate limiting or throttling by upstream.
|
||||
/// </summary>
|
||||
RateLimited,
|
||||
|
||||
/// <summary>
|
||||
/// Invalid or malformed data from upstream.
|
||||
/// </summary>
|
||||
DataFormat,
|
||||
|
||||
/// <summary>
|
||||
/// Upstream service unavailable.
|
||||
/// </summary>
|
||||
ServiceUnavailable,
|
||||
|
||||
/// <summary>
|
||||
/// Internal processing error.
|
||||
/// </summary>
|
||||
Internal,
|
||||
|
||||
/// <summary>
|
||||
/// Configuration or setup error.
|
||||
/// </summary>
|
||||
Configuration,
|
||||
|
||||
/// <summary>
|
||||
/// Operation cancelled.
|
||||
/// </summary>
|
||||
Cancelled,
|
||||
|
||||
/// <summary>
|
||||
/// Operation timed out.
|
||||
/// </summary>
|
||||
Timeout
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Classified error for orchestrator reporting.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerError
|
||||
{
|
||||
public VexWorkerError(
|
||||
string code,
|
||||
VexWorkerErrorCategory category,
|
||||
string message,
|
||||
bool retryable,
|
||||
int? retryAfterSeconds = null,
|
||||
string? stage = null,
|
||||
ImmutableDictionary<string, string>? details = null)
|
||||
{
|
||||
Code = code ?? throw new ArgumentNullException(nameof(code));
|
||||
Category = category;
|
||||
Message = message ?? string.Empty;
|
||||
Retryable = retryable;
|
||||
RetryAfterSeconds = retryAfterSeconds;
|
||||
Stage = stage;
|
||||
Details = details ?? ImmutableDictionary<string, string>.Empty;
|
||||
}
|
||||
|
||||
public string Code { get; }
|
||||
public VexWorkerErrorCategory Category { get; }
|
||||
public string Message { get; }
|
||||
public bool Retryable { get; }
|
||||
public int? RetryAfterSeconds { get; }
|
||||
public string? Stage { get; }
|
||||
public ImmutableDictionary<string, string> Details { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Creates a transient network error.
|
||||
/// </summary>
|
||||
public static VexWorkerError Network(string message, int? retryAfterSeconds = 30)
|
||||
=> new("NETWORK_ERROR", VexWorkerErrorCategory.Network, message, retryable: true, retryAfterSeconds);
|
||||
|
||||
/// <summary>
|
||||
/// Creates an authorization error.
|
||||
/// </summary>
|
||||
public static VexWorkerError Authorization(string message)
|
||||
=> new("AUTH_ERROR", VexWorkerErrorCategory.Authorization, message, retryable: false);
|
||||
|
||||
/// <summary>
|
||||
/// Creates a rate-limited error.
|
||||
/// </summary>
|
||||
public static VexWorkerError RateLimited(string message, int retryAfterSeconds)
|
||||
=> new("RATE_LIMITED", VexWorkerErrorCategory.RateLimited, message, retryable: true, retryAfterSeconds);
|
||||
|
||||
/// <summary>
|
||||
/// Creates a service unavailable error.
|
||||
/// </summary>
|
||||
public static VexWorkerError ServiceUnavailable(string message, int? retryAfterSeconds = 60)
|
||||
=> new("SERVICE_UNAVAILABLE", VexWorkerErrorCategory.ServiceUnavailable, message, retryable: true, retryAfterSeconds);
|
||||
|
||||
/// <summary>
|
||||
/// Creates a data format error.
|
||||
/// </summary>
|
||||
public static VexWorkerError DataFormat(string message)
|
||||
=> new("DATA_FORMAT_ERROR", VexWorkerErrorCategory.DataFormat, message, retryable: false);
|
||||
|
||||
/// <summary>
|
||||
/// Creates an internal error.
|
||||
/// </summary>
|
||||
public static VexWorkerError Internal(string message)
|
||||
=> new("INTERNAL_ERROR", VexWorkerErrorCategory.Internal, message, retryable: false);
|
||||
|
||||
/// <summary>
|
||||
/// Creates a timeout error.
|
||||
/// </summary>
|
||||
public static VexWorkerError Timeout(string message, int? retryAfterSeconds = 30)
|
||||
=> new("TIMEOUT", VexWorkerErrorCategory.Timeout, message, retryable: true, retryAfterSeconds);
|
||||
|
||||
/// <summary>
|
||||
/// Creates a cancelled error.
|
||||
/// </summary>
|
||||
public static VexWorkerError Cancelled(string message)
|
||||
=> new("CANCELLED", VexWorkerErrorCategory.Cancelled, message, retryable: false);
|
||||
|
||||
/// <summary>
|
||||
/// Classifies an exception into an appropriate error.
|
||||
/// </summary>
|
||||
public static VexWorkerError FromException(Exception ex, string? stage = null)
|
||||
{
|
||||
return ex switch
|
||||
{
|
||||
OperationCanceledException => Cancelled(ex.Message),
|
||||
TimeoutException => Timeout(ex.Message),
|
||||
System.Net.Http.HttpRequestException httpEx when httpEx.StatusCode == System.Net.HttpStatusCode.TooManyRequests
|
||||
=> RateLimited(ex.Message, 60),
|
||||
System.Net.Http.HttpRequestException httpEx when httpEx.StatusCode == System.Net.HttpStatusCode.Unauthorized
|
||||
|| httpEx.StatusCode == System.Net.HttpStatusCode.Forbidden
|
||||
=> Authorization(ex.Message),
|
||||
System.Net.Http.HttpRequestException httpEx when httpEx.StatusCode == System.Net.HttpStatusCode.ServiceUnavailable
|
||||
|| httpEx.StatusCode == System.Net.HttpStatusCode.BadGateway
|
||||
|| httpEx.StatusCode == System.Net.HttpStatusCode.GatewayTimeout
|
||||
=> ServiceUnavailable(ex.Message),
|
||||
System.Net.Http.HttpRequestException => Network(ex.Message),
|
||||
System.Net.Sockets.SocketException => Network(ex.Message),
|
||||
System.IO.IOException => Network(ex.Message),
|
||||
System.Text.Json.JsonException => DataFormat(ex.Message),
|
||||
FormatException => DataFormat(ex.Message),
|
||||
InvalidOperationException => Internal(ex.Message),
|
||||
_ => new VexWorkerError("UNKNOWN_ERROR", VexWorkerErrorCategory.Unknown, ex.Message, retryable: false, stage: stage)
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Checkpoint state for resumable ingestion.
|
||||
/// </summary>
|
||||
public sealed record VexWorkerCheckpoint(
|
||||
string ConnectorId,
|
||||
string? Cursor,
|
||||
DateTimeOffset? LastProcessedAt,
|
||||
ImmutableArray<string> ProcessedDigests,
|
||||
ImmutableDictionary<string, string> ResumeTokens)
|
||||
{
|
||||
public static VexWorkerCheckpoint Empty(string connectorId) => new(
|
||||
connectorId,
|
||||
Cursor: null,
|
||||
LastProcessedAt: null,
|
||||
ProcessedDigests: ImmutableArray<string>.Empty,
|
||||
ResumeTokens: ImmutableDictionary<string, string>.Empty);
|
||||
}
|
||||
@@ -124,7 +124,16 @@ public sealed class OpenVexExporter : IVexExporter
|
||||
SourceUri: source.DocumentSource.ToString(),
|
||||
Detail: source.Detail,
|
||||
FirstObserved: source.FirstSeen.UtcDateTime.ToString("O", CultureInfo.InvariantCulture),
|
||||
LastObserved: source.LastSeen.UtcDateTime.ToString("O", CultureInfo.InvariantCulture)))
|
||||
LastObserved: source.LastSeen.UtcDateTime.ToString("O", CultureInfo.InvariantCulture),
|
||||
// VEX Lens enrichment fields
|
||||
IssuerHint: source.IssuerHint,
|
||||
SignatureType: source.SignatureType,
|
||||
KeyId: source.KeyId,
|
||||
TransparencyLogRef: source.TransparencyLogRef,
|
||||
TrustWeight: source.TrustWeight,
|
||||
TrustTier: source.TrustTier,
|
||||
StalenessSeconds: source.StalenessSeconds,
|
||||
ProductTreeSnippet: source.ProductTreeSnippet))
|
||||
.ToImmutableArray();
|
||||
|
||||
var statementId = FormattableString.Invariant($"{statement.VulnerabilityId}#{NormalizeProductKey(statement.Product.Key)}");
|
||||
@@ -200,6 +209,9 @@ internal sealed record OpenVexExportProduct(
|
||||
[property: JsonPropertyName("purl"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? Purl,
|
||||
[property: JsonPropertyName("cpe"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? Cpe);
|
||||
|
||||
/// <summary>
|
||||
/// OpenVEX source entry with VEX Lens enrichment fields for consensus computation.
|
||||
/// </summary>
|
||||
internal sealed record OpenVexExportSource(
|
||||
[property: JsonPropertyName("provider")] string Provider,
|
||||
[property: JsonPropertyName("status")] string Status,
|
||||
@@ -208,7 +220,16 @@ internal sealed record OpenVexExportSource(
|
||||
[property: JsonPropertyName("source_uri")] string SourceUri,
|
||||
[property: JsonPropertyName("detail"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? Detail,
|
||||
[property: JsonPropertyName("first_observed")] string FirstObserved,
|
||||
[property: JsonPropertyName("last_observed")] string LastObserved);
|
||||
[property: JsonPropertyName("last_observed")] string LastObserved,
|
||||
// VEX Lens enrichment fields for consensus without callback to Excititor
|
||||
[property: JsonPropertyName("issuer_hint"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? IssuerHint,
|
||||
[property: JsonPropertyName("signature_type"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? SignatureType,
|
||||
[property: JsonPropertyName("key_id"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? KeyId,
|
||||
[property: JsonPropertyName("transparency_log_ref"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? TransparencyLogRef,
|
||||
[property: JsonPropertyName("trust_weight"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] decimal? TrustWeight,
|
||||
[property: JsonPropertyName("trust_tier"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? TrustTier,
|
||||
[property: JsonPropertyName("staleness_seconds"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] long? StalenessSeconds,
|
||||
[property: JsonPropertyName("product_tree_snippet"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? ProductTreeSnippet);
|
||||
|
||||
internal sealed record OpenVexExportMetadata(
|
||||
[property: JsonPropertyName("generated_at")] string GeneratedAt,
|
||||
|
||||
@@ -169,17 +169,60 @@ public static class OpenVexStatementMerger
|
||||
private static ImmutableArray<OpenVexSourceEntry> BuildSources(ImmutableArray<VexClaim> claims)
|
||||
{
|
||||
var builder = ImmutableArray.CreateBuilder<OpenVexSourceEntry>(claims.Length);
|
||||
var now = DateTimeOffset.UtcNow;
|
||||
|
||||
foreach (var claim in claims)
|
||||
{
|
||||
// Extract VEX Lens enrichment from signature metadata
|
||||
var signature = claim.Document.Signature;
|
||||
var trust = signature?.Trust;
|
||||
|
||||
// Compute staleness from trust metadata retrieval time or last seen
|
||||
long? stalenessSeconds = null;
|
||||
if (trust?.RetrievedAtUtc is { } retrievedAt)
|
||||
{
|
||||
stalenessSeconds = (long)Math.Ceiling((now - retrievedAt).TotalSeconds);
|
||||
}
|
||||
else if (signature?.VerifiedAt is { } verifiedAt)
|
||||
{
|
||||
stalenessSeconds = (long)Math.Ceiling((now - verifiedAt).TotalSeconds);
|
||||
}
|
||||
|
||||
// Extract product tree snippet from additional metadata (if present)
|
||||
string? productTreeSnippet = null;
|
||||
if (claim.AdditionalMetadata.TryGetValue("csaf.product_tree", out var productTree))
|
||||
{
|
||||
productTreeSnippet = productTree;
|
||||
}
|
||||
|
||||
// Derive trust tier from issuer or provider type
|
||||
string? trustTier = null;
|
||||
if (trust is not null)
|
||||
{
|
||||
trustTier = trust.TenantOverrideApplied ? "tenant-override" : DeriveIssuerTier(trust.IssuerId);
|
||||
}
|
||||
else if (claim.AdditionalMetadata.TryGetValue("issuer.tier", out var tier))
|
||||
{
|
||||
trustTier = tier;
|
||||
}
|
||||
|
||||
builder.Add(new OpenVexSourceEntry(
|
||||
claim.ProviderId,
|
||||
claim.Status,
|
||||
claim.Justification,
|
||||
claim.Document.Digest,
|
||||
claim.Document.SourceUri,
|
||||
claim.Detail,
|
||||
claim.FirstSeen,
|
||||
claim.LastSeen));
|
||||
providerId: claim.ProviderId,
|
||||
status: claim.Status,
|
||||
justification: claim.Justification,
|
||||
documentDigest: claim.Document.Digest,
|
||||
documentSource: claim.Document.SourceUri,
|
||||
detail: claim.Detail,
|
||||
firstSeen: claim.FirstSeen,
|
||||
lastSeen: claim.LastSeen,
|
||||
issuerHint: signature?.Issuer ?? signature?.Subject,
|
||||
signatureType: signature?.Type,
|
||||
keyId: signature?.KeyId,
|
||||
transparencyLogRef: signature?.TransparencyLogReference,
|
||||
trustWeight: trust?.EffectiveWeight,
|
||||
trustTier: trustTier,
|
||||
stalenessSeconds: stalenessSeconds,
|
||||
productTreeSnippet: productTreeSnippet));
|
||||
}
|
||||
|
||||
return builder
|
||||
@@ -189,6 +232,34 @@ public static class OpenVexStatementMerger
|
||||
.ToImmutableArray();
|
||||
}
|
||||
|
||||
private static string? DeriveIssuerTier(string issuerId)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(issuerId))
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
// Common issuer tier patterns
|
||||
var lowerIssuerId = issuerId.ToLowerInvariant();
|
||||
if (lowerIssuerId.Contains("vendor") || lowerIssuerId.Contains("upstream"))
|
||||
{
|
||||
return "vendor";
|
||||
}
|
||||
|
||||
if (lowerIssuerId.Contains("distro") || lowerIssuerId.Contains("rhel") ||
|
||||
lowerIssuerId.Contains("ubuntu") || lowerIssuerId.Contains("debian"))
|
||||
{
|
||||
return "distro-trusted";
|
||||
}
|
||||
|
||||
if (lowerIssuerId.Contains("community") || lowerIssuerId.Contains("oss"))
|
||||
{
|
||||
return "community";
|
||||
}
|
||||
|
||||
return "other";
|
||||
}
|
||||
|
||||
private static VexProduct MergeProduct(ImmutableArray<VexClaim> claims)
|
||||
{
|
||||
var key = claims[0].Product.Key;
|
||||
@@ -266,17 +337,85 @@ public sealed record OpenVexMergedStatement(
|
||||
DateTimeOffset FirstObserved,
|
||||
DateTimeOffset LastObserved);
|
||||
|
||||
public sealed record OpenVexSourceEntry(
|
||||
string ProviderId,
|
||||
VexClaimStatus Status,
|
||||
VexJustification? Justification,
|
||||
string DocumentDigest,
|
||||
Uri DocumentSource,
|
||||
string? Detail,
|
||||
DateTimeOffset FirstSeen,
|
||||
DateTimeOffset LastSeen)
|
||||
/// <summary>
|
||||
/// Represents a merged VEX source entry with enrichment for VEX Lens consumption.
|
||||
/// </summary>
|
||||
public sealed record OpenVexSourceEntry
|
||||
{
|
||||
public string DocumentDigest { get; } = string.IsNullOrWhiteSpace(DocumentDigest)
|
||||
? throw new ArgumentException("Document digest must be provided.", nameof(DocumentDigest))
|
||||
: DocumentDigest.Trim();
|
||||
public OpenVexSourceEntry(
|
||||
string providerId,
|
||||
VexClaimStatus status,
|
||||
VexJustification? justification,
|
||||
string documentDigest,
|
||||
Uri documentSource,
|
||||
string? detail,
|
||||
DateTimeOffset firstSeen,
|
||||
DateTimeOffset lastSeen,
|
||||
string? issuerHint = null,
|
||||
string? signatureType = null,
|
||||
string? keyId = null,
|
||||
string? transparencyLogRef = null,
|
||||
decimal? trustWeight = null,
|
||||
string? trustTier = null,
|
||||
long? stalenessSeconds = null,
|
||||
string? productTreeSnippet = null)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(documentDigest))
|
||||
{
|
||||
throw new ArgumentException("Document digest must be provided.", nameof(documentDigest));
|
||||
}
|
||||
|
||||
ProviderId = providerId;
|
||||
Status = status;
|
||||
Justification = justification;
|
||||
DocumentDigest = documentDigest.Trim();
|
||||
DocumentSource = documentSource;
|
||||
Detail = detail;
|
||||
FirstSeen = firstSeen;
|
||||
LastSeen = lastSeen;
|
||||
|
||||
// VEX Lens enrichment fields
|
||||
IssuerHint = string.IsNullOrWhiteSpace(issuerHint) ? null : issuerHint.Trim();
|
||||
SignatureType = string.IsNullOrWhiteSpace(signatureType) ? null : signatureType.Trim();
|
||||
KeyId = string.IsNullOrWhiteSpace(keyId) ? null : keyId.Trim();
|
||||
TransparencyLogRef = string.IsNullOrWhiteSpace(transparencyLogRef) ? null : transparencyLogRef.Trim();
|
||||
TrustWeight = trustWeight;
|
||||
TrustTier = string.IsNullOrWhiteSpace(trustTier) ? null : trustTier.Trim();
|
||||
StalenessSeconds = stalenessSeconds;
|
||||
ProductTreeSnippet = string.IsNullOrWhiteSpace(productTreeSnippet) ? null : productTreeSnippet.Trim();
|
||||
}
|
||||
|
||||
public string ProviderId { get; }
|
||||
public VexClaimStatus Status { get; }
|
||||
public VexJustification? Justification { get; }
|
||||
public string DocumentDigest { get; }
|
||||
public Uri DocumentSource { get; }
|
||||
public string? Detail { get; }
|
||||
public DateTimeOffset FirstSeen { get; }
|
||||
public DateTimeOffset LastSeen { get; }
|
||||
|
||||
// VEX Lens enrichment fields for consensus computation
|
||||
/// <summary>Issuer identity/hint (e.g., vendor name, distro-trusted) for trust weighting.</summary>
|
||||
public string? IssuerHint { get; }
|
||||
|
||||
/// <summary>Cryptographic signature type (jws, pgp, cosign, etc.).</summary>
|
||||
public string? SignatureType { get; }
|
||||
|
||||
/// <summary>Key identifier used for signature verification.</summary>
|
||||
public string? KeyId { get; }
|
||||
|
||||
/// <summary>Transparency log reference (e.g., Rekor URL) for attestation verification.</summary>
|
||||
public string? TransparencyLogRef { get; }
|
||||
|
||||
/// <summary>Trust weight (0-1) from issuer directory for consensus calculation.</summary>
|
||||
public decimal? TrustWeight { get; }
|
||||
|
||||
/// <summary>Trust tier label (vendor, distro-trusted, community, etc.).</summary>
|
||||
public string? TrustTier { get; }
|
||||
|
||||
/// <summary>Seconds since the document was last verified/retrieved.</summary>
|
||||
public long? StalenessSeconds { get; }
|
||||
|
||||
/// <summary>Product tree snippet (JSON) from CSAF documents for product matching.</summary>
|
||||
public string? ProductTreeSnippet { get; }
|
||||
}
|
||||
|
||||
@@ -44,7 +44,12 @@ public sealed record VexConnectorState(
|
||||
DateTimeOffset? LastSuccessAt,
|
||||
int FailureCount,
|
||||
DateTimeOffset? NextEligibleRun,
|
||||
string? LastFailureReason)
|
||||
string? LastFailureReason,
|
||||
DateTimeOffset? LastHeartbeatAt = null,
|
||||
string? LastHeartbeatStatus = null,
|
||||
string? LastArtifactHash = null,
|
||||
string? LastArtifactKind = null,
|
||||
string? LastCheckpoint = null)
|
||||
{
|
||||
public VexConnectorState(
|
||||
string connectorId,
|
||||
@@ -58,7 +63,12 @@ public sealed record VexConnectorState(
|
||||
LastSuccessAt: null,
|
||||
FailureCount: 0,
|
||||
NextEligibleRun: null,
|
||||
LastFailureReason: null)
|
||||
LastFailureReason: null,
|
||||
LastHeartbeatAt: null,
|
||||
LastHeartbeatStatus: null,
|
||||
LastArtifactHash: null,
|
||||
LastArtifactKind: null,
|
||||
LastCheckpoint: null)
|
||||
{
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
using MongoDB.Bson;
|
||||
using MongoDB.Driver;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo.Migrations;
|
||||
|
||||
/// <summary>
|
||||
/// Adds idempotency indexes to the vex_raw collection to enforce content-addressed storage.
|
||||
/// Ensures that:
|
||||
/// 1. Each document is uniquely identified by its content digest
|
||||
/// 2. Provider+Source combinations are unique per digest
|
||||
/// 3. Supports efficient queries for evidence retrieval
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Rollback: Run db.vex_raw.dropIndex("idx_provider_sourceUri_digest_unique")
|
||||
/// and db.vex_raw.dropIndex("idx_digest_providerId") to reverse this migration.
|
||||
/// </remarks>
|
||||
internal sealed class VexRawIdempotencyIndexMigration : IVexMongoMigration
|
||||
{
|
||||
public string Id => "20251127-vex-raw-idempotency-indexes";
|
||||
|
||||
public async ValueTask ExecuteAsync(IMongoDatabase database, CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
|
||||
var collection = database.GetCollection<BsonDocument>(VexMongoCollectionNames.Raw);
|
||||
|
||||
// Index 1: Unique constraint on providerId + sourceUri + digest
|
||||
// Ensures the same document from the same provider/source is only stored once
|
||||
var providerSourceDigestIndex = new BsonDocument
|
||||
{
|
||||
{ "providerId", 1 },
|
||||
{ "sourceUri", 1 },
|
||||
{ "digest", 1 }
|
||||
};
|
||||
|
||||
var uniqueIndexModel = new CreateIndexModel<BsonDocument>(
|
||||
providerSourceDigestIndex,
|
||||
new CreateIndexOptions
|
||||
{
|
||||
Unique = true,
|
||||
Name = "idx_provider_sourceUri_digest_unique",
|
||||
Background = true
|
||||
});
|
||||
|
||||
// Index 2: Compound index for efficient evidence queries by digest + provider
|
||||
var digestProviderIndex = new BsonDocument
|
||||
{
|
||||
{ "digest", 1 },
|
||||
{ "providerId", 1 }
|
||||
};
|
||||
|
||||
var queryIndexModel = new CreateIndexModel<BsonDocument>(
|
||||
digestProviderIndex,
|
||||
new CreateIndexOptions
|
||||
{
|
||||
Name = "idx_digest_providerId",
|
||||
Background = true
|
||||
});
|
||||
|
||||
// Index 3: TTL index candidate for future cleanup (optional staleness tracking)
|
||||
var retrievedAtIndex = new BsonDocument
|
||||
{
|
||||
{ "retrievedAt", 1 }
|
||||
};
|
||||
|
||||
var retrievedAtIndexModel = new CreateIndexModel<BsonDocument>(
|
||||
retrievedAtIndex,
|
||||
new CreateIndexOptions
|
||||
{
|
||||
Name = "idx_retrievedAt",
|
||||
Background = true
|
||||
});
|
||||
|
||||
// Create all indexes
|
||||
await collection.Indexes.CreateManyAsync(
|
||||
new[] { uniqueIndexModel, queryIndexModel, retrievedAtIndexModel },
|
||||
cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extension methods for idempotency index management.
|
||||
/// </summary>
|
||||
public static class VexRawIdempotencyIndexExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Drops the idempotency indexes (for rollback).
|
||||
/// </summary>
|
||||
public static async Task RollbackIdempotencyIndexesAsync(
|
||||
this IMongoDatabase database,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
|
||||
var collection = database.GetCollection<BsonDocument>(VexMongoCollectionNames.Raw);
|
||||
|
||||
var indexNames = new[]
|
||||
{
|
||||
"idx_provider_sourceUri_digest_unique",
|
||||
"idx_digest_providerId",
|
||||
"idx_retrievedAt"
|
||||
};
|
||||
|
||||
foreach (var indexName in indexNames)
|
||||
{
|
||||
try
|
||||
{
|
||||
await collection.Indexes.DropOneAsync(indexName, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
catch (MongoCommandException ex) when (ex.CodeName == "IndexNotFound")
|
||||
{
|
||||
// Index doesn't exist, skip
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Verifies that idempotency indexes exist.
|
||||
/// </summary>
|
||||
public static async Task<bool> VerifyIdempotencyIndexesExistAsync(
|
||||
this IMongoDatabase database,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
|
||||
var collection = database.GetCollection<BsonDocument>(VexMongoCollectionNames.Raw);
|
||||
var cursor = await collection.Indexes.ListAsync(cancellationToken).ConfigureAwait(false);
|
||||
var indexes = await cursor.ToListAsync(cancellationToken).ConfigureAwait(false);
|
||||
|
||||
var indexNames = indexes.Select(i => i.GetValue("name", "").AsString).ToHashSet();
|
||||
|
||||
return indexNames.Contains("idx_provider_sourceUri_digest_unique") &&
|
||||
indexNames.Contains("idx_digest_providerId");
|
||||
}
|
||||
}
|
||||
@@ -25,15 +25,17 @@ internal sealed class VexRawSchemaMigration : IVexMongoMigration
|
||||
|
||||
if (!exists)
|
||||
{
|
||||
await database.CreateCollectionAsync(
|
||||
VexMongoCollectionNames.Raw,
|
||||
new CreateCollectionOptions
|
||||
// In MongoDB.Driver 3.x, CreateCollectionOptions doesn't support Validator directly.
|
||||
// Use the create command instead.
|
||||
var createCommand = new BsonDocument
|
||||
{
|
||||
Validator = validator,
|
||||
ValidationAction = DocumentValidationAction.Warn,
|
||||
ValidationLevel = DocumentValidationLevel.Moderate,
|
||||
},
|
||||
cancellationToken).ConfigureAwait(false);
|
||||
{ "create", VexMongoCollectionNames.Raw },
|
||||
{ "validator", validator },
|
||||
{ "validationAction", "warn" },
|
||||
{ "validationLevel", "moderate" }
|
||||
};
|
||||
await database.RunCommandAsync<BsonDocument>(createCommand, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
return;
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
using MongoDB.Driver;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo.Migrations;
|
||||
|
||||
/// <summary>
|
||||
/// Migration that creates indexes for the vex.timeline_events collection.
|
||||
/// </summary>
|
||||
internal sealed class VexTimelineEventIndexMigration : IVexMongoMigration
|
||||
{
|
||||
public string Id => "20251127-timeline-events";
|
||||
|
||||
public async ValueTask ExecuteAsync(IMongoDatabase database, CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
|
||||
var collection = database.GetCollection<VexTimelineEventRecord>(VexMongoCollectionNames.TimelineEvents);
|
||||
|
||||
// Unique index on tenant + event ID
|
||||
var tenantEventIdIndex = Builders<VexTimelineEventRecord>.IndexKeys
|
||||
.Ascending(x => x.Tenant)
|
||||
.Ascending(x => x.Id);
|
||||
|
||||
// Index for querying by time range (descending for recent-first queries)
|
||||
var tenantTimeIndex = Builders<VexTimelineEventRecord>.IndexKeys
|
||||
.Ascending(x => x.Tenant)
|
||||
.Descending(x => x.CreatedAt);
|
||||
|
||||
// Index for querying by trace ID
|
||||
var tenantTraceIndex = Builders<VexTimelineEventRecord>.IndexKeys
|
||||
.Ascending(x => x.Tenant)
|
||||
.Ascending(x => x.TraceId)
|
||||
.Ascending(x => x.CreatedAt);
|
||||
|
||||
// Index for querying by provider
|
||||
var tenantProviderIndex = Builders<VexTimelineEventRecord>.IndexKeys
|
||||
.Ascending(x => x.Tenant)
|
||||
.Ascending(x => x.ProviderId)
|
||||
.Descending(x => x.CreatedAt);
|
||||
|
||||
// Index for querying by event type
|
||||
var tenantEventTypeIndex = Builders<VexTimelineEventRecord>.IndexKeys
|
||||
.Ascending(x => x.Tenant)
|
||||
.Ascending(x => x.EventType)
|
||||
.Descending(x => x.CreatedAt);
|
||||
|
||||
// TTL index for automatic cleanup (30 days by default)
|
||||
// Uncomment if timeline events should expire:
|
||||
// var ttlIndex = Builders<VexTimelineEventRecord>.IndexKeys.Ascending(x => x.CreatedAt);
|
||||
// var ttlOptions = new CreateIndexOptions { ExpireAfter = TimeSpan.FromDays(30) };
|
||||
|
||||
await Task.WhenAll(
|
||||
collection.Indexes.CreateOneAsync(
|
||||
new CreateIndexModel<VexTimelineEventRecord>(tenantEventIdIndex, new CreateIndexOptions { Unique = true }),
|
||||
cancellationToken: cancellationToken),
|
||||
collection.Indexes.CreateOneAsync(
|
||||
new CreateIndexModel<VexTimelineEventRecord>(tenantTimeIndex),
|
||||
cancellationToken: cancellationToken),
|
||||
collection.Indexes.CreateOneAsync(
|
||||
new CreateIndexModel<VexTimelineEventRecord>(tenantTraceIndex),
|
||||
cancellationToken: cancellationToken),
|
||||
collection.Indexes.CreateOneAsync(
|
||||
new CreateIndexModel<VexTimelineEventRecord>(tenantProviderIndex),
|
||||
cancellationToken: cancellationToken),
|
||||
collection.Indexes.CreateOneAsync(
|
||||
new CreateIndexModel<VexTimelineEventRecord>(tenantEventTypeIndex),
|
||||
cancellationToken: cancellationToken)
|
||||
).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
using MongoDB.Driver;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo;
|
||||
|
||||
/// <summary>
|
||||
/// MongoDB implementation of <see cref="IVexLinksetEventPublisher"/>.
|
||||
/// Events are persisted to the vex.linkset_events collection for replay and audit.
|
||||
/// </summary>
|
||||
internal sealed class MongoVexLinksetEventPublisher : IVexLinksetEventPublisher
|
||||
{
|
||||
private readonly IMongoCollection<VexLinksetEventRecord> _collection;
|
||||
|
||||
public MongoVexLinksetEventPublisher(IMongoDatabase database)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
_collection = database.GetCollection<VexLinksetEventRecord>(VexMongoCollectionNames.LinksetEvents);
|
||||
}
|
||||
|
||||
public async Task PublishAsync(VexLinksetUpdatedEvent @event, CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(@event);
|
||||
|
||||
var record = ToRecord(@event);
|
||||
await _collection.InsertOneAsync(record, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
public async Task PublishManyAsync(IEnumerable<VexLinksetUpdatedEvent> events, CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(events);
|
||||
|
||||
var records = events
|
||||
.Where(e => e is not null)
|
||||
.Select(ToRecord)
|
||||
.ToList();
|
||||
|
||||
if (records.Count == 0)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
var options = new InsertManyOptions { IsOrdered = false };
|
||||
await _collection.InsertManyAsync(records, options, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static VexLinksetEventRecord ToRecord(VexLinksetUpdatedEvent @event)
|
||||
{
|
||||
var eventId = $"{@event.LinksetId}:{@event.CreatedAtUtc.UtcTicks}";
|
||||
|
||||
return new VexLinksetEventRecord
|
||||
{
|
||||
Id = eventId,
|
||||
EventType = @event.EventType,
|
||||
Tenant = @event.Tenant.ToLowerInvariant(),
|
||||
LinksetId = @event.LinksetId,
|
||||
VulnerabilityId = @event.VulnerabilityId,
|
||||
ProductKey = @event.ProductKey,
|
||||
Observations = @event.Observations
|
||||
.Select(o => new VexLinksetEventObservationRecord
|
||||
{
|
||||
ObservationId = o.ObservationId,
|
||||
ProviderId = o.ProviderId,
|
||||
Status = o.Status,
|
||||
Confidence = o.Confidence
|
||||
})
|
||||
.ToList(),
|
||||
Disagreements = @event.Disagreements
|
||||
.Select(d => new VexLinksetDisagreementRecord
|
||||
{
|
||||
ProviderId = d.ProviderId,
|
||||
Status = d.Status,
|
||||
Justification = d.Justification,
|
||||
Confidence = d.Confidence
|
||||
})
|
||||
.ToList(),
|
||||
CreatedAtUtc = @event.CreatedAtUtc.UtcDateTime,
|
||||
PublishedAtUtc = DateTime.UtcNow,
|
||||
ConflictCount = @event.Disagreements.Length,
|
||||
ObservationCount = @event.Observations.Length
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,339 @@
|
||||
using System.Collections.Immutable;
|
||||
using MongoDB.Driver;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo;
|
||||
|
||||
internal sealed class MongoVexLinksetStore : IVexLinksetStore
|
||||
{
|
||||
private readonly IMongoCollection<VexLinksetRecord> _collection;
|
||||
|
||||
public MongoVexLinksetStore(IMongoDatabase database)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
_collection = database.GetCollection<VexLinksetRecord>(VexMongoCollectionNames.Linksets);
|
||||
}
|
||||
|
||||
public async ValueTask<bool> InsertAsync(
|
||||
VexLinkset linkset,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(linkset);
|
||||
|
||||
var record = ToRecord(linkset);
|
||||
|
||||
try
|
||||
{
|
||||
await _collection.InsertOneAsync(record, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
return true;
|
||||
}
|
||||
catch (MongoWriteException ex) when (ex.WriteError?.Category == ServerErrorCategory.DuplicateKey)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask<bool> UpsertAsync(
|
||||
VexLinkset linkset,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(linkset);
|
||||
|
||||
var record = ToRecord(linkset);
|
||||
var normalizedTenant = NormalizeTenant(linkset.Tenant);
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.LinksetId, linkset.LinksetId));
|
||||
|
||||
var options = new ReplaceOptions { IsUpsert = true };
|
||||
var result = await _collection
|
||||
.ReplaceOneAsync(filter, record, options, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return result.UpsertedId is not null;
|
||||
}
|
||||
|
||||
public async ValueTask<VexLinkset?> GetByIdAsync(
|
||||
string tenant,
|
||||
string linksetId,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedId = linksetId?.Trim() ?? throw new ArgumentNullException(nameof(linksetId));
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.LinksetId, normalizedId));
|
||||
|
||||
var record = await _collection
|
||||
.Find(filter)
|
||||
.FirstOrDefaultAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return record is null ? null : ToModel(record);
|
||||
}
|
||||
|
||||
public async ValueTask<VexLinkset> GetOrCreateAsync(
|
||||
string tenant,
|
||||
string vulnerabilityId,
|
||||
string productKey,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedVuln = vulnerabilityId?.Trim() ?? throw new ArgumentNullException(nameof(vulnerabilityId));
|
||||
var normalizedProduct = productKey?.Trim() ?? throw new ArgumentNullException(nameof(productKey));
|
||||
|
||||
var linksetId = VexLinkset.CreateLinksetId(normalizedTenant, normalizedVuln, normalizedProduct);
|
||||
|
||||
var existing = await GetByIdAsync(normalizedTenant, linksetId, cancellationToken).ConfigureAwait(false);
|
||||
if (existing is not null)
|
||||
{
|
||||
return existing;
|
||||
}
|
||||
|
||||
var newLinkset = new VexLinkset(
|
||||
linksetId,
|
||||
normalizedTenant,
|
||||
normalizedVuln,
|
||||
normalizedProduct,
|
||||
observations: Array.Empty<VexLinksetObservationRefModel>(),
|
||||
disagreements: null,
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
updatedAt: DateTimeOffset.UtcNow);
|
||||
|
||||
try
|
||||
{
|
||||
await InsertAsync(newLinkset, cancellationToken).ConfigureAwait(false);
|
||||
return newLinkset;
|
||||
}
|
||||
catch (MongoWriteException ex) when (ex.WriteError?.Category == ServerErrorCategory.DuplicateKey)
|
||||
{
|
||||
// Race condition - another process created it. Fetch and return.
|
||||
var created = await GetByIdAsync(normalizedTenant, linksetId, cancellationToken).ConfigureAwait(false);
|
||||
return created ?? newLinkset;
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<VexLinkset>> FindByVulnerabilityAsync(
|
||||
string tenant,
|
||||
string vulnerabilityId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedVuln = vulnerabilityId?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(vulnerabilityId));
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.VulnerabilityId, normalizedVuln));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexLinksetRecord>.Sort.Descending(r => r.UpdatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<VexLinkset>> FindByProductKeyAsync(
|
||||
string tenant,
|
||||
string productKey,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedProduct = productKey?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(productKey));
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.ProductKey, normalizedProduct));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexLinksetRecord>.Sort.Descending(r => r.UpdatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<VexLinkset>> FindWithConflictsAsync(
|
||||
string tenant,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.SizeGt(r => r.Disagreements, 0));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexLinksetRecord>.Sort.Descending(r => r.UpdatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<VexLinkset>> FindByProviderAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedProvider = providerId?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(providerId));
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.AnyEq(r => r.ProviderIds, normalizedProvider));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexLinksetRecord>.Sort.Descending(r => r.UpdatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<bool> DeleteAsync(
|
||||
string tenant,
|
||||
string linksetId,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedId = linksetId?.Trim() ?? throw new ArgumentNullException(nameof(linksetId));
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.LinksetId, normalizedId));
|
||||
|
||||
var result = await _collection
|
||||
.DeleteOneAsync(filter, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return result.DeletedCount > 0;
|
||||
}
|
||||
|
||||
public async ValueTask<long> CountAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant);
|
||||
|
||||
return await _collection
|
||||
.CountDocumentsAsync(filter, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
public async ValueTask<long> CountWithConflictsAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
|
||||
var filter = Builders<VexLinksetRecord>.Filter.And(
|
||||
Builders<VexLinksetRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexLinksetRecord>.Filter.SizeGt(r => r.Disagreements, 0));
|
||||
|
||||
return await _collection
|
||||
.CountDocumentsAsync(filter, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static string NormalizeTenant(string tenant)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(tenant))
|
||||
{
|
||||
throw new ArgumentException("tenant is required", nameof(tenant));
|
||||
}
|
||||
|
||||
return tenant.Trim().ToLowerInvariant();
|
||||
}
|
||||
|
||||
private static VexLinksetRecord ToRecord(VexLinkset linkset)
|
||||
{
|
||||
return new VexLinksetRecord
|
||||
{
|
||||
Id = linkset.LinksetId,
|
||||
Tenant = linkset.Tenant.ToLowerInvariant(),
|
||||
LinksetId = linkset.LinksetId,
|
||||
VulnerabilityId = linkset.VulnerabilityId.ToLowerInvariant(),
|
||||
ProductKey = linkset.ProductKey.ToLowerInvariant(),
|
||||
ProviderIds = linkset.ProviderIds.ToList(),
|
||||
Statuses = linkset.Statuses.ToList(),
|
||||
CreatedAt = linkset.CreatedAt.UtcDateTime,
|
||||
UpdatedAt = linkset.UpdatedAt.UtcDateTime,
|
||||
Observations = linkset.Observations.Select(ToObservationRecord).ToList(),
|
||||
Disagreements = linkset.Disagreements.Select(ToDisagreementRecord).ToList()
|
||||
};
|
||||
}
|
||||
|
||||
private static VexObservationLinksetObservationRecord ToObservationRecord(VexLinksetObservationRefModel obs)
|
||||
{
|
||||
return new VexObservationLinksetObservationRecord
|
||||
{
|
||||
ObservationId = obs.ObservationId,
|
||||
ProviderId = obs.ProviderId,
|
||||
Status = obs.Status,
|
||||
Confidence = obs.Confidence
|
||||
};
|
||||
}
|
||||
|
||||
private static VexLinksetDisagreementRecord ToDisagreementRecord(VexObservationDisagreement disagreement)
|
||||
{
|
||||
return new VexLinksetDisagreementRecord
|
||||
{
|
||||
ProviderId = disagreement.ProviderId,
|
||||
Status = disagreement.Status,
|
||||
Justification = disagreement.Justification,
|
||||
Confidence = disagreement.Confidence
|
||||
};
|
||||
}
|
||||
|
||||
private static VexLinkset ToModel(VexLinksetRecord record)
|
||||
{
|
||||
var observations = record.Observations?
|
||||
.Where(o => o is not null)
|
||||
.Select(o => new VexLinksetObservationRefModel(
|
||||
o.ObservationId,
|
||||
o.ProviderId,
|
||||
o.Status,
|
||||
o.Confidence))
|
||||
.ToImmutableArray() ?? ImmutableArray<VexLinksetObservationRefModel>.Empty;
|
||||
|
||||
var disagreements = record.Disagreements?
|
||||
.Where(d => d is not null)
|
||||
.Select(d => new VexObservationDisagreement(
|
||||
d.ProviderId,
|
||||
d.Status,
|
||||
d.Justification,
|
||||
d.Confidence))
|
||||
.ToImmutableArray() ?? ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
|
||||
return new VexLinkset(
|
||||
linksetId: record.LinksetId,
|
||||
tenant: record.Tenant,
|
||||
vulnerabilityId: record.VulnerabilityId,
|
||||
productKey: record.ProductKey,
|
||||
observations: observations,
|
||||
disagreements: disagreements,
|
||||
createdAt: new DateTimeOffset(record.CreatedAt, TimeSpan.Zero),
|
||||
updatedAt: new DateTimeOffset(record.UpdatedAt, TimeSpan.Zero));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,398 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Text.Json.Nodes;
|
||||
using MongoDB.Bson;
|
||||
using MongoDB.Driver;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo;
|
||||
|
||||
internal sealed class MongoVexObservationStore : IVexObservationStore
|
||||
{
|
||||
private readonly IMongoCollection<VexObservationRecord> _collection;
|
||||
|
||||
public MongoVexObservationStore(IMongoDatabase database)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
_collection = database.GetCollection<VexObservationRecord>(VexMongoCollectionNames.Observations);
|
||||
}
|
||||
|
||||
public async ValueTask<bool> InsertAsync(
|
||||
VexObservation observation,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(observation);
|
||||
|
||||
var record = ToRecord(observation);
|
||||
|
||||
try
|
||||
{
|
||||
await _collection.InsertOneAsync(record, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
return true;
|
||||
}
|
||||
catch (MongoWriteException ex) when (ex.WriteError?.Category == ServerErrorCategory.DuplicateKey)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask<bool> UpsertAsync(
|
||||
VexObservation observation,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(observation);
|
||||
|
||||
var record = ToRecord(observation);
|
||||
var normalizedTenant = NormalizeTenant(observation.Tenant);
|
||||
|
||||
var filter = Builders<VexObservationRecord>.Filter.And(
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.ObservationId, observation.ObservationId));
|
||||
|
||||
var options = new ReplaceOptions { IsUpsert = true };
|
||||
var result = await _collection
|
||||
.ReplaceOneAsync(filter, record, options, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return result.UpsertedId is not null;
|
||||
}
|
||||
|
||||
public async ValueTask<int> InsertManyAsync(
|
||||
string tenant,
|
||||
IEnumerable<VexObservation> observations,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var records = observations
|
||||
.Where(o => o is not null && string.Equals(NormalizeTenant(o.Tenant), normalizedTenant, StringComparison.Ordinal))
|
||||
.Select(ToRecord)
|
||||
.ToList();
|
||||
|
||||
if (records.Count == 0)
|
||||
{
|
||||
return 0;
|
||||
}
|
||||
|
||||
var options = new InsertManyOptions { IsOrdered = false };
|
||||
try
|
||||
{
|
||||
await _collection.InsertManyAsync(records, options, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
return records.Count;
|
||||
}
|
||||
catch (MongoBulkWriteException<VexObservationRecord> ex)
|
||||
{
|
||||
// Return the count of successful inserts
|
||||
var duplicates = ex.WriteErrors?.Count(e => e.Category == ServerErrorCategory.DuplicateKey) ?? 0;
|
||||
return records.Count - duplicates;
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask<VexObservation?> GetByIdAsync(
|
||||
string tenant,
|
||||
string observationId,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedId = observationId?.Trim() ?? throw new ArgumentNullException(nameof(observationId));
|
||||
|
||||
var filter = Builders<VexObservationRecord>.Filter.And(
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.ObservationId, normalizedId));
|
||||
|
||||
var record = await _collection
|
||||
.Find(filter)
|
||||
.FirstOrDefaultAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return record is null ? null : ToModel(record);
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<VexObservation>> FindByVulnerabilityAndProductAsync(
|
||||
string tenant,
|
||||
string vulnerabilityId,
|
||||
string productKey,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedVuln = vulnerabilityId?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(vulnerabilityId));
|
||||
var normalizedProduct = productKey?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(productKey));
|
||||
|
||||
var filter = Builders<VexObservationRecord>.Filter.And(
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.VulnerabilityId, normalizedVuln),
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.ProductKey, normalizedProduct));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexObservationRecord>.Sort.Descending(r => r.CreatedAt))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<VexObservation>> FindByProviderAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedProvider = providerId?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(providerId));
|
||||
|
||||
var filter = Builders<VexObservationRecord>.Filter.And(
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.ProviderId, normalizedProvider));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexObservationRecord>.Sort.Descending(r => r.CreatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<bool> DeleteAsync(
|
||||
string tenant,
|
||||
string observationId,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedId = observationId?.Trim() ?? throw new ArgumentNullException(nameof(observationId));
|
||||
|
||||
var filter = Builders<VexObservationRecord>.Filter.And(
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexObservationRecord>.Filter.Eq(r => r.ObservationId, normalizedId));
|
||||
|
||||
var result = await _collection
|
||||
.DeleteOneAsync(filter, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return result.DeletedCount > 0;
|
||||
}
|
||||
|
||||
public async ValueTask<long> CountAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
|
||||
var filter = Builders<VexObservationRecord>.Filter.Eq(r => r.Tenant, normalizedTenant);
|
||||
|
||||
return await _collection
|
||||
.CountDocumentsAsync(filter, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static string NormalizeTenant(string tenant)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(tenant))
|
||||
{
|
||||
throw new ArgumentException("tenant is required", nameof(tenant));
|
||||
}
|
||||
|
||||
return tenant.Trim().ToLowerInvariant();
|
||||
}
|
||||
|
||||
private static VexObservationRecord ToRecord(VexObservation observation)
|
||||
{
|
||||
var firstStatement = observation.Statements.FirstOrDefault();
|
||||
|
||||
return new VexObservationRecord
|
||||
{
|
||||
Id = observation.ObservationId,
|
||||
Tenant = observation.Tenant,
|
||||
ObservationId = observation.ObservationId,
|
||||
VulnerabilityId = firstStatement?.VulnerabilityId?.ToLowerInvariant() ?? string.Empty,
|
||||
ProductKey = firstStatement?.ProductKey?.ToLowerInvariant() ?? string.Empty,
|
||||
ProviderId = observation.ProviderId,
|
||||
StreamId = observation.StreamId,
|
||||
Status = firstStatement?.Status.ToString().ToLowerInvariant() ?? "unknown",
|
||||
Document = new VexObservationDocumentRecord
|
||||
{
|
||||
Digest = observation.Upstream.ContentHash,
|
||||
SourceUri = null,
|
||||
Format = observation.Content.Format,
|
||||
Revision = observation.Upstream.DocumentVersion,
|
||||
Signature = new VexObservationSignatureRecord
|
||||
{
|
||||
Present = observation.Upstream.Signature.Present,
|
||||
Subject = observation.Upstream.Signature.Format,
|
||||
Issuer = observation.Upstream.Signature.KeyId,
|
||||
VerifiedAt = null
|
||||
}
|
||||
},
|
||||
Upstream = new VexObservationUpstreamRecord
|
||||
{
|
||||
UpstreamId = observation.Upstream.UpstreamId,
|
||||
DocumentVersion = observation.Upstream.DocumentVersion,
|
||||
FetchedAt = observation.Upstream.FetchedAt,
|
||||
ReceivedAt = observation.Upstream.ReceivedAt,
|
||||
ContentHash = observation.Upstream.ContentHash,
|
||||
Signature = new VexObservationSignatureRecord
|
||||
{
|
||||
Present = observation.Upstream.Signature.Present,
|
||||
Subject = observation.Upstream.Signature.Format,
|
||||
Issuer = observation.Upstream.Signature.KeyId,
|
||||
VerifiedAt = null
|
||||
}
|
||||
},
|
||||
Content = new VexObservationContentRecord
|
||||
{
|
||||
Format = observation.Content.Format,
|
||||
SpecVersion = observation.Content.SpecVersion,
|
||||
Raw = BsonDocument.Parse(observation.Content.Raw.ToJsonString())
|
||||
},
|
||||
Statements = observation.Statements.Select(ToStatementRecord).ToList(),
|
||||
Linkset = ToLinksetRecord(observation.Linkset),
|
||||
CreatedAt = observation.CreatedAt.UtcDateTime
|
||||
};
|
||||
}
|
||||
|
||||
private static VexObservationStatementRecord ToStatementRecord(VexObservationStatement statement)
|
||||
{
|
||||
return new VexObservationStatementRecord
|
||||
{
|
||||
VulnerabilityId = statement.VulnerabilityId,
|
||||
ProductKey = statement.ProductKey,
|
||||
Status = statement.Status.ToString().ToLowerInvariant(),
|
||||
LastObserved = statement.LastObserved,
|
||||
Locator = statement.Locator,
|
||||
Justification = statement.Justification?.ToString().ToLowerInvariant(),
|
||||
IntroducedVersion = statement.IntroducedVersion,
|
||||
FixedVersion = statement.FixedVersion,
|
||||
Detail = null,
|
||||
ScopeScore = null,
|
||||
Epss = null,
|
||||
Kev = null
|
||||
};
|
||||
}
|
||||
|
||||
private static VexObservationLinksetRecord ToLinksetRecord(VexObservationLinkset linkset)
|
||||
{
|
||||
return new VexObservationLinksetRecord
|
||||
{
|
||||
Aliases = linkset.Aliases.ToList(),
|
||||
Purls = linkset.Purls.ToList(),
|
||||
Cpes = linkset.Cpes.ToList(),
|
||||
References = linkset.References.Select(r => new VexObservationReferenceRecord
|
||||
{
|
||||
Type = r.Type,
|
||||
Url = r.Url
|
||||
}).ToList(),
|
||||
ReconciledFrom = linkset.ReconciledFrom.ToList(),
|
||||
Disagreements = linkset.Disagreements.Select(d => new VexLinksetDisagreementRecord
|
||||
{
|
||||
ProviderId = d.ProviderId,
|
||||
Status = d.Status,
|
||||
Justification = d.Justification,
|
||||
Confidence = d.Confidence
|
||||
}).ToList(),
|
||||
Observations = linkset.Observations.Select(o => new VexObservationLinksetObservationRecord
|
||||
{
|
||||
ObservationId = o.ObservationId,
|
||||
ProviderId = o.ProviderId,
|
||||
Status = o.Status,
|
||||
Confidence = o.Confidence
|
||||
}).ToList()
|
||||
};
|
||||
}
|
||||
|
||||
private static VexObservation ToModel(VexObservationRecord record)
|
||||
{
|
||||
var statements = record.Statements.Select(MapStatement).ToImmutableArray();
|
||||
var linkset = MapLinkset(record.Linkset);
|
||||
|
||||
var upstreamSignature = record.Upstream?.Signature is null
|
||||
? new VexObservationSignature(false, null, null, null)
|
||||
: new VexObservationSignature(
|
||||
record.Upstream.Signature.Present,
|
||||
record.Upstream.Signature.Subject,
|
||||
record.Upstream.Signature.Issuer,
|
||||
signature: null);
|
||||
|
||||
var upstream = record.Upstream is null
|
||||
? new VexObservationUpstream(
|
||||
upstreamId: record.ObservationId,
|
||||
documentVersion: null,
|
||||
fetchedAt: record.CreatedAt,
|
||||
receivedAt: record.CreatedAt,
|
||||
contentHash: record.Document.Digest,
|
||||
signature: upstreamSignature)
|
||||
: new VexObservationUpstream(
|
||||
record.Upstream.UpstreamId,
|
||||
record.Upstream.DocumentVersion,
|
||||
record.Upstream.FetchedAt,
|
||||
record.Upstream.ReceivedAt,
|
||||
record.Upstream.ContentHash,
|
||||
upstreamSignature);
|
||||
|
||||
var content = record.Content is null
|
||||
? new VexObservationContent("unknown", null, new JsonObject())
|
||||
: new VexObservationContent(
|
||||
record.Content.Format ?? "unknown",
|
||||
record.Content.SpecVersion,
|
||||
JsonNode.Parse(record.Content.Raw.ToJson()) ?? new JsonObject(),
|
||||
metadata: ImmutableDictionary<string, string>.Empty);
|
||||
|
||||
return new VexObservation(
|
||||
observationId: record.ObservationId,
|
||||
tenant: record.Tenant,
|
||||
providerId: record.ProviderId,
|
||||
streamId: string.IsNullOrWhiteSpace(record.StreamId) ? record.ProviderId : record.StreamId,
|
||||
upstream: upstream,
|
||||
statements: statements,
|
||||
content: content,
|
||||
linkset: linkset,
|
||||
createdAt: new DateTimeOffset(record.CreatedAt, TimeSpan.Zero),
|
||||
supersedes: ImmutableArray<string>.Empty,
|
||||
attributes: ImmutableDictionary<string, string>.Empty);
|
||||
}
|
||||
|
||||
private static VexObservationStatement MapStatement(VexObservationStatementRecord record)
|
||||
{
|
||||
var justification = string.IsNullOrWhiteSpace(record.Justification)
|
||||
? (VexJustification?)null
|
||||
: Enum.Parse<VexJustification>(record.Justification, ignoreCase: true);
|
||||
|
||||
return new VexObservationStatement(
|
||||
record.VulnerabilityId,
|
||||
record.ProductKey,
|
||||
Enum.Parse<VexClaimStatus>(record.Status, ignoreCase: true),
|
||||
record.LastObserved,
|
||||
locator: record.Locator,
|
||||
justification: justification,
|
||||
introducedVersion: record.IntroducedVersion,
|
||||
fixedVersion: record.FixedVersion,
|
||||
purl: null,
|
||||
cpe: null,
|
||||
evidence: null,
|
||||
metadata: ImmutableDictionary<string, string>.Empty);
|
||||
}
|
||||
|
||||
private static VexObservationLinkset MapLinkset(VexObservationLinksetRecord record)
|
||||
{
|
||||
var aliases = record?.Aliases?.Where(NotNullOrWhiteSpace).Select(a => a.Trim()).ToImmutableArray() ?? ImmutableArray<string>.Empty;
|
||||
var purls = record?.Purls?.Where(NotNullOrWhiteSpace).Select(p => p.Trim()).ToImmutableArray() ?? ImmutableArray<string>.Empty;
|
||||
var cpes = record?.Cpes?.Where(NotNullOrWhiteSpace).Select(c => c.Trim()).ToImmutableArray() ?? ImmutableArray<string>.Empty;
|
||||
var references = record?.References?.Select(r => new VexObservationReference(r.Type, r.Url)).ToImmutableArray() ?? ImmutableArray<VexObservationReference>.Empty;
|
||||
var reconciledFrom = record?.ReconciledFrom?.Where(NotNullOrWhiteSpace).Select(r => r.Trim()).ToImmutableArray() ?? ImmutableArray<string>.Empty;
|
||||
var disagreements = record?.Disagreements?.Select(d => new VexObservationDisagreement(d.ProviderId, d.Status, d.Justification, d.Confidence)).ToImmutableArray() ?? ImmutableArray<VexObservationDisagreement>.Empty;
|
||||
var observationRefs = record?.Observations?.Select(o => new VexLinksetObservationRefModel(
|
||||
o.ObservationId,
|
||||
o.ProviderId,
|
||||
o.Status,
|
||||
o.Confidence)).ToImmutableArray() ?? ImmutableArray<VexLinksetObservationRefModel>.Empty;
|
||||
|
||||
return new VexObservationLinkset(aliases, purls, cpes, references, reconciledFrom, disagreements, observationRefs);
|
||||
}
|
||||
|
||||
private static bool NotNullOrWhiteSpace(string? value) => !string.IsNullOrWhiteSpace(value);
|
||||
}
|
||||
@@ -0,0 +1,316 @@
|
||||
using System.Collections.Immutable;
|
||||
using MongoDB.Bson.Serialization.Attributes;
|
||||
using MongoDB.Driver;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo;
|
||||
|
||||
/// <summary>
|
||||
/// MongoDB record for timeline events.
|
||||
/// </summary>
|
||||
[BsonIgnoreExtraElements]
|
||||
internal sealed class VexTimelineEventRecord
|
||||
{
|
||||
[BsonId]
|
||||
public string Id { get; set; } = default!;
|
||||
|
||||
public string Tenant { get; set; } = default!;
|
||||
|
||||
public string ProviderId { get; set; } = default!;
|
||||
|
||||
public string StreamId { get; set; } = default!;
|
||||
|
||||
public string EventType { get; set; } = default!;
|
||||
|
||||
public string TraceId { get; set; } = default!;
|
||||
|
||||
public string JustificationSummary { get; set; } = string.Empty;
|
||||
|
||||
public string? EvidenceHash { get; set; }
|
||||
|
||||
public string? PayloadHash { get; set; }
|
||||
|
||||
public DateTime CreatedAt { get; set; }
|
||||
= DateTime.SpecifyKind(DateTime.UtcNow, DateTimeKind.Utc);
|
||||
|
||||
public Dictionary<string, string> Attributes { get; set; } = new(StringComparer.Ordinal);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// MongoDB implementation of the timeline event store.
|
||||
/// </summary>
|
||||
internal sealed class MongoVexTimelineEventStore : IVexTimelineEventStore
|
||||
{
|
||||
private readonly IMongoCollection<VexTimelineEventRecord> _collection;
|
||||
|
||||
public MongoVexTimelineEventStore(IMongoDatabase database)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(database);
|
||||
_collection = database.GetCollection<VexTimelineEventRecord>(VexMongoCollectionNames.TimelineEvents);
|
||||
}
|
||||
|
||||
public async ValueTask<string> InsertAsync(
|
||||
TimelineEvent evt,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(evt);
|
||||
|
||||
var record = ToRecord(evt);
|
||||
|
||||
try
|
||||
{
|
||||
await _collection.InsertOneAsync(record, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
return record.Id;
|
||||
}
|
||||
catch (MongoWriteException ex) when (ex.WriteError?.Category == ServerErrorCategory.DuplicateKey)
|
||||
{
|
||||
// Event already exists, return the ID anyway
|
||||
return record.Id;
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask<int> InsertManyAsync(
|
||||
string tenant,
|
||||
IEnumerable<TimelineEvent> events,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var records = events
|
||||
.Where(e => e is not null && string.Equals(NormalizeTenant(e.Tenant), normalizedTenant, StringComparison.Ordinal))
|
||||
.Select(ToRecord)
|
||||
.ToList();
|
||||
|
||||
if (records.Count == 0)
|
||||
{
|
||||
return 0;
|
||||
}
|
||||
|
||||
var options = new InsertManyOptions { IsOrdered = false };
|
||||
try
|
||||
{
|
||||
await _collection.InsertManyAsync(records, options, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
return records.Count;
|
||||
}
|
||||
catch (MongoBulkWriteException<VexTimelineEventRecord> ex)
|
||||
{
|
||||
var duplicates = ex.WriteErrors?.Count(e => e.Category == ServerErrorCategory.DuplicateKey) ?? 0;
|
||||
return records.Count - duplicates;
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<TimelineEvent>> FindByTimeRangeAsync(
|
||||
string tenant,
|
||||
DateTimeOffset from,
|
||||
DateTimeOffset to,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var fromUtc = from.UtcDateTime;
|
||||
var toUtc = to.UtcDateTime;
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.And(
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexTimelineEventRecord>.Filter.Gte(r => r.CreatedAt, fromUtc),
|
||||
Builders<VexTimelineEventRecord>.Filter.Lte(r => r.CreatedAt, toUtc));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexTimelineEventRecord>.Sort.Ascending(r => r.CreatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<TimelineEvent>> FindByTraceIdAsync(
|
||||
string tenant,
|
||||
string traceId,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedTraceId = traceId?.Trim() ?? throw new ArgumentNullException(nameof(traceId));
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.And(
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.TraceId, normalizedTraceId));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexTimelineEventRecord>.Sort.Ascending(r => r.CreatedAt))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<TimelineEvent>> FindByProviderAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedProvider = providerId?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(providerId));
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.And(
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.ProviderId, normalizedProvider));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexTimelineEventRecord>.Sort.Descending(r => r.CreatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<TimelineEvent>> FindByEventTypeAsync(
|
||||
string tenant,
|
||||
string eventType,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedType = eventType?.Trim().ToLowerInvariant()
|
||||
?? throw new ArgumentNullException(nameof(eventType));
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.And(
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.EventType, normalizedType));
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexTimelineEventRecord>.Sort.Descending(r => r.CreatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<TimelineEvent>> GetRecentAsync(
|
||||
string tenant,
|
||||
int limit,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant);
|
||||
|
||||
var records = await _collection
|
||||
.Find(filter)
|
||||
.Sort(Builders<VexTimelineEventRecord>.Sort.Descending(r => r.CreatedAt))
|
||||
.Limit(Math.Max(1, limit))
|
||||
.ToListAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return records.Select(ToModel).ToList();
|
||||
}
|
||||
|
||||
public async ValueTask<TimelineEvent?> GetByIdAsync(
|
||||
string tenant,
|
||||
string eventId,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var normalizedId = eventId?.Trim() ?? throw new ArgumentNullException(nameof(eventId));
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.And(
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Id, normalizedId));
|
||||
|
||||
var record = await _collection
|
||||
.Find(filter)
|
||||
.FirstOrDefaultAsync(cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
return record is null ? null : ToModel(record);
|
||||
}
|
||||
|
||||
public async ValueTask<long> CountAsync(
|
||||
string tenant,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant);
|
||||
|
||||
return await _collection
|
||||
.CountDocumentsAsync(filter, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
public async ValueTask<long> CountInRangeAsync(
|
||||
string tenant,
|
||||
DateTimeOffset from,
|
||||
DateTimeOffset to,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var normalizedTenant = NormalizeTenant(tenant);
|
||||
var fromUtc = from.UtcDateTime;
|
||||
var toUtc = to.UtcDateTime;
|
||||
|
||||
var filter = Builders<VexTimelineEventRecord>.Filter.And(
|
||||
Builders<VexTimelineEventRecord>.Filter.Eq(r => r.Tenant, normalizedTenant),
|
||||
Builders<VexTimelineEventRecord>.Filter.Gte(r => r.CreatedAt, fromUtc),
|
||||
Builders<VexTimelineEventRecord>.Filter.Lte(r => r.CreatedAt, toUtc));
|
||||
|
||||
return await _collection
|
||||
.CountDocumentsAsync(filter, cancellationToken: cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static string NormalizeTenant(string tenant)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(tenant))
|
||||
{
|
||||
throw new ArgumentException("tenant is required", nameof(tenant));
|
||||
}
|
||||
|
||||
return tenant.Trim().ToLowerInvariant();
|
||||
}
|
||||
|
||||
private static VexTimelineEventRecord ToRecord(TimelineEvent evt)
|
||||
{
|
||||
return new VexTimelineEventRecord
|
||||
{
|
||||
Id = evt.EventId,
|
||||
Tenant = evt.Tenant,
|
||||
ProviderId = evt.ProviderId.ToLowerInvariant(),
|
||||
StreamId = evt.StreamId.ToLowerInvariant(),
|
||||
EventType = evt.EventType.ToLowerInvariant(),
|
||||
TraceId = evt.TraceId,
|
||||
JustificationSummary = evt.JustificationSummary,
|
||||
EvidenceHash = evt.EvidenceHash,
|
||||
PayloadHash = evt.PayloadHash,
|
||||
CreatedAt = evt.CreatedAt.UtcDateTime,
|
||||
Attributes = evt.Attributes.ToDictionary(kvp => kvp.Key, kvp => kvp.Value, StringComparer.Ordinal)
|
||||
};
|
||||
}
|
||||
|
||||
private static TimelineEvent ToModel(VexTimelineEventRecord record)
|
||||
{
|
||||
var attributes = record.Attributes?.ToImmutableDictionary(StringComparer.Ordinal)
|
||||
?? ImmutableDictionary<string, string>.Empty;
|
||||
|
||||
return new TimelineEvent(
|
||||
eventId: record.Id,
|
||||
tenant: record.Tenant,
|
||||
providerId: record.ProviderId,
|
||||
streamId: record.StreamId,
|
||||
eventType: record.EventType,
|
||||
traceId: record.TraceId,
|
||||
justificationSummary: record.JustificationSummary,
|
||||
createdAt: new DateTimeOffset(DateTime.SpecifyKind(record.CreatedAt, DateTimeKind.Utc)),
|
||||
evidenceHash: record.EvidenceHash,
|
||||
payloadHash: record.PayloadHash,
|
||||
attributes: attributes);
|
||||
}
|
||||
}
|
||||
@@ -60,11 +60,19 @@ public static class VexMongoServiceCollectionExtensions
|
||||
services.AddScoped<IAirgapImportStore, MongoAirgapImportStore>();
|
||||
services.AddScoped<VexStatementBackfillService>();
|
||||
services.AddScoped<IVexObservationLookup, MongoVexObservationLookup>();
|
||||
services.AddScoped<IVexObservationStore, MongoVexObservationStore>();
|
||||
services.AddScoped<IVexLinksetStore, MongoVexLinksetStore>();
|
||||
services.AddScoped<IVexLinksetEventPublisher, MongoVexLinksetEventPublisher>();
|
||||
services.AddScoped<VexLinksetDisagreementService>();
|
||||
services.AddScoped<IVexTimelineEventStore, MongoVexTimelineEventStore>();
|
||||
services.AddScoped<IVexTimelineEventEmitter, VexTimelineEventEmitter>();
|
||||
services.AddSingleton<IVexMongoMigration, VexInitialIndexMigration>();
|
||||
services.AddSingleton<IVexMongoMigration, VexTimelineEventIndexMigration>();
|
||||
services.AddSingleton<IVexMongoMigration, VexRawSchemaMigration>();
|
||||
services.AddSingleton<IVexMongoMigration, VexConsensusSignalsMigration>();
|
||||
services.AddSingleton<IVexMongoMigration, VexConsensusHoldMigration>();
|
||||
services.AddSingleton<IVexMongoMigration, VexObservationCollectionsMigration>();
|
||||
services.AddSingleton<IVexMongoMigration, VexRawIdempotencyIndexMigration>();
|
||||
services.AddSingleton<VexMongoMigrationRunner>();
|
||||
services.AddHostedService<VexMongoMigrationHostedService>();
|
||||
return services;
|
||||
|
||||
@@ -0,0 +1,299 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Text.RegularExpressions;
|
||||
using MongoDB.Bson;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo.Validation;
|
||||
|
||||
/// <summary>
|
||||
/// Validates VEX raw documents against the schema defined in <see cref="Migrations.VexRawSchemaMigration"/>.
|
||||
/// Provides programmatic validation for operators to prove Excititor stores only immutable evidence.
|
||||
/// </summary>
|
||||
public static class VexRawSchemaValidator
|
||||
{
|
||||
private static readonly ImmutableHashSet<string> ValidFormats = ImmutableHashSet.Create(
|
||||
StringComparer.OrdinalIgnoreCase,
|
||||
"csaf", "cyclonedx", "openvex");
|
||||
|
||||
private static readonly ImmutableHashSet<BsonType> ValidContentTypes = ImmutableHashSet.Create(
|
||||
BsonType.Binary, BsonType.String);
|
||||
|
||||
private static readonly ImmutableHashSet<BsonType> ValidGridFsTypes = ImmutableHashSet.Create(
|
||||
BsonType.ObjectId, BsonType.Null, BsonType.String);
|
||||
|
||||
/// <summary>
|
||||
/// Validates a VEX raw document against the schema requirements.
|
||||
/// </summary>
|
||||
/// <param name="document">The document to validate.</param>
|
||||
/// <returns>Validation result with any violations found.</returns>
|
||||
public static VexRawValidationResult Validate(BsonDocument document)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(document);
|
||||
|
||||
var violations = new List<VexRawSchemaViolation>();
|
||||
|
||||
// Required fields
|
||||
ValidateRequired(document, "_id", violations);
|
||||
ValidateRequired(document, "providerId", violations);
|
||||
ValidateRequired(document, "format", violations);
|
||||
ValidateRequired(document, "sourceUri", violations);
|
||||
ValidateRequired(document, "retrievedAt", violations);
|
||||
ValidateRequired(document, "digest", violations);
|
||||
|
||||
// Field types and constraints
|
||||
ValidateStringField(document, "_id", minLength: 1, violations);
|
||||
ValidateStringField(document, "providerId", minLength: 1, violations);
|
||||
ValidateFormatEnum(document, violations);
|
||||
ValidateStringField(document, "sourceUri", minLength: 1, violations);
|
||||
ValidateDateField(document, "retrievedAt", violations);
|
||||
ValidateStringField(document, "digest", minLength: 32, violations);
|
||||
|
||||
// Optional fields with type constraints
|
||||
if (document.Contains("content"))
|
||||
{
|
||||
ValidateContentField(document, violations);
|
||||
}
|
||||
|
||||
if (document.Contains("gridFsObjectId"))
|
||||
{
|
||||
ValidateGridFsObjectIdField(document, violations);
|
||||
}
|
||||
|
||||
if (document.Contains("metadata"))
|
||||
{
|
||||
ValidateMetadataField(document, violations);
|
||||
}
|
||||
|
||||
return new VexRawValidationResult(
|
||||
document.GetValue("_id", BsonNull.Value).ToString() ?? "<unknown>",
|
||||
violations.Count == 0,
|
||||
violations.ToImmutableArray());
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Validates multiple documents and returns aggregated results.
|
||||
/// </summary>
|
||||
public static VexRawBatchValidationResult ValidateBatch(IEnumerable<BsonDocument> documents)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(documents);
|
||||
|
||||
var results = new List<VexRawValidationResult>();
|
||||
foreach (var doc in documents)
|
||||
{
|
||||
results.Add(Validate(doc));
|
||||
}
|
||||
|
||||
var valid = results.Count(r => r.IsValid);
|
||||
var invalid = results.Count(r => !r.IsValid);
|
||||
|
||||
return new VexRawBatchValidationResult(
|
||||
results.Count,
|
||||
valid,
|
||||
invalid,
|
||||
results.Where(r => !r.IsValid).ToImmutableArray());
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the MongoDB JSON Schema document for offline validation.
|
||||
/// </summary>
|
||||
public static BsonDocument GetJsonSchema()
|
||||
{
|
||||
var properties = new BsonDocument
|
||||
{
|
||||
{ "_id", new BsonDocument { { "bsonType", "string" }, { "description", "Content digest serving as immutable key" } } },
|
||||
{ "providerId", new BsonDocument { { "bsonType", "string" }, { "minLength", 1 }, { "description", "VEX provider identifier" } } },
|
||||
{ "format", new BsonDocument
|
||||
{
|
||||
{ "bsonType", "string" },
|
||||
{ "enum", new BsonArray { "csaf", "cyclonedx", "openvex" } },
|
||||
{ "description", "VEX document format" }
|
||||
}
|
||||
},
|
||||
{ "sourceUri", new BsonDocument { { "bsonType", "string" }, { "minLength", 1 }, { "description", "Original source URI" } } },
|
||||
{ "retrievedAt", new BsonDocument { { "bsonType", "date" }, { "description", "Timestamp when document was fetched" } } },
|
||||
{ "digest", new BsonDocument { { "bsonType", "string" }, { "minLength", 32 }, { "description", "Content hash (SHA-256 hex)" } } },
|
||||
{ "content", new BsonDocument
|
||||
{
|
||||
{ "bsonType", new BsonArray { "binData", "string" } },
|
||||
{ "description", "Raw document content (binary or base64 string)" }
|
||||
}
|
||||
},
|
||||
{ "gridFsObjectId", new BsonDocument
|
||||
{
|
||||
{ "bsonType", new BsonArray { "objectId", "null", "string" } },
|
||||
{ "description", "GridFS reference for large documents" }
|
||||
}
|
||||
},
|
||||
{ "metadata", new BsonDocument
|
||||
{
|
||||
{ "bsonType", "object" },
|
||||
{ "additionalProperties", true },
|
||||
{ "description", "Provider-specific metadata (string values only)" }
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
return new BsonDocument
|
||||
{
|
||||
{
|
||||
"$jsonSchema",
|
||||
new BsonDocument
|
||||
{
|
||||
{ "bsonType", "object" },
|
||||
{ "title", "VEX Raw Document Schema" },
|
||||
{ "description", "Schema for immutable VEX evidence storage. Documents are content-addressed and must not be modified after insertion." },
|
||||
{ "required", new BsonArray { "_id", "providerId", "format", "sourceUri", "retrievedAt", "digest" } },
|
||||
{ "properties", properties },
|
||||
{ "additionalProperties", true }
|
||||
}
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the schema as a JSON string for operator documentation.
|
||||
/// </summary>
|
||||
public static string GetJsonSchemaAsJson()
|
||||
{
|
||||
return GetJsonSchema().ToJson(new MongoDB.Bson.IO.JsonWriterSettings { Indent = true });
|
||||
}
|
||||
|
||||
private static void ValidateRequired(BsonDocument doc, string field, List<VexRawSchemaViolation> violations)
|
||||
{
|
||||
if (!doc.Contains(field) || doc[field].IsBsonNull)
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation(field, $"Required field '{field}' is missing or null"));
|
||||
}
|
||||
}
|
||||
|
||||
private static void ValidateStringField(BsonDocument doc, string field, int minLength, List<VexRawSchemaViolation> violations)
|
||||
{
|
||||
if (!doc.Contains(field))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
var value = doc[field];
|
||||
if (value.IsBsonNull)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
if (!value.IsString)
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation(field, $"Field '{field}' must be a string, got {value.BsonType}"));
|
||||
return;
|
||||
}
|
||||
|
||||
if (value.AsString.Length < minLength)
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation(field, $"Field '{field}' must have minimum length {minLength}, got {value.AsString.Length}"));
|
||||
}
|
||||
}
|
||||
|
||||
private static void ValidateFormatEnum(BsonDocument doc, List<VexRawSchemaViolation> violations)
|
||||
{
|
||||
if (!doc.Contains("format"))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
var value = doc["format"];
|
||||
if (value.IsBsonNull || !value.IsString)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
if (!ValidFormats.Contains(value.AsString))
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation("format", $"Field 'format' must be one of [{string.Join(", ", ValidFormats)}], got '{value.AsString}'"));
|
||||
}
|
||||
}
|
||||
|
||||
private static void ValidateDateField(BsonDocument doc, string field, List<VexRawSchemaViolation> violations)
|
||||
{
|
||||
if (!doc.Contains(field))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
var value = doc[field];
|
||||
if (value.IsBsonNull)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
if (value.BsonType != BsonType.DateTime)
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation(field, $"Field '{field}' must be a date, got {value.BsonType}"));
|
||||
}
|
||||
}
|
||||
|
||||
private static void ValidateContentField(BsonDocument doc, List<VexRawSchemaViolation> violations)
|
||||
{
|
||||
var value = doc["content"];
|
||||
if (value.IsBsonNull)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
if (!ValidContentTypes.Contains(value.BsonType))
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation("content", $"Field 'content' must be binary or string, got {value.BsonType}"));
|
||||
}
|
||||
}
|
||||
|
||||
private static void ValidateGridFsObjectIdField(BsonDocument doc, List<VexRawSchemaViolation> violations)
|
||||
{
|
||||
var value = doc["gridFsObjectId"];
|
||||
if (!ValidGridFsTypes.Contains(value.BsonType))
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation("gridFsObjectId", $"Field 'gridFsObjectId' must be objectId, null, or string, got {value.BsonType}"));
|
||||
}
|
||||
}
|
||||
|
||||
private static void ValidateMetadataField(BsonDocument doc, List<VexRawSchemaViolation> violations)
|
||||
{
|
||||
var value = doc["metadata"];
|
||||
if (value.IsBsonNull)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
if (value.BsonType != BsonType.Document)
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation("metadata", $"Field 'metadata' must be an object, got {value.BsonType}"));
|
||||
return;
|
||||
}
|
||||
|
||||
var metadata = value.AsBsonDocument;
|
||||
foreach (var element in metadata)
|
||||
{
|
||||
if (!element.Value.IsString && !element.Value.IsBsonNull)
|
||||
{
|
||||
violations.Add(new VexRawSchemaViolation($"metadata.{element.Name}", $"Metadata field '{element.Name}' must be a string, got {element.Value.BsonType}"));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Represents a schema violation found during validation.
|
||||
/// </summary>
|
||||
public sealed record VexRawSchemaViolation(string Field, string Message);
|
||||
|
||||
/// <summary>
|
||||
/// Result of validating a single VEX raw document.
|
||||
/// </summary>
|
||||
public sealed record VexRawValidationResult(
|
||||
string DocumentId,
|
||||
bool IsValid,
|
||||
ImmutableArray<VexRawSchemaViolation> Violations);
|
||||
|
||||
/// <summary>
|
||||
/// Result of validating a batch of VEX raw documents.
|
||||
/// </summary>
|
||||
public sealed record VexRawBatchValidationResult(
|
||||
int TotalCount,
|
||||
int ValidCount,
|
||||
int InvalidCount,
|
||||
ImmutableArray<VexRawValidationResult> InvalidDocuments);
|
||||
@@ -47,6 +47,7 @@ public static class VexMongoMappingRegistry
|
||||
RegisterClassMap<VexConnectorStateDocument>();
|
||||
RegisterClassMap<VexConsensusHoldRecord>();
|
||||
RegisterClassMap<AirgapImportRecord>();
|
||||
RegisterClassMap<VexTimelineEventRecord>();
|
||||
}
|
||||
|
||||
private static void RegisterClassMap<TDocument>()
|
||||
@@ -80,5 +81,7 @@ public static class VexMongoCollectionNames
|
||||
public const string Attestations = "vex.attestations";
|
||||
public const string Observations = "vex.observations";
|
||||
public const string Linksets = "vex.linksets";
|
||||
public const string LinksetEvents = "vex.linkset_events";
|
||||
public const string AirgapImports = "vex.airgap_imports";
|
||||
public const string TimelineEvents = "vex.timeline_events";
|
||||
}
|
||||
|
||||
@@ -490,6 +490,10 @@ internal sealed class VexLinksetRecord
|
||||
|
||||
public DateTime CreatedAt { get; set; } = DateTime.SpecifyKind(DateTime.UtcNow, DateTimeKind.Utc);
|
||||
|
||||
public DateTime UpdatedAt { get; set; } = DateTime.SpecifyKind(DateTime.UtcNow, DateTimeKind.Utc);
|
||||
|
||||
public List<VexObservationLinksetObservationRecord> Observations { get; set; } = new();
|
||||
|
||||
public List<VexLinksetDisagreementRecord> Disagreements { get; set; } = new();
|
||||
}
|
||||
|
||||
@@ -1310,6 +1314,21 @@ internal sealed class VexConnectorStateDocument
|
||||
public string? LastFailureReason { get; set; }
|
||||
= null;
|
||||
|
||||
public DateTime? LastHeartbeatAt { get; set; }
|
||||
= null;
|
||||
|
||||
public string? LastHeartbeatStatus { get; set; }
|
||||
= null;
|
||||
|
||||
public string? LastArtifactHash { get; set; }
|
||||
= null;
|
||||
|
||||
public string? LastArtifactKind { get; set; }
|
||||
= null;
|
||||
|
||||
public string? LastCheckpoint { get; set; }
|
||||
= null;
|
||||
|
||||
public static VexConnectorStateDocument FromRecord(VexConnectorState state)
|
||||
=> new()
|
||||
{
|
||||
@@ -1323,6 +1342,11 @@ internal sealed class VexConnectorStateDocument
|
||||
FailureCount = state.FailureCount,
|
||||
NextEligibleRun = state.NextEligibleRun?.UtcDateTime,
|
||||
LastFailureReason = state.LastFailureReason,
|
||||
LastHeartbeatAt = state.LastHeartbeatAt?.UtcDateTime,
|
||||
LastHeartbeatStatus = state.LastHeartbeatStatus,
|
||||
LastArtifactHash = state.LastArtifactHash,
|
||||
LastArtifactKind = state.LastArtifactKind,
|
||||
LastCheckpoint = state.LastCheckpoint,
|
||||
};
|
||||
|
||||
public VexConnectorState ToRecord()
|
||||
@@ -1336,6 +1360,9 @@ internal sealed class VexConnectorStateDocument
|
||||
var nextEligibleRun = NextEligibleRun.HasValue
|
||||
? new DateTimeOffset(DateTime.SpecifyKind(NextEligibleRun.Value, DateTimeKind.Utc))
|
||||
: (DateTimeOffset?)null;
|
||||
var lastHeartbeatAt = LastHeartbeatAt.HasValue
|
||||
? new DateTimeOffset(DateTime.SpecifyKind(LastHeartbeatAt.Value, DateTimeKind.Utc))
|
||||
: (DateTimeOffset?)null;
|
||||
|
||||
return new VexConnectorState(
|
||||
ConnectorId,
|
||||
@@ -1345,6 +1372,52 @@ internal sealed class VexConnectorStateDocument
|
||||
lastSuccessAt,
|
||||
FailureCount,
|
||||
nextEligibleRun,
|
||||
string.IsNullOrWhiteSpace(LastFailureReason) ? null : LastFailureReason);
|
||||
string.IsNullOrWhiteSpace(LastFailureReason) ? null : LastFailureReason,
|
||||
lastHeartbeatAt,
|
||||
LastHeartbeatStatus,
|
||||
LastArtifactHash,
|
||||
LastArtifactKind,
|
||||
LastCheckpoint);
|
||||
}
|
||||
}
|
||||
|
||||
[BsonIgnoreExtraElements]
|
||||
internal sealed class VexLinksetEventRecord
|
||||
{
|
||||
[BsonId]
|
||||
public string Id { get; set; } = default!;
|
||||
|
||||
public string EventType { get; set; } = default!;
|
||||
|
||||
public string Tenant { get; set; } = default!;
|
||||
|
||||
public string LinksetId { get; set; } = default!;
|
||||
|
||||
public string VulnerabilityId { get; set; } = default!;
|
||||
|
||||
public string ProductKey { get; set; } = default!;
|
||||
|
||||
public List<VexLinksetEventObservationRecord> Observations { get; set; } = new();
|
||||
|
||||
public List<VexLinksetDisagreementRecord> Disagreements { get; set; } = new();
|
||||
|
||||
public DateTime CreatedAtUtc { get; set; } = DateTime.SpecifyKind(DateTime.UtcNow, DateTimeKind.Utc);
|
||||
|
||||
public DateTime PublishedAtUtc { get; set; } = DateTime.SpecifyKind(DateTime.UtcNow, DateTimeKind.Utc);
|
||||
|
||||
public int ConflictCount { get; set; } = 0;
|
||||
|
||||
public int ObservationCount { get; set; } = 0;
|
||||
}
|
||||
|
||||
[BsonIgnoreExtraElements]
|
||||
internal sealed class VexLinksetEventObservationRecord
|
||||
{
|
||||
public string ObservationId { get; set; } = default!;
|
||||
|
||||
public string ProviderId { get; set; } = default!;
|
||||
|
||||
public string Status { get; set; } = default!;
|
||||
|
||||
public double? Confidence { get; set; } = null;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,169 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
|
||||
namespace StellaOps.Excititor.Storage.Mongo;
|
||||
|
||||
/// <summary>
|
||||
/// Default implementation of <see cref="IVexTimelineEventEmitter"/> that persists events to MongoDB.
|
||||
/// </summary>
|
||||
internal sealed class VexTimelineEventEmitter : IVexTimelineEventEmitter
|
||||
{
|
||||
private readonly IVexTimelineEventStore _store;
|
||||
private readonly ILogger<VexTimelineEventEmitter> _logger;
|
||||
private readonly TimeProvider _timeProvider;
|
||||
|
||||
public VexTimelineEventEmitter(
|
||||
IVexTimelineEventStore store,
|
||||
ILogger<VexTimelineEventEmitter> logger,
|
||||
TimeProvider? timeProvider = null)
|
||||
{
|
||||
_store = store ?? throw new ArgumentNullException(nameof(store));
|
||||
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
|
||||
_timeProvider = timeProvider ?? TimeProvider.System;
|
||||
}
|
||||
|
||||
public async ValueTask EmitObservationIngestAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
string streamId,
|
||||
string traceId,
|
||||
string observationId,
|
||||
string evidenceHash,
|
||||
string justificationSummary,
|
||||
ImmutableDictionary<string, string>? attributes = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
var eventAttributes = (attributes ?? ImmutableDictionary<string, string>.Empty)
|
||||
.SetItem(VexTimelineEventAttributes.ObservationId, observationId);
|
||||
|
||||
var evt = new TimelineEvent(
|
||||
eventId: GenerateEventId(tenant, providerId, VexTimelineEventTypes.ObservationIngested),
|
||||
tenant: tenant,
|
||||
providerId: providerId,
|
||||
streamId: streamId,
|
||||
eventType: VexTimelineEventTypes.ObservationIngested,
|
||||
traceId: traceId,
|
||||
justificationSummary: justificationSummary,
|
||||
createdAt: _timeProvider.GetUtcNow(),
|
||||
evidenceHash: evidenceHash,
|
||||
payloadHash: null,
|
||||
attributes: eventAttributes);
|
||||
|
||||
await EmitAsync(evt, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
public async ValueTask EmitLinksetUpdateAsync(
|
||||
string tenant,
|
||||
string providerId,
|
||||
string streamId,
|
||||
string traceId,
|
||||
string linksetId,
|
||||
string vulnerabilityId,
|
||||
string productKey,
|
||||
string payloadHash,
|
||||
string justificationSummary,
|
||||
ImmutableDictionary<string, string>? attributes = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
var eventAttributes = (attributes ?? ImmutableDictionary<string, string>.Empty)
|
||||
.SetItem(VexTimelineEventAttributes.LinksetId, linksetId)
|
||||
.SetItem(VexTimelineEventAttributes.VulnerabilityId, vulnerabilityId)
|
||||
.SetItem(VexTimelineEventAttributes.ProductKey, productKey);
|
||||
|
||||
var evt = new TimelineEvent(
|
||||
eventId: GenerateEventId(tenant, providerId, VexTimelineEventTypes.LinksetUpdated),
|
||||
tenant: tenant,
|
||||
providerId: providerId,
|
||||
streamId: streamId,
|
||||
eventType: VexTimelineEventTypes.LinksetUpdated,
|
||||
traceId: traceId,
|
||||
justificationSummary: justificationSummary,
|
||||
createdAt: _timeProvider.GetUtcNow(),
|
||||
evidenceHash: null,
|
||||
payloadHash: payloadHash,
|
||||
attributes: eventAttributes);
|
||||
|
||||
await EmitAsync(evt, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
public async ValueTask EmitAsync(
|
||||
TimelineEvent evt,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(evt);
|
||||
|
||||
try
|
||||
{
|
||||
var eventId = await _store.InsertAsync(evt, cancellationToken).ConfigureAwait(false);
|
||||
|
||||
_logger.LogDebug(
|
||||
"Timeline event emitted: {EventType} for tenant {Tenant}, provider {ProviderId}, trace {TraceId}",
|
||||
evt.EventType,
|
||||
evt.Tenant,
|
||||
evt.ProviderId,
|
||||
evt.TraceId);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogWarning(
|
||||
ex,
|
||||
"Failed to emit timeline event {EventType} for tenant {Tenant}, provider {ProviderId}: {Message}",
|
||||
evt.EventType,
|
||||
evt.Tenant,
|
||||
evt.ProviderId,
|
||||
ex.Message);
|
||||
|
||||
// Don't throw - timeline events are non-critical and shouldn't block main operations
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask EmitBatchAsync(
|
||||
string tenant,
|
||||
IEnumerable<TimelineEvent> events,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(events);
|
||||
|
||||
var eventList = events.ToList();
|
||||
if (eventList.Count == 0)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
var insertedCount = await _store.InsertManyAsync(tenant, eventList, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
_logger.LogDebug(
|
||||
"Batch timeline events emitted: {InsertedCount}/{TotalCount} for tenant {Tenant}",
|
||||
insertedCount,
|
||||
eventList.Count,
|
||||
tenant);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogWarning(
|
||||
ex,
|
||||
"Failed to emit batch timeline events for tenant {Tenant}: {Message}",
|
||||
tenant,
|
||||
ex.Message);
|
||||
|
||||
// Don't throw - timeline events are non-critical
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Generates a deterministic event ID based on tenant, provider, event type, and timestamp.
|
||||
/// </summary>
|
||||
private string GenerateEventId(string tenant, string providerId, string eventType)
|
||||
{
|
||||
var timestamp = _timeProvider.GetUtcNow().ToUnixTimeMilliseconds();
|
||||
var input = $"{tenant}|{providerId}|{eventType}|{timestamp}|{Guid.NewGuid():N}";
|
||||
var hash = SHA256.HashData(Encoding.UTF8.GetBytes(input));
|
||||
return $"evt:{Convert.ToHexString(hash).ToLowerInvariant()[..32]}";
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,170 @@
|
||||
using System;
|
||||
using System.Linq;
|
||||
using StellaOps.Excititor.Core.Canonicalization;
|
||||
using Xunit;
|
||||
|
||||
namespace StellaOps.Excititor.Core.UnitTests.Canonicalization;
|
||||
|
||||
public class VexAdvisoryKeyCanonicalizerTests
|
||||
{
|
||||
private readonly VexAdvisoryKeyCanonicalizer _canonicalizer = new();
|
||||
|
||||
[Theory]
|
||||
[InlineData("CVE-2025-12345", "CVE-2025-12345", VexAdvisoryScope.Global)]
|
||||
[InlineData("cve-2025-12345", "CVE-2025-12345", VexAdvisoryScope.Global)]
|
||||
[InlineData("CVE-2024-1234567", "CVE-2024-1234567", VexAdvisoryScope.Global)]
|
||||
public void Canonicalize_Cve_ReturnsGlobalScope(string input, string expectedKey, VexAdvisoryScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(expectedKey, result.AdvisoryKey);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Single(result.Links);
|
||||
Assert.Equal("cve", result.Links[0].Type);
|
||||
Assert.True(result.Links[0].IsOriginal);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("GHSA-abcd-efgh-ijkl", "ECO:GHSA-ABCD-EFGH-IJKL", VexAdvisoryScope.Ecosystem)]
|
||||
[InlineData("ghsa-1234-5678-90ab", "ECO:GHSA-1234-5678-90AB", VexAdvisoryScope.Ecosystem)]
|
||||
public void Canonicalize_Ghsa_ReturnsEcosystemScope(string input, string expectedKey, VexAdvisoryScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(expectedKey, result.AdvisoryKey);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Equal("ghsa", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("RHSA-2025:1234", "VND:RHSA-2025:1234", VexAdvisoryScope.Vendor)]
|
||||
[InlineData("RHBA-2024:5678", "VND:RHBA-2024:5678", VexAdvisoryScope.Vendor)]
|
||||
public void Canonicalize_Rhsa_ReturnsVendorScope(string input, string expectedKey, VexAdvisoryScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(expectedKey, result.AdvisoryKey);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Equal("rhsa", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("DSA-5678", "DST:DSA-5678", VexAdvisoryScope.Distribution)]
|
||||
[InlineData("DSA-1234-1", "DST:DSA-1234-1", VexAdvisoryScope.Distribution)]
|
||||
[InlineData("USN-6543", "DST:USN-6543", VexAdvisoryScope.Distribution)]
|
||||
[InlineData("USN-1234-2", "DST:USN-1234-2", VexAdvisoryScope.Distribution)]
|
||||
public void Canonicalize_DistributionIds_ReturnsDistributionScope(string input, string expectedKey, VexAdvisoryScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(expectedKey, result.AdvisoryKey);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_WithAliases_PreservesAllLinks()
|
||||
{
|
||||
var aliases = new[] { "RHSA-2025:1234", "GHSA-abcd-efgh-ijkl" };
|
||||
|
||||
var result = _canonicalizer.Canonicalize("CVE-2025-12345", aliases);
|
||||
|
||||
Assert.Equal("CVE-2025-12345", result.AdvisoryKey);
|
||||
Assert.Equal(3, result.Links.Length);
|
||||
|
||||
var original = result.Links.Single(l => l.IsOriginal);
|
||||
Assert.Equal("CVE-2025-12345", original.Identifier);
|
||||
Assert.Equal("cve", original.Type);
|
||||
|
||||
var nonOriginal = result.Links.Where(l => !l.IsOriginal).ToArray();
|
||||
Assert.Equal(2, nonOriginal.Length);
|
||||
Assert.Contains(nonOriginal, l => l.Type == "rhsa");
|
||||
Assert.Contains(nonOriginal, l => l.Type == "ghsa");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_WithDuplicateAliases_DeduplicatesLinks()
|
||||
{
|
||||
var aliases = new[] { "CVE-2025-12345", "cve-2025-12345", "RHSA-2025:1234" };
|
||||
|
||||
var result = _canonicalizer.Canonicalize("CVE-2025-12345", aliases);
|
||||
|
||||
// Should have 2 links: original CVE and RHSA (duplicates removed)
|
||||
Assert.Equal(2, result.Links.Length);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_UnknownFormat_ReturnsUnknownScope()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize("VENDOR-CUSTOM-12345");
|
||||
|
||||
Assert.Equal("UNK:VENDOR-CUSTOM-12345", result.AdvisoryKey);
|
||||
Assert.Equal(VexAdvisoryScope.Unknown, result.Scope);
|
||||
Assert.Equal("other", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_NullInput_ThrowsArgumentException()
|
||||
{
|
||||
Assert.ThrowsAny<ArgumentException>(() => _canonicalizer.Canonicalize(null!));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_EmptyInput_ThrowsArgumentException()
|
||||
{
|
||||
Assert.ThrowsAny<ArgumentException>(() => _canonicalizer.Canonicalize(""));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_WhitespaceInput_ThrowsArgumentException()
|
||||
{
|
||||
Assert.ThrowsAny<ArgumentException>(() => _canonicalizer.Canonicalize(" "));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ExtractCveFromAliases_WithCve_ReturnsCve()
|
||||
{
|
||||
var aliases = new[] { "RHSA-2025:1234", "CVE-2025-99999", "GHSA-xxxx-yyyy-zzzz" };
|
||||
|
||||
var cve = _canonicalizer.ExtractCveFromAliases(aliases);
|
||||
|
||||
Assert.Equal("CVE-2025-99999", cve);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ExtractCveFromAliases_WithoutCve_ReturnsNull()
|
||||
{
|
||||
var aliases = new[] { "RHSA-2025:1234", "GHSA-xxxx-yyyy-zzzz" };
|
||||
|
||||
var cve = _canonicalizer.ExtractCveFromAliases(aliases);
|
||||
|
||||
Assert.Null(cve);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ExtractCveFromAliases_NullInput_ReturnsNull()
|
||||
{
|
||||
var cve = _canonicalizer.ExtractCveFromAliases(null);
|
||||
|
||||
Assert.Null(cve);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void OriginalId_ReturnsOriginalIdentifier()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize("CVE-2025-12345");
|
||||
|
||||
Assert.Equal("CVE-2025-12345", result.OriginalId);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Aliases_ReturnsNonOriginalIdentifiers()
|
||||
{
|
||||
var aliases = new[] { "RHSA-2025:1234", "GHSA-abcd-efgh-ijkl" };
|
||||
var result = _canonicalizer.Canonicalize("CVE-2025-12345", aliases);
|
||||
|
||||
var aliasArray = result.Aliases.ToArray();
|
||||
Assert.Equal(2, aliasArray.Length);
|
||||
Assert.Contains("RHSA-2025:1234", aliasArray);
|
||||
Assert.Contains("GHSA-abcd-efgh-ijkl", aliasArray);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,235 @@
|
||||
using System;
|
||||
using System.Linq;
|
||||
using StellaOps.Excititor.Core.Canonicalization;
|
||||
using Xunit;
|
||||
|
||||
namespace StellaOps.Excititor.Core.UnitTests.Canonicalization;
|
||||
|
||||
public class VexProductKeyCanonicalizerTests
|
||||
{
|
||||
private readonly VexProductKeyCanonicalizer _canonicalizer = new();
|
||||
|
||||
[Theory]
|
||||
[InlineData("pkg:npm/leftpad@1.0.0", "pkg:npm/leftpad@1.0.0", VexProductKeyType.Purl, VexProductScope.Package)]
|
||||
[InlineData("pkg:maven/org.apache.log4j/log4j-core@2.17.0", "pkg:maven/org.apache.log4j/log4j-core@2.17.0", VexProductKeyType.Purl, VexProductScope.Package)]
|
||||
[InlineData("PKG:pypi/requests@2.28.0", "pkg:pypi/requests@2.28.0", VexProductKeyType.Purl, VexProductScope.Package)]
|
||||
public void Canonicalize_Purl_ReturnsPackageScope(string input, string expectedKey, VexProductKeyType expectedType, VexProductScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(expectedKey, result.ProductKey);
|
||||
Assert.Equal(expectedType, result.KeyType);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Single(result.Links);
|
||||
Assert.Equal("purl", result.Links[0].Type);
|
||||
Assert.True(result.Links[0].IsOriginal);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("cpe:2.3:a:apache:log4j:2.14.0:*:*:*:*:*:*:*", "cpe:2.3:a:apache:log4j:2.14.0:*:*:*:*:*:*:*", VexProductKeyType.Cpe, VexProductScope.Component)]
|
||||
[InlineData("cpe:/a:apache:log4j:2.14.0", "cpe:/a:apache:log4j:2.14.0", VexProductKeyType.Cpe, VexProductScope.Component)]
|
||||
[InlineData("CPE:2.3:a:vendor:product:1.0", "cpe:2.3:a:vendor:product:1.0", VexProductKeyType.Cpe, VexProductScope.Component)]
|
||||
public void Canonicalize_Cpe_ReturnsComponentScope(string input, string expectedKey, VexProductKeyType expectedType, VexProductScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(expectedKey, result.ProductKey);
|
||||
Assert.Equal(expectedType, result.KeyType);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Equal("cpe", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("openssl-3.0.9-1.el9.x86_64", VexProductKeyType.RpmNevra, VexProductScope.OsPackage)]
|
||||
[InlineData("kernel-5.14.0-284.25.1.el9_2.x86_64", VexProductKeyType.RpmNevra, VexProductScope.OsPackage)]
|
||||
public void Canonicalize_RpmNevra_ReturnsOsPackageScope(string input, VexProductKeyType expectedType, VexProductScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.StartsWith("rpm:", result.ProductKey);
|
||||
Assert.Equal(expectedType, result.KeyType);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Equal("rpmnevra", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("oci:ghcr.io/example/app@sha256:abc123", VexProductKeyType.OciImage, VexProductScope.Container)]
|
||||
[InlineData("oci:docker.io/library/nginx:1.25", VexProductKeyType.OciImage, VexProductScope.Container)]
|
||||
public void Canonicalize_OciImage_ReturnsContainerScope(string input, VexProductKeyType expectedType, VexProductScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(input, result.ProductKey);
|
||||
Assert.Equal(expectedType, result.KeyType);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Equal("ociimage", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("platform:redhat:rhel:9", VexProductKeyType.Platform, VexProductScope.Platform)]
|
||||
[InlineData("platform:ubuntu:jammy:22.04", VexProductKeyType.Platform, VexProductScope.Platform)]
|
||||
public void Canonicalize_Platform_ReturnsPlatformScope(string input, VexProductKeyType expectedType, VexProductScope expectedScope)
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(input);
|
||||
|
||||
Assert.Equal(input, result.ProductKey);
|
||||
Assert.Equal(expectedType, result.KeyType);
|
||||
Assert.Equal(expectedScope, result.Scope);
|
||||
Assert.Equal("platform", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_WithPurl_PrefersPurlAsCanonicalKey()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(
|
||||
originalKey: "openssl-3.0.9",
|
||||
purl: "pkg:rpm/redhat/openssl@3.0.9");
|
||||
|
||||
Assert.Equal("pkg:rpm/redhat/openssl@3.0.9", result.ProductKey);
|
||||
Assert.Equal(VexProductScope.Package, result.Scope);
|
||||
Assert.Equal(2, result.Links.Length);
|
||||
|
||||
var original = result.Links.Single(l => l.IsOriginal);
|
||||
Assert.Equal("openssl-3.0.9", original.Identifier);
|
||||
|
||||
var purlLink = result.Links.Single(l => l.Type == "purl");
|
||||
Assert.Equal("pkg:rpm/redhat/openssl@3.0.9", purlLink.Identifier);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_WithCpe_PrefersCpeWhenNoPurl()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(
|
||||
originalKey: "openssl",
|
||||
cpe: "cpe:2.3:a:openssl:openssl:3.0.9:*:*:*:*:*:*:*");
|
||||
|
||||
Assert.Equal("cpe:2.3:a:openssl:openssl:3.0.9:*:*:*:*:*:*:*", result.ProductKey);
|
||||
Assert.Equal(VexProductScope.Component, result.Scope);
|
||||
Assert.Equal(2, result.Links.Length);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_WithComponentIdentifiers_PreservesAllLinks()
|
||||
{
|
||||
var componentIds = new[]
|
||||
{
|
||||
"pkg:rpm/redhat/openssl@3.0.9",
|
||||
"cpe:2.3:a:openssl:openssl:3.0.9:*:*:*:*:*:*:*"
|
||||
};
|
||||
|
||||
var result = _canonicalizer.Canonicalize(
|
||||
originalKey: "openssl-3.0.9",
|
||||
componentIdentifiers: componentIds);
|
||||
|
||||
// PURL should be chosen as canonical key
|
||||
Assert.Equal("pkg:rpm/redhat/openssl@3.0.9", result.ProductKey);
|
||||
Assert.Equal(3, result.Links.Length);
|
||||
|
||||
var original = result.Links.Single(l => l.IsOriginal);
|
||||
Assert.Equal("openssl-3.0.9", original.Identifier);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_WithDuplicates_DeduplicatesLinks()
|
||||
{
|
||||
var componentIds = new[]
|
||||
{
|
||||
"pkg:npm/leftpad@1.0.0",
|
||||
"pkg:npm/leftpad@1.0.0", // Duplicate
|
||||
};
|
||||
|
||||
var result = _canonicalizer.Canonicalize(
|
||||
originalKey: "pkg:npm/leftpad@1.0.0",
|
||||
componentIdentifiers: componentIds);
|
||||
|
||||
Assert.Single(result.Links);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_UnknownFormat_ReturnsOtherType()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize("some-custom-product-id");
|
||||
|
||||
Assert.Equal("product:some-custom-product-id", result.ProductKey);
|
||||
Assert.Equal(VexProductKeyType.Other, result.KeyType);
|
||||
Assert.Equal(VexProductScope.Unknown, result.Scope);
|
||||
Assert.Equal("other", result.Links[0].Type);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_NullInput_ThrowsArgumentException()
|
||||
{
|
||||
Assert.ThrowsAny<ArgumentException>(() => _canonicalizer.Canonicalize(null!));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Canonicalize_EmptyInput_ThrowsArgumentException()
|
||||
{
|
||||
Assert.ThrowsAny<ArgumentException>(() => _canonicalizer.Canonicalize(""));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ExtractPurlFromIdentifiers_WithPurl_ReturnsPurl()
|
||||
{
|
||||
var identifiers = new[]
|
||||
{
|
||||
"cpe:2.3:a:openssl:openssl:3.0.9:*:*:*:*:*:*:*",
|
||||
"pkg:rpm/redhat/openssl@3.0.9",
|
||||
"openssl-3.0.9"
|
||||
};
|
||||
|
||||
var purl = _canonicalizer.ExtractPurlFromIdentifiers(identifiers);
|
||||
|
||||
Assert.Equal("pkg:rpm/redhat/openssl@3.0.9", purl);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ExtractPurlFromIdentifiers_WithoutPurl_ReturnsNull()
|
||||
{
|
||||
var identifiers = new[]
|
||||
{
|
||||
"cpe:2.3:a:openssl:openssl:3.0.9:*:*:*:*:*:*:*",
|
||||
"openssl-3.0.9"
|
||||
};
|
||||
|
||||
var purl = _canonicalizer.ExtractPurlFromIdentifiers(identifiers);
|
||||
|
||||
Assert.Null(purl);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ExtractPurlFromIdentifiers_NullInput_ReturnsNull()
|
||||
{
|
||||
var purl = _canonicalizer.ExtractPurlFromIdentifiers(null);
|
||||
|
||||
Assert.Null(purl);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void OriginalKey_ReturnsOriginalIdentifier()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize("pkg:npm/leftpad@1.0.0");
|
||||
|
||||
Assert.Equal("pkg:npm/leftpad@1.0.0", result.OriginalKey);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Purl_ReturnsPurlLink()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(
|
||||
originalKey: "openssl",
|
||||
purl: "pkg:rpm/redhat/openssl@3.0.9");
|
||||
|
||||
Assert.Equal("pkg:rpm/redhat/openssl@3.0.9", result.Purl);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Cpe_ReturnsCpeLink()
|
||||
{
|
||||
var result = _canonicalizer.Canonicalize(
|
||||
originalKey: "openssl",
|
||||
cpe: "cpe:2.3:a:openssl:openssl:3.0.9:*:*:*:*:*:*:*");
|
||||
|
||||
Assert.Equal("cpe:2.3:a:openssl:openssl:3.0.9:*:*:*:*:*:*:*", result.Cpe);
|
||||
}
|
||||
}
|
||||
@@ -11,6 +11,7 @@
|
||||
</PropertyGroup>
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="../../__Libraries/StellaOps.Excititor.Core/StellaOps.Excititor.Core.csproj" />
|
||||
<ProjectReference Include="../../__Libraries/StellaOps.Excititor.Attestation/StellaOps.Excititor.Attestation.csproj" />
|
||||
<PackageReference Include="FluentAssertions" Version="6.12.0" />
|
||||
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.0" />
|
||||
<PackageReference Include="xunit" Version="2.9.2" />
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
using System;
|
||||
using System.Collections.Immutable;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
using Xunit;
|
||||
|
||||
namespace StellaOps.Excititor.Core.UnitTests;
|
||||
|
||||
public class TimelineEventTests
|
||||
{
|
||||
[Fact]
|
||||
public void Constructor_NormalizesFields_AndPreservesValues()
|
||||
{
|
||||
var now = DateTimeOffset.UtcNow;
|
||||
var attributes = ImmutableDictionary<string, string>.Empty
|
||||
.Add("key1", "value1")
|
||||
.Add("key2", "value2");
|
||||
|
||||
var evt = new TimelineEvent(
|
||||
eventId: " evt-001 ",
|
||||
tenant: " TENANT-A ",
|
||||
providerId: " provider-x ",
|
||||
streamId: " csaf ",
|
||||
eventType: " vex.observation.ingested ",
|
||||
traceId: " trace-abc-123 ",
|
||||
justificationSummary: " Component not present in runtime ",
|
||||
createdAt: now,
|
||||
evidenceHash: " sha256:deadbeef ",
|
||||
payloadHash: " sha256:cafebabe ",
|
||||
attributes: attributes);
|
||||
|
||||
Assert.Equal("evt-001", evt.EventId);
|
||||
Assert.Equal("tenant-a", evt.Tenant); // lowercase
|
||||
Assert.Equal("provider-x", evt.ProviderId);
|
||||
Assert.Equal("csaf", evt.StreamId);
|
||||
Assert.Equal("vex.observation.ingested", evt.EventType);
|
||||
Assert.Equal("trace-abc-123", evt.TraceId);
|
||||
Assert.Equal("Component not present in runtime", evt.JustificationSummary);
|
||||
Assert.Equal(now, evt.CreatedAt);
|
||||
Assert.Equal("sha256:deadbeef", evt.EvidenceHash);
|
||||
Assert.Equal("sha256:cafebabe", evt.PayloadHash);
|
||||
Assert.Equal(2, evt.Attributes.Count);
|
||||
Assert.Equal("value1", evt.Attributes["key1"]);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Constructor_ThrowsOnNullOrWhiteSpaceRequiredFields()
|
||||
{
|
||||
var now = DateTimeOffset.UtcNow;
|
||||
|
||||
Assert.Throws<ArgumentException>(() => new TimelineEvent(
|
||||
eventId: null!,
|
||||
tenant: "tenant",
|
||||
providerId: "provider",
|
||||
streamId: "stream",
|
||||
eventType: "type",
|
||||
traceId: "trace",
|
||||
justificationSummary: "summary",
|
||||
createdAt: now));
|
||||
|
||||
Assert.Throws<ArgumentException>(() => new TimelineEvent(
|
||||
eventId: " ",
|
||||
tenant: "tenant",
|
||||
providerId: "provider",
|
||||
streamId: "stream",
|
||||
eventType: "type",
|
||||
traceId: "trace",
|
||||
justificationSummary: "summary",
|
||||
createdAt: now));
|
||||
|
||||
Assert.Throws<ArgumentException>(() => new TimelineEvent(
|
||||
eventId: "evt-001",
|
||||
tenant: null!,
|
||||
providerId: "provider",
|
||||
streamId: "stream",
|
||||
eventType: "type",
|
||||
traceId: "trace",
|
||||
justificationSummary: "summary",
|
||||
createdAt: now));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Constructor_HandlesNullOptionalFields()
|
||||
{
|
||||
var now = DateTimeOffset.UtcNow;
|
||||
|
||||
var evt = new TimelineEvent(
|
||||
eventId: "evt-001",
|
||||
tenant: "tenant-a",
|
||||
providerId: "provider-x",
|
||||
streamId: "csaf",
|
||||
eventType: "vex.observation.ingested",
|
||||
traceId: "trace-abc-123",
|
||||
justificationSummary: null!,
|
||||
createdAt: now,
|
||||
evidenceHash: null,
|
||||
payloadHash: null,
|
||||
attributes: null);
|
||||
|
||||
Assert.Equal(string.Empty, evt.JustificationSummary);
|
||||
Assert.Null(evt.EvidenceHash);
|
||||
Assert.Null(evt.PayloadHash);
|
||||
Assert.Empty(evt.Attributes);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Constructor_FiltersNullAttributeKeysAndValues()
|
||||
{
|
||||
var now = DateTimeOffset.UtcNow;
|
||||
var attributes = ImmutableDictionary<string, string>.Empty
|
||||
.Add("valid-key", "valid-value")
|
||||
.Add(" ", "bad-key")
|
||||
.Add("null-value", null!);
|
||||
|
||||
var evt = new TimelineEvent(
|
||||
eventId: "evt-001",
|
||||
tenant: "tenant-a",
|
||||
providerId: "provider-x",
|
||||
streamId: "csaf",
|
||||
eventType: "vex.observation.ingested",
|
||||
traceId: "trace-abc-123",
|
||||
justificationSummary: "summary",
|
||||
createdAt: now,
|
||||
attributes: attributes);
|
||||
|
||||
// Only valid key-value pair should remain
|
||||
Assert.Single(evt.Attributes);
|
||||
Assert.True(evt.Attributes.ContainsKey("valid-key"));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void EventTypes_Constants_AreCorrect()
|
||||
{
|
||||
Assert.Equal("vex.observation.ingested", VexTimelineEventTypes.ObservationIngested);
|
||||
Assert.Equal("vex.observation.updated", VexTimelineEventTypes.ObservationUpdated);
|
||||
Assert.Equal("vex.observation.superseded", VexTimelineEventTypes.ObservationSuperseded);
|
||||
Assert.Equal("vex.linkset.created", VexTimelineEventTypes.LinksetCreated);
|
||||
Assert.Equal("vex.linkset.updated", VexTimelineEventTypes.LinksetUpdated);
|
||||
Assert.Equal("vex.linkset.conflict_detected", VexTimelineEventTypes.LinksetConflictDetected);
|
||||
Assert.Equal("vex.linkset.conflict_resolved", VexTimelineEventTypes.LinksetConflictResolved);
|
||||
Assert.Equal("vex.evidence.sealed", VexTimelineEventTypes.EvidenceSealed);
|
||||
Assert.Equal("vex.attestation.attached", VexTimelineEventTypes.AttestationAttached);
|
||||
Assert.Equal("vex.attestation.verified", VexTimelineEventTypes.AttestationVerified);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void AttributeKeys_Constants_AreCorrect()
|
||||
{
|
||||
Assert.Equal("observation_id", VexTimelineEventAttributes.ObservationId);
|
||||
Assert.Equal("linkset_id", VexTimelineEventAttributes.LinksetId);
|
||||
Assert.Equal("vulnerability_id", VexTimelineEventAttributes.VulnerabilityId);
|
||||
Assert.Equal("product_key", VexTimelineEventAttributes.ProductKey);
|
||||
Assert.Equal("status", VexTimelineEventAttributes.Status);
|
||||
Assert.Equal("conflict_type", VexTimelineEventAttributes.ConflictType);
|
||||
Assert.Equal("attestation_id", VexTimelineEventAttributes.AttestationId);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,209 @@
|
||||
using System;
|
||||
using System.Collections.Immutable;
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Nodes;
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
using Microsoft.Extensions.Logging.Abstractions;
|
||||
using StellaOps.Excititor.Attestation.Evidence;
|
||||
using StellaOps.Excititor.Attestation.Signing;
|
||||
using StellaOps.Excititor.Core.Evidence;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
using Xunit;
|
||||
|
||||
namespace StellaOps.Excititor.Core.UnitTests;
|
||||
|
||||
public class VexEvidenceAttestorTests
|
||||
{
|
||||
[Fact]
|
||||
public async Task AttestManifestAsync_CreatesValidAttestation()
|
||||
{
|
||||
var signer = new FakeSigner();
|
||||
var attestor = new VexEvidenceAttestor(signer, NullLogger<VexEvidenceAttestor>.Instance);
|
||||
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
"obs-001",
|
||||
"provider-a",
|
||||
"sha256:0000000000000000000000000000000000000000000000000000000000000001",
|
||||
"linkset-1");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "locker:excititor:test-tenant:2025-11-27:0001",
|
||||
createdAt: DateTimeOffset.Parse("2025-11-27T10:00:00Z"),
|
||||
items: new[] { item });
|
||||
|
||||
var result = await attestor.AttestManifestAsync(manifest);
|
||||
|
||||
Assert.NotNull(result);
|
||||
Assert.NotNull(result.SignedManifest);
|
||||
Assert.NotNull(result.DsseEnvelopeJson);
|
||||
Assert.StartsWith("sha256:", result.DsseEnvelopeHash);
|
||||
Assert.StartsWith("attest:evidence:test-tenant:", result.AttestationId);
|
||||
Assert.NotNull(result.SignedManifest.Signature);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task AttestManifestAsync_EnvelopeContainsCorrectPayload()
|
||||
{
|
||||
var signer = new FakeSigner();
|
||||
var attestor = new VexEvidenceAttestor(signer, NullLogger<VexEvidenceAttestor>.Instance);
|
||||
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
"obs-001",
|
||||
"provider-a",
|
||||
"sha256:abc123",
|
||||
"linkset-1");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var result = await attestor.AttestManifestAsync(manifest);
|
||||
|
||||
var envelope = JsonSerializer.Deserialize<JsonObject>(result.DsseEnvelopeJson);
|
||||
Assert.NotNull(envelope);
|
||||
Assert.Equal("application/vnd.in-toto+json", envelope["payloadType"]?.GetValue<string>());
|
||||
|
||||
var payload = Convert.FromBase64String(envelope["payload"]?.GetValue<string>() ?? "");
|
||||
var statement = JsonSerializer.Deserialize<JsonObject>(payload);
|
||||
Assert.NotNull(statement);
|
||||
Assert.Equal(VexEvidenceInTotoStatement.InTotoStatementType, statement["_type"]?.GetValue<string>());
|
||||
Assert.Equal(VexEvidenceInTotoStatement.EvidenceLockerPredicateType, statement["predicateType"]?.GetValue<string>());
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task VerifyAttestationAsync_ReturnsValidForCorrectAttestation()
|
||||
{
|
||||
var signer = new FakeSigner();
|
||||
var attestor = new VexEvidenceAttestor(signer, NullLogger<VexEvidenceAttestor>.Instance);
|
||||
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
"obs-001",
|
||||
"provider-a",
|
||||
"sha256:abc123",
|
||||
"linkset-1");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var attestation = await attestor.AttestManifestAsync(manifest);
|
||||
var verification = await attestor.VerifyAttestationAsync(manifest, attestation.DsseEnvelopeJson);
|
||||
|
||||
Assert.True(verification.IsValid);
|
||||
Assert.Null(verification.FailureReason);
|
||||
Assert.True(verification.Diagnostics.ContainsKey("envelope_hash"));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task VerifyAttestationAsync_ReturnsInvalidForWrongManifest()
|
||||
{
|
||||
var signer = new FakeSigner();
|
||||
var attestor = new VexEvidenceAttestor(signer, NullLogger<VexEvidenceAttestor>.Instance);
|
||||
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
"obs-001",
|
||||
"provider-a",
|
||||
"sha256:abc123",
|
||||
"linkset-1");
|
||||
var manifest1 = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "manifest-1",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var manifest2 = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "manifest-2",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var attestation = await attestor.AttestManifestAsync(manifest1);
|
||||
var verification = await attestor.VerifyAttestationAsync(manifest2, attestation.DsseEnvelopeJson);
|
||||
|
||||
Assert.False(verification.IsValid);
|
||||
Assert.Contains("Manifest ID mismatch", verification.FailureReason);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task VerifyAttestationAsync_ReturnsInvalidForInvalidJson()
|
||||
{
|
||||
var signer = new FakeSigner();
|
||||
var attestor = new VexEvidenceAttestor(signer, NullLogger<VexEvidenceAttestor>.Instance);
|
||||
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
"obs-001",
|
||||
"provider-a",
|
||||
"sha256:abc123",
|
||||
"linkset-1");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var verification = await attestor.VerifyAttestationAsync(manifest, "not valid json");
|
||||
|
||||
Assert.False(verification.IsValid);
|
||||
Assert.Contains("JSON parse error", verification.FailureReason);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task VerifyAttestationAsync_ReturnsInvalidForEmptyEnvelope()
|
||||
{
|
||||
var signer = new FakeSigner();
|
||||
var attestor = new VexEvidenceAttestor(signer, NullLogger<VexEvidenceAttestor>.Instance);
|
||||
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
"obs-001",
|
||||
"provider-a",
|
||||
"sha256:abc123",
|
||||
"linkset-1");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var verification = await attestor.VerifyAttestationAsync(manifest, "");
|
||||
|
||||
Assert.False(verification.IsValid);
|
||||
Assert.Equal("DSSE envelope is required.", verification.FailureReason);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexEvidenceAttestationPredicate_FromManifest_CapturesAllFields()
|
||||
{
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
"obs-001",
|
||||
"provider-a",
|
||||
"sha256:abc123",
|
||||
"linkset-1");
|
||||
var metadata = ImmutableDictionary<string, string>.Empty.Add("sealed", "true");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.Parse("2025-11-27T10:00:00Z"),
|
||||
items: new[] { item },
|
||||
metadata: metadata);
|
||||
|
||||
var predicate = VexEvidenceAttestationPredicate.FromManifest(manifest);
|
||||
|
||||
Assert.Equal("test-manifest", predicate.ManifestId);
|
||||
Assert.Equal("test-tenant", predicate.Tenant);
|
||||
Assert.Equal(manifest.MerkleRoot, predicate.MerkleRoot);
|
||||
Assert.Equal(1, predicate.ItemCount);
|
||||
Assert.Equal("true", predicate.Metadata["sealed"]);
|
||||
}
|
||||
|
||||
private sealed class FakeSigner : IVexSigner
|
||||
{
|
||||
public ValueTask<VexSignedPayload> SignAsync(ReadOnlyMemory<byte> payload, CancellationToken cancellationToken)
|
||||
{
|
||||
var signature = Convert.ToBase64String(payload.Span.ToArray());
|
||||
return ValueTask.FromResult(new VexSignedPayload(signature, "fake-key-001"));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,199 @@
|
||||
using System;
|
||||
using System.Collections.Immutable;
|
||||
using System.Text.Json.Nodes;
|
||||
using StellaOps.Excititor.Core.Evidence;
|
||||
using StellaOps.Excititor.Core.Observations;
|
||||
using Xunit;
|
||||
|
||||
namespace StellaOps.Excititor.Core.UnitTests;
|
||||
|
||||
public class VexEvidenceLockerTests
|
||||
{
|
||||
[Fact]
|
||||
public void VexEvidenceSnapshotItem_NormalizesFields()
|
||||
{
|
||||
var item = new VexEvidenceSnapshotItem(
|
||||
observationId: " obs-001 ",
|
||||
providerId: " PROVIDER-A ",
|
||||
contentHash: " sha256:abc123 ",
|
||||
linksetId: " CVE-2024-0001:pkg:npm/lodash ");
|
||||
|
||||
Assert.Equal("obs-001", item.ObservationId);
|
||||
Assert.Equal("provider-a", item.ProviderId);
|
||||
Assert.Equal("sha256:abc123", item.ContentHash);
|
||||
Assert.Equal("CVE-2024-0001:pkg:npm/lodash", item.LinksetId);
|
||||
Assert.Null(item.DsseEnvelopeHash);
|
||||
Assert.Equal("ingest", item.Provenance.Source);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexEvidenceProvenance_CreatesCorrectProvenance()
|
||||
{
|
||||
var provenance = new VexEvidenceProvenance("mirror", 5, "sha256:manifest123");
|
||||
|
||||
Assert.Equal("mirror", provenance.Source);
|
||||
Assert.Equal(5, provenance.MirrorGeneration);
|
||||
Assert.Equal("sha256:manifest123", provenance.ExportCenterManifest);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexLockerManifest_SortsItemsDeterministically()
|
||||
{
|
||||
var item1 = new VexEvidenceSnapshotItem("obs-002", "provider-b", "sha256:bbb", "linkset-1");
|
||||
var item2 = new VexEvidenceSnapshotItem("obs-001", "provider-a", "sha256:aaa", "linkset-1");
|
||||
var item3 = new VexEvidenceSnapshotItem("obs-001", "provider-b", "sha256:ccc", "linkset-2");
|
||||
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test-tenant",
|
||||
manifestId: "locker:excititor:test:2025-11-27:0001",
|
||||
createdAt: DateTimeOffset.Parse("2025-11-27T10:00:00Z"),
|
||||
items: new[] { item1, item2, item3 });
|
||||
|
||||
// Should be sorted by observationId, then providerId
|
||||
Assert.Equal(3, manifest.Items.Length);
|
||||
Assert.Equal("obs-001", manifest.Items[0].ObservationId);
|
||||
Assert.Equal("provider-a", manifest.Items[0].ProviderId);
|
||||
Assert.Equal("obs-001", manifest.Items[1].ObservationId);
|
||||
Assert.Equal("provider-b", manifest.Items[1].ProviderId);
|
||||
Assert.Equal("obs-002", manifest.Items[2].ObservationId);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexLockerManifest_ComputesMerkleRoot()
|
||||
{
|
||||
var item1 = new VexEvidenceSnapshotItem("obs-001", "provider-a", "sha256:0000000000000000000000000000000000000000000000000000000000000001", "linkset-1");
|
||||
var item2 = new VexEvidenceSnapshotItem("obs-002", "provider-a", "sha256:0000000000000000000000000000000000000000000000000000000000000002", "linkset-1");
|
||||
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item1, item2 });
|
||||
|
||||
Assert.StartsWith("sha256:", manifest.MerkleRoot);
|
||||
Assert.Equal(71, manifest.MerkleRoot.Length); // "sha256:" + 64 hex chars
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexLockerManifest_CreateManifestId_GeneratesCorrectFormat()
|
||||
{
|
||||
var id = VexLockerManifest.CreateManifestId("TestTenant", DateTimeOffset.Parse("2025-11-27T15:30:00Z"), 42);
|
||||
|
||||
Assert.Equal("locker:excititor:testtenant:2025-11-27:0042", id);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexLockerManifest_WithSignature_PreservesData()
|
||||
{
|
||||
var item = new VexEvidenceSnapshotItem("obs-001", "provider-a", "sha256:abc123", "linkset-1");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var signed = manifest.WithSignature("dsse-signature-base64");
|
||||
|
||||
Assert.Null(manifest.Signature);
|
||||
Assert.Equal("dsse-signature-base64", signed.Signature);
|
||||
Assert.Equal(manifest.MerkleRoot, signed.MerkleRoot);
|
||||
Assert.Equal(manifest.Items.Length, signed.Items.Length);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexEvidenceLockerService_CreateSnapshotItem_FromObservation()
|
||||
{
|
||||
var observation = BuildTestObservation("obs-001", "provider-a", "sha256:content123");
|
||||
var service = new VexEvidenceLockerService();
|
||||
|
||||
var item = service.CreateSnapshotItem(observation, "linkset-001");
|
||||
|
||||
Assert.Equal("obs-001", item.ObservationId);
|
||||
Assert.Equal("provider-a", item.ProviderId);
|
||||
Assert.Equal("sha256:content123", item.ContentHash);
|
||||
Assert.Equal("linkset-001", item.LinksetId);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexEvidenceLockerService_BuildManifest_CreatesValidManifest()
|
||||
{
|
||||
var obs1 = BuildTestObservation("obs-001", "provider-a", "sha256:aaa");
|
||||
var obs2 = BuildTestObservation("obs-002", "provider-b", "sha256:bbb");
|
||||
var service = new VexEvidenceLockerService();
|
||||
|
||||
var manifest = service.BuildManifest(
|
||||
tenant: "test-tenant",
|
||||
observations: new[] { obs2, obs1 },
|
||||
linksetIdSelector: o => $"linkset:{o.ObservationId}",
|
||||
timestamp: DateTimeOffset.Parse("2025-11-27T10:00:00Z"),
|
||||
sequence: 1,
|
||||
isSealed: true);
|
||||
|
||||
Assert.Equal("test-tenant", manifest.Tenant);
|
||||
Assert.Equal("locker:excititor:test-tenant:2025-11-27:0001", manifest.ManifestId);
|
||||
Assert.Equal(2, manifest.Items.Length);
|
||||
Assert.Equal("obs-001", manifest.Items[0].ObservationId); // sorted
|
||||
Assert.Equal("true", manifest.Metadata["sealed"]);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexEvidenceLockerService_VerifyManifest_ReturnsTrueForValidManifest()
|
||||
{
|
||||
var item = new VexEvidenceSnapshotItem("obs-001", "provider-a", "sha256:0000000000000000000000000000000000000000000000000000000000000001", "linkset-1");
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: new[] { item });
|
||||
|
||||
var service = new VexEvidenceLockerService();
|
||||
Assert.True(service.VerifyManifest(manifest));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexLockerManifest_EmptyItems_ProducesEmptyMerkleRoot()
|
||||
{
|
||||
var manifest = new VexLockerManifest(
|
||||
tenant: "test",
|
||||
manifestId: "test-manifest",
|
||||
createdAt: DateTimeOffset.UtcNow,
|
||||
items: Array.Empty<VexEvidenceSnapshotItem>());
|
||||
|
||||
Assert.StartsWith("sha256:", manifest.MerkleRoot);
|
||||
Assert.Empty(manifest.Items);
|
||||
}
|
||||
|
||||
private static VexObservation BuildTestObservation(string id, string provider, string contentHash)
|
||||
{
|
||||
var upstream = new VexObservationUpstream(
|
||||
upstreamId: $"upstream-{id}",
|
||||
documentVersion: "1",
|
||||
fetchedAt: DateTimeOffset.UtcNow,
|
||||
receivedAt: DateTimeOffset.UtcNow,
|
||||
contentHash: contentHash,
|
||||
signature: new VexObservationSignature(false, null, null, null));
|
||||
|
||||
var content = new VexObservationContent(
|
||||
format: "openvex",
|
||||
specVersion: "1.0.0",
|
||||
raw: JsonNode.Parse("{}")!,
|
||||
metadata: null);
|
||||
|
||||
var linkset = new VexObservationLinkset(
|
||||
aliases: Array.Empty<string>(),
|
||||
purls: Array.Empty<string>(),
|
||||
cpes: Array.Empty<string>(),
|
||||
references: Array.Empty<VexObservationReference>());
|
||||
|
||||
return new VexObservation(
|
||||
observationId: id,
|
||||
tenant: "test",
|
||||
providerId: provider,
|
||||
streamId: "ingest",
|
||||
upstream: upstream,
|
||||
statements: ImmutableArray<VexObservationStatement>.Empty,
|
||||
content: content,
|
||||
linkset: linkset,
|
||||
createdAt: DateTimeOffset.UtcNow);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,199 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.IO;
|
||||
using System.Net;
|
||||
using System.Net.Http.Json;
|
||||
using System.Text.Json;
|
||||
using Microsoft.Extensions.Configuration;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using EphemeralMongo;
|
||||
using MongoRunner = EphemeralMongo.MongoRunner;
|
||||
using MongoRunnerOptions = EphemeralMongo.MongoRunnerOptions;
|
||||
using StellaOps.Excititor.Attestation.Signing;
|
||||
using StellaOps.Excititor.Connectors.Abstractions;
|
||||
using StellaOps.Excititor.Policy;
|
||||
using StellaOps.Excititor.Core;
|
||||
|
||||
namespace StellaOps.Excititor.WebService.Tests;
|
||||
|
||||
/// <summary>
|
||||
/// Tests for OpenAPI discovery endpoints (WEB-OAS-61-001).
|
||||
/// Validates /.well-known/openapi and /openapi/excititor.json endpoints.
|
||||
/// </summary>
|
||||
public sealed class OpenApiDiscoveryEndpointTests : IDisposable
|
||||
{
|
||||
private readonly TestWebApplicationFactory _factory;
|
||||
private readonly IMongoRunner _runner;
|
||||
|
||||
public OpenApiDiscoveryEndpointTests()
|
||||
{
|
||||
_runner = MongoRunner.Run(new MongoRunnerOptions { UseSingleNodeReplicaSet = true });
|
||||
_factory = new TestWebApplicationFactory(
|
||||
configureConfiguration: config =>
|
||||
{
|
||||
var rootPath = Path.Combine(Path.GetTempPath(), "excititor-openapi-tests");
|
||||
Directory.CreateDirectory(rootPath);
|
||||
var settings = new Dictionary<string, string?>
|
||||
{
|
||||
["Excititor:Storage:Mongo:ConnectionString"] = _runner.ConnectionString,
|
||||
["Excititor:Storage:Mongo:DatabaseName"] = "excititor-openapi-tests",
|
||||
["Excititor:Storage:Mongo:RawBucketName"] = "vex.raw",
|
||||
["Excititor:Storage:Mongo:GridFsInlineThresholdBytes"] = "256",
|
||||
["Excititor:Artifacts:FileSystem:RootPath"] = rootPath,
|
||||
};
|
||||
config.AddInMemoryCollection(settings!);
|
||||
},
|
||||
configureServices: services =>
|
||||
{
|
||||
TestServiceOverrides.Apply(services);
|
||||
services.AddSingleton<IVexSigner, FakeSigner>();
|
||||
services.AddSingleton<IVexPolicyEvaluator, FakePolicyEvaluator>();
|
||||
services.AddSingleton(new VexConnectorDescriptor("excititor:test", VexProviderKind.Distro, "Test Connector"));
|
||||
});
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task WellKnownOpenApi_ReturnsServiceMetadata()
|
||||
{
|
||||
var client = _factory.CreateClient();
|
||||
var response = await client.GetAsync("/.well-known/openapi");
|
||||
|
||||
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
|
||||
|
||||
var json = await response.Content.ReadAsStringAsync();
|
||||
var doc = JsonDocument.Parse(json);
|
||||
var root = doc.RootElement;
|
||||
|
||||
Assert.Equal("excititor", root.GetProperty("service").GetString());
|
||||
Assert.Equal("3.1.0", root.GetProperty("specVersion").GetString());
|
||||
Assert.Equal("application/json", root.GetProperty("format").GetString());
|
||||
Assert.Equal("/openapi/excititor.json", root.GetProperty("url").GetString());
|
||||
Assert.Equal("#/components/schemas/Error", root.GetProperty("errorEnvelopeSchema").GetString());
|
||||
Assert.True(root.TryGetProperty("version", out _), "Response should include version");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OpenApiSpec_ReturnsValidOpenApi31Document()
|
||||
{
|
||||
var client = _factory.CreateClient();
|
||||
var response = await client.GetAsync("/openapi/excititor.json");
|
||||
|
||||
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
|
||||
|
||||
var json = await response.Content.ReadAsStringAsync();
|
||||
var doc = JsonDocument.Parse(json);
|
||||
var root = doc.RootElement;
|
||||
|
||||
// Verify OpenAPI version
|
||||
Assert.Equal("3.1.0", root.GetProperty("openapi").GetString());
|
||||
|
||||
// Verify info object
|
||||
var info = root.GetProperty("info");
|
||||
Assert.Equal("StellaOps Excititor API", info.GetProperty("title").GetString());
|
||||
Assert.True(info.TryGetProperty("version", out _), "Info should include version");
|
||||
Assert.True(info.TryGetProperty("description", out _), "Info should include description");
|
||||
|
||||
// Verify paths exist
|
||||
Assert.True(root.TryGetProperty("paths", out var paths), "Spec should include paths");
|
||||
Assert.True(paths.TryGetProperty("/excititor/status", out _), "Paths should include /excititor/status");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OpenApiSpec_IncludesErrorSchemaComponent()
|
||||
{
|
||||
var client = _factory.CreateClient();
|
||||
var response = await client.GetAsync("/openapi/excititor.json");
|
||||
|
||||
var json = await response.Content.ReadAsStringAsync();
|
||||
var doc = JsonDocument.Parse(json);
|
||||
var root = doc.RootElement;
|
||||
|
||||
// Verify components/schemas/Error exists
|
||||
Assert.True(root.TryGetProperty("components", out var components), "Spec should include components");
|
||||
Assert.True(components.TryGetProperty("schemas", out var schemas), "Components should include schemas");
|
||||
Assert.True(schemas.TryGetProperty("Error", out var errorSchema), "Schemas should include Error");
|
||||
|
||||
// Verify Error schema structure
|
||||
Assert.Equal("object", errorSchema.GetProperty("type").GetString());
|
||||
Assert.True(errorSchema.TryGetProperty("properties", out var props), "Error schema should have properties");
|
||||
Assert.True(props.TryGetProperty("error", out _), "Error schema should have error property");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OpenApiSpec_IncludesTimelineEndpoint()
|
||||
{
|
||||
var client = _factory.CreateClient();
|
||||
var response = await client.GetAsync("/openapi/excititor.json");
|
||||
|
||||
var json = await response.Content.ReadAsStringAsync();
|
||||
var doc = JsonDocument.Parse(json);
|
||||
var root = doc.RootElement;
|
||||
|
||||
var paths = root.GetProperty("paths");
|
||||
Assert.True(paths.TryGetProperty("/obs/excititor/timeline", out var timelinePath),
|
||||
"Paths should include /obs/excititor/timeline");
|
||||
|
||||
// Verify it has a GET operation
|
||||
Assert.True(timelinePath.TryGetProperty("get", out var getOp), "Timeline path should have GET operation");
|
||||
Assert.True(getOp.TryGetProperty("summary", out _), "GET operation should have summary");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OpenApiSpec_IncludesLinkHeaderExample()
|
||||
{
|
||||
var client = _factory.CreateClient();
|
||||
var response = await client.GetAsync("/openapi/excititor.json");
|
||||
|
||||
var json = await response.Content.ReadAsStringAsync();
|
||||
|
||||
// Verify the spec contains a Link header reference for OpenAPI describedby
|
||||
// JSON escapes quotes, so check for the essential parts
|
||||
Assert.Contains("/openapi/excititor.json", json);
|
||||
Assert.Contains("describedby", json);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task WellKnownOpenApi_ContentTypeIsJson()
|
||||
{
|
||||
var client = _factory.CreateClient();
|
||||
var response = await client.GetAsync("/.well-known/openapi");
|
||||
|
||||
Assert.Equal("application/json", response.Content.Headers.ContentType?.MediaType);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task OpenApiSpec_ContentTypeIsJson()
|
||||
{
|
||||
var client = _factory.CreateClient();
|
||||
var response = await client.GetAsync("/openapi/excititor.json");
|
||||
|
||||
Assert.Equal("application/json", response.Content.Headers.ContentType?.MediaType);
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
_factory.Dispose();
|
||||
_runner.Dispose();
|
||||
}
|
||||
|
||||
private sealed class FakeSigner : IVexSigner
|
||||
{
|
||||
public ValueTask<VexSignedPayload> SignAsync(ReadOnlyMemory<byte> payload, CancellationToken cancellationToken)
|
||||
=> ValueTask.FromResult(new VexSignedPayload("signature", "key"));
|
||||
}
|
||||
|
||||
private sealed class FakePolicyEvaluator : IVexPolicyEvaluator
|
||||
{
|
||||
public string Version => "test";
|
||||
|
||||
public VexPolicySnapshot Snapshot => VexPolicySnapshot.Default;
|
||||
|
||||
public double GetProviderWeight(VexProvider provider) => 1.0;
|
||||
|
||||
public bool IsClaimEligible(VexClaim claim, VexProvider provider, out string? rejectionReason)
|
||||
{
|
||||
rejectionReason = null;
|
||||
return true;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -40,5 +40,6 @@
|
||||
<Compile Include="GraphStatusFactoryTests.cs" />
|
||||
<Compile Include="GraphTooltipFactoryTests.cs" />
|
||||
<Compile Include="AttestationVerifyEndpointTests.cs" />
|
||||
<Compile Include="OpenApiDiscoveryEndpointTests.cs" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
|
||||
@@ -16,7 +16,9 @@ using StellaOps.Aoc;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Aoc;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.Core.Orchestration;
|
||||
using StellaOps.Excititor.Worker.Options;
|
||||
using StellaOps.Excititor.Worker.Orchestration;
|
||||
using StellaOps.Excititor.Worker.Scheduling;
|
||||
using StellaOps.Excititor.Worker.Signature;
|
||||
using StellaOps.Plugin;
|
||||
@@ -115,7 +117,8 @@ public sealed class DefaultVexProviderRunnerIntegrationTests : IAsyncLifetime
|
||||
storedCount.Should().Be(9); // documents before the failing digest persist
|
||||
|
||||
guard.FailDigest = null;
|
||||
time.Advance(TimeSpan.FromMinutes(10));
|
||||
// Advance past the quarantine duration (30 mins) since AOC guard failures are non-retryable
|
||||
time.Advance(TimeSpan.FromMinutes(35));
|
||||
await runner.RunAsync(schedule, CancellationToken.None);
|
||||
|
||||
var finalCount = await rawCollection.CountDocumentsAsync(FilterDefinition<BsonDocument>.Empty);
|
||||
@@ -177,12 +180,23 @@ public sealed class DefaultVexProviderRunnerIntegrationTests : IAsyncLifetime
|
||||
},
|
||||
};
|
||||
|
||||
var orchestratorOptions = Microsoft.Extensions.Options.Options.Create(new VexWorkerOrchestratorOptions { Enabled = false });
|
||||
var orchestratorClient = new NoopOrchestratorClient();
|
||||
var heartbeatService = new VexWorkerHeartbeatService(
|
||||
orchestratorClient,
|
||||
orchestratorOptions,
|
||||
timeProvider,
|
||||
NullLogger<VexWorkerHeartbeatService>.Instance);
|
||||
|
||||
return new DefaultVexProviderRunner(
|
||||
services,
|
||||
new PluginCatalog(),
|
||||
orchestratorClient,
|
||||
heartbeatService,
|
||||
NullLogger<DefaultVexProviderRunner>.Instance,
|
||||
timeProvider,
|
||||
Microsoft.Extensions.Options.Options.Create(options));
|
||||
Microsoft.Extensions.Options.Options.Create(options),
|
||||
orchestratorOptions);
|
||||
}
|
||||
|
||||
private static List<DocumentSpec> CreateDocumentSpecs(int count)
|
||||
@@ -330,6 +344,39 @@ public sealed class DefaultVexProviderRunnerIntegrationTests : IAsyncLifetime
|
||||
=> ValueTask.FromResult<VexSignatureMetadata?>(null);
|
||||
}
|
||||
|
||||
private sealed class NoopOrchestratorClient : IVexWorkerOrchestratorClient
|
||||
{
|
||||
public ValueTask<VexWorkerJobContext> StartJobAsync(string tenant, string connectorId, string? checkpoint, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.FromResult(new VexWorkerJobContext(tenant, connectorId, Guid.NewGuid(), checkpoint, DateTimeOffset.UtcNow));
|
||||
|
||||
public ValueTask SendHeartbeatAsync(VexWorkerJobContext context, VexWorkerHeartbeat heartbeat, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask RecordArtifactAsync(VexWorkerJobContext context, VexWorkerArtifact artifact, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask CompleteJobAsync(VexWorkerJobContext context, VexWorkerJobResult result, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask FailJobAsync(VexWorkerJobContext context, string errorCode, string? errorMessage, int? retryAfterSeconds, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask FailJobAsync(VexWorkerJobContext context, VexWorkerError error, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask<VexWorkerCommand?> GetPendingCommandAsync(VexWorkerJobContext context, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.FromResult<VexWorkerCommand?>(null);
|
||||
|
||||
public ValueTask AcknowledgeCommandAsync(VexWorkerJobContext context, long commandSequence, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask SaveCheckpointAsync(VexWorkerJobContext context, VexWorkerCheckpoint checkpoint, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask<VexWorkerCheckpoint?> LoadCheckpointAsync(string connectorId, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.FromResult<VexWorkerCheckpoint?>(null);
|
||||
}
|
||||
|
||||
private sealed class DirectSessionProvider : IVexMongoSessionProvider
|
||||
{
|
||||
private readonly IMongoClient _client;
|
||||
|
||||
@@ -19,7 +19,9 @@ using StellaOps.Excititor.Connectors.Abstractions;
|
||||
using StellaOps.Excititor.Core;
|
||||
using StellaOps.Excititor.Core.Aoc;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.Core.Orchestration;
|
||||
using StellaOps.Excititor.Worker.Options;
|
||||
using StellaOps.Excititor.Worker.Orchestration;
|
||||
using StellaOps.Excititor.Worker.Scheduling;
|
||||
using StellaOps.Excititor.Worker.Signature;
|
||||
using StellaOps.Aoc;
|
||||
@@ -332,6 +334,45 @@ public sealed class DefaultVexProviderRunnerTests
|
||||
{
|
||||
var now = new DateTimeOffset(2025, 10, 21, 17, 0, 0, TimeSpan.Zero);
|
||||
var time = new FixedTimeProvider(now);
|
||||
// Use a network exception which is classified as retryable
|
||||
var connector = TestConnector.Failure("excititor:test", new System.Net.Http.HttpRequestException("network failure"));
|
||||
var stateRepository = new InMemoryStateRepository();
|
||||
stateRepository.Save(new VexConnectorState(
|
||||
"excititor:test",
|
||||
LastUpdated: now.AddDays(-2),
|
||||
DocumentDigests: ImmutableArray<string>.Empty,
|
||||
ResumeTokens: ImmutableDictionary<string, string>.Empty,
|
||||
LastSuccessAt: now.AddDays(-1),
|
||||
FailureCount: 1,
|
||||
NextEligibleRun: null,
|
||||
LastFailureReason: null));
|
||||
|
||||
var services = CreateServiceProvider(connector, stateRepository);
|
||||
var runner = CreateRunner(services, time, options =>
|
||||
{
|
||||
options.Retry.BaseDelay = TimeSpan.FromMinutes(5);
|
||||
options.Retry.MaxDelay = TimeSpan.FromMinutes(60);
|
||||
options.Retry.FailureThreshold = 3;
|
||||
options.Retry.QuarantineDuration = TimeSpan.FromHours(12);
|
||||
options.Retry.JitterRatio = 0;
|
||||
});
|
||||
|
||||
await Assert.ThrowsAsync<System.Net.Http.HttpRequestException>(async () => await runner.RunAsync(new VexWorkerSchedule(connector.Id, TimeSpan.FromMinutes(10), TimeSpan.Zero, EmptySettings), CancellationToken.None).AsTask());
|
||||
|
||||
var state = stateRepository.Get("excititor:test");
|
||||
state.Should().NotBeNull();
|
||||
state!.FailureCount.Should().Be(2);
|
||||
state.LastFailureReason.Should().Be("network failure");
|
||||
// Exponential backoff: 5 mins * 2^(2-1) = 10 mins
|
||||
state.NextEligibleRun.Should().Be(now + TimeSpan.FromMinutes(10));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task RunAsync_NonRetryableFailure_AppliesQuarantine()
|
||||
{
|
||||
var now = new DateTimeOffset(2025, 10, 21, 17, 0, 0, TimeSpan.Zero);
|
||||
var time = new FixedTimeProvider(now);
|
||||
// InvalidOperationException is classified as non-retryable
|
||||
var connector = TestConnector.Failure("excititor:test", new InvalidOperationException("boom"));
|
||||
var stateRepository = new InMemoryStateRepository();
|
||||
stateRepository.Save(new VexConnectorState(
|
||||
@@ -360,7 +401,8 @@ public sealed class DefaultVexProviderRunnerTests
|
||||
state.Should().NotBeNull();
|
||||
state!.FailureCount.Should().Be(2);
|
||||
state.LastFailureReason.Should().Be("boom");
|
||||
state.NextEligibleRun.Should().Be(now + TimeSpan.FromMinutes(10));
|
||||
// Non-retryable errors apply quarantine immediately
|
||||
state.NextEligibleRun.Should().Be(now + TimeSpan.FromHours(12));
|
||||
}
|
||||
|
||||
private static ServiceProvider CreateServiceProvider(
|
||||
@@ -390,12 +432,22 @@ public sealed class DefaultVexProviderRunnerTests
|
||||
{
|
||||
var options = new VexWorkerOptions();
|
||||
configure(options);
|
||||
var orchestratorOptions = Microsoft.Extensions.Options.Options.Create(new VexWorkerOrchestratorOptions { Enabled = false });
|
||||
var orchestratorClient = new NoopOrchestratorClient();
|
||||
var heartbeatService = new VexWorkerHeartbeatService(
|
||||
orchestratorClient,
|
||||
orchestratorOptions,
|
||||
timeProvider,
|
||||
NullLogger<VexWorkerHeartbeatService>.Instance);
|
||||
return new DefaultVexProviderRunner(
|
||||
serviceProvider,
|
||||
new PluginCatalog(),
|
||||
orchestratorClient,
|
||||
heartbeatService,
|
||||
NullLogger<DefaultVexProviderRunner>.Instance,
|
||||
timeProvider,
|
||||
Microsoft.Extensions.Options.Options.Create(options));
|
||||
Microsoft.Extensions.Options.Options.Create(options),
|
||||
orchestratorOptions);
|
||||
}
|
||||
|
||||
private sealed class FixedTimeProvider : TimeProvider
|
||||
@@ -527,6 +579,39 @@ public sealed class DefaultVexProviderRunnerTests
|
||||
=> ValueTask.FromResult<VexSignatureMetadata?>(null);
|
||||
}
|
||||
|
||||
private sealed class NoopOrchestratorClient : IVexWorkerOrchestratorClient
|
||||
{
|
||||
public ValueTask<VexWorkerJobContext> StartJobAsync(string tenant, string connectorId, string? checkpoint, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.FromResult(new VexWorkerJobContext(tenant, connectorId, Guid.NewGuid(), checkpoint, DateTimeOffset.UtcNow));
|
||||
|
||||
public ValueTask SendHeartbeatAsync(VexWorkerJobContext context, VexWorkerHeartbeat heartbeat, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask RecordArtifactAsync(VexWorkerJobContext context, VexWorkerArtifact artifact, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask CompleteJobAsync(VexWorkerJobContext context, VexWorkerJobResult result, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask FailJobAsync(VexWorkerJobContext context, string errorCode, string? errorMessage, int? retryAfterSeconds, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask FailJobAsync(VexWorkerJobContext context, VexWorkerError error, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask<VexWorkerCommand?> GetPendingCommandAsync(VexWorkerJobContext context, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.FromResult<VexWorkerCommand?>(null);
|
||||
|
||||
public ValueTask AcknowledgeCommandAsync(VexWorkerJobContext context, long commandSequence, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask SaveCheckpointAsync(VexWorkerJobContext context, VexWorkerCheckpoint checkpoint, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.CompletedTask;
|
||||
|
||||
public ValueTask<VexWorkerCheckpoint?> LoadCheckpointAsync(string connectorId, CancellationToken cancellationToken = default)
|
||||
=> ValueTask.FromResult<VexWorkerCheckpoint?>(null);
|
||||
}
|
||||
|
||||
private sealed class InMemoryStateRepository : IVexConnectorStateRepository
|
||||
{
|
||||
private readonly ConcurrentDictionary<string, VexConnectorState> _states = new(StringComparer.Ordinal);
|
||||
@@ -545,6 +630,9 @@ public sealed class DefaultVexProviderRunnerTests
|
||||
Save(state);
|
||||
return ValueTask.CompletedTask;
|
||||
}
|
||||
|
||||
public ValueTask<IReadOnlyCollection<VexConnectorState>> ListAsync(CancellationToken cancellationToken, IClientSessionHandle? session = null)
|
||||
=> ValueTask.FromResult<IReadOnlyCollection<VexConnectorState>>(_states.Values.ToList());
|
||||
}
|
||||
|
||||
private sealed class TestConnector : IVexConnector
|
||||
|
||||
@@ -0,0 +1,178 @@
|
||||
using System;
|
||||
using System.Collections.Generic;
|
||||
using System.Collections.Immutable;
|
||||
using System.Linq;
|
||||
using System.Threading;
|
||||
using System.Threading.Tasks;
|
||||
using Microsoft.Extensions.Logging.Abstractions;
|
||||
using Microsoft.Extensions.Options;
|
||||
using StellaOps.Excititor.Core.Orchestration;
|
||||
using StellaOps.Excititor.Storage.Mongo;
|
||||
using StellaOps.Excititor.Worker.Options;
|
||||
using StellaOps.Excititor.Worker.Orchestration;
|
||||
using Xunit;
|
||||
|
||||
namespace StellaOps.Excititor.Worker.Tests.Orchestration;
|
||||
|
||||
public class VexWorkerOrchestratorClientTests
|
||||
{
|
||||
private readonly InMemoryConnectorStateRepository _stateRepository = new();
|
||||
private readonly FakeTimeProvider _timeProvider = new();
|
||||
private readonly IOptions<VexWorkerOrchestratorOptions> _options = Microsoft.Extensions.Options.Options.Create(new VexWorkerOrchestratorOptions
|
||||
{
|
||||
Enabled = true,
|
||||
DefaultTenant = "test-tenant"
|
||||
});
|
||||
|
||||
[Fact]
|
||||
public async Task StartJobAsync_CreatesJobContext()
|
||||
{
|
||||
var client = CreateClient();
|
||||
|
||||
var context = await client.StartJobAsync("tenant-a", "connector-001", "checkpoint-123");
|
||||
|
||||
Assert.NotNull(context);
|
||||
Assert.Equal("tenant-a", context.Tenant);
|
||||
Assert.Equal("connector-001", context.ConnectorId);
|
||||
Assert.Equal("checkpoint-123", context.Checkpoint);
|
||||
Assert.NotEqual(Guid.Empty, context.RunId);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task SendHeartbeatAsync_UpdatesConnectorState()
|
||||
{
|
||||
var client = CreateClient();
|
||||
var context = await client.StartJobAsync("tenant-a", "connector-001", null);
|
||||
|
||||
var heartbeat = new VexWorkerHeartbeat(
|
||||
VexWorkerHeartbeatStatus.Running,
|
||||
Progress: 50,
|
||||
QueueDepth: null,
|
||||
LastArtifactHash: "sha256:abc123",
|
||||
LastArtifactKind: "vex-document",
|
||||
ErrorCode: null,
|
||||
RetryAfterSeconds: null);
|
||||
|
||||
await client.SendHeartbeatAsync(context, heartbeat);
|
||||
|
||||
var state = await _stateRepository.GetAsync("connector-001", CancellationToken.None);
|
||||
Assert.NotNull(state);
|
||||
Assert.Equal("Running", state.LastHeartbeatStatus);
|
||||
Assert.NotNull(state.LastHeartbeatAt);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task RecordArtifactAsync_TracksArtifactHash()
|
||||
{
|
||||
var client = CreateClient();
|
||||
var context = await client.StartJobAsync("tenant-a", "connector-001", null);
|
||||
|
||||
var artifact = new VexWorkerArtifact(
|
||||
"sha256:deadbeef",
|
||||
"vex-raw-document",
|
||||
"provider-001",
|
||||
"doc-001",
|
||||
_timeProvider.GetUtcNow());
|
||||
|
||||
await client.RecordArtifactAsync(context, artifact);
|
||||
|
||||
var state = await _stateRepository.GetAsync("connector-001", CancellationToken.None);
|
||||
Assert.NotNull(state);
|
||||
Assert.Equal("sha256:deadbeef", state.LastArtifactHash);
|
||||
Assert.Equal("vex-raw-document", state.LastArtifactKind);
|
||||
Assert.Contains("sha256:deadbeef", state.DocumentDigests);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task CompleteJobAsync_UpdatesStateWithResults()
|
||||
{
|
||||
var client = CreateClient();
|
||||
var context = await client.StartJobAsync("tenant-a", "connector-001", null);
|
||||
var completedAt = _timeProvider.GetUtcNow();
|
||||
|
||||
var result = new VexWorkerJobResult(
|
||||
DocumentsProcessed: 10,
|
||||
ClaimsGenerated: 25,
|
||||
LastCheckpoint: "checkpoint-new",
|
||||
LastArtifactHash: "sha256:final",
|
||||
CompletedAt: completedAt);
|
||||
|
||||
await client.CompleteJobAsync(context, result);
|
||||
|
||||
var state = await _stateRepository.GetAsync("connector-001", CancellationToken.None);
|
||||
Assert.NotNull(state);
|
||||
Assert.Equal("Succeeded", state.LastHeartbeatStatus);
|
||||
Assert.Equal("checkpoint-new", state.LastCheckpoint);
|
||||
Assert.Equal("sha256:final", state.LastArtifactHash);
|
||||
Assert.Equal(0, state.FailureCount);
|
||||
Assert.Null(state.NextEligibleRun);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task FailJobAsync_UpdatesStateWithError()
|
||||
{
|
||||
var client = CreateClient();
|
||||
var context = await client.StartJobAsync("tenant-a", "connector-001", null);
|
||||
|
||||
await client.FailJobAsync(context, "CONN_ERROR", "Connection failed", retryAfterSeconds: 60);
|
||||
|
||||
var state = await _stateRepository.GetAsync("connector-001", CancellationToken.None);
|
||||
Assert.NotNull(state);
|
||||
Assert.Equal("Failed", state.LastHeartbeatStatus);
|
||||
Assert.Equal(1, state.FailureCount);
|
||||
Assert.Contains("CONN_ERROR", state.LastFailureReason);
|
||||
Assert.NotNull(state.NextEligibleRun);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void VexWorkerJobContext_SequenceIncrements()
|
||||
{
|
||||
var context = new VexWorkerJobContext(
|
||||
"tenant-a",
|
||||
"connector-001",
|
||||
Guid.NewGuid(),
|
||||
null,
|
||||
DateTimeOffset.UtcNow);
|
||||
|
||||
Assert.Equal(0, context.Sequence);
|
||||
Assert.Equal(1, context.NextSequence());
|
||||
Assert.Equal(2, context.NextSequence());
|
||||
Assert.Equal(3, context.NextSequence());
|
||||
}
|
||||
|
||||
private VexWorkerOrchestratorClient CreateClient()
|
||||
=> new(
|
||||
_stateRepository,
|
||||
_timeProvider,
|
||||
_options,
|
||||
NullLogger<VexWorkerOrchestratorClient>.Instance);
|
||||
|
||||
private sealed class FakeTimeProvider : TimeProvider
|
||||
{
|
||||
private DateTimeOffset _now = new(2025, 11, 27, 12, 0, 0, TimeSpan.Zero);
|
||||
|
||||
public override DateTimeOffset GetUtcNow() => _now;
|
||||
|
||||
public void Advance(TimeSpan duration) => _now = _now.Add(duration);
|
||||
}
|
||||
|
||||
private sealed class InMemoryConnectorStateRepository : IVexConnectorStateRepository
|
||||
{
|
||||
private readonly Dictionary<string, VexConnectorState> _states = new(StringComparer.OrdinalIgnoreCase);
|
||||
|
||||
public ValueTask<VexConnectorState?> GetAsync(string connectorId, CancellationToken cancellationToken, MongoDB.Driver.IClientSessionHandle? session = null)
|
||||
{
|
||||
_states.TryGetValue(connectorId, out var state);
|
||||
return ValueTask.FromResult(state);
|
||||
}
|
||||
|
||||
public ValueTask SaveAsync(VexConnectorState state, CancellationToken cancellationToken, MongoDB.Driver.IClientSessionHandle? session = null)
|
||||
{
|
||||
_states[state.ConnectorId] = state;
|
||||
return ValueTask.CompletedTask;
|
||||
}
|
||||
|
||||
public ValueTask<IReadOnlyCollection<VexConnectorState>> ListAsync(CancellationToken cancellationToken, MongoDB.Driver.IClientSessionHandle? session = null)
|
||||
=> ValueTask.FromResult<IReadOnlyCollection<VexConnectorState>>(_states.Values.ToList());
|
||||
}
|
||||
}
|
||||
@@ -15,7 +15,7 @@ public sealed class TenantAuthorityClientFactoryTests
|
||||
{
|
||||
var options = new TenantAuthorityOptions();
|
||||
options.BaseUrls.Add("tenant-a", "https://authority.example/");
|
||||
var factory = new TenantAuthorityClientFactory(Options.Create(options));
|
||||
var factory = new TenantAuthorityClientFactory(Microsoft.Extensions.Options.Options.Create(options));
|
||||
|
||||
using var client = factory.Create("tenant-a");
|
||||
|
||||
@@ -29,7 +29,7 @@ public sealed class TenantAuthorityClientFactoryTests
|
||||
{
|
||||
var options = new TenantAuthorityOptions();
|
||||
options.BaseUrls.Add("tenant-a", "https://authority.example/");
|
||||
var factory = new TenantAuthorityClientFactory(Options.Create(options));
|
||||
var factory = new TenantAuthorityClientFactory(Microsoft.Extensions.Options.Options.Create(options));
|
||||
|
||||
FluentActions.Invoking(() => factory.Create(string.Empty))
|
||||
.Should().Throw<ArgumentException>();
|
||||
@@ -40,7 +40,7 @@ public sealed class TenantAuthorityClientFactoryTests
|
||||
{
|
||||
var options = new TenantAuthorityOptions();
|
||||
options.BaseUrls.Add("tenant-a", "https://authority.example/");
|
||||
var factory = new TenantAuthorityClientFactory(Options.Create(options));
|
||||
var factory = new TenantAuthorityClientFactory(Microsoft.Extensions.Options.Options.Create(options));
|
||||
|
||||
FluentActions.Invoking(() => factory.Create("tenant-b"))
|
||||
.Should().Throw<InvalidOperationException>();
|
||||
|
||||
@@ -0,0 +1,352 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Diagnostics;
|
||||
|
||||
namespace StellaOps.Policy.Engine.DeterminismGuard;
|
||||
|
||||
/// <summary>
|
||||
/// Service that enforces determinism constraints during policy evaluation.
|
||||
/// Combines static analysis and runtime monitoring.
|
||||
/// </summary>
|
||||
public sealed class DeterminismGuardService
|
||||
{
|
||||
private readonly ProhibitedPatternAnalyzer _analyzer;
|
||||
private readonly DeterminismGuardOptions _options;
|
||||
private readonly RuntimeDeterminismMonitor _runtimeMonitor;
|
||||
|
||||
public DeterminismGuardService(DeterminismGuardOptions? options = null)
|
||||
{
|
||||
_options = options ?? DeterminismGuardOptions.Default;
|
||||
_analyzer = new ProhibitedPatternAnalyzer();
|
||||
_runtimeMonitor = new RuntimeDeterminismMonitor(_options);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Analyzes source code for determinism violations.
|
||||
/// </summary>
|
||||
public DeterminismAnalysisResult AnalyzeSource(string sourceCode, string? fileName = null)
|
||||
{
|
||||
return _analyzer.AnalyzeSource(sourceCode, fileName, _options);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a guarded execution scope for policy evaluation.
|
||||
/// </summary>
|
||||
public EvaluationScope CreateScope(string scopeId, DateTimeOffset evaluationTimestamp)
|
||||
{
|
||||
return new EvaluationScope(scopeId, evaluationTimestamp, _options, _runtimeMonitor);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Validates that a policy evaluation context is deterministic.
|
||||
/// </summary>
|
||||
public DeterminismAnalysisResult ValidateContext<TContext>(TContext context, string contextName)
|
||||
{
|
||||
var stopwatch = Stopwatch.StartNew();
|
||||
var violations = new List<DeterminismViolation>();
|
||||
|
||||
// Check for null
|
||||
if (context is null)
|
||||
{
|
||||
violations.Add(new DeterminismViolation
|
||||
{
|
||||
Category = DeterminismViolationCategory.Other,
|
||||
ViolationType = "NullContext",
|
||||
Message = $"Evaluation context '{contextName}' is null",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Provide a valid evaluation context"
|
||||
});
|
||||
}
|
||||
|
||||
stopwatch.Stop();
|
||||
|
||||
var countBySeverity = violations
|
||||
.GroupBy(v => v.Severity)
|
||||
.ToImmutableDictionary(g => g.Key, g => g.Count());
|
||||
|
||||
var hasBlockingViolation = violations.Any(v => v.Severity >= _options.FailOnSeverity);
|
||||
var passed = !_options.EnforcementEnabled || !hasBlockingViolation;
|
||||
|
||||
return new DeterminismAnalysisResult
|
||||
{
|
||||
Passed = passed,
|
||||
Violations = violations.ToImmutableArray(),
|
||||
CountBySeverity = countBySeverity,
|
||||
AnalysisDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
EnforcementEnabled = _options.EnforcementEnabled
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets a determinism-safe time provider that only returns injected timestamps.
|
||||
/// </summary>
|
||||
public DeterministicTimeProvider GetTimeProvider(DateTimeOffset fixedTimestamp)
|
||||
{
|
||||
return new DeterministicTimeProvider(fixedTimestamp);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A guarded scope for policy evaluation that tracks determinism violations.
|
||||
/// </summary>
|
||||
public sealed class EvaluationScope : IDisposable
|
||||
{
|
||||
private readonly string _scopeId;
|
||||
private readonly DateTimeOffset _evaluationTimestamp;
|
||||
private readonly DeterminismGuardOptions _options;
|
||||
private readonly RuntimeDeterminismMonitor _monitor;
|
||||
private readonly Stopwatch _stopwatch;
|
||||
private readonly List<DeterminismViolation> _violations;
|
||||
private bool _disposed;
|
||||
|
||||
internal EvaluationScope(
|
||||
string scopeId,
|
||||
DateTimeOffset evaluationTimestamp,
|
||||
DeterminismGuardOptions options,
|
||||
RuntimeDeterminismMonitor monitor)
|
||||
{
|
||||
_scopeId = scopeId ?? throw new ArgumentNullException(nameof(scopeId));
|
||||
_evaluationTimestamp = evaluationTimestamp;
|
||||
_options = options;
|
||||
_monitor = monitor;
|
||||
_stopwatch = Stopwatch.StartNew();
|
||||
_violations = new List<DeterminismViolation>();
|
||||
|
||||
if (_options.EnableRuntimeMonitoring)
|
||||
{
|
||||
_monitor.EnterScope(scopeId);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Scope identifier for tracing.
|
||||
/// </summary>
|
||||
public string ScopeId => _scopeId;
|
||||
|
||||
/// <summary>
|
||||
/// The fixed evaluation timestamp for this scope.
|
||||
/// </summary>
|
||||
public DateTimeOffset EvaluationTimestamp => _evaluationTimestamp;
|
||||
|
||||
/// <summary>
|
||||
/// Reports a runtime violation detected during evaluation.
|
||||
/// </summary>
|
||||
public void ReportViolation(DeterminismViolation violation)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(violation);
|
||||
|
||||
lock (_violations)
|
||||
{
|
||||
_violations.Add(violation);
|
||||
}
|
||||
|
||||
if (_options.EnforcementEnabled && violation.Severity >= _options.FailOnSeverity)
|
||||
{
|
||||
throw new DeterminismViolationException(violation);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the current timestamp (always returns the fixed evaluation timestamp).
|
||||
/// </summary>
|
||||
public DateTimeOffset GetTimestamp() => _evaluationTimestamp;
|
||||
|
||||
/// <summary>
|
||||
/// Gets all violations recorded in this scope.
|
||||
/// </summary>
|
||||
public IReadOnlyList<DeterminismViolation> GetViolations()
|
||||
{
|
||||
lock (_violations)
|
||||
{
|
||||
return _violations.ToList();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Completes the scope and returns analysis results.
|
||||
/// </summary>
|
||||
public DeterminismAnalysisResult Complete()
|
||||
{
|
||||
_stopwatch.Stop();
|
||||
|
||||
IReadOnlyList<DeterminismViolation> allViolations;
|
||||
lock (_violations)
|
||||
{
|
||||
allViolations = _violations.ToList();
|
||||
}
|
||||
|
||||
var countBySeverity = allViolations
|
||||
.GroupBy(v => v.Severity)
|
||||
.ToImmutableDictionary(g => g.Key, g => g.Count());
|
||||
|
||||
var hasBlockingViolation = allViolations.Any(v => v.Severity >= _options.FailOnSeverity);
|
||||
var passed = !_options.EnforcementEnabled || !hasBlockingViolation;
|
||||
|
||||
return new DeterminismAnalysisResult
|
||||
{
|
||||
Passed = passed,
|
||||
Violations = allViolations.ToImmutableArray(),
|
||||
CountBySeverity = countBySeverity,
|
||||
AnalysisDurationMs = _stopwatch.ElapsedMilliseconds,
|
||||
EnforcementEnabled = _options.EnforcementEnabled
|
||||
};
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
if (_disposed)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
_disposed = true;
|
||||
|
||||
if (_options.EnableRuntimeMonitoring)
|
||||
{
|
||||
_monitor.ExitScope(_scopeId);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Exception thrown when a determinism violation is detected with enforcement enabled.
|
||||
/// </summary>
|
||||
public sealed class DeterminismViolationException : Exception
|
||||
{
|
||||
public DeterminismViolationException(DeterminismViolation violation)
|
||||
: base($"Determinism violation: {violation.Message}")
|
||||
{
|
||||
Violation = violation;
|
||||
}
|
||||
|
||||
public DeterminismViolation Violation { get; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Time provider that always returns a fixed timestamp.
|
||||
/// </summary>
|
||||
public sealed class DeterministicTimeProvider : TimeProvider
|
||||
{
|
||||
private readonly DateTimeOffset _fixedTimestamp;
|
||||
|
||||
public DeterministicTimeProvider(DateTimeOffset fixedTimestamp)
|
||||
{
|
||||
_fixedTimestamp = fixedTimestamp;
|
||||
}
|
||||
|
||||
public override DateTimeOffset GetUtcNow() => _fixedTimestamp;
|
||||
|
||||
public override TimeZoneInfo LocalTimeZone => TimeZoneInfo.Utc;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Runtime monitor for detecting non-deterministic operations.
|
||||
/// </summary>
|
||||
internal sealed class RuntimeDeterminismMonitor
|
||||
{
|
||||
private readonly DeterminismGuardOptions _options;
|
||||
private readonly HashSet<string> _activeScopes = new(StringComparer.Ordinal);
|
||||
private readonly object _lock = new();
|
||||
|
||||
public RuntimeDeterminismMonitor(DeterminismGuardOptions options)
|
||||
{
|
||||
_options = options;
|
||||
}
|
||||
|
||||
public void EnterScope(string scopeId)
|
||||
{
|
||||
lock (_lock)
|
||||
{
|
||||
_activeScopes.Add(scopeId);
|
||||
}
|
||||
}
|
||||
|
||||
public void ExitScope(string scopeId)
|
||||
{
|
||||
lock (_lock)
|
||||
{
|
||||
_activeScopes.Remove(scopeId);
|
||||
}
|
||||
}
|
||||
|
||||
public bool IsInScope => _activeScopes.Count > 0;
|
||||
|
||||
/// <summary>
|
||||
/// Checks if we're in a guarded scope and should intercept operations.
|
||||
/// </summary>
|
||||
public bool ShouldIntercept()
|
||||
{
|
||||
return _options.EnableRuntimeMonitoring && IsInScope;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extension methods for integrating determinism guard with evaluation.
|
||||
/// </summary>
|
||||
public static class DeterminismGuardExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Executes an evaluation function within a determinism-guarded scope.
|
||||
/// </summary>
|
||||
public static TResult ExecuteGuarded<TResult>(
|
||||
this DeterminismGuardService guard,
|
||||
string scopeId,
|
||||
DateTimeOffset evaluationTimestamp,
|
||||
Func<EvaluationScope, TResult> evaluation)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(guard);
|
||||
ArgumentNullException.ThrowIfNull(evaluation);
|
||||
|
||||
using var scope = guard.CreateScope(scopeId, evaluationTimestamp);
|
||||
|
||||
try
|
||||
{
|
||||
return evaluation(scope);
|
||||
}
|
||||
finally
|
||||
{
|
||||
var result = scope.Complete();
|
||||
if (!result.Passed)
|
||||
{
|
||||
// Log violations even if not throwing
|
||||
foreach (var violation in result.Violations)
|
||||
{
|
||||
// In production, this would log to structured logging
|
||||
System.Diagnostics.Debug.WriteLine(
|
||||
$"[DeterminismGuard] {violation.Severity}: {violation.Message}");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Executes an async evaluation function within a determinism-guarded scope.
|
||||
/// </summary>
|
||||
public static async Task<TResult> ExecuteGuardedAsync<TResult>(
|
||||
this DeterminismGuardService guard,
|
||||
string scopeId,
|
||||
DateTimeOffset evaluationTimestamp,
|
||||
Func<EvaluationScope, Task<TResult>> evaluation)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(guard);
|
||||
ArgumentNullException.ThrowIfNull(evaluation);
|
||||
|
||||
using var scope = guard.CreateScope(scopeId, evaluationTimestamp);
|
||||
|
||||
try
|
||||
{
|
||||
return await evaluation(scope).ConfigureAwait(false);
|
||||
}
|
||||
finally
|
||||
{
|
||||
var result = scope.Complete();
|
||||
if (!result.Passed)
|
||||
{
|
||||
foreach (var violation in result.Violations)
|
||||
{
|
||||
System.Diagnostics.Debug.WriteLine(
|
||||
$"[DeterminismGuard] {violation.Severity}: {violation.Message}");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,197 @@
|
||||
using System.Collections.Immutable;
|
||||
|
||||
namespace StellaOps.Policy.Engine.DeterminismGuard;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a determinism violation detected during static analysis or runtime.
|
||||
/// </summary>
|
||||
public sealed record DeterminismViolation
|
||||
{
|
||||
/// <summary>
|
||||
/// Category of the violation.
|
||||
/// </summary>
|
||||
public required DeterminismViolationCategory Category { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Specific violation type.
|
||||
/// </summary>
|
||||
public required string ViolationType { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Human-readable description of the violation.
|
||||
/// </summary>
|
||||
public required string Message { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Source location (file path, if known).
|
||||
/// </summary>
|
||||
public string? SourceFile { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Line number (if known from static analysis).
|
||||
/// </summary>
|
||||
public int? LineNumber { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Member or method name where violation occurred.
|
||||
/// </summary>
|
||||
public string? MemberName { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Severity of the violation.
|
||||
/// </summary>
|
||||
public required DeterminismViolationSeverity Severity { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Suggested remediation.
|
||||
/// </summary>
|
||||
public string? Remediation { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Category of determinism violation.
|
||||
/// </summary>
|
||||
public enum DeterminismViolationCategory
|
||||
{
|
||||
/// <summary>Wall-clock time access (DateTime.Now, etc.).</summary>
|
||||
WallClock,
|
||||
|
||||
/// <summary>Random number generation.</summary>
|
||||
RandomNumber,
|
||||
|
||||
/// <summary>Network access (HttpClient, sockets, etc.).</summary>
|
||||
NetworkAccess,
|
||||
|
||||
/// <summary>Filesystem access.</summary>
|
||||
FileSystemAccess,
|
||||
|
||||
/// <summary>Environment variable access.</summary>
|
||||
EnvironmentAccess,
|
||||
|
||||
/// <summary>GUID generation.</summary>
|
||||
GuidGeneration,
|
||||
|
||||
/// <summary>Thread/Task operations that may introduce non-determinism.</summary>
|
||||
ConcurrencyHazard,
|
||||
|
||||
/// <summary>Floating-point operations that may have platform variance.</summary>
|
||||
FloatingPointHazard,
|
||||
|
||||
/// <summary>Dictionary iteration without stable ordering.</summary>
|
||||
UnstableIteration,
|
||||
|
||||
/// <summary>Other non-deterministic operation.</summary>
|
||||
Other
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Severity level of a determinism violation.
|
||||
/// </summary>
|
||||
public enum DeterminismViolationSeverity
|
||||
{
|
||||
/// <summary>Informational - may not cause issues.</summary>
|
||||
Info,
|
||||
|
||||
/// <summary>Warning - potential non-determinism.</summary>
|
||||
Warning,
|
||||
|
||||
/// <summary>Error - definite non-determinism source.</summary>
|
||||
Error,
|
||||
|
||||
/// <summary>Critical - must be fixed before deployment.</summary>
|
||||
Critical
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Result of determinism analysis.
|
||||
/// </summary>
|
||||
public sealed record DeterminismAnalysisResult
|
||||
{
|
||||
/// <summary>
|
||||
/// Whether the analysis passed (no critical/error violations).
|
||||
/// </summary>
|
||||
public required bool Passed { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// All violations found.
|
||||
/// </summary>
|
||||
public required ImmutableArray<DeterminismViolation> Violations { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Count of violations by severity.
|
||||
/// </summary>
|
||||
public required ImmutableDictionary<DeterminismViolationSeverity, int> CountBySeverity { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Analysis duration in milliseconds.
|
||||
/// </summary>
|
||||
public required long AnalysisDurationMs { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Whether the guard is currently enforcing (blocking on violations).
|
||||
/// </summary>
|
||||
public required bool EnforcementEnabled { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Creates a passing result with no violations.
|
||||
/// </summary>
|
||||
public static DeterminismAnalysisResult Pass(long durationMs, bool enforcementEnabled) => new()
|
||||
{
|
||||
Passed = true,
|
||||
Violations = ImmutableArray<DeterminismViolation>.Empty,
|
||||
CountBySeverity = ImmutableDictionary<DeterminismViolationSeverity, int>.Empty,
|
||||
AnalysisDurationMs = durationMs,
|
||||
EnforcementEnabled = enforcementEnabled
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Configuration for determinism guard behavior.
|
||||
/// </summary>
|
||||
public sealed record DeterminismGuardOptions
|
||||
{
|
||||
/// <summary>
|
||||
/// Whether enforcement is enabled (blocks on violations).
|
||||
/// </summary>
|
||||
public bool EnforcementEnabled { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// Minimum severity level to fail enforcement.
|
||||
/// </summary>
|
||||
public DeterminismViolationSeverity FailOnSeverity { get; init; } = DeterminismViolationSeverity.Error;
|
||||
|
||||
/// <summary>
|
||||
/// Whether to log all violations regardless of enforcement.
|
||||
/// </summary>
|
||||
public bool LogAllViolations { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// Whether to analyze code statically before execution.
|
||||
/// </summary>
|
||||
public bool EnableStaticAnalysis { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// Whether to monitor runtime behavior.
|
||||
/// </summary>
|
||||
public bool EnableRuntimeMonitoring { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// Patterns to exclude from analysis (e.g., test code).
|
||||
/// </summary>
|
||||
public ImmutableArray<string> ExcludePatterns { get; init; } = ImmutableArray<string>.Empty;
|
||||
|
||||
/// <summary>
|
||||
/// Default options for production use.
|
||||
/// </summary>
|
||||
public static DeterminismGuardOptions Default { get; } = new();
|
||||
|
||||
/// <summary>
|
||||
/// Options for development/testing (warnings only).
|
||||
/// </summary>
|
||||
public static DeterminismGuardOptions Development { get; } = new()
|
||||
{
|
||||
EnforcementEnabled = false,
|
||||
FailOnSeverity = DeterminismViolationSeverity.Critical,
|
||||
LogAllViolations = true
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,375 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Diagnostics;
|
||||
using StellaOps.PolicyDsl;
|
||||
|
||||
namespace StellaOps.Policy.Engine.DeterminismGuard;
|
||||
|
||||
/// <summary>
|
||||
/// Wraps policy evaluation with determinism guard protection.
|
||||
/// Enforces static analysis and runtime monitoring during evaluation.
|
||||
/// </summary>
|
||||
public sealed class GuardedPolicyEvaluator
|
||||
{
|
||||
private readonly DeterminismGuardService _guard;
|
||||
private readonly ProhibitedPatternAnalyzer _analyzer;
|
||||
|
||||
public GuardedPolicyEvaluator(DeterminismGuardOptions? options = null)
|
||||
{
|
||||
var opts = options ?? DeterminismGuardOptions.Default;
|
||||
_guard = new DeterminismGuardService(opts);
|
||||
_analyzer = new ProhibitedPatternAnalyzer();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Pre-validates policy source code for determinism violations.
|
||||
/// Should be called during policy compilation/registration.
|
||||
/// </summary>
|
||||
public DeterminismAnalysisResult ValidatePolicySource(
|
||||
string sourceCode,
|
||||
string? fileName = null,
|
||||
DeterminismGuardOptions? options = null)
|
||||
{
|
||||
return _guard.AnalyzeSource(sourceCode, fileName);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Pre-validates multiple policy source files.
|
||||
/// </summary>
|
||||
public DeterminismAnalysisResult ValidatePolicySources(
|
||||
IEnumerable<(string SourceCode, string FileName)> sources,
|
||||
DeterminismGuardOptions? options = null)
|
||||
{
|
||||
var opts = options ?? DeterminismGuardOptions.Default;
|
||||
return _analyzer.AnalyzeMultiple(sources, opts);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Evaluates a policy within a determinism-guarded scope.
|
||||
/// </summary>
|
||||
public GuardedEvaluationResult<TResult> Evaluate<TResult>(
|
||||
string scopeId,
|
||||
DateTimeOffset evaluationTimestamp,
|
||||
Func<EvaluationScope, TResult> evaluation)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(evaluation);
|
||||
|
||||
var stopwatch = Stopwatch.StartNew();
|
||||
using var scope = _guard.CreateScope(scopeId, evaluationTimestamp);
|
||||
|
||||
try
|
||||
{
|
||||
var result = evaluation(scope);
|
||||
var guardResult = scope.Complete();
|
||||
stopwatch.Stop();
|
||||
|
||||
return new GuardedEvaluationResult<TResult>
|
||||
{
|
||||
Succeeded = guardResult.Passed,
|
||||
Result = result,
|
||||
Violations = guardResult.Violations,
|
||||
EvaluationDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
ScopeId = scopeId,
|
||||
EvaluationTimestamp = evaluationTimestamp
|
||||
};
|
||||
}
|
||||
catch (DeterminismViolationException ex)
|
||||
{
|
||||
var guardResult = scope.Complete();
|
||||
stopwatch.Stop();
|
||||
|
||||
return new GuardedEvaluationResult<TResult>
|
||||
{
|
||||
Succeeded = false,
|
||||
Result = default,
|
||||
Violations = guardResult.Violations,
|
||||
BlockingViolation = ex.Violation,
|
||||
EvaluationDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
ScopeId = scopeId,
|
||||
EvaluationTimestamp = evaluationTimestamp
|
||||
};
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
var violations = scope.GetViolations();
|
||||
stopwatch.Stop();
|
||||
|
||||
// Record the unexpected exception as a violation
|
||||
var exceptionViolation = new DeterminismViolation
|
||||
{
|
||||
Category = DeterminismViolationCategory.Other,
|
||||
ViolationType = "EvaluationException",
|
||||
Message = $"Unexpected exception during evaluation: {ex.Message}",
|
||||
Severity = DeterminismViolationSeverity.Critical,
|
||||
Remediation = "Review policy logic for errors"
|
||||
};
|
||||
|
||||
var allViolations = violations
|
||||
.Append(exceptionViolation)
|
||||
.ToImmutableArray();
|
||||
|
||||
return new GuardedEvaluationResult<TResult>
|
||||
{
|
||||
Succeeded = false,
|
||||
Result = default,
|
||||
Violations = allViolations,
|
||||
BlockingViolation = exceptionViolation,
|
||||
EvaluationDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
ScopeId = scopeId,
|
||||
EvaluationTimestamp = evaluationTimestamp,
|
||||
Exception = ex
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Evaluates a policy asynchronously within a determinism-guarded scope.
|
||||
/// </summary>
|
||||
public async Task<GuardedEvaluationResult<TResult>> EvaluateAsync<TResult>(
|
||||
string scopeId,
|
||||
DateTimeOffset evaluationTimestamp,
|
||||
Func<EvaluationScope, Task<TResult>> evaluation,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(evaluation);
|
||||
|
||||
var stopwatch = Stopwatch.StartNew();
|
||||
using var scope = _guard.CreateScope(scopeId, evaluationTimestamp);
|
||||
|
||||
try
|
||||
{
|
||||
var result = await evaluation(scope).ConfigureAwait(false);
|
||||
var guardResult = scope.Complete();
|
||||
stopwatch.Stop();
|
||||
|
||||
return new GuardedEvaluationResult<TResult>
|
||||
{
|
||||
Succeeded = guardResult.Passed,
|
||||
Result = result,
|
||||
Violations = guardResult.Violations,
|
||||
EvaluationDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
ScopeId = scopeId,
|
||||
EvaluationTimestamp = evaluationTimestamp
|
||||
};
|
||||
}
|
||||
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
throw;
|
||||
}
|
||||
catch (DeterminismViolationException ex)
|
||||
{
|
||||
var guardResult = scope.Complete();
|
||||
stopwatch.Stop();
|
||||
|
||||
return new GuardedEvaluationResult<TResult>
|
||||
{
|
||||
Succeeded = false,
|
||||
Result = default,
|
||||
Violations = guardResult.Violations,
|
||||
BlockingViolation = ex.Violation,
|
||||
EvaluationDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
ScopeId = scopeId,
|
||||
EvaluationTimestamp = evaluationTimestamp
|
||||
};
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
var violations = scope.GetViolations();
|
||||
stopwatch.Stop();
|
||||
|
||||
var exceptionViolation = new DeterminismViolation
|
||||
{
|
||||
Category = DeterminismViolationCategory.Other,
|
||||
ViolationType = "EvaluationException",
|
||||
Message = $"Unexpected exception during evaluation: {ex.Message}",
|
||||
Severity = DeterminismViolationSeverity.Critical,
|
||||
Remediation = "Review policy logic for errors"
|
||||
};
|
||||
|
||||
var allViolations = violations
|
||||
.Append(exceptionViolation)
|
||||
.ToImmutableArray();
|
||||
|
||||
return new GuardedEvaluationResult<TResult>
|
||||
{
|
||||
Succeeded = false,
|
||||
Result = default,
|
||||
Violations = allViolations,
|
||||
BlockingViolation = exceptionViolation,
|
||||
EvaluationDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
ScopeId = scopeId,
|
||||
EvaluationTimestamp = evaluationTimestamp,
|
||||
Exception = ex
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the determinism guard service for advanced usage.
|
||||
/// </summary>
|
||||
public DeterminismGuardService Guard => _guard;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Result of a guarded policy evaluation.
|
||||
/// </summary>
|
||||
public sealed record GuardedEvaluationResult<TResult>
|
||||
{
|
||||
/// <summary>
|
||||
/// Whether the evaluation succeeded without blocking violations.
|
||||
/// </summary>
|
||||
public required bool Succeeded { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// The evaluation result (may be default if failed).
|
||||
/// </summary>
|
||||
public TResult? Result { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// All violations detected during evaluation.
|
||||
/// </summary>
|
||||
public required ImmutableArray<DeterminismViolation> Violations { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// The violation that caused evaluation to be blocked (if any).
|
||||
/// </summary>
|
||||
public DeterminismViolation? BlockingViolation { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Evaluation duration in milliseconds.
|
||||
/// </summary>
|
||||
public required long EvaluationDurationMs { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Scope identifier for tracing.
|
||||
/// </summary>
|
||||
public required string ScopeId { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// The fixed evaluation timestamp used.
|
||||
/// </summary>
|
||||
public required DateTimeOffset EvaluationTimestamp { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Exception that occurred during evaluation (if any).
|
||||
/// </summary>
|
||||
public Exception? Exception { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Number of violations by severity.
|
||||
/// </summary>
|
||||
public ImmutableDictionary<DeterminismViolationSeverity, int> ViolationCountBySeverity =>
|
||||
Violations
|
||||
.GroupBy(v => v.Severity)
|
||||
.ToImmutableDictionary(g => g.Key, g => g.Count());
|
||||
|
||||
/// <summary>
|
||||
/// Whether there are any violations (blocking or not).
|
||||
/// </summary>
|
||||
public bool HasViolations => !Violations.IsDefaultOrEmpty;
|
||||
|
||||
/// <summary>
|
||||
/// Whether the evaluation was blocked by a violation.
|
||||
/// </summary>
|
||||
public bool WasBlocked => BlockingViolation is not null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Builder for creating guarded policy evaluator with custom configuration.
|
||||
/// </summary>
|
||||
public sealed class GuardedPolicyEvaluatorBuilder
|
||||
{
|
||||
private bool _enforcementEnabled = true;
|
||||
private DeterminismViolationSeverity _failOnSeverity = DeterminismViolationSeverity.Error;
|
||||
private bool _enableStaticAnalysis = true;
|
||||
private bool _enableRuntimeMonitoring = true;
|
||||
private bool _logAllViolations = true;
|
||||
private ImmutableArray<string> _excludePatterns = ImmutableArray<string>.Empty;
|
||||
|
||||
/// <summary>
|
||||
/// Enables or disables enforcement (blocking on violations).
|
||||
/// </summary>
|
||||
public GuardedPolicyEvaluatorBuilder WithEnforcement(bool enabled)
|
||||
{
|
||||
_enforcementEnabled = enabled;
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Sets the minimum severity level to block evaluation.
|
||||
/// </summary>
|
||||
public GuardedPolicyEvaluatorBuilder FailOnSeverity(DeterminismViolationSeverity severity)
|
||||
{
|
||||
_failOnSeverity = severity;
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Enables or disables static code analysis.
|
||||
/// </summary>
|
||||
public GuardedPolicyEvaluatorBuilder WithStaticAnalysis(bool enabled)
|
||||
{
|
||||
_enableStaticAnalysis = enabled;
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Enables or disables runtime monitoring.
|
||||
/// </summary>
|
||||
public GuardedPolicyEvaluatorBuilder WithRuntimeMonitoring(bool enabled)
|
||||
{
|
||||
_enableRuntimeMonitoring = enabled;
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Enables or disables logging of all violations.
|
||||
/// </summary>
|
||||
public GuardedPolicyEvaluatorBuilder WithViolationLogging(bool enabled)
|
||||
{
|
||||
_logAllViolations = enabled;
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds patterns to exclude from analysis.
|
||||
/// </summary>
|
||||
public GuardedPolicyEvaluatorBuilder ExcludePatterns(params string[] patterns)
|
||||
{
|
||||
_excludePatterns = _excludePatterns.AddRange(patterns);
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates the configured GuardedPolicyEvaluator.
|
||||
/// </summary>
|
||||
public GuardedPolicyEvaluator Build()
|
||||
{
|
||||
var options = new DeterminismGuardOptions
|
||||
{
|
||||
EnforcementEnabled = _enforcementEnabled,
|
||||
FailOnSeverity = _failOnSeverity,
|
||||
EnableStaticAnalysis = _enableStaticAnalysis,
|
||||
EnableRuntimeMonitoring = _enableRuntimeMonitoring,
|
||||
LogAllViolations = _logAllViolations,
|
||||
ExcludePatterns = _excludePatterns
|
||||
};
|
||||
|
||||
return new GuardedPolicyEvaluator(options);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a development-mode evaluator (warnings only, no blocking).
|
||||
/// </summary>
|
||||
public static GuardedPolicyEvaluator CreateDevelopment()
|
||||
{
|
||||
return new GuardedPolicyEvaluator(DeterminismGuardOptions.Development);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a production-mode evaluator (full enforcement).
|
||||
/// </summary>
|
||||
public static GuardedPolicyEvaluator CreateProduction()
|
||||
{
|
||||
return new GuardedPolicyEvaluator(DeterminismGuardOptions.Default);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,412 @@
|
||||
using System.Collections.Immutable;
|
||||
using System.Diagnostics;
|
||||
using System.Text.RegularExpressions;
|
||||
|
||||
namespace StellaOps.Policy.Engine.DeterminismGuard;
|
||||
|
||||
/// <summary>
|
||||
/// Static analyzer that detects prohibited non-deterministic patterns in source code.
|
||||
/// </summary>
|
||||
public sealed partial class ProhibitedPatternAnalyzer
|
||||
{
|
||||
private static readonly ImmutableArray<ProhibitedPattern> Patterns = CreatePatterns();
|
||||
|
||||
/// <summary>
|
||||
/// Analyzes source code for prohibited patterns.
|
||||
/// </summary>
|
||||
public DeterminismAnalysisResult AnalyzeSource(
|
||||
string sourceCode,
|
||||
string? fileName,
|
||||
DeterminismGuardOptions options)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(sourceCode);
|
||||
options ??= DeterminismGuardOptions.Default;
|
||||
|
||||
var stopwatch = Stopwatch.StartNew();
|
||||
var violations = new List<DeterminismViolation>();
|
||||
|
||||
// Check exclusions
|
||||
if (fileName is not null && IsExcluded(fileName, options.ExcludePatterns))
|
||||
{
|
||||
return DeterminismAnalysisResult.Pass(stopwatch.ElapsedMilliseconds, options.EnforcementEnabled);
|
||||
}
|
||||
|
||||
// Split into lines for line number tracking
|
||||
var lines = sourceCode.Split('\n');
|
||||
|
||||
for (var lineIndex = 0; lineIndex < lines.Length; lineIndex++)
|
||||
{
|
||||
var line = lines[lineIndex];
|
||||
var lineNumber = lineIndex + 1;
|
||||
|
||||
// Skip comments
|
||||
var trimmedLine = line.TrimStart();
|
||||
if (trimmedLine.StartsWith("//") || trimmedLine.StartsWith("/*") || trimmedLine.StartsWith("*"))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
foreach (var pattern in Patterns)
|
||||
{
|
||||
if (pattern.Regex.IsMatch(line))
|
||||
{
|
||||
violations.Add(new DeterminismViolation
|
||||
{
|
||||
Category = pattern.Category,
|
||||
ViolationType = pattern.ViolationType,
|
||||
Message = pattern.Message,
|
||||
SourceFile = fileName,
|
||||
LineNumber = lineNumber,
|
||||
MemberName = ExtractMemberContext(lines, lineIndex),
|
||||
Severity = pattern.Severity,
|
||||
Remediation = pattern.Remediation
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
stopwatch.Stop();
|
||||
|
||||
var countBySeverity = violations
|
||||
.GroupBy(v => v.Severity)
|
||||
.ToImmutableDictionary(g => g.Key, g => g.Count());
|
||||
|
||||
var hasBlockingViolation = violations.Any(v => v.Severity >= options.FailOnSeverity);
|
||||
var passed = !options.EnforcementEnabled || !hasBlockingViolation;
|
||||
|
||||
return new DeterminismAnalysisResult
|
||||
{
|
||||
Passed = passed,
|
||||
Violations = violations.ToImmutableArray(),
|
||||
CountBySeverity = countBySeverity,
|
||||
AnalysisDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
EnforcementEnabled = options.EnforcementEnabled
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Analyzes multiple source files.
|
||||
/// </summary>
|
||||
public DeterminismAnalysisResult AnalyzeMultiple(
|
||||
IEnumerable<(string SourceCode, string FileName)> sources,
|
||||
DeterminismGuardOptions options)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(sources);
|
||||
options ??= DeterminismGuardOptions.Default;
|
||||
|
||||
var stopwatch = Stopwatch.StartNew();
|
||||
var allViolations = new List<DeterminismViolation>();
|
||||
|
||||
foreach (var (sourceCode, fileName) in sources)
|
||||
{
|
||||
var result = AnalyzeSource(sourceCode, fileName, options with { EnforcementEnabled = false });
|
||||
allViolations.AddRange(result.Violations);
|
||||
}
|
||||
|
||||
stopwatch.Stop();
|
||||
|
||||
var countBySeverity = allViolations
|
||||
.GroupBy(v => v.Severity)
|
||||
.ToImmutableDictionary(g => g.Key, g => g.Count());
|
||||
|
||||
var hasBlockingViolation = allViolations.Any(v => v.Severity >= options.FailOnSeverity);
|
||||
var passed = !options.EnforcementEnabled || !hasBlockingViolation;
|
||||
|
||||
return new DeterminismAnalysisResult
|
||||
{
|
||||
Passed = passed,
|
||||
Violations = allViolations.ToImmutableArray(),
|
||||
CountBySeverity = countBySeverity,
|
||||
AnalysisDurationMs = stopwatch.ElapsedMilliseconds,
|
||||
EnforcementEnabled = options.EnforcementEnabled
|
||||
};
|
||||
}
|
||||
|
||||
private static bool IsExcluded(string fileName, ImmutableArray<string> excludePatterns)
|
||||
{
|
||||
if (excludePatterns.IsDefaultOrEmpty)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
return excludePatterns.Any(pattern =>
|
||||
fileName.Contains(pattern, StringComparison.OrdinalIgnoreCase));
|
||||
}
|
||||
|
||||
private static string? ExtractMemberContext(string[] lines, int lineIndex)
|
||||
{
|
||||
// Look backwards for method/property/class declaration
|
||||
for (var i = lineIndex; i >= 0 && i > lineIndex - 20; i--)
|
||||
{
|
||||
var line = lines[i].Trim();
|
||||
|
||||
// Method pattern
|
||||
var methodMatch = MethodDeclarationRegex().Match(line);
|
||||
if (methodMatch.Success)
|
||||
{
|
||||
return methodMatch.Groups[1].Value;
|
||||
}
|
||||
|
||||
// Property pattern
|
||||
var propertyMatch = PropertyDeclarationRegex().Match(line);
|
||||
if (propertyMatch.Success)
|
||||
{
|
||||
return propertyMatch.Groups[1].Value;
|
||||
}
|
||||
|
||||
// Class pattern
|
||||
var classMatch = ClassDeclarationRegex().Match(line);
|
||||
if (classMatch.Success)
|
||||
{
|
||||
return classMatch.Groups[1].Value;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
[GeneratedRegex(@"(?:public|private|protected|internal)\s+.*?\s+(\w+)\s*\(")]
|
||||
private static partial Regex MethodDeclarationRegex();
|
||||
|
||||
[GeneratedRegex(@"(?:public|private|protected|internal)\s+.*?\s+(\w+)\s*\{")]
|
||||
private static partial Regex PropertyDeclarationRegex();
|
||||
|
||||
[GeneratedRegex(@"(?:class|struct|record)\s+(\w+)")]
|
||||
private static partial Regex ClassDeclarationRegex();
|
||||
|
||||
private static ImmutableArray<ProhibitedPattern> CreatePatterns()
|
||||
{
|
||||
return ImmutableArray.Create(
|
||||
// Wall-clock violations
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.WallClock,
|
||||
ViolationType = "DateTime.Now",
|
||||
Regex = DateTimeNowRegex(),
|
||||
Message = "DateTime.Now usage detected - non-deterministic wall-clock access",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Use injected timestamp from evaluation context (context.Now)"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.WallClock,
|
||||
ViolationType = "DateTime.UtcNow",
|
||||
Regex = DateTimeUtcNowRegex(),
|
||||
Message = "DateTime.UtcNow usage detected - non-deterministic wall-clock access",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Use injected timestamp from evaluation context (context.Now)"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.WallClock,
|
||||
ViolationType = "DateTimeOffset.Now",
|
||||
Regex = DateTimeOffsetNowRegex(),
|
||||
Message = "DateTimeOffset.Now usage detected - non-deterministic wall-clock access",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Use injected timestamp from evaluation context (context.Now)"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.WallClock,
|
||||
ViolationType = "DateTimeOffset.UtcNow",
|
||||
Regex = DateTimeOffsetUtcNowRegex(),
|
||||
Message = "DateTimeOffset.UtcNow usage detected - non-deterministic wall-clock access",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Use injected timestamp from evaluation context (context.Now)"
|
||||
},
|
||||
|
||||
// Random number violations
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.RandomNumber,
|
||||
ViolationType = "Random",
|
||||
Regex = RandomClassRegex(),
|
||||
Message = "Random class usage detected - non-deterministic random number generation",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Use deterministic seeded random if needed, or remove randomness"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.RandomNumber,
|
||||
ViolationType = "RandomNumberGenerator",
|
||||
Regex = CryptoRandomRegex(),
|
||||
Message = "Cryptographic random usage detected - non-deterministic",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Remove cryptographic random from evaluation path"
|
||||
},
|
||||
|
||||
// GUID generation
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.GuidGeneration,
|
||||
ViolationType = "Guid.NewGuid",
|
||||
Regex = GuidNewGuidRegex(),
|
||||
Message = "Guid.NewGuid() usage detected - non-deterministic identifier generation",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Use deterministic ID generation based on content hash"
|
||||
},
|
||||
|
||||
// Network access
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.NetworkAccess,
|
||||
ViolationType = "HttpClient",
|
||||
Regex = HttpClientRegex(),
|
||||
Message = "HttpClient usage detected - network access is non-deterministic",
|
||||
Severity = DeterminismViolationSeverity.Critical,
|
||||
Remediation = "Remove network access from evaluation path"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.NetworkAccess,
|
||||
ViolationType = "WebClient",
|
||||
Regex = WebClientRegex(),
|
||||
Message = "WebClient usage detected - network access is non-deterministic",
|
||||
Severity = DeterminismViolationSeverity.Critical,
|
||||
Remediation = "Remove network access from evaluation path"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.NetworkAccess,
|
||||
ViolationType = "Socket",
|
||||
Regex = SocketRegex(),
|
||||
Message = "Socket usage detected - network access is non-deterministic",
|
||||
Severity = DeterminismViolationSeverity.Critical,
|
||||
Remediation = "Remove socket access from evaluation path"
|
||||
},
|
||||
|
||||
// Environment access
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.EnvironmentAccess,
|
||||
ViolationType = "Environment.GetEnvironmentVariable",
|
||||
Regex = EnvironmentGetEnvRegex(),
|
||||
Message = "Environment variable access detected - host-dependent",
|
||||
Severity = DeterminismViolationSeverity.Error,
|
||||
Remediation = "Use evaluation context environment properties instead"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.EnvironmentAccess,
|
||||
ViolationType = "Environment.MachineName",
|
||||
Regex = EnvironmentMachineNameRegex(),
|
||||
Message = "Environment.MachineName access detected - host-dependent",
|
||||
Severity = DeterminismViolationSeverity.Warning,
|
||||
Remediation = "Remove host-specific information from evaluation"
|
||||
},
|
||||
|
||||
// Filesystem access
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.FileSystemAccess,
|
||||
ViolationType = "File.Read",
|
||||
Regex = FileReadRegex(),
|
||||
Message = "File read operation detected - filesystem access is non-deterministic",
|
||||
Severity = DeterminismViolationSeverity.Critical,
|
||||
Remediation = "Remove file access from evaluation path"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.FileSystemAccess,
|
||||
ViolationType = "File.Write",
|
||||
Regex = FileWriteRegex(),
|
||||
Message = "File write operation detected - filesystem access is non-deterministic",
|
||||
Severity = DeterminismViolationSeverity.Critical,
|
||||
Remediation = "Remove file access from evaluation path"
|
||||
},
|
||||
|
||||
// Floating-point hazards
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.FloatingPointHazard,
|
||||
ViolationType = "double comparison",
|
||||
Regex = DoubleComparisonRegex(),
|
||||
Message = "Direct double comparison detected - may have platform variance",
|
||||
Severity = DeterminismViolationSeverity.Warning,
|
||||
Remediation = "Use decimal type for precise comparisons"
|
||||
},
|
||||
|
||||
// Unstable iteration
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.UnstableIteration,
|
||||
ViolationType = "Dictionary iteration",
|
||||
Regex = DictionaryIterationRegex(),
|
||||
Message = "Dictionary iteration detected - may have unstable ordering",
|
||||
Severity = DeterminismViolationSeverity.Warning,
|
||||
Remediation = "Use SortedDictionary or OrderBy before iteration"
|
||||
},
|
||||
new ProhibitedPattern
|
||||
{
|
||||
Category = DeterminismViolationCategory.UnstableIteration,
|
||||
ViolationType = "HashSet iteration",
|
||||
Regex = HashSetIterationRegex(),
|
||||
Message = "HashSet iteration detected - may have unstable ordering",
|
||||
Severity = DeterminismViolationSeverity.Warning,
|
||||
Remediation = "Use SortedSet or OrderBy before iteration"
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
// Generated regex patterns for prohibited patterns
|
||||
[GeneratedRegex(@"DateTime\.Now(?!\w)")]
|
||||
private static partial Regex DateTimeNowRegex();
|
||||
|
||||
[GeneratedRegex(@"DateTime\.UtcNow(?!\w)")]
|
||||
private static partial Regex DateTimeUtcNowRegex();
|
||||
|
||||
[GeneratedRegex(@"DateTimeOffset\.Now(?!\w)")]
|
||||
private static partial Regex DateTimeOffsetNowRegex();
|
||||
|
||||
[GeneratedRegex(@"DateTimeOffset\.UtcNow(?!\w)")]
|
||||
private static partial Regex DateTimeOffsetUtcNowRegex();
|
||||
|
||||
[GeneratedRegex(@"new\s+Random\s*\(")]
|
||||
private static partial Regex RandomClassRegex();
|
||||
|
||||
[GeneratedRegex(@"RandomNumberGenerator")]
|
||||
private static partial Regex CryptoRandomRegex();
|
||||
|
||||
[GeneratedRegex(@"Guid\.NewGuid\s*\(")]
|
||||
private static partial Regex GuidNewGuidRegex();
|
||||
|
||||
[GeneratedRegex(@"HttpClient")]
|
||||
private static partial Regex HttpClientRegex();
|
||||
|
||||
[GeneratedRegex(@"WebClient")]
|
||||
private static partial Regex WebClientRegex();
|
||||
|
||||
[GeneratedRegex(@"(?:TcpClient|UdpClient|Socket)\s*\(")]
|
||||
private static partial Regex SocketRegex();
|
||||
|
||||
[GeneratedRegex(@"Environment\.GetEnvironmentVariable")]
|
||||
private static partial Regex EnvironmentGetEnvRegex();
|
||||
|
||||
[GeneratedRegex(@"Environment\.MachineName")]
|
||||
private static partial Regex EnvironmentMachineNameRegex();
|
||||
|
||||
[GeneratedRegex(@"File\.(?:Read|Open|ReadAll)")]
|
||||
private static partial Regex FileReadRegex();
|
||||
|
||||
[GeneratedRegex(@"File\.(?:Write|Create|Append)")]
|
||||
private static partial Regex FileWriteRegex();
|
||||
|
||||
[GeneratedRegex(@"(?:double|float)\s+\w+\s*[=<>!]=")]
|
||||
private static partial Regex DoubleComparisonRegex();
|
||||
|
||||
[GeneratedRegex(@"foreach\s*\([^)]+\s+in\s+\w*[Dd]ictionary")]
|
||||
private static partial Regex DictionaryIterationRegex();
|
||||
|
||||
[GeneratedRegex(@"foreach\s*\([^)]+\s+in\s+\w*[Hh]ashSet")]
|
||||
private static partial Regex HashSetIterationRegex();
|
||||
|
||||
private sealed record ProhibitedPattern
|
||||
{
|
||||
public required DeterminismViolationCategory Category { get; init; }
|
||||
public required string ViolationType { get; init; }
|
||||
public required Regex Regex { get; init; }
|
||||
public required string Message { get; init; }
|
||||
public required DeterminismViolationSeverity Severity { get; init; }
|
||||
public string? Remediation { get; init; }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace StellaOps.Policy.Engine.Domain;
|
||||
|
||||
/// <summary>
|
||||
/// Request for a policy decision with source evidence summaries (POLICY-ENGINE-40-003).
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionRequest(
|
||||
[property: JsonPropertyName("snapshot_id")] string SnapshotId,
|
||||
[property: JsonPropertyName("tenant_id")] string? TenantId = null,
|
||||
[property: JsonPropertyName("component_purl")] string? ComponentPurl = null,
|
||||
[property: JsonPropertyName("advisory_id")] string? AdvisoryId = null,
|
||||
[property: JsonPropertyName("include_evidence")] bool IncludeEvidence = true,
|
||||
[property: JsonPropertyName("max_sources")] int MaxSources = 5);
|
||||
|
||||
/// <summary>
|
||||
/// Response containing policy decisions with source evidence summaries.
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionResponse(
|
||||
[property: JsonPropertyName("snapshot_id")] string SnapshotId,
|
||||
[property: JsonPropertyName("decisions")] IReadOnlyList<PolicyDecisionItem> Decisions,
|
||||
[property: JsonPropertyName("summary")] PolicyDecisionSummary Summary);
|
||||
|
||||
/// <summary>
|
||||
/// A single policy decision with associated evidence.
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionItem(
|
||||
[property: JsonPropertyName("tenant_id")] string TenantId,
|
||||
[property: JsonPropertyName("component_purl")] string ComponentPurl,
|
||||
[property: JsonPropertyName("advisory_id")] string AdvisoryId,
|
||||
[property: JsonPropertyName("severity_fused")] string SeverityFused,
|
||||
[property: JsonPropertyName("score")] decimal Score,
|
||||
[property: JsonPropertyName("status")] string Status,
|
||||
[property: JsonPropertyName("top_sources")] IReadOnlyList<PolicyDecisionSource> TopSources,
|
||||
[property: JsonPropertyName("evidence")] PolicyDecisionEvidence? Evidence,
|
||||
[property: JsonPropertyName("conflict_count")] int ConflictCount,
|
||||
[property: JsonPropertyName("reason_codes")] IReadOnlyList<string> ReasonCodes);
|
||||
|
||||
/// <summary>
|
||||
/// Top severity source information for a decision.
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionSource(
|
||||
[property: JsonPropertyName("source")] string Source,
|
||||
[property: JsonPropertyName("weight")] decimal Weight,
|
||||
[property: JsonPropertyName("severity")] string Severity,
|
||||
[property: JsonPropertyName("score")] decimal Score,
|
||||
[property: JsonPropertyName("rank")] int Rank);
|
||||
|
||||
/// <summary>
|
||||
/// Evidence summary for a policy decision.
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionEvidence(
|
||||
[property: JsonPropertyName("headline")] string Headline,
|
||||
[property: JsonPropertyName("severity")] string Severity,
|
||||
[property: JsonPropertyName("locator")] PolicyDecisionLocator Locator,
|
||||
[property: JsonPropertyName("signals")] IReadOnlyList<string> Signals);
|
||||
|
||||
/// <summary>
|
||||
/// Evidence locator information.
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionLocator(
|
||||
[property: JsonPropertyName("file_path")] string FilePath,
|
||||
[property: JsonPropertyName("digest")] string? Digest);
|
||||
|
||||
/// <summary>
|
||||
/// Summary statistics for the decision response.
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionSummary(
|
||||
[property: JsonPropertyName("total_decisions")] int TotalDecisions,
|
||||
[property: JsonPropertyName("total_conflicts")] int TotalConflicts,
|
||||
[property: JsonPropertyName("severity_counts")] IReadOnlyDictionary<string, int> SeverityCounts,
|
||||
[property: JsonPropertyName("top_severity_sources")] IReadOnlyList<PolicyDecisionSourceRank> TopSeveritySources);
|
||||
|
||||
/// <summary>
|
||||
/// Aggregated source rank across all decisions.
|
||||
/// </summary>
|
||||
public sealed record PolicyDecisionSourceRank(
|
||||
[property: JsonPropertyName("source")] string Source,
|
||||
[property: JsonPropertyName("total_weight")] decimal TotalWeight,
|
||||
[property: JsonPropertyName("decision_count")] int DecisionCount,
|
||||
[property: JsonPropertyName("average_score")] decimal AverageScore);
|
||||
@@ -0,0 +1,360 @@
|
||||
using System.Security.Claims;
|
||||
using Microsoft.AspNetCore.Http.HttpResults;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using StellaOps.Auth.Abstractions;
|
||||
using StellaOps.Policy.Engine.Services;
|
||||
using StellaOps.Policy.RiskProfile.Overrides;
|
||||
|
||||
namespace StellaOps.Policy.Engine.Endpoints;
|
||||
|
||||
internal static class OverrideEndpoints
|
||||
{
|
||||
public static IEndpointRouteBuilder MapOverrides(this IEndpointRouteBuilder endpoints)
|
||||
{
|
||||
var group = endpoints.MapGroup("/api/risk/overrides")
|
||||
.RequireAuthorization()
|
||||
.WithTags("Risk Overrides");
|
||||
|
||||
group.MapPost("/", CreateOverride)
|
||||
.WithName("CreateOverride")
|
||||
.WithSummary("Create a new override with audit metadata.")
|
||||
.Produces<OverrideResponse>(StatusCodes.Status201Created)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest);
|
||||
|
||||
group.MapGet("/{overrideId}", GetOverride)
|
||||
.WithName("GetOverride")
|
||||
.WithSummary("Get an override by ID.")
|
||||
.Produces<OverrideResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapDelete("/{overrideId}", DeleteOverride)
|
||||
.WithName("DeleteOverride")
|
||||
.WithSummary("Delete an override.")
|
||||
.Produces(StatusCodes.Status204NoContent)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapGet("/profile/{profileId}", ListProfileOverrides)
|
||||
.WithName("ListProfileOverrides")
|
||||
.WithSummary("List all overrides for a risk profile.")
|
||||
.Produces<OverrideListResponse>(StatusCodes.Status200OK);
|
||||
|
||||
group.MapPost("/validate", ValidateOverride)
|
||||
.WithName("ValidateOverride")
|
||||
.WithSummary("Validate an override for conflicts before creating.")
|
||||
.Produces<OverrideValidationResponse>(StatusCodes.Status200OK);
|
||||
|
||||
group.MapPost("/{overrideId}:approve", ApproveOverride)
|
||||
.WithName("ApproveOverride")
|
||||
.WithSummary("Approve an override that requires review.")
|
||||
.Produces<OverrideResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapPost("/{overrideId}:disable", DisableOverride)
|
||||
.WithName("DisableOverride")
|
||||
.WithSummary("Disable an active override.")
|
||||
.Produces<OverrideResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapGet("/{overrideId}/history", GetOverrideHistory)
|
||||
.WithName("GetOverrideHistory")
|
||||
.WithSummary("Get application history for an override.")
|
||||
.Produces<OverrideHistoryResponse>(StatusCodes.Status200OK);
|
||||
|
||||
return endpoints;
|
||||
}
|
||||
|
||||
private static IResult CreateOverride(
|
||||
HttpContext context,
|
||||
[FromBody] CreateOverrideRequest request,
|
||||
OverrideService overrideService,
|
||||
RiskProfileConfigurationService profileService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyEdit);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || string.IsNullOrWhiteSpace(request.ProfileId))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "ProfileId is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(request.Reason))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "Reason is required for audit purposes.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
// Verify profile exists
|
||||
var profile = profileService.GetProfile(request.ProfileId);
|
||||
if (profile == null)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Profile not found",
|
||||
Detail = $"Risk profile '{request.ProfileId}' was not found.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
// Validate for conflicts
|
||||
var validation = overrideService.ValidateConflicts(request);
|
||||
if (validation.HasConflicts)
|
||||
{
|
||||
var conflictDetails = string.Join("; ", validation.Conflicts.Select(c => c.Description));
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Override conflicts detected",
|
||||
Detail = conflictDetails,
|
||||
Status = StatusCodes.Status400BadRequest,
|
||||
Extensions = { ["conflicts"] = validation.Conflicts }
|
||||
});
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
|
||||
try
|
||||
{
|
||||
var auditedOverride = overrideService.Create(request, actorId);
|
||||
|
||||
return Results.Created(
|
||||
$"/api/risk/overrides/{auditedOverride.OverrideId}",
|
||||
new OverrideResponse(auditedOverride, validation.Warnings));
|
||||
}
|
||||
catch (ArgumentException ex)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = ex.Message,
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private static IResult GetOverride(
|
||||
HttpContext context,
|
||||
[FromRoute] string overrideId,
|
||||
OverrideService overrideService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var auditedOverride = overrideService.Get(overrideId);
|
||||
if (auditedOverride == null)
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Override not found",
|
||||
Detail = $"Override '{overrideId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.Ok(new OverrideResponse(auditedOverride, null));
|
||||
}
|
||||
|
||||
private static IResult DeleteOverride(
|
||||
HttpContext context,
|
||||
[FromRoute] string overrideId,
|
||||
OverrideService overrideService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyEdit);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!overrideService.Delete(overrideId))
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Override not found",
|
||||
Detail = $"Override '{overrideId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.NoContent();
|
||||
}
|
||||
|
||||
private static IResult ListProfileOverrides(
|
||||
HttpContext context,
|
||||
[FromRoute] string profileId,
|
||||
[FromQuery] bool includeInactive,
|
||||
OverrideService overrideService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var overrides = overrideService.ListByProfile(profileId, includeInactive);
|
||||
|
||||
return Results.Ok(new OverrideListResponse(profileId, overrides));
|
||||
}
|
||||
|
||||
private static IResult ValidateOverride(
|
||||
HttpContext context,
|
||||
[FromBody] CreateOverrideRequest request,
|
||||
OverrideService overrideService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "Request body is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var validation = overrideService.ValidateConflicts(request);
|
||||
|
||||
return Results.Ok(new OverrideValidationResponse(validation));
|
||||
}
|
||||
|
||||
private static IResult ApproveOverride(
|
||||
HttpContext context,
|
||||
[FromRoute] string overrideId,
|
||||
OverrideService overrideService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyActivate);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
|
||||
try
|
||||
{
|
||||
var auditedOverride = overrideService.Approve(overrideId, actorId ?? "system");
|
||||
if (auditedOverride == null)
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Override not found",
|
||||
Detail = $"Override '{overrideId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.Ok(new OverrideResponse(auditedOverride, null));
|
||||
}
|
||||
catch (InvalidOperationException ex)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Approval failed",
|
||||
Detail = ex.Message,
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private static IResult DisableOverride(
|
||||
HttpContext context,
|
||||
[FromRoute] string overrideId,
|
||||
[FromQuery] string? reason,
|
||||
OverrideService overrideService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyEdit);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
|
||||
var auditedOverride = overrideService.Disable(overrideId, actorId ?? "system", reason);
|
||||
if (auditedOverride == null)
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Override not found",
|
||||
Detail = $"Override '{overrideId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.Ok(new OverrideResponse(auditedOverride, null));
|
||||
}
|
||||
|
||||
private static IResult GetOverrideHistory(
|
||||
HttpContext context,
|
||||
[FromRoute] string overrideId,
|
||||
[FromQuery] int limit,
|
||||
OverrideService overrideService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var effectiveLimit = limit > 0 ? limit : 100;
|
||||
var history = overrideService.GetApplicationHistory(overrideId, effectiveLimit);
|
||||
|
||||
return Results.Ok(new OverrideHistoryResponse(overrideId, history));
|
||||
}
|
||||
|
||||
private static string? ResolveActorId(HttpContext context)
|
||||
{
|
||||
var user = context.User;
|
||||
var actor = user?.FindFirst(ClaimTypes.NameIdentifier)?.Value
|
||||
?? user?.FindFirst(ClaimTypes.Upn)?.Value
|
||||
?? user?.FindFirst("sub")?.Value;
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(actor))
|
||||
{
|
||||
return actor;
|
||||
}
|
||||
|
||||
if (context.Request.Headers.TryGetValue("X-StellaOps-Actor", out var header) && !string.IsNullOrWhiteSpace(header))
|
||||
{
|
||||
return header.ToString();
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
#region Response DTOs
|
||||
|
||||
internal sealed record OverrideResponse(
|
||||
AuditedOverride Override,
|
||||
IReadOnlyList<string>? Warnings);
|
||||
|
||||
internal sealed record OverrideListResponse(
|
||||
string ProfileId,
|
||||
IReadOnlyList<AuditedOverride> Overrides);
|
||||
|
||||
internal sealed record OverrideValidationResponse(OverrideConflictValidation Validation);
|
||||
|
||||
internal sealed record OverrideHistoryResponse(
|
||||
string OverrideId,
|
||||
IReadOnlyList<OverrideApplicationRecord> History);
|
||||
|
||||
#endregion
|
||||
@@ -0,0 +1,77 @@
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using StellaOps.Policy.Engine.Domain;
|
||||
using StellaOps.Policy.Engine.Services;
|
||||
|
||||
namespace StellaOps.Policy.Engine.Endpoints;
|
||||
|
||||
/// <summary>
|
||||
/// API endpoint for policy decisions with source evidence summaries (POLICY-ENGINE-40-003).
|
||||
/// </summary>
|
||||
public static class PolicyDecisionEndpoint
|
||||
{
|
||||
public static IEndpointRouteBuilder MapPolicyDecisions(this IEndpointRouteBuilder routes)
|
||||
{
|
||||
routes.MapPost("/policy/decisions", GetDecisionsAsync)
|
||||
.WithName("PolicyEngine.Decisions")
|
||||
.WithDescription("Request policy decisions with source evidence summaries, top severity sources, and conflict counts.");
|
||||
|
||||
routes.MapGet("/policy/decisions/{snapshotId}", GetDecisionsBySnapshotAsync)
|
||||
.WithName("PolicyEngine.Decisions.BySnapshot")
|
||||
.WithDescription("Get policy decisions for a specific snapshot.");
|
||||
|
||||
return routes;
|
||||
}
|
||||
|
||||
private static async Task<IResult> GetDecisionsAsync(
|
||||
[FromBody] PolicyDecisionRequest request,
|
||||
PolicyDecisionService service,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
try
|
||||
{
|
||||
var response = await service.GetDecisionsAsync(request, cancellationToken).ConfigureAwait(false);
|
||||
return Results.Ok(response);
|
||||
}
|
||||
catch (ArgumentException ex)
|
||||
{
|
||||
return Results.BadRequest(new { message = ex.Message });
|
||||
}
|
||||
catch (KeyNotFoundException ex)
|
||||
{
|
||||
return Results.NotFound(new { message = ex.Message });
|
||||
}
|
||||
}
|
||||
|
||||
private static async Task<IResult> GetDecisionsBySnapshotAsync(
|
||||
[FromRoute] string snapshotId,
|
||||
[FromQuery] string? tenantId,
|
||||
[FromQuery] string? componentPurl,
|
||||
[FromQuery] string? advisoryId,
|
||||
[FromQuery] bool includeEvidence = true,
|
||||
[FromQuery] int maxSources = 5,
|
||||
PolicyDecisionService service = default!,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
try
|
||||
{
|
||||
var request = new PolicyDecisionRequest(
|
||||
SnapshotId: snapshotId,
|
||||
TenantId: tenantId,
|
||||
ComponentPurl: componentPurl,
|
||||
AdvisoryId: advisoryId,
|
||||
IncludeEvidence: includeEvidence,
|
||||
MaxSources: maxSources);
|
||||
|
||||
var response = await service.GetDecisionsAsync(request, cancellationToken).ConfigureAwait(false);
|
||||
return Results.Ok(response);
|
||||
}
|
||||
catch (ArgumentException ex)
|
||||
{
|
||||
return Results.BadRequest(new { message = ex.Message });
|
||||
}
|
||||
catch (KeyNotFoundException ex)
|
||||
{
|
||||
return Results.NotFound(new { message = ex.Message });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,195 @@
|
||||
using System.Security.Claims;
|
||||
using Microsoft.AspNetCore.Http.HttpResults;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using StellaOps.Auth.Abstractions;
|
||||
using StellaOps.Policy.Engine.Events;
|
||||
using StellaOps.Policy.Engine.Services;
|
||||
|
||||
namespace StellaOps.Policy.Engine.Endpoints;
|
||||
|
||||
internal static class ProfileEventEndpoints
|
||||
{
|
||||
public static IEndpointRouteBuilder MapProfileEvents(this IEndpointRouteBuilder endpoints)
|
||||
{
|
||||
var group = endpoints.MapGroup("/api/risk/events")
|
||||
.RequireAuthorization()
|
||||
.WithTags("Profile Events");
|
||||
|
||||
group.MapGet("/", GetRecentEvents)
|
||||
.WithName("GetRecentProfileEvents")
|
||||
.WithSummary("Get recent profile lifecycle events.")
|
||||
.Produces<EventListResponse>(StatusCodes.Status200OK);
|
||||
|
||||
group.MapGet("/filter", GetFilteredEvents)
|
||||
.WithName("GetFilteredProfileEvents")
|
||||
.WithSummary("Get profile events with optional filtering.")
|
||||
.Produces<EventListResponse>(StatusCodes.Status200OK);
|
||||
|
||||
group.MapPost("/subscribe", CreateSubscription)
|
||||
.WithName("CreateEventSubscription")
|
||||
.WithSummary("Subscribe to profile lifecycle events.")
|
||||
.Produces<SubscriptionResponse>(StatusCodes.Status201Created);
|
||||
|
||||
group.MapDelete("/subscribe/{subscriptionId}", DeleteSubscription)
|
||||
.WithName("DeleteEventSubscription")
|
||||
.WithSummary("Unsubscribe from profile lifecycle events.")
|
||||
.Produces(StatusCodes.Status204NoContent)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapGet("/subscribe/{subscriptionId}/poll", PollSubscription)
|
||||
.WithName("PollEventSubscription")
|
||||
.WithSummary("Poll for events from a subscription.")
|
||||
.Produces<EventListResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
return endpoints;
|
||||
}
|
||||
|
||||
private static IResult GetRecentEvents(
|
||||
HttpContext context,
|
||||
[FromQuery] int limit,
|
||||
ProfileEventPublisher eventPublisher)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var effectiveLimit = limit > 0 ? limit : 100;
|
||||
var events = eventPublisher.GetRecentEvents(effectiveLimit);
|
||||
|
||||
return Results.Ok(new EventListResponse(events));
|
||||
}
|
||||
|
||||
private static IResult GetFilteredEvents(
|
||||
HttpContext context,
|
||||
[FromQuery] ProfileEventType? eventType,
|
||||
[FromQuery] string? profileId,
|
||||
[FromQuery] DateTimeOffset? since,
|
||||
[FromQuery] int limit,
|
||||
ProfileEventPublisher eventPublisher)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var effectiveLimit = limit > 0 ? limit : 100;
|
||||
var events = eventPublisher.GetEventsFiltered(eventType, profileId, since, effectiveLimit);
|
||||
|
||||
return Results.Ok(new EventListResponse(events));
|
||||
}
|
||||
|
||||
private static IResult CreateSubscription(
|
||||
HttpContext context,
|
||||
[FromBody] CreateSubscriptionRequest request,
|
||||
ProfileEventPublisher eventPublisher)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || request.EventTypes == null || request.EventTypes.Count == 0)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "At least one event type is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
var subscription = eventPublisher.Subscribe(
|
||||
request.EventTypes,
|
||||
request.ProfileFilter,
|
||||
request.WebhookUrl,
|
||||
actorId);
|
||||
|
||||
return Results.Created(
|
||||
$"/api/risk/events/subscribe/{subscription.SubscriptionId}",
|
||||
new SubscriptionResponse(subscription));
|
||||
}
|
||||
|
||||
private static IResult DeleteSubscription(
|
||||
HttpContext context,
|
||||
[FromRoute] string subscriptionId,
|
||||
ProfileEventPublisher eventPublisher)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!eventPublisher.Unsubscribe(subscriptionId))
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Subscription not found",
|
||||
Detail = $"Subscription '{subscriptionId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.NoContent();
|
||||
}
|
||||
|
||||
private static IResult PollSubscription(
|
||||
HttpContext context,
|
||||
[FromRoute] string subscriptionId,
|
||||
[FromQuery] int limit,
|
||||
ProfileEventPublisher eventPublisher)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var effectiveLimit = limit > 0 ? limit : 100;
|
||||
var events = eventPublisher.GetEvents(subscriptionId, effectiveLimit);
|
||||
|
||||
// If no events, the subscription might not exist
|
||||
// We return empty list either way since the subscription might just have no events
|
||||
|
||||
return Results.Ok(new EventListResponse(events));
|
||||
}
|
||||
|
||||
private static string? ResolveActorId(HttpContext context)
|
||||
{
|
||||
var user = context.User;
|
||||
var actor = user?.FindFirst(ClaimTypes.NameIdentifier)?.Value
|
||||
?? user?.FindFirst(ClaimTypes.Upn)?.Value
|
||||
?? user?.FindFirst("sub")?.Value;
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(actor))
|
||||
{
|
||||
return actor;
|
||||
}
|
||||
|
||||
if (context.Request.Headers.TryGetValue("X-StellaOps-Actor", out var header) && !string.IsNullOrWhiteSpace(header))
|
||||
{
|
||||
return header.ToString();
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
#region Request/Response DTOs
|
||||
|
||||
internal sealed record EventListResponse(IReadOnlyList<ProfileEvent> Events);
|
||||
|
||||
internal sealed record CreateSubscriptionRequest(
|
||||
IReadOnlyList<ProfileEventType> EventTypes,
|
||||
string? ProfileFilter,
|
||||
string? WebhookUrl);
|
||||
|
||||
internal sealed record SubscriptionResponse(EventSubscription Subscription);
|
||||
|
||||
#endregion
|
||||
@@ -0,0 +1,238 @@
|
||||
using System.Security.Claims;
|
||||
using System.Text.Json;
|
||||
using Microsoft.AspNetCore.Http.HttpResults;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using StellaOps.Auth.Abstractions;
|
||||
using StellaOps.Policy.Engine.Services;
|
||||
using StellaOps.Policy.RiskProfile.Export;
|
||||
|
||||
namespace StellaOps.Policy.Engine.Endpoints;
|
||||
|
||||
internal static class ProfileExportEndpoints
|
||||
{
|
||||
public static IEndpointRouteBuilder MapProfileExport(this IEndpointRouteBuilder endpoints)
|
||||
{
|
||||
var group = endpoints.MapGroup("/api/risk/profiles/export")
|
||||
.RequireAuthorization()
|
||||
.WithTags("Profile Export/Import");
|
||||
|
||||
group.MapPost("/", ExportProfiles)
|
||||
.WithName("ExportProfiles")
|
||||
.WithSummary("Export risk profiles as a signed bundle.")
|
||||
.Produces<ExportResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest);
|
||||
|
||||
group.MapPost("/download", DownloadBundle)
|
||||
.WithName("DownloadProfileBundle")
|
||||
.WithSummary("Export and download risk profiles as a JSON file.")
|
||||
.Produces<FileContentHttpResult>(StatusCodes.Status200OK, contentType: "application/json");
|
||||
|
||||
endpoints.MapPost("/api/risk/profiles/import", ImportProfiles)
|
||||
.RequireAuthorization()
|
||||
.WithName("ImportProfiles")
|
||||
.WithSummary("Import risk profiles from a signed bundle.")
|
||||
.WithTags("Profile Export/Import")
|
||||
.Produces<ImportResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest);
|
||||
|
||||
endpoints.MapPost("/api/risk/profiles/verify", VerifyBundle)
|
||||
.RequireAuthorization()
|
||||
.WithName("VerifyProfileBundle")
|
||||
.WithSummary("Verify the signature of a profile bundle without importing.")
|
||||
.WithTags("Profile Export/Import")
|
||||
.Produces<VerifyResponse>(StatusCodes.Status200OK);
|
||||
|
||||
return endpoints;
|
||||
}
|
||||
|
||||
private static IResult ExportProfiles(
|
||||
HttpContext context,
|
||||
[FromBody] ExportProfilesRequest request,
|
||||
RiskProfileConfigurationService profileService,
|
||||
ProfileExportService exportService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || request.ProfileIds == null || request.ProfileIds.Count == 0)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "At least one profile ID is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var profiles = new List<StellaOps.Policy.RiskProfile.Models.RiskProfileModel>();
|
||||
var notFound = new List<string>();
|
||||
|
||||
foreach (var profileId in request.ProfileIds)
|
||||
{
|
||||
var profile = profileService.GetProfile(profileId);
|
||||
if (profile != null)
|
||||
{
|
||||
profiles.Add(profile);
|
||||
}
|
||||
else
|
||||
{
|
||||
notFound.Add(profileId);
|
||||
}
|
||||
}
|
||||
|
||||
if (notFound.Count > 0)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Profiles not found",
|
||||
Detail = $"The following profiles were not found: {string.Join(", ", notFound)}",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
var bundle = exportService.Export(profiles, request, actorId);
|
||||
|
||||
return Results.Ok(new ExportResponse(bundle));
|
||||
}
|
||||
|
||||
private static IResult DownloadBundle(
|
||||
HttpContext context,
|
||||
[FromBody] ExportProfilesRequest request,
|
||||
RiskProfileConfigurationService profileService,
|
||||
ProfileExportService exportService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || request.ProfileIds == null || request.ProfileIds.Count == 0)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "At least one profile ID is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var profiles = new List<StellaOps.Policy.RiskProfile.Models.RiskProfileModel>();
|
||||
|
||||
foreach (var profileId in request.ProfileIds)
|
||||
{
|
||||
var profile = profileService.GetProfile(profileId);
|
||||
if (profile != null)
|
||||
{
|
||||
profiles.Add(profile);
|
||||
}
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
var bundle = exportService.Export(profiles, request, actorId);
|
||||
var json = exportService.SerializeBundle(bundle);
|
||||
var bytes = System.Text.Encoding.UTF8.GetBytes(json);
|
||||
|
||||
var fileName = $"risk-profiles-{bundle.BundleId}.json";
|
||||
return Results.File(bytes, "application/json", fileName);
|
||||
}
|
||||
|
||||
private static IResult ImportProfiles(
|
||||
HttpContext context,
|
||||
[FromBody] ImportProfilesRequest request,
|
||||
RiskProfileConfigurationService profileService,
|
||||
ProfileExportService exportService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyEdit);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || request.Bundle == null)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "Bundle is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
|
||||
// Create an export service with save capability
|
||||
var importExportService = new ProfileExportService(
|
||||
timeProvider: TimeProvider.System,
|
||||
profileLookup: id => profileService.GetProfile(id),
|
||||
lifecycleLookup: null,
|
||||
profileSave: profile => profileService.RegisterProfile(profile),
|
||||
keyLookup: null);
|
||||
|
||||
var result = importExportService.Import(request, actorId);
|
||||
|
||||
return Results.Ok(new ImportResponse(result));
|
||||
}
|
||||
|
||||
private static IResult VerifyBundle(
|
||||
HttpContext context,
|
||||
[FromBody] RiskProfileBundle bundle,
|
||||
ProfileExportService exportService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (bundle == null)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "Bundle is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var verification = exportService.VerifySignature(bundle);
|
||||
|
||||
return Results.Ok(new VerifyResponse(verification, bundle.Metadata));
|
||||
}
|
||||
|
||||
private static string? ResolveActorId(HttpContext context)
|
||||
{
|
||||
var user = context.User;
|
||||
var actor = user?.FindFirst(ClaimTypes.NameIdentifier)?.Value
|
||||
?? user?.FindFirst(ClaimTypes.Upn)?.Value
|
||||
?? user?.FindFirst("sub")?.Value;
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(actor))
|
||||
{
|
||||
return actor;
|
||||
}
|
||||
|
||||
if (context.Request.Headers.TryGetValue("X-StellaOps-Actor", out var header) && !string.IsNullOrWhiteSpace(header))
|
||||
{
|
||||
return header.ToString();
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
#region Response DTOs
|
||||
|
||||
internal sealed record ExportResponse(RiskProfileBundle Bundle);
|
||||
|
||||
internal sealed record ImportResponse(ImportResult Result);
|
||||
|
||||
internal sealed record VerifyResponse(
|
||||
SignatureVerificationResult Verification,
|
||||
BundleMetadata Metadata);
|
||||
|
||||
#endregion
|
||||
@@ -0,0 +1,433 @@
|
||||
using Microsoft.AspNetCore.Http.HttpResults;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using StellaOps.Auth.Abstractions;
|
||||
using StellaOps.Policy.Engine.Services;
|
||||
using StellaOps.Policy.Engine.Simulation;
|
||||
|
||||
namespace StellaOps.Policy.Engine.Endpoints;
|
||||
|
||||
internal static class RiskSimulationEndpoints
|
||||
{
|
||||
public static IEndpointRouteBuilder MapRiskSimulation(this IEndpointRouteBuilder endpoints)
|
||||
{
|
||||
var group = endpoints.MapGroup("/api/risk/simulation")
|
||||
.RequireAuthorization()
|
||||
.WithTags("Risk Simulation");
|
||||
|
||||
group.MapPost("/", RunSimulation)
|
||||
.WithName("RunRiskSimulation")
|
||||
.WithSummary("Run a risk simulation with score distributions and contribution breakdowns.")
|
||||
.Produces<RiskSimulationResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapPost("/quick", RunQuickSimulation)
|
||||
.WithName("RunQuickRiskSimulation")
|
||||
.WithSummary("Run a quick risk simulation without detailed breakdowns.")
|
||||
.Produces<QuickSimulationResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapPost("/compare", CompareProfiles)
|
||||
.WithName("CompareProfileSimulations")
|
||||
.WithSummary("Compare risk scoring between two profile configurations.")
|
||||
.Produces<ProfileComparisonResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest);
|
||||
|
||||
group.MapPost("/whatif", RunWhatIfSimulation)
|
||||
.WithName("RunWhatIfSimulation")
|
||||
.WithSummary("Run a what-if simulation with hypothetical signal changes.")
|
||||
.Produces<WhatIfSimulationResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest);
|
||||
|
||||
return endpoints;
|
||||
}
|
||||
|
||||
private static IResult RunSimulation(
|
||||
HttpContext context,
|
||||
[FromBody] RiskSimulationRequest request,
|
||||
RiskSimulationService simulationService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || string.IsNullOrWhiteSpace(request.ProfileId))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "ProfileId is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
if (request.Findings == null || request.Findings.Count == 0)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "At least one finding is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
var result = simulationService.Simulate(request);
|
||||
return Results.Ok(new RiskSimulationResponse(result));
|
||||
}
|
||||
catch (InvalidOperationException ex) when (ex.Message.Contains("not found"))
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Profile not found",
|
||||
Detail = ex.Message,
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private static IResult RunQuickSimulation(
|
||||
HttpContext context,
|
||||
[FromBody] QuickSimulationRequest request,
|
||||
RiskSimulationService simulationService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || string.IsNullOrWhiteSpace(request.ProfileId))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "ProfileId is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var fullRequest = new RiskSimulationRequest(
|
||||
ProfileId: request.ProfileId,
|
||||
ProfileVersion: request.ProfileVersion,
|
||||
Findings: request.Findings,
|
||||
IncludeContributions: false,
|
||||
IncludeDistribution: true,
|
||||
Mode: SimulationMode.Quick);
|
||||
|
||||
try
|
||||
{
|
||||
var result = simulationService.Simulate(fullRequest);
|
||||
|
||||
var quickResponse = new QuickSimulationResponse(
|
||||
SimulationId: result.SimulationId,
|
||||
ProfileId: result.ProfileId,
|
||||
ProfileVersion: result.ProfileVersion,
|
||||
Timestamp: result.Timestamp,
|
||||
AggregateMetrics: result.AggregateMetrics,
|
||||
Distribution: result.Distribution,
|
||||
ExecutionTimeMs: result.ExecutionTimeMs);
|
||||
|
||||
return Results.Ok(quickResponse);
|
||||
}
|
||||
catch (InvalidOperationException ex) when (ex.Message.Contains("not found"))
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Profile not found",
|
||||
Detail = ex.Message,
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private static IResult CompareProfiles(
|
||||
HttpContext context,
|
||||
[FromBody] ProfileComparisonRequest request,
|
||||
RiskSimulationService simulationService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null ||
|
||||
string.IsNullOrWhiteSpace(request.BaseProfileId) ||
|
||||
string.IsNullOrWhiteSpace(request.CompareProfileId))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "Both BaseProfileId and CompareProfileId are required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
var baseRequest = new RiskSimulationRequest(
|
||||
ProfileId: request.BaseProfileId,
|
||||
ProfileVersion: request.BaseProfileVersion,
|
||||
Findings: request.Findings,
|
||||
IncludeContributions: true,
|
||||
IncludeDistribution: true,
|
||||
Mode: SimulationMode.Full);
|
||||
|
||||
var compareRequest = new RiskSimulationRequest(
|
||||
ProfileId: request.CompareProfileId,
|
||||
ProfileVersion: request.CompareProfileVersion,
|
||||
Findings: request.Findings,
|
||||
IncludeContributions: true,
|
||||
IncludeDistribution: true,
|
||||
Mode: SimulationMode.Full);
|
||||
|
||||
var baseResult = simulationService.Simulate(baseRequest);
|
||||
var compareResult = simulationService.Simulate(compareRequest);
|
||||
|
||||
var deltas = ComputeDeltas(baseResult, compareResult);
|
||||
|
||||
return Results.Ok(new ProfileComparisonResponse(
|
||||
BaseProfile: new ProfileSimulationSummary(
|
||||
baseResult.ProfileId,
|
||||
baseResult.ProfileVersion,
|
||||
baseResult.AggregateMetrics),
|
||||
CompareProfile: new ProfileSimulationSummary(
|
||||
compareResult.ProfileId,
|
||||
compareResult.ProfileVersion,
|
||||
compareResult.AggregateMetrics),
|
||||
Deltas: deltas));
|
||||
}
|
||||
catch (InvalidOperationException ex) when (ex.Message.Contains("not found"))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Profile not found",
|
||||
Detail = ex.Message,
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private static IResult RunWhatIfSimulation(
|
||||
HttpContext context,
|
||||
[FromBody] WhatIfSimulationRequest request,
|
||||
RiskSimulationService simulationService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || string.IsNullOrWhiteSpace(request.ProfileId))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "ProfileId is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
// Run baseline simulation
|
||||
var baselineRequest = new RiskSimulationRequest(
|
||||
ProfileId: request.ProfileId,
|
||||
ProfileVersion: request.ProfileVersion,
|
||||
Findings: request.Findings,
|
||||
IncludeContributions: true,
|
||||
IncludeDistribution: true,
|
||||
Mode: SimulationMode.Full);
|
||||
|
||||
var baselineResult = simulationService.Simulate(baselineRequest);
|
||||
|
||||
// Apply hypothetical changes to findings and re-simulate
|
||||
var modifiedFindings = ApplyHypotheticalChanges(request.Findings, request.HypotheticalChanges);
|
||||
|
||||
var modifiedRequest = new RiskSimulationRequest(
|
||||
ProfileId: request.ProfileId,
|
||||
ProfileVersion: request.ProfileVersion,
|
||||
Findings: modifiedFindings,
|
||||
IncludeContributions: true,
|
||||
IncludeDistribution: true,
|
||||
Mode: SimulationMode.WhatIf);
|
||||
|
||||
var modifiedResult = simulationService.Simulate(modifiedRequest);
|
||||
|
||||
return Results.Ok(new WhatIfSimulationResponse(
|
||||
BaselineResult: baselineResult,
|
||||
ModifiedResult: modifiedResult,
|
||||
ImpactSummary: ComputeImpactSummary(baselineResult, modifiedResult)));
|
||||
}
|
||||
catch (InvalidOperationException ex) when (ex.Message.Contains("not found"))
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Profile not found",
|
||||
Detail = ex.Message,
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private static ComparisonDeltas ComputeDeltas(
|
||||
RiskSimulationResult baseResult,
|
||||
RiskSimulationResult compareResult)
|
||||
{
|
||||
return new ComparisonDeltas(
|
||||
MeanScoreDelta: compareResult.AggregateMetrics.MeanScore - baseResult.AggregateMetrics.MeanScore,
|
||||
MedianScoreDelta: compareResult.AggregateMetrics.MedianScore - baseResult.AggregateMetrics.MedianScore,
|
||||
CriticalCountDelta: compareResult.AggregateMetrics.CriticalCount - baseResult.AggregateMetrics.CriticalCount,
|
||||
HighCountDelta: compareResult.AggregateMetrics.HighCount - baseResult.AggregateMetrics.HighCount,
|
||||
MediumCountDelta: compareResult.AggregateMetrics.MediumCount - baseResult.AggregateMetrics.MediumCount,
|
||||
LowCountDelta: compareResult.AggregateMetrics.LowCount - baseResult.AggregateMetrics.LowCount);
|
||||
}
|
||||
|
||||
private static IReadOnlyList<SimulationFinding> ApplyHypotheticalChanges(
|
||||
IReadOnlyList<SimulationFinding> findings,
|
||||
IReadOnlyList<HypotheticalChange> changes)
|
||||
{
|
||||
var result = new List<SimulationFinding>();
|
||||
|
||||
foreach (var finding in findings)
|
||||
{
|
||||
var modifiedSignals = new Dictionary<string, object?>(finding.Signals);
|
||||
|
||||
foreach (var change in changes)
|
||||
{
|
||||
if (change.ApplyToAll || change.FindingIds.Contains(finding.FindingId))
|
||||
{
|
||||
modifiedSignals[change.SignalName] = change.NewValue;
|
||||
}
|
||||
}
|
||||
|
||||
result.Add(finding with { Signals = modifiedSignals });
|
||||
}
|
||||
|
||||
return result.AsReadOnly();
|
||||
}
|
||||
|
||||
private static WhatIfImpactSummary ComputeImpactSummary(
|
||||
RiskSimulationResult baseline,
|
||||
RiskSimulationResult modified)
|
||||
{
|
||||
var baseScores = baseline.FindingScores.ToDictionary(f => f.FindingId, f => f.NormalizedScore);
|
||||
var modScores = modified.FindingScores.ToDictionary(f => f.FindingId, f => f.NormalizedScore);
|
||||
|
||||
var improved = 0;
|
||||
var worsened = 0;
|
||||
var unchanged = 0;
|
||||
var totalDelta = 0.0;
|
||||
|
||||
foreach (var (findingId, baseScore) in baseScores)
|
||||
{
|
||||
if (modScores.TryGetValue(findingId, out var modScore))
|
||||
{
|
||||
var delta = modScore - baseScore;
|
||||
totalDelta += delta;
|
||||
|
||||
if (Math.Abs(delta) < 0.1)
|
||||
unchanged++;
|
||||
else if (delta < 0)
|
||||
improved++;
|
||||
else
|
||||
worsened++;
|
||||
}
|
||||
}
|
||||
|
||||
return new WhatIfImpactSummary(
|
||||
FindingsImproved: improved,
|
||||
FindingsWorsened: worsened,
|
||||
FindingsUnchanged: unchanged,
|
||||
AverageScoreDelta: baseline.FindingScores.Count > 0
|
||||
? totalDelta / baseline.FindingScores.Count
|
||||
: 0,
|
||||
SeverityShifts: new SeverityShifts(
|
||||
ToLower: improved,
|
||||
ToHigher: worsened,
|
||||
Unchanged: unchanged));
|
||||
}
|
||||
}
|
||||
|
||||
#region Request/Response DTOs
|
||||
|
||||
internal sealed record RiskSimulationResponse(RiskSimulationResult Result);
|
||||
|
||||
internal sealed record QuickSimulationRequest(
|
||||
string ProfileId,
|
||||
string? ProfileVersion,
|
||||
IReadOnlyList<SimulationFinding> Findings);
|
||||
|
||||
internal sealed record QuickSimulationResponse(
|
||||
string SimulationId,
|
||||
string ProfileId,
|
||||
string ProfileVersion,
|
||||
DateTimeOffset Timestamp,
|
||||
AggregateRiskMetrics AggregateMetrics,
|
||||
RiskDistribution? Distribution,
|
||||
double ExecutionTimeMs);
|
||||
|
||||
internal sealed record ProfileComparisonRequest(
|
||||
string BaseProfileId,
|
||||
string? BaseProfileVersion,
|
||||
string CompareProfileId,
|
||||
string? CompareProfileVersion,
|
||||
IReadOnlyList<SimulationFinding> Findings);
|
||||
|
||||
internal sealed record ProfileComparisonResponse(
|
||||
ProfileSimulationSummary BaseProfile,
|
||||
ProfileSimulationSummary CompareProfile,
|
||||
ComparisonDeltas Deltas);
|
||||
|
||||
internal sealed record ProfileSimulationSummary(
|
||||
string ProfileId,
|
||||
string ProfileVersion,
|
||||
AggregateRiskMetrics Metrics);
|
||||
|
||||
internal sealed record ComparisonDeltas(
|
||||
double MeanScoreDelta,
|
||||
double MedianScoreDelta,
|
||||
int CriticalCountDelta,
|
||||
int HighCountDelta,
|
||||
int MediumCountDelta,
|
||||
int LowCountDelta);
|
||||
|
||||
internal sealed record WhatIfSimulationRequest(
|
||||
string ProfileId,
|
||||
string? ProfileVersion,
|
||||
IReadOnlyList<SimulationFinding> Findings,
|
||||
IReadOnlyList<HypotheticalChange> HypotheticalChanges);
|
||||
|
||||
internal sealed record HypotheticalChange(
|
||||
string SignalName,
|
||||
object? NewValue,
|
||||
bool ApplyToAll = true,
|
||||
IReadOnlyList<string>? FindingIds = null)
|
||||
{
|
||||
public IReadOnlyList<string> FindingIds { get; init; } = FindingIds ?? Array.Empty<string>();
|
||||
}
|
||||
|
||||
internal sealed record WhatIfSimulationResponse(
|
||||
RiskSimulationResult BaselineResult,
|
||||
RiskSimulationResult ModifiedResult,
|
||||
WhatIfImpactSummary ImpactSummary);
|
||||
|
||||
internal sealed record WhatIfImpactSummary(
|
||||
int FindingsImproved,
|
||||
int FindingsWorsened,
|
||||
int FindingsUnchanged,
|
||||
double AverageScoreDelta,
|
||||
SeverityShifts SeverityShifts);
|
||||
|
||||
internal sealed record SeverityShifts(
|
||||
int ToLower,
|
||||
int ToHigher,
|
||||
int Unchanged);
|
||||
|
||||
#endregion
|
||||
@@ -0,0 +1,290 @@
|
||||
using System.Security.Claims;
|
||||
using Microsoft.AspNetCore.Http.HttpResults;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using StellaOps.Auth.Abstractions;
|
||||
using StellaOps.Policy.Engine.Services;
|
||||
using StellaOps.Policy.RiskProfile.Scope;
|
||||
|
||||
namespace StellaOps.Policy.Engine.Endpoints;
|
||||
|
||||
internal static class ScopeAttachmentEndpoints
|
||||
{
|
||||
public static IEndpointRouteBuilder MapScopeAttachments(this IEndpointRouteBuilder endpoints)
|
||||
{
|
||||
var group = endpoints.MapGroup("/api/risk/scopes")
|
||||
.RequireAuthorization()
|
||||
.WithTags("Risk Profile Scopes");
|
||||
|
||||
group.MapPost("/attachments", CreateAttachment)
|
||||
.WithName("CreateScopeAttachment")
|
||||
.WithSummary("Attach a risk profile to a scope (organization, project, environment, or component).")
|
||||
.Produces<ScopeAttachmentResponse>(StatusCodes.Status201Created)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status400BadRequest);
|
||||
|
||||
group.MapGet("/attachments/{attachmentId}", GetAttachment)
|
||||
.WithName("GetScopeAttachment")
|
||||
.WithSummary("Get a scope attachment by ID.")
|
||||
.Produces<ScopeAttachmentResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapDelete("/attachments/{attachmentId}", DeleteAttachment)
|
||||
.WithName("DeleteScopeAttachment")
|
||||
.WithSummary("Delete a scope attachment.")
|
||||
.Produces(StatusCodes.Status204NoContent)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapPost("/attachments/{attachmentId}:expire", ExpireAttachment)
|
||||
.WithName("ExpireScopeAttachment")
|
||||
.WithSummary("Expire a scope attachment immediately.")
|
||||
.Produces<ScopeAttachmentResponse>(StatusCodes.Status200OK)
|
||||
.Produces<ProblemHttpResult>(StatusCodes.Status404NotFound);
|
||||
|
||||
group.MapGet("/attachments", ListAttachments)
|
||||
.WithName("ListScopeAttachments")
|
||||
.WithSummary("List scope attachments with optional filtering.")
|
||||
.Produces<ScopeAttachmentListResponse>(StatusCodes.Status200OK);
|
||||
|
||||
group.MapPost("/resolve", ResolveScope)
|
||||
.WithName("ResolveScope")
|
||||
.WithSummary("Resolve the effective risk profile for a given scope selector.")
|
||||
.Produces<ScopeResolutionResponse>(StatusCodes.Status200OK);
|
||||
|
||||
group.MapGet("/{scopeType}/{scopeId}/attachments", GetScopeAttachments)
|
||||
.WithName("GetScopeAttachments")
|
||||
.WithSummary("Get all attachments for a specific scope.")
|
||||
.Produces<ScopeAttachmentListResponse>(StatusCodes.Status200OK);
|
||||
|
||||
return endpoints;
|
||||
}
|
||||
|
||||
private static IResult CreateAttachment(
|
||||
HttpContext context,
|
||||
[FromBody] CreateScopeAttachmentRequest request,
|
||||
ScopeAttachmentService attachmentService,
|
||||
RiskProfileConfigurationService profileService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyEdit);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (request == null || string.IsNullOrWhiteSpace(request.ProfileId))
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "ProfileId is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
// Verify profile exists
|
||||
var profile = profileService.GetProfile(request.ProfileId);
|
||||
if (profile == null)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Profile not found",
|
||||
Detail = $"Risk profile '{request.ProfileId}' was not found.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
|
||||
try
|
||||
{
|
||||
var attachment = attachmentService.Create(request, actorId);
|
||||
|
||||
return Results.Created(
|
||||
$"/api/risk/scopes/attachments/{attachment.Id}",
|
||||
new ScopeAttachmentResponse(attachment));
|
||||
}
|
||||
catch (ArgumentException ex)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = ex.Message,
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private static IResult GetAttachment(
|
||||
HttpContext context,
|
||||
[FromRoute] string attachmentId,
|
||||
ScopeAttachmentService attachmentService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var attachment = attachmentService.Get(attachmentId);
|
||||
if (attachment == null)
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Attachment not found",
|
||||
Detail = $"Scope attachment '{attachmentId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.Ok(new ScopeAttachmentResponse(attachment));
|
||||
}
|
||||
|
||||
private static IResult DeleteAttachment(
|
||||
HttpContext context,
|
||||
[FromRoute] string attachmentId,
|
||||
ScopeAttachmentService attachmentService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyEdit);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (!attachmentService.Delete(attachmentId))
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Attachment not found",
|
||||
Detail = $"Scope attachment '{attachmentId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.NoContent();
|
||||
}
|
||||
|
||||
private static IResult ExpireAttachment(
|
||||
HttpContext context,
|
||||
[FromRoute] string attachmentId,
|
||||
ScopeAttachmentService attachmentService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyEdit);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var actorId = ResolveActorId(context);
|
||||
var attachment = attachmentService.Expire(attachmentId, actorId);
|
||||
|
||||
if (attachment == null)
|
||||
{
|
||||
return Results.NotFound(new ProblemDetails
|
||||
{
|
||||
Title = "Attachment not found",
|
||||
Detail = $"Scope attachment '{attachmentId}' was not found.",
|
||||
Status = StatusCodes.Status404NotFound
|
||||
});
|
||||
}
|
||||
|
||||
return Results.Ok(new ScopeAttachmentResponse(attachment));
|
||||
}
|
||||
|
||||
private static IResult ListAttachments(
|
||||
HttpContext context,
|
||||
[FromQuery] ScopeType? scopeType,
|
||||
[FromQuery] string? scopeId,
|
||||
[FromQuery] string? profileId,
|
||||
[FromQuery] bool includeExpired,
|
||||
[FromQuery] int limit,
|
||||
ScopeAttachmentService attachmentService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var query = new ScopeAttachmentQuery(
|
||||
ScopeType: scopeType,
|
||||
ScopeId: scopeId,
|
||||
ProfileId: profileId,
|
||||
IncludeExpired: includeExpired,
|
||||
Limit: limit > 0 ? limit : 100);
|
||||
|
||||
var attachments = attachmentService.Query(query);
|
||||
|
||||
return Results.Ok(new ScopeAttachmentListResponse(attachments));
|
||||
}
|
||||
|
||||
private static IResult ResolveScope(
|
||||
HttpContext context,
|
||||
[FromBody] ScopeSelector selector,
|
||||
ScopeAttachmentService attachmentService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
if (selector == null)
|
||||
{
|
||||
return Results.BadRequest(new ProblemDetails
|
||||
{
|
||||
Title = "Invalid request",
|
||||
Detail = "Scope selector is required.",
|
||||
Status = StatusCodes.Status400BadRequest
|
||||
});
|
||||
}
|
||||
|
||||
var result = attachmentService.Resolve(selector);
|
||||
|
||||
return Results.Ok(new ScopeResolutionResponse(result));
|
||||
}
|
||||
|
||||
private static IResult GetScopeAttachments(
|
||||
HttpContext context,
|
||||
[FromRoute] ScopeType scopeType,
|
||||
[FromRoute] string scopeId,
|
||||
ScopeAttachmentService attachmentService)
|
||||
{
|
||||
var scopeResult = ScopeAuthorization.RequireScope(context, StellaOpsScopes.PolicyRead);
|
||||
if (scopeResult is not null)
|
||||
{
|
||||
return scopeResult;
|
||||
}
|
||||
|
||||
var attachments = attachmentService.GetAttachmentsForScope(scopeType, scopeId);
|
||||
|
||||
return Results.Ok(new ScopeAttachmentListResponse(attachments));
|
||||
}
|
||||
|
||||
private static string? ResolveActorId(HttpContext context)
|
||||
{
|
||||
var user = context.User;
|
||||
var actor = user?.FindFirst(ClaimTypes.NameIdentifier)?.Value
|
||||
?? user?.FindFirst(ClaimTypes.Upn)?.Value
|
||||
?? user?.FindFirst("sub")?.Value;
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(actor))
|
||||
{
|
||||
return actor;
|
||||
}
|
||||
|
||||
if (context.Request.Headers.TryGetValue("X-StellaOps-Actor", out var header) && !string.IsNullOrWhiteSpace(header))
|
||||
{
|
||||
return header.ToString();
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
#region Response DTOs
|
||||
|
||||
internal sealed record ScopeAttachmentResponse(ScopeAttachment Attachment);
|
||||
|
||||
internal sealed record ScopeAttachmentListResponse(IReadOnlyList<ScopeAttachment> Attachments);
|
||||
|
||||
internal sealed record ScopeResolutionResponse(ScopeResolutionResult Result);
|
||||
|
||||
#endregion
|
||||
@@ -17,7 +17,32 @@ internal sealed record PolicyEvaluationContext(
|
||||
PolicyEvaluationAdvisory Advisory,
|
||||
PolicyEvaluationVexEvidence Vex,
|
||||
PolicyEvaluationSbom Sbom,
|
||||
PolicyEvaluationExceptions Exceptions);
|
||||
PolicyEvaluationExceptions Exceptions,
|
||||
PolicyEvaluationReachability Reachability,
|
||||
DateTimeOffset? EvaluationTimestamp = null)
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets the evaluation timestamp for deterministic time-based operations.
|
||||
/// This value is injected at evaluation time rather than using DateTime.UtcNow
|
||||
/// to ensure deterministic, reproducible results.
|
||||
/// </summary>
|
||||
public DateTimeOffset Now => EvaluationTimestamp ?? DateTimeOffset.MinValue;
|
||||
|
||||
/// <summary>
|
||||
/// Creates a context without reachability data (for backwards compatibility).
|
||||
/// </summary>
|
||||
public PolicyEvaluationContext(
|
||||
PolicyEvaluationSeverity severity,
|
||||
PolicyEvaluationEnvironment environment,
|
||||
PolicyEvaluationAdvisory advisory,
|
||||
PolicyEvaluationVexEvidence vex,
|
||||
PolicyEvaluationSbom sbom,
|
||||
PolicyEvaluationExceptions exceptions,
|
||||
DateTimeOffset? evaluationTimestamp = null)
|
||||
: this(severity, environment, advisory, vex, sbom, exceptions, PolicyEvaluationReachability.Unknown, evaluationTimestamp)
|
||||
{
|
||||
}
|
||||
}
|
||||
|
||||
internal sealed record PolicyEvaluationSeverity(string Normalized, decimal? Score = null);
|
||||
|
||||
@@ -158,3 +183,96 @@ internal sealed record PolicyExceptionApplication(
|
||||
string AppliedStatus,
|
||||
string? AppliedSeverity,
|
||||
ImmutableDictionary<string, string> Metadata);
|
||||
|
||||
/// <summary>
|
||||
/// Reachability evidence for policy evaluation.
|
||||
/// </summary>
|
||||
internal sealed record PolicyEvaluationReachability(
|
||||
string State,
|
||||
decimal Confidence,
|
||||
decimal Score,
|
||||
bool HasRuntimeEvidence,
|
||||
string? Source,
|
||||
string? Method,
|
||||
string? EvidenceRef)
|
||||
{
|
||||
/// <summary>
|
||||
/// Default unknown reachability state.
|
||||
/// </summary>
|
||||
public static readonly PolicyEvaluationReachability Unknown = new(
|
||||
State: "unknown",
|
||||
Confidence: 0m,
|
||||
Score: 0m,
|
||||
HasRuntimeEvidence: false,
|
||||
Source: null,
|
||||
Method: null,
|
||||
EvidenceRef: null);
|
||||
|
||||
/// <summary>
|
||||
/// Reachable state.
|
||||
/// </summary>
|
||||
public static PolicyEvaluationReachability Reachable(
|
||||
decimal confidence = 1m,
|
||||
decimal score = 1m,
|
||||
bool hasRuntimeEvidence = false,
|
||||
string? source = null,
|
||||
string? method = null) => new(
|
||||
State: "reachable",
|
||||
Confidence: confidence,
|
||||
Score: score,
|
||||
HasRuntimeEvidence: hasRuntimeEvidence,
|
||||
Source: source,
|
||||
Method: method,
|
||||
EvidenceRef: null);
|
||||
|
||||
/// <summary>
|
||||
/// Unreachable state.
|
||||
/// </summary>
|
||||
public static PolicyEvaluationReachability Unreachable(
|
||||
decimal confidence = 1m,
|
||||
bool hasRuntimeEvidence = false,
|
||||
string? source = null,
|
||||
string? method = null) => new(
|
||||
State: "unreachable",
|
||||
Confidence: confidence,
|
||||
Score: 0m,
|
||||
HasRuntimeEvidence: hasRuntimeEvidence,
|
||||
Source: source,
|
||||
Method: method,
|
||||
EvidenceRef: null);
|
||||
|
||||
/// <summary>
|
||||
/// Whether the reachability state is definitively reachable.
|
||||
/// </summary>
|
||||
public bool IsReachable => State.Equals("reachable", StringComparison.OrdinalIgnoreCase);
|
||||
|
||||
/// <summary>
|
||||
/// Whether the reachability state is definitively unreachable.
|
||||
/// </summary>
|
||||
public bool IsUnreachable => State.Equals("unreachable", StringComparison.OrdinalIgnoreCase);
|
||||
|
||||
/// <summary>
|
||||
/// Whether the reachability state is unknown.
|
||||
/// </summary>
|
||||
public bool IsUnknown => State.Equals("unknown", StringComparison.OrdinalIgnoreCase);
|
||||
|
||||
/// <summary>
|
||||
/// Whether the reachability state is under investigation.
|
||||
/// </summary>
|
||||
public bool IsUnderInvestigation => State.Equals("under_investigation", StringComparison.OrdinalIgnoreCase);
|
||||
|
||||
/// <summary>
|
||||
/// Whether this reachability data has high confidence (>= 0.8).
|
||||
/// </summary>
|
||||
public bool IsHighConfidence => Confidence >= 0.8m;
|
||||
|
||||
/// <summary>
|
||||
/// Whether this reachability data has medium confidence (>= 0.5 and < 0.8).
|
||||
/// </summary>
|
||||
public bool IsMediumConfidence => Confidence >= 0.5m && Confidence < 0.8m;
|
||||
|
||||
/// <summary>
|
||||
/// Whether this reachability data has low confidence (< 0.5).
|
||||
/// </summary>
|
||||
public bool IsLowConfidence => Confidence < 0.5m;
|
||||
}
|
||||
|
||||
@@ -63,6 +63,8 @@ internal sealed class PolicyExpressionEvaluator
|
||||
"vex" => new EvaluationValue(new VexScope(this, context.Vex)),
|
||||
"advisory" => new EvaluationValue(new AdvisoryScope(context.Advisory)),
|
||||
"sbom" => new EvaluationValue(new SbomScope(context.Sbom)),
|
||||
"reachability" => new EvaluationValue(new ReachabilityScope(context.Reachability)),
|
||||
"now" => new EvaluationValue(context.Now),
|
||||
"true" => EvaluationValue.True,
|
||||
"false" => EvaluationValue.False,
|
||||
_ => EvaluationValue.Null,
|
||||
@@ -98,6 +100,11 @@ internal sealed class PolicyExpressionEvaluator
|
||||
return sbom.Get(member.Member);
|
||||
}
|
||||
|
||||
if (raw is ReachabilityScope reachability)
|
||||
{
|
||||
return reachability.Get(member.Member);
|
||||
}
|
||||
|
||||
if (raw is ComponentScope componentScope)
|
||||
{
|
||||
return componentScope.Get(member.Member);
|
||||
@@ -811,4 +818,51 @@ internal sealed class PolicyExpressionEvaluator
|
||||
return vex.Statements[^1];
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// SPL scope for reachability predicates.
|
||||
/// Provides access to reachability state, confidence, score, and evidence.
|
||||
/// </summary>
|
||||
/// <example>
|
||||
/// SPL predicates supported:
|
||||
/// - reachability.state == "reachable"
|
||||
/// - reachability.state == "unreachable"
|
||||
/// - reachability.state == "unknown"
|
||||
/// - reachability.confidence >= 0.8
|
||||
/// - reachability.score > 0.5
|
||||
/// - reachability.has_runtime_evidence == true
|
||||
/// - reachability.is_reachable == true
|
||||
/// - reachability.is_unreachable == true
|
||||
/// - reachability.is_high_confidence == true
|
||||
/// - reachability.source == "grype"
|
||||
/// - reachability.method == "static"
|
||||
/// </example>
|
||||
private sealed class ReachabilityScope
|
||||
{
|
||||
private readonly PolicyEvaluationReachability reachability;
|
||||
|
||||
public ReachabilityScope(PolicyEvaluationReachability reachability)
|
||||
{
|
||||
this.reachability = reachability;
|
||||
}
|
||||
|
||||
public EvaluationValue Get(string member) => member.ToLowerInvariant() switch
|
||||
{
|
||||
"state" => new EvaluationValue(reachability.State),
|
||||
"confidence" => new EvaluationValue(reachability.Confidence),
|
||||
"score" => new EvaluationValue(reachability.Score),
|
||||
"has_runtime_evidence" or "hasruntimeevidence" => new EvaluationValue(reachability.HasRuntimeEvidence),
|
||||
"source" => new EvaluationValue(reachability.Source),
|
||||
"method" => new EvaluationValue(reachability.Method),
|
||||
"evidence_ref" or "evidenceref" => new EvaluationValue(reachability.EvidenceRef),
|
||||
"is_reachable" or "isreachable" => new EvaluationValue(reachability.IsReachable),
|
||||
"is_unreachable" or "isunreachable" => new EvaluationValue(reachability.IsUnreachable),
|
||||
"is_unknown" or "isunknown" => new EvaluationValue(reachability.IsUnknown),
|
||||
"is_under_investigation" or "isunderinvestigation" => new EvaluationValue(reachability.IsUnderInvestigation),
|
||||
"is_high_confidence" or "ishighconfidence" => new EvaluationValue(reachability.IsHighConfidence),
|
||||
"is_medium_confidence" or "ismediumconfidence" => new EvaluationValue(reachability.IsMediumConfidence),
|
||||
"is_low_confidence" or "islowconfidence" => new EvaluationValue(reachability.IsLowConfidence),
|
||||
_ => EvaluationValue.Null,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user