bd2529502e
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Scanner Analyzers / Discover Analyzers (push) Has been cancelled
Scanner Analyzers / Build Analyzers (push) Has been cancelled
Scanner Analyzers / Test Language Analyzers (push) Has been cancelled
Scanner Analyzers / Validate Test Fixtures (push) Has been cancelled
Scanner Analyzers / Verify Deterministic Output (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
- Added WineCspHttpProvider class to interface with Wine-hosted CryptoPro CSP. - Implemented ICryptoProvider, ICryptoProviderDiagnostics, and IDisposable interfaces. - Introduced WineCspHttpSigner and WineCspHttpHasher for signing and hashing operations. - Created WineCspProviderOptions for configuration settings including service URL and key options. - Developed CryptoProGostSigningService to handle GOST signing operations and key management. - Implemented HTTP service for the Wine CSP with endpoints for signing, verification, and hashing. - Added Swagger documentation for API endpoints. - Included health checks and error handling for service availability. - Established DTOs for request and response models in the service.
88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# Policy Notification Contract · Risk Profile Lifecycle and Threshold Changes
|
|
|
|
## Purpose
|
|
- Provide a stable payload/transport contract for notifying downstream systems when risk profiles are created, updated, activated/deactivated, or when scoring thresholds change.
|
|
- Unblocks `POLICY-RISK-69-001` by supplying the “notifications contract” referenced in sprint planning.
|
|
|
|
## Event Types
|
|
- `policy.profile.created` — new profile draft created.
|
|
- `policy.profile.activated` — profile version activated for a tenant/scope.
|
|
- `policy.profile.deactivated` — profile version retired or superseded.
|
|
- `policy.profile.threshold_changed` — risk thresholds updated (any level).
|
|
- `policy.profile.override_added` / `override_removed` — override lifecycle changes.
|
|
- `policy.profile.simulation_ready` — simulation results available for consumption.
|
|
|
|
## Transport
|
|
- Primary: Notifications service topic `notifications.policy.profiles` (tenant-scoped).
|
|
- Alt: Webhook delivery using POST with `X-Stella-Tenant` and HMAC-SHA256 signature header `X-Stella-Signature` (hex digest over body with shared secret).
|
|
- Idempotency: `event_id` is a UUIDv7; consumers must de-duplicate.
|
|
|
|
## Payload Schema (JSON)
|
|
```json
|
|
{
|
|
"event_id": "018f9a2e-8f7d-7fbb-9db4-9f9a3d9c4caa",
|
|
"event_type": "policy.profile.threshold_changed",
|
|
"emitted_at": "2025-12-07T12:00:00Z",
|
|
"tenant_id": "tenant-123",
|
|
"profile_id": "risk-profile-core",
|
|
"profile_version": "3.2.0",
|
|
"change_reason": "Updated high/critical thresholds per policy board decision",
|
|
"actor": {
|
|
"type": "user",
|
|
"id": "alice@example.com"
|
|
},
|
|
"thresholds": {
|
|
"info": 0.1,
|
|
"low": 0.25,
|
|
"medium": 0.5,
|
|
"high": 0.75,
|
|
"critical": 0.9
|
|
},
|
|
"effective_scope": {
|
|
"tenants": ["tenant-123"],
|
|
"projects": ["proj-a", "proj-b"],
|
|
"purl_patterns": ["pkg:npm/*"],
|
|
"cpe_patterns": ["cpe:2.3:*:vendor:*:product:*:*:*:*:*:*:*"],
|
|
"tags": ["prod", "pci"]
|
|
},
|
|
"hash": {
|
|
"algorithm": "sha256",
|
|
"value": "b6c1d6c618a01f9fef6db7e6d86e3c57b1a2cc77ce88a7b7d8e8ac4c28e0a1df"
|
|
},
|
|
"links": {
|
|
"profile_url": "https://policy.example.com/api/risk/profiles/risk-profile-core",
|
|
"diff_url": "https://policy.example.com/api/risk/profiles/risk-profile-core/diff?from=3.1.0&to=3.2.0",
|
|
"simulation_url": "https://policy.example.com/api/risk/simulations/results/018f9a2e-8f7d-7fbb-9db4-9f9a3d9c4caa"
|
|
},
|
|
"trace": {
|
|
"trace_id": "4f2d1b7c6a9846a5b9a72f4c3ed1f2c1",
|
|
"span_id": "9c4caa8f7d7fbb9d"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Validation Rules
|
|
- `emitted_at` is UTC ISO-8601; ordering is deterministic by `(emitted_at, event_id)`.
|
|
- `tenant_id` is required; `projects` optional but recommended for multi-project scopes.
|
|
- `hash.value` MUST be the SHA-256 of the serialized risk profile bundle that triggered the event.
|
|
- `links.*` SHOULD point to the canonical Policy Engine endpoints; omit if not reachable in air-gap.
|
|
- Webhook delivery MUST include `X-Stella-Signature` = `hex(HMAC_SHA256(shared_secret, raw_body))`.
|
|
|
|
## CLI Consumption (sample output)
|
|
Example consumption for downstream automation (captured from `policy notify tail`):
|
|
```
|
|
$ stella policy notify tail --topic notifications.policy.profiles --tenant tenant-123 --limit 1
|
|
event_id: 018f9a2e-8f7d-7fbb-9db4-9f9a3d9c4caa
|
|
event_type: policy.profile.threshold_changed
|
|
profile_id: risk-profile-core@3.2.0
|
|
thresholds: info=0.10 low=0.25 medium=0.50 high=0.75 critical=0.90
|
|
scope.tenants: tenant-123
|
|
scope.projects: proj-a, proj-b
|
|
hash.sha256: b6c1d6c618a01f9fef6db7e6d86e3c57b1a2cc77ce88a7b7d8e8ac4c28e0a1df
|
|
links.profile_url: https://policy.example.com/api/risk/profiles/risk-profile-core
|
|
```
|
|
|
|
## Versioning
|
|
- Version 1.0 frozen with this document; additive fields require minor version bump (`event_schema_version` header optional, default `1.0`).
|
|
- Breaking changes require new event types or topic.
|