CerbiShield.Contracts 1.3.1

CerbiShield.Contracts

Shared message contracts for the CerbiShield ecosystem — the single source of truth for DTOs exchanged between all CerbiShield microservices.

Installation

dotnet add package CerbiShield.Contracts

Version 1.2.0 (Current)

Scoring Event Evidence Metadata

ScoringEventDto schema version 1.2 is an additive evidence extension for auditor-ready source-side logging governance. All evidence fields are nullable so producers using v1.1 payloads remain valid and consumers can adopt the metadata incrementally.

Rule → App → Violation Linkage

ViolationDto now carries full context so downstream consumers (dashboards, analytics, reports) can trace every violation back to the exact rule, profile, and app that produced it.

Composite RuleId Format

The RuleId field now supports a stable composite format:

{profile}:{field}:{code}

Examples:

• Orders:UserId:Missing — Required field UserId is missing in the Orders profile
• Payments:creditCardPlain:Forbidden — Forbidden field detected
• Analytics:sessionId:InvalidType — Type mismatch on sessionId

This composite key enables the Violation Explorer dashboard to group, filter, and drill into violations by rule, field, profile, and app.

Backward-Compatible Schema Validation

ScoringEventValidator now accepts any schema version between 1.0 and 1.2 (inclusive), so existing producers sending 1.0 or 1.1 events are not rejected when consumers upgrade to this package.

Full Changelog

• ViolationDto: added Description, ProfileName, AppName
• ContractVersions.ScoringEventSchemaVersion: 1.1 → 1.2
• ScoringEventValidator: range-based schema version check (1.0–1.2)
• Package version: 1.3.0 → 1.3.1-preview.1 (repo package version already used the 1.3.x multi-targeting scheme)

Version 1.1.0

• Added ServiceName, AppVersion, InstanceId, DeploymentId to ScoringEventDto
• Added GovernanceConfigDto for dashboard-generated configs
• TenantId can now come from governance config
• SchemaVersion bumped to 1.1

Package Contents

Scoring Contracts

• ScoringEventDto — Canonical scoring event payload (v1.2: additive nullable evidence metadata; v1.1: +ServiceName, AppVersion, InstanceId, DeploymentId)
• ScoringQueueEnvelopeDto — Queue envelope wrapper
• ScoreBreakdownDto — Score breakdown by category (Overall, Governance, Safety)
• ViolationDto — Governance violation details (v1.2: +Description, ProfileName, AppName)
• GovernanceFlagsDto — Governance processing flags

Governance Contracts

• GovernanceConfigDto — Dashboard-generated config with embedded TenantId
• GovernanceProfileDto — Profile with rules and environment overrides
• GovernanceRuleDto — Individual governance rule
• EnvironmentOverrideDto — Per-environment severity adjustments

Aggregation Contracts

• AppMetricDto — Application-level metric data points

Validation

• ScoringEventValidator — Validates ScoringEventDto instances (schema version range, required fields, score bounds)
• ValidationResult — Validation result record

Schema Versions

Data Flow

┌──────────────────┐     ┌─────────────────────┐     ┌──────────────────────┐
│  Runtime Engine   │────▶│  Scoring Shipper     │────▶│  Scoring Aggregator  │
│  (GovernanceRT)   │     │  (Serilog/MEL/Stream)│     │  (ScoringApi)        │
└──────────────────┘     └─────────────────────┘     └──────────────────────┘
        │                         │                           │
        │  ViolationDto           │  ScoringEventDto          │  ScoringEvent
        │  .RuleId                │  .Violations[]            │  .ViolationCount
        │  .Code                  │  .AppName                 │  .GovernanceProfile
        │  .Field                 │  .GovernanceProfile       │
        │  .Description           │  .DeploymentId            │
        │  .ProfileName           │                           ▼
        │  .AppName               │               ┌──────────────────────┐
        │                         │               │  Analytics API       │
        ▼                         ▼               │  (ViolationExplorer) │
   GovernanceStore           Dashboard            └──────────────────────┘
   (Playground)

License