feat: Implement DefaultCryptoHmac for compliance-aware HMAC operations
- Added DefaultCryptoHmac class implementing ICryptoHmac interface. - Introduced purpose-based HMAC computation methods. - Implemented verification methods for HMACs with constant-time comparison. - Created HmacAlgorithms and HmacPurpose classes for well-known identifiers. - Added compliance profile support for HMAC algorithms. - Included asynchronous methods for HMAC computation from streams.
This commit is contained in:
StellaOps Bot
@@ -1,6 +1,6 @@
|
||||
# Risk API (draft outline)
|
||||
# Risk API
|
||||
|
||||
> Draft scaffold; populate once 67-001 explainability outputs and API publishing workflow are available. Keep examples deterministic; include ETags and error payloads when provided.
|
||||
> Based on `CONTRACT-RISK-SCORING-002` (2025-12-05). Examples are frozen in `docs/risk/samples/api/risk-api-samples.json` with hashes in `SHA256SUMS`. Keep ETags and error payloads deterministic.
|
||||
|
||||
## Purpose
|
||||
- Document risk-related endpoints for profile management, simulation, scoring results, explainability retrieval, and export.
|
||||
@@ -10,32 +10,32 @@
|
||||
- In scope: endpoint list, methods, request/response schemas, auth/tenancy headers, rate limits, feature flags, error model.
|
||||
- Out of scope: console/UI workflow details (see `explainability.md`).
|
||||
|
||||
## Endpoint Outline (placeholders)
|
||||
- `GET /api/risk/profiles` — list profiles (filters by tenant, status).
|
||||
- `POST /api/risk/profiles` — create/update; includes DSSE/attestation fields.
|
||||
- `POST /api/risk/simulations` — run simulation with fixture set; supports dry-run.
|
||||
- `GET /api/risk/results/{id}` — retrieve scored results + explainability link.
|
||||
- `GET /api/risk/explain/{id}` — fetch explainability payload.
|
||||
- `GET /api/risk/export/{id}` — export bundle (JSON/CSV) with hash manifest.
|
||||
- Feature flags: `<pending>`
|
||||
## Endpoints (v1)
|
||||
- `POST /api/v1/risk/jobs` — submit scoring job (body: job request); returns `202` with `job_id` and `status` (`queued`). Sample: `risk-api-samples.json#submit_job_request`.
|
||||
- `GET /api/v1/risk/jobs/{job_id}` — job status + results array (sample: `get_job_status`).
|
||||
- `GET /api/v1/risk/explain/{job_id}` — explainability payload (sample references `../explain/explain-trace.json`).
|
||||
- `GET /api/v1/risk/profiles` — list profiles (tenant-filtered); include `profile_hash`, `version`, `etag`.
|
||||
- `POST /api/v1/risk/profiles` — create/update profile with DSSE/attestation metadata; returns `201` with `etag`.
|
||||
- `POST /api/v1/risk/simulations` — dry-run scoring with fixtures; returns explain + contributions without persisting results.
|
||||
- `GET /api/v1/risk/export/{job_id}` — export bundle (JSON + CSV + manifest) for auditors.
|
||||
- Feature flags: `risk.jobs`, `risk.explain`, `risk.simulations`, `risk.export` (toggle exposure per tenant).
|
||||
|
||||
## Auth & Tenancy
|
||||
- Required headers: `X-Stella-Tenant`, `X-Stella-Scope`, auth tokens (PAT/OAuth2) — confirm once schema published.
|
||||
- Imposed rule reminder must be present on every page.
|
||||
- Required headers: `X-Stella-Tenant`, `Authorization: Bearer <token>`, optional `X-Stella-Scope` for imposed rule reminders.
|
||||
- Imposed rule reminder must be present in responses where tenant-bound resources are returned.
|
||||
|
||||
## Error Model (pending)
|
||||
- Standard error envelope: code, message, correlation_id, severity, remediation.
|
||||
- Rate limit headers and retry guidance.
|
||||
## Error Model
|
||||
- Envelope: `code`, `message`, `correlation_id`, `severity`, `remediation`.
|
||||
- Rate-limit headers: `Retry-After`, `X-RateLimit-Remaining` (document values in SDKs).
|
||||
|
||||
## Determinism & Offline Posture
|
||||
- Provide sample requests/responses under `docs/risk/samples/`; include SHA256 table.
|
||||
- No live dependencies; use frozen fixtures.
|
||||
- Samples: `docs/risk/samples/api/risk-api-samples.json` (hashes in `SHA256SUMS`); explain sample reused via relative reference.
|
||||
- No live dependencies; use frozen fixtures. Keep ordering of fields stable in docs and samples.
|
||||
|
||||
## Open Items
|
||||
- API publishing workflow outputs
|
||||
- Final endpoint list and field names
|
||||
- Error/code catalog
|
||||
- SDK generator targets and examples
|
||||
- Add ETag examples for profile list/create once generators emit them.
|
||||
- Populate error/code catalog and SDK targets once available.
|
||||
- Align feature flag names with deployment config.
|
||||
|
||||
## References
|
||||
- `docs/risk/overview.md`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Risk Explainability (draft outline)
|
||||
# Risk Explainability
|
||||
|
||||
> Draft scaffold; fill once 66-004 outputs and UI telemetry captures arrive. Keep fixtures deterministic (frozen payloads, stable ordering, SHA tables).
|
||||
> Source: `CONTRACT-RISK-SCORING-002` (2025-12-05). Fixtures live under `docs/risk/samples/explain/`; all hashes in `SHA256SUMS`. Keep outputs deterministic (frozen payloads, stable ordering).
|
||||
|
||||
## Purpose
|
||||
- Show how the scoring engine produces per-factor contributions and traces that UI/CLI/export surfaces render for auditors and operators.
|
||||
@@ -10,23 +10,23 @@
|
||||
- In scope: explainability payload shape, field meanings, provenance, UI/CLI mapping, offline/export behavior.
|
||||
- Out of scope: formula math (see `formulas.md`), API specifics (see `api.md`).
|
||||
|
||||
## Payload Shape (pending)
|
||||
- Envelope fields: score, severity, factors[], provenance, timestamps (UTC), profile version, environment.
|
||||
- Factor entry fields: id, type, input_value, normalized_value, weight, contribution, source, evidence_refs[].
|
||||
- UI/CLI expectations: stable ordering, highlight top contributors, include attestation status.
|
||||
## Payload Shape
|
||||
- Envelope: `job_id`, `tenant_id`, `context_id`, `profile_id`, `profile_version`, `profile_hash`, `finding_id`, `raw_score`, `normalized_score`, `severity`, `signal_values{}`, `signal_contributions{}`, optional `override_applied`, `override_reason`, `gates_triggered[]`, `scored_at`, `provenance` (job hash + fixture hashes).
|
||||
- Factor entries (from `signal_values`/`signal_contributions`): `name`, `source`, `type`, `path`, `raw_value`, `normalized_value`, `weight`, `contribution`, `provenance`.
|
||||
- UI/CLI expectations: deterministic ordering (factor type → source → timestamp), highlight top contributors, show attestation status for each factor.
|
||||
|
||||
## UI/CLI Views (to fill)
|
||||
- Console panels and charts (needs telemetry captures)
|
||||
- CLI `stella risk explain` output (deterministic table examples)
|
||||
- Export Center bundles (JSON + CSV + hash manifests)
|
||||
## UI/CLI Views
|
||||
- Console: table of factors sorted by contribution, severity badge, gate badges (e.g., KEV+reachability), link to provenance hashes.
|
||||
- CLI `stella risk explain job-001`: render table using fixture `explain-trace.json`; include `--json` option that emits the same payload.
|
||||
- Export Center: embed explain payload + SHA256 manifest; CSV export keeps deterministic ordering.
|
||||
|
||||
## Determinism & Offline Posture
|
||||
- Store example payloads under `docs/risk/samples/`; record `SHA256SUMS`.
|
||||
- No live calls; all captures from frozen fixtures.
|
||||
- Example payload: `docs/risk/samples/explain/explain-trace.json` (hash in `SHA256SUMS`).
|
||||
- No live calls; all captures from frozen fixtures. Use exact ordering and timestamps when regenerating.
|
||||
|
||||
## Open Items
|
||||
- Capture UI telemetry (Console Guild) and CLI sample outputs.
|
||||
- Finalize explainability JSON schema once 66-004 is approved.
|
||||
- Capture UI telemetry screenshots/frames for console + CLI to replace textual description.
|
||||
- Add schema file once JSON schema is frozen; update references accordingly.
|
||||
|
||||
## References
|
||||
- `docs/risk/overview.md`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Risk Factors (draft outline)
|
||||
# Risk Factors
|
||||
|
||||
> Draft scaffold; fill once 66-002/66-003 inputs (engine contract + sample payloads) arrive. Keep fixtures deterministic and offline-friendly.
|
||||
> Aligned to `CONTRACT-RISK-SCORING-002` (published 2025-12-05). Keep fixtures deterministic and offline-friendly.
|
||||
|
||||
## Purpose
|
||||
- Catalog supported factors (exploit likelihood, VEX state, reachability, runtime facts, fix availability, asset criticality, provenance trust, tenant overrides) and how they normalize into risk math.
|
||||
@@ -10,32 +10,34 @@
|
||||
- In scope: factor definitions, required/optional fields, normalization rules, TTLs, provenance expectations.
|
||||
- Out of scope: full formula math (see `formulas.md`), API wiring (see `api.md`).
|
||||
|
||||
## Factor Catalog (to fill with schema-backed tables)
|
||||
- Exploit likelihood — fields: source, score, last_seen, confidence
|
||||
- VEX status — fields: status, justification, impact_statement
|
||||
- Reachability — fields: entrypoint, callgraph evidence, runtime observation
|
||||
- Runtime facts — fields: host, container, signal type, timestamp (UTC), provenance attestation
|
||||
- Fix availability — fields: advisory id, patch released at, mitigation guidance
|
||||
- Asset criticality — fields: business tier, data class, tenancy scope
|
||||
- Provenance trust — fields: signature status, key id, chain of custody
|
||||
- Custom/tenant overrides — fields: override reason, reviewer, expiry/TTL
|
||||
## Factor Catalog (mirrors profile `signals[]`)
|
||||
| Factor | Required fields | Optional fields | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| CVSS / exploit likelihood | `name`, `source`, `type:"numeric"`, `path`, `transform:"normalize_10"` | `unit:"score"`, `last_seen`, `confidence` | Normalize 0–10 to 0–1; clamp and keep original in provenance. |
|
||||
| KEV flag | `name`, `source`, `type:"boolean"`, `path` | `last_seen` | Boolean boost; drives severity overrides/decisions. |
|
||||
| Reachability | `name`, `source`, `type:"numeric"`, `path` | `unit:"score"`, `guards` | May fuse static reachability + runtime observation; ordered by entrypoint/path hash. |
|
||||
| Runtime facts | `name`, `source`, `type:"categorical" or "numeric"`, `path` | `trace_id`, `span_id` | Includes host/container identity and provenance for runtime traces. |
|
||||
| Fix availability | `name`, `source`, `type`, `path` | `mitigation`, `vendor_status` | Decay older advisories; keep mitigation text intact. |
|
||||
| Asset criticality | `name`, `source`, `type`, `path` | `tenant_scope`, `owner` | Used as multiplier/guard in formulas. |
|
||||
| Provenance trust | `name`, `source`, `type:"categorical"`, `path` | `key_id`, `chain_of_custody` | Gate low-trust inputs; must carry attestation hash. |
|
||||
| Custom overrides | `name`, `source`, `type`, `path` | `override_reason`, `reviewer`, `expires_at` | Logged and expiring; surfaced in `signal_contributions`. |
|
||||
|
||||
## Normalization Rules (outline)
|
||||
- Input validation + schema versioning
|
||||
- Unit ranges (0–1) and clamping
|
||||
- Time decay / TTL handling
|
||||
- Precedence rules when multiple sources disagree
|
||||
## Normalization Rules
|
||||
- Validate against profile `signals.type` and known transforms; reject unknown fields.
|
||||
- Clamp numeric inputs to 0–1; record original value in provenance for audit.
|
||||
- TTL/decay: apply per-factor defaults (pending payload fixtures); drop expired signals deterministically.
|
||||
- Precedence: signed → unsigned; runtime → static; newer → older; when tied, lowest hash order.
|
||||
|
||||
Interim notes: follow legacy profile guidance — preserve provenance, never mutate source evidence, and keep ordering stable so explainability hashes are repeatable across UI/CLI/exports.
|
||||
|
||||
## Determinism & Ordering
|
||||
- Sort factors by type then source; stable hashing rules for fixtures.
|
||||
- Record SHA256 for sample payloads once provided.
|
||||
- Sort factors by `factor_type` then `source` then `timestamp_utc`; deterministic hashing for fixtures.
|
||||
- Record SHA256 for sample payloads in `docs/risk/samples/factors/SHA256SUMS` once provided.
|
||||
|
||||
## Open Items
|
||||
- Engine contract and sample payloads for each factor
|
||||
- TTL/decay parameters from Risk Engine Guild
|
||||
- Provenance attestation examples
|
||||
- Sample payloads per factor for fixtures + hashes.
|
||||
- TTL/decay parameters from Risk Engine Guild.
|
||||
- Provenance attestation examples (signed runtime traces, KEV ingestion evidence).
|
||||
|
||||
## References
|
||||
- `docs/risk/overview.md`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Risk Formulas (draft outline)
|
||||
# Risk Formulas
|
||||
|
||||
> Draft scaffold; fill once 66-003/66-004 inputs (engine rollout notes + factor contract) are available. Keep math examples deterministic with fixed fixtures.
|
||||
> Based on `CONTRACT-RISK-SCORING-002` (2025-12-05). Keep math examples deterministic with fixed fixtures.
|
||||
|
||||
## Purpose
|
||||
- Describe how normalized factors combine into a 0–100 risk score with severity bands.
|
||||
@@ -11,37 +11,49 @@
|
||||
- In scope: weighting strategies, aggregation functions, severity thresholds, gating rules, tie-breakers.
|
||||
- Out of scope: full API payloads (see `api.md`), factor definitions (see `factors.md`).
|
||||
|
||||
## Formula Building Blocks (to fill)
|
||||
- Weighted sum / capped contribution
|
||||
- Max/min guards per factor family
|
||||
- Threshold gates (e.g., block if exploitability + reachability high)
|
||||
- Decay/time weighting
|
||||
- Tenant/asset overrides and imposed rules
|
||||
## Formula Building Blocks
|
||||
- Weighted sum with per-factor caps; enforce max contribution per family (exploitability, reachability, runtime).
|
||||
- Base rule (contract): `raw_score = Σ(signal_value × weight)`, `normalized_score = clamp(raw_score, 0.0, 1.0)`.
|
||||
- VEX gate: if `signals.HasVexDenial`, return `0.0` immediately (mitigated finding).
|
||||
- CVSS + KEV provider: `score = clamp01((cvss/10) + (kev ? 0.2 : 0))`.
|
||||
- Guard rails: hard gates when `(exploit_likelihood >= T1) AND (reachability >= T2)` or when provenance trust below minimum.
|
||||
- Decay/time weighting: exponential decay for stale runtime/KEV signals; fresh VEX `not_affected` may down-weight exploit scores.
|
||||
- Tenant/asset overrides: additive/override blocks with expiry; always logged in explainability output.
|
||||
- Safety: divide-by-zero and null handling must be deterministic and reflected in explain trace.
|
||||
|
||||
## Severity Mapping (outline)
|
||||
- Proposed bands (example placeholder):
|
||||
- Critical: 90–100
|
||||
- High: 70–89
|
||||
- Medium: 40–69
|
||||
- Low: 1–39
|
||||
- Info: 0
|
||||
- Final bands pending governance approval; update once PLLG0104 confirms.
|
||||
## Severity Mapping
|
||||
- Contract levels: `critical`, `high`, `medium`, `low`, `informational` (priority 1–5).
|
||||
- Map `normalized_score` to bands per profile policy; include band rationale in explainability payload.
|
||||
|
||||
## Determinism
|
||||
- Stable ordering of factors before aggregation.
|
||||
- Use fixed precision (e.g., 4 decimals) before severity mapping.
|
||||
- Hash fixtures and record SHA256 for every example payload.
|
||||
- Use fixed precision (e.g., 4 decimals) before severity mapping; round not truncate.
|
||||
- Hash fixtures and record SHA256 for every example payload in `docs/risk/samples/formulas/SHA256SUMS`.
|
||||
|
||||
Interim notes: mirror legacy rule — simulation and production must share the exact evaluation codepath; no per-environment divergences. Severity buckets must be deterministic and governed by Authority scopes.
|
||||
|
||||
## Examples (placeholders)
|
||||
- TBD sample JSON: input factors + output score + contributions table.
|
||||
- TBD CLI/Console screenshots once telemetry assets provided.
|
||||
## Example (contract-aligned)
|
||||
```json
|
||||
{
|
||||
"finding_id": "f-123",
|
||||
"profile_id": "default-profile",
|
||||
"profile_version": "1.0.0",
|
||||
"raw_score": 0.75,
|
||||
"normalized_score": 0.85,
|
||||
"severity": "high",
|
||||
"signal_values": { "cvss": 7.5, "kev": true, "reachability": 0.9 },
|
||||
"signal_contributions": { "cvss": 0.4, "kev": 0.3, "reachability": 0.3 },
|
||||
"override_applied": "kev-boost",
|
||||
"override_reason": "Known Exploited Vulnerability",
|
||||
"scored_at": "2025-12-05T00:00:02Z"
|
||||
}
|
||||
```
|
||||
- CLI/Console screenshots pending telemetry assets (keep deterministic fixture IDs).
|
||||
|
||||
## Open Items
|
||||
- Engine rollout notes for gating/weighting defaults
|
||||
- Severity band approval
|
||||
- Sample payloads and UI traces
|
||||
- Fixtures for jobs/results and explainability traces.
|
||||
- Final per-profile severity thresholds (document once agreed).
|
||||
- UI traces for console/CLI explainability views.
|
||||
|
||||
## References
|
||||
- `docs/risk/overview.md`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Risk Overview (draft outline)
|
||||
# Risk Overview
|
||||
|
||||
> Draft scaffold only. Populate content after PLLG0104 risk profile schema approval and risk engine/API samples land. Keep all fixtures deterministic (UTC timestamps, stable ordering, sealed sample payloads) and avoid external assets.
|
||||
> Source of truth: `CONTRACT-RISK-SCORING-002` (published 2025-12-05). Keep fixtures deterministic (UTC timestamps, stable ordering, sealed sample payloads) and avoid external assets.
|
||||
|
||||
## Purpose
|
||||
- Explain the risk model at a glance: factors, formulas, scoring semantics (0–100), and severity bands.
|
||||
@@ -11,36 +11,37 @@
|
||||
- In scope: concepts, glossary, lifecycle, artifacts, cross-module data flow diagrams (add after schema approval).
|
||||
- Out of scope: detailed factor math (goes to `formulas.md`), API specifics (goes to `api.md`).
|
||||
|
||||
## Core Concepts (to fill)
|
||||
- Risk factor vs. evidence vs. signal
|
||||
- Profile vs. formula vs. severity mapping
|
||||
- Provenance and attestations
|
||||
- Explainability payloads and UI/CLI displays
|
||||
- Determinism expectations (ordering, timestamps, hashing)
|
||||
## Core Concepts
|
||||
- **Signal → evidence → factor:** raw events (scanner, VEX, runtime) become evidence once validated; evidence is normalized into factors listed under profile `signals[]`.
|
||||
- **Profile vs. formula:** a profile bundles factor weights, thresholds, overrides, and severity mapping; formulas describe how weighted signals aggregate and when gates short-circuit.
|
||||
- **Provenance:** every input keeps its attestation/signature and source hash; explainability echoes `profile_hash`, factor hashes, and job correlation IDs.
|
||||
- **Explainability payloads:** UI/CLI show per-factor contributions (`signal_contributions`), source hashes, and rule gates; exports reuse the same envelope.
|
||||
- **Determinism:** stable ordering (factor type → source → timestamp), UTC ISO-8601 timestamps, fixed precision math, sealed fixtures.
|
||||
|
||||
Interim notes (from legacy doc and sprint context): profiles take normalized factors (exploit likelihood, VEX status, reachability, runtime evidence, fix availability, asset criticality, provenance trust) and output 0–100 scores with severity buckets; same code path for simulation and production to ensure determinism.
|
||||
Profiles use normalized factors (exploit likelihood, KEV flag, reachability, runtime evidence, fix availability, asset criticality, provenance trust) to produce 0–1 scores mapped to severity buckets. Simulation and production share the exact code path.
|
||||
|
||||
## Lifecycle (outline)
|
||||
1. Evidence ingestion (signals, VEX, reachability, runtime)
|
||||
2. Factor normalization
|
||||
3. Profile evaluation
|
||||
4. Severity assignment + gating
|
||||
5. Explainability + observability
|
||||
6. Export/archival paths
|
||||
## Lifecycle
|
||||
1. **Job submit:** POST `/api/v1/risk/jobs` with `tenant_id`, `context_id`, `profile_id`, finding list; request is signed and queued.
|
||||
2. **Evidence ingestion:** scanner surface + reachability graphs, Zastava runtime signals, VEX/KEV feeds, mirror bundles (offline).
|
||||
3. **Normalization:** clamp units to 0–1, apply TTL/decay, dedupe by provenance hash, map to canonical factor catalog.
|
||||
4. **Profile evaluation:** apply weighted sum and overrides; respect gates (e.g., KEV + reachability) and Authority-imposed rules.
|
||||
5. **Severity assignment:** map `normalized_score` to severity levels (critical/high/medium/low/informational) with rationale.
|
||||
6. **Explainability & observability:** emit per-factor contribution table, provenance pointers, evaluation latency metrics; surface via `/risk/jobs/{id}` and export bundles.
|
||||
7. **Export/archival:** package explainability + profile version/hash for Findings Ledger/Export Center; mirror-friendly.
|
||||
|
||||
## Artifacts & Schemas (pending)
|
||||
- Risk profile schema: `<pending PLLG0104>`
|
||||
- Risk factor catalog: shared shapes reused by `factors.md`
|
||||
- Explainability envelope: shared with UI/CLI; add JSON examples once provided.
|
||||
## Artifacts & Schemas
|
||||
- Contract: `CONTRACT-RISK-SCORING-002` (2025-12-05) — risk scoring jobs, results, and profile model.
|
||||
- Profile schema fields: `id`, `version`, `description`, optional `extends`, `signals[] {name, source, type, path, transform, unit}`, `weights{}`, `overrides{severity[], decisions[]}`, `metadata`, `provenance`.
|
||||
- Job/result fields: `job_id`, `profile_hash`, `normalized_score`, `severity`, `signal_values`, `signal_contributions`, optional overrides and timestamps.
|
||||
- Explainability envelope: reuse `signal_contributions` + `profile_hash`; store fixtures under `docs/risk/samples/explain/`.
|
||||
|
||||
## Determinism & Offline Posture
|
||||
- Use frozen fixture sets with SHA256 tables.
|
||||
- Document regeneration steps (no live network calls) once payloads arrive.
|
||||
- Use frozen fixture sets with SHA256 tables; keep manifests in `docs/risk/samples/*/SHA256SUMS`.
|
||||
- Regenerate examples via documented scripts only; no live network calls.
|
||||
- Simulation, API, UI, and export consumers must share the same deterministic ordering and precision.
|
||||
|
||||
## Open Items
|
||||
- PLLG0104 schema approval
|
||||
- Risk engine API payload samples
|
||||
- UI telemetry captures for explainability walkthroughs
|
||||
- Need real payload fixtures (jobs + explainability traces) and UI telemetry captures; placeholders remain in samples folders.
|
||||
|
||||
## References (to link once available)
|
||||
- `docs/risk/profiles.md`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Risk Profiles (draft outline)
|
||||
# Risk Profiles
|
||||
|
||||
> Draft scaffold pending PLLG0104 risk profile schema approval. Do not publish externally until schemas and sample payloads arrive. Mirrors existing `docs/risk/risk-profiles.md`; this file will supersede it once populated.
|
||||
> Contract source: `CONTRACT-RISK-SCORING-002` (published 2025-12-05). This file supersedes `docs/risk/risk-profiles.md` once fixtures are added.
|
||||
|
||||
## Purpose
|
||||
- Define how profiles group factors, weights, thresholds, and severity bands.
|
||||
@@ -10,10 +10,42 @@
|
||||
- Audience: policy authors, risk engineers, platform SREs.
|
||||
- Coverage: profile schema, lifecycle, governance, promotion paths, rollback, and observability hooks.
|
||||
|
||||
## Schema (placeholder)
|
||||
- Profile schema reference: `<pending PLLG0104>`
|
||||
- Required fields: id, versioning, factors list, weights, thresholds, severity mapping, metadata, provenance.
|
||||
- Optional fields: tenant overrides, imposed rules, time-to-live.
|
||||
## Schema (from CONTRACT-RISK-SCORING-002)
|
||||
- Required: `id`, `version`, `description`, `signals[]`, `weights`, `metadata`.
|
||||
- `signals[]` fields: `name`, `source`, `type` (`numeric|boolean|categorical`), `path`, optional `transform`, optional `unit`.
|
||||
- Overrides: `overrides.severity[] { when, set }`, `overrides.decisions[] { when, action, reason }`.
|
||||
- Optional: `extends`, rollout flags, tenant overrides, `valid_from`/`valid_until`.
|
||||
- Storage rules: immutable once promoted; each change creates a new version with DSSE envelope and SHA256 manifest entry (`docs/risk/samples/profiles/SHA256SUMS`).
|
||||
|
||||
### Example Profile (contract snippet)
|
||||
```json
|
||||
{
|
||||
"id": "default-profile",
|
||||
"version": "1.0.0",
|
||||
"description": "Default risk profile for vulnerability prioritization",
|
||||
"extends": "base-profile",
|
||||
"signals": [
|
||||
{ "name": "cvss", "source": "nvd", "type": "numeric", "path": "/cvss/base_score", "transform": "normalize_10", "unit": "score" },
|
||||
{ "name": "kev", "source": "cisa", "type": "boolean", "path": "/kev/in_catalog" },
|
||||
{ "name": "reachability", "source": "scanner", "type": "numeric", "path": "/reachability/score" }
|
||||
],
|
||||
"weights": { "cvss": 0.4, "kev": 0.3, "reachability": 0.3 },
|
||||
"overrides": {
|
||||
"severity": [{ "when": { "kev": true }, "set": "critical" }],
|
||||
"decisions": [{ "when": { "kev": true, "reachability": { "$gt": 0.8 } }, "action": "deny", "reason": "KEV with high reachability" }]
|
||||
},
|
||||
"metadata": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Severity Levels
|
||||
| Level | Value | Priority |
|
||||
| --- | --- | --- |
|
||||
| Critical | `critical` | 1 |
|
||||
| High | `high` | 2 |
|
||||
| Medium | `medium` | 3 |
|
||||
| Low | `low` | 4 |
|
||||
| Informational | `informational` | 5 |
|
||||
|
||||
## Lifecycle (outline)
|
||||
1. Authoring in Policy Studio (draft state)
|
||||
@@ -23,19 +55,20 @@
|
||||
5. Rollback hooks and audit trail
|
||||
|
||||
## Governance & Determinism
|
||||
- Profiles stored with DSSE/signatures; record SHA256 for fixtures.
|
||||
- Same evaluation codepath for simulation and production; note required feature flags.
|
||||
- Offline posture: include profiles and fixtures inside mirror bundles.
|
||||
- Profiles stored with DSSE/signatures; fixtures recorded in `docs/risk/samples/profiles/SHA256SUMS`.
|
||||
- Simulation and production share the same evaluation codepath; feature flags must be documented in `metadata.flags`.
|
||||
- Offline posture: include profiles, fixtures, and explainability bundles inside mirror packages with manifest hashes.
|
||||
|
||||
## Explainability & Observability
|
||||
- Per-factor contribution outputs (JSON) with stable ordering.
|
||||
- Metrics to log: evaluation latency, cache hit ratio, factor coverage.
|
||||
- Dashboards/alerts to enumerate once telemetry payloads are supplied.
|
||||
- Per-factor contribution outputs (JSON) with stable ordering (factor type → source).
|
||||
- Metrics: evaluation latency (p50/p95), cache hit ratio, factor coverage %, profile hit rate, failed provenance validations.
|
||||
- Dashboards/alerts: to be filled when telemetry payloads arrive; reserve panels for gating violations and override usage.
|
||||
|
||||
## Open Items
|
||||
- PLLG0104 schema approval and sample JSON payloads
|
||||
- Feature-flag list for registry alignment
|
||||
- Telemetry field list for dashboards/alerts
|
||||
- Add signed fixtures (profiles + hashes) under `docs/risk/samples/profiles/` once payloads arrive.
|
||||
- Capture feature-flag list for registry alignment.
|
||||
- Telemetry field list for dashboards/alerts.
|
||||
- Finalize migration note when legacy `docs/risk/risk-profiles.md` is archived.
|
||||
|
||||
## References
|
||||
- `docs/risk/overview.md`
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
9408221415b389f6dad1c235de160e88721555b406ab0e2bdbfa3119c6696a4d README.md
|
||||
96926cd81dfb6ff02d62d1fde5d7b2b7b5b3950e50eb651e51b8ae3042ac9506 risk-api-samples.json
|
||||
|
||||
61
docs/risk/samples/api/risk-api-samples.json
Normal file
61
docs/risk/samples/api/risk-api-samples.json
Normal file
@@ -0,0 +1,61 @@
|
||||
{
|
||||
"submit_job_request": {
|
||||
"method": "POST",
|
||||
"path": "/api/v1/risk/jobs",
|
||||
"headers": {
|
||||
"Content-Type": "application/json",
|
||||
"X-Stella-Tenant": "tenant-default"
|
||||
},
|
||||
"body": {
|
||||
"tenant_id": "tenant-default",
|
||||
"context_id": "ctx-001",
|
||||
"profile_id": "default-profile",
|
||||
"findings": [
|
||||
{
|
||||
"finding_id": "finding-123",
|
||||
"component_purl": "pkg:npm/lodash@4.17.20",
|
||||
"advisory_id": "CVE-2024-1234",
|
||||
"trigger": "created"
|
||||
}
|
||||
],
|
||||
"priority": "normal",
|
||||
"requested_at": "2025-12-05T00:00:00Z"
|
||||
},
|
||||
"response": {
|
||||
"status": 202,
|
||||
"body": {"job_id": "job-001", "status": "queued"}
|
||||
}
|
||||
},
|
||||
"get_job_status": {
|
||||
"method": "GET",
|
||||
"path": "/api/v1/risk/jobs/job-001",
|
||||
"response": {
|
||||
"status": 200,
|
||||
"body": {
|
||||
"job_id": "job-001",
|
||||
"status": "completed",
|
||||
"results": [
|
||||
{
|
||||
"finding_id": "finding-123",
|
||||
"profile_id": "default-profile",
|
||||
"profile_version": "1.0.0",
|
||||
"raw_score": 0.75,
|
||||
"normalized_score": 0.85,
|
||||
"severity": "high",
|
||||
"signal_values": {"cvss": 7.5, "kev": true, "reachability": 0.9},
|
||||
"signal_contributions": {"cvss": 0.4, "kev": 0.3, "reachability": 0.3},
|
||||
"scored_at": "2025-12-05T00:00:02Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"get_explain": {
|
||||
"method": "GET",
|
||||
"path": "/api/v1/risk/explain/job-001",
|
||||
"response": {
|
||||
"status": 200,
|
||||
"body_ref": "../explain/explain-trace.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
30a64dcc9fb41d06774a9c125456c212a29915a083cd1d2170f16f343bd0764f README.md
|
||||
1d2e56eebf0a266f80519f073e1db532c4a4f2d7fa604ea5c05d4e208719cc7c explain-trace.json
|
||||
|
||||
34
docs/risk/samples/explain/explain-trace.json
Normal file
34
docs/risk/samples/explain/explain-trace.json
Normal file
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"job_id": "job-001",
|
||||
"tenant_id": "tenant-default",
|
||||
"context_id": "ctx-001",
|
||||
"profile_id": "default-profile",
|
||||
"profile_version": "1.0.0",
|
||||
"profile_hash": "sha256:profilehash",
|
||||
"finding_id": "finding-123",
|
||||
"raw_score": 0.75,
|
||||
"normalized_score": 0.85,
|
||||
"severity": "high",
|
||||
"signal_values": {
|
||||
"cvss": 7.5,
|
||||
"kev": true,
|
||||
"reachability": 0.9
|
||||
},
|
||||
"signal_contributions": {
|
||||
"cvss": 0.4,
|
||||
"kev": 0.3,
|
||||
"reachability": 0.3
|
||||
},
|
||||
"override_applied": "kev-boost",
|
||||
"override_reason": "Known Exploited Vulnerability",
|
||||
"gates_triggered": ["kev_and_reachability"],
|
||||
"scored_at": "2025-12-05T00:00:02Z",
|
||||
"provenance": {
|
||||
"job_hash": "sha256:jobhash",
|
||||
"fixtures": [
|
||||
"sha256:cvsshash",
|
||||
"sha256:kevhash",
|
||||
"sha256:reachhash"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
5b7eee78aed1ee13378737c35cd2b5e91aa4abbbd0e70029219d5e357b40ab1f README.md
|
||||
13cf45be5a287a38d000aff4db266616e765fc1acdc1df9f37b2e03eb729d1d2 factors-normalized.json
|
||||
|
||||
44
docs/risk/samples/factors/factors-normalized.json
Normal file
44
docs/risk/samples/factors/factors-normalized.json
Normal file
@@ -0,0 +1,44 @@
|
||||
{
|
||||
"profile_id": "default-profile",
|
||||
"context_id": "ctx-001",
|
||||
"factors": [
|
||||
{
|
||||
"name": "cvss",
|
||||
"source": "nvd",
|
||||
"type": "numeric",
|
||||
"path": "/cvss/base_score",
|
||||
"raw_value": 7.5,
|
||||
"normalized_value": 0.75,
|
||||
"weight": 0.4,
|
||||
"contribution": 0.4,
|
||||
"timestamp_utc": "2025-12-05T00:00:00Z",
|
||||
"provenance": "sha256:cvsshash"
|
||||
},
|
||||
{
|
||||
"name": "kev",
|
||||
"source": "cisa",
|
||||
"type": "boolean",
|
||||
"path": "/kev/in_catalog",
|
||||
"raw_value": true,
|
||||
"normalized_value": 1.0,
|
||||
"weight": 0.3,
|
||||
"contribution": 0.3,
|
||||
"timestamp_utc": "2025-12-05T00:00:00Z",
|
||||
"provenance": "sha256:kevhash"
|
||||
},
|
||||
{
|
||||
"name": "reachability",
|
||||
"source": "scanner",
|
||||
"type": "numeric",
|
||||
"path": "/reachability/score",
|
||||
"raw_value": 0.9,
|
||||
"normalized_value": 0.9,
|
||||
"weight": 0.3,
|
||||
"contribution": 0.3,
|
||||
"timestamp_utc": "2025-12-05T00:00:01Z",
|
||||
"provenance": "sha256:reachhash"
|
||||
}
|
||||
],
|
||||
"ordering": "factor_type->source->timestamp_utc",
|
||||
"precision": 4
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
e9d2913ad6fe38423ffeea7b5a33f6e15a59d93784200d0686a9b26a80dd3885 README.md
|
||||
c8242d4051232152d024dd37324b346dcf019a5e46b7b82fae8349ad802affab default-profile.json
|
||||
|
||||
18
docs/risk/samples/profiles/default-profile.json
Normal file
18
docs/risk/samples/profiles/default-profile.json
Normal file
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"id": "default-profile",
|
||||
"version": "1.0.0",
|
||||
"description": "Default risk profile for vulnerability prioritization",
|
||||
"extends": "base-profile",
|
||||
"signals": [
|
||||
{ "name": "cvss", "source": "nvd", "type": "numeric", "path": "/cvss/base_score", "transform": "normalize_10", "unit": "score" },
|
||||
{ "name": "kev", "source": "cisa", "type": "boolean", "path": "/kev/in_catalog" },
|
||||
{ "name": "reachability", "source": "scanner", "type": "numeric", "path": "/reachability/score", "unit": "score" }
|
||||
],
|
||||
"weights": { "cvss": 0.4, "kev": 0.3, "reachability": 0.3 },
|
||||
"overrides": {
|
||||
"severity": [ { "when": { "kev": true }, "set": "critical" } ],
|
||||
"decisions": [ { "when": { "kev": true, "reachability": { "$gt": 0.8 } }, "action": "deny", "reason": "KEV with high reachability" } ]
|
||||
},
|
||||
"metadata": { "author": "docs-guild", "created_at": "2025-12-05T00:00:00Z" },
|
||||
"provenance": { "hash": "sha256:placeholder", "signed": false }
|
||||
}
|
||||
Reference in New Issue
Block a user