Files

StellaOps Bot 5e514532df Implement VEX document verification system with issuer management and signature verification

- Added IIssuerDirectory interface for managing VEX document issuers, including methods for registration, revocation, and trust validation.
- Created InMemoryIssuerDirectory class as an in-memory implementation of IIssuerDirectory for testing and single-instance deployments.
- Introduced ISignatureVerifier interface for verifying signatures on VEX documents, with support for multiple signature formats.
- Developed SignatureVerifier class as the default implementation of ISignatureVerifier, allowing extensibility for different signature formats.
- Implemented handlers for DSSE and JWS signature formats, including methods for verification and signature extraction.
- Defined various records and enums for issuer and signature metadata, enhancing the structure and clarity of the verification process.

2025-12-06 13:41:22 +02:00

4.2 KiB

Raw Blame History

Policy Normalized Field Removal Design

Document ID: DESIGN-POLICY-NORMALIZED-FIELD-REMOVAL-001 Version: 1.0 Status: Draft Last Updated: 2025-12-06

Overview

This document defines the migration plan for removing deprecated and legacy normalized fields from Policy Engine models. These fields were introduced for backwards compatibility but are now superseded by deterministic, canonical alternatives.

Background

The Policy Engine currently includes several "normalized" fields that were designed for cross-source comparison but have been deprecated in favor of deterministic scoring:

normalized_score - Originally used for cross-vendor score comparison, now superseded by canonical severity scoring
source_rank - Used for source prioritization, now handled by trust weighting service
Duplicated severity fields - Multiple representations of the same severity data

Fields Analysis

Candidates for Removal

Field	Location	Status	Migration Path
`normalized_score`	`RiskScoringResult`	DEPRECATED	Use `severity` with canonical mapping
`source_rank` in scoring	`PolicyDecisionSourceRank`	DEPRECATED	Use trust weighting service
Legacy `severity_counts`	Multiple models	KEEP	Still used for aggregation

Fields to Retain

Field	Location	Reason
`severity`	All scoring models	Canonical severity (critical/high/medium/low/info)
`profile_hash`	`RiskScoringResult`	Deterministic policy identification
`trust_weight`	Decision models	Active trust weighting system
`raw_score`	Scoring results	Needed for audit/debugging

Migration Plan

Phase 1: Deprecation (Current State)

Fields marked with [Obsolete] attribute to warn consumers:

[Obsolete("Use severity with canonical mapping. Scheduled for removal in v2.0")]
[JsonPropertyName("normalized_score")]
public double NormalizedScore { get; init; }

Phase 2: Soft Removal (v1.5)

Remove fields from serialization by default
Add configuration flag to re-enable for backwards compatibility
Update API documentation

Phase 3: Hard Removal (v2.0)

Remove fields from models entirely
Remove backwards compatibility flags

API Impact

Before (Current)

{
  "finding_id": "CVE-2024-1234",
  "raw_score": 7.5,
  "normalized_score": 0.75,
  "severity": "high",
  "source_ranks": [
    {"source": "nvd", "rank": 1},
    {"source": "vendor", "rank": 2}
  ]
}

After (Target)

{
  "finding_id": "CVE-2024-1234",
  "raw_score": 7.5,
  "severity": "high",
  "trust_weights": {
    "nvd": 1.0,
    "vendor": 0.8
  }
}

Implementation Steps

Step 1: Add Deprecation Markers

Add [Obsolete] to target fields with clear migration guidance.

Step 2: Create Compatibility Layer

Add opt-in flag for legacy serialization:

public class PolicyScoringOptions
{
    /// <summary>
    /// Include deprecated normalized_score field for backwards compatibility.
    /// </summary>
    public bool IncludeLegacyNormalizedScore { get; set; } = false;
}

Step 3: Update Serialization

Use conditional serialization based on options:

[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public double? NormalizedScore =>
    _options.IncludeLegacyNormalizedScore ? _normalizedScore : null;

Step 4: Update Documentation

Mark fields as deprecated in OpenAPI spec
Add migration guide to release notes

Fixtures

Sample payloads are available in:

docs/modules/policy/samples/policy-normalized-field-removal-before.json
docs/modules/policy/samples/policy-normalized-field-removal-after.json

Rollback Strategy

If issues arise during migration:

Re-enable legacy fields via configuration
No data loss - fields are computed, not stored

Acceptance Criteria

Deprecated fields marked with [Obsolete]
Configuration option for backwards compatibility
API documentation updated
Migration guide published
Fixtures validate before/after behavior

4.2 KiB Raw Blame History