stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

up
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-24 07:52:25 +02:00
parent 5970f0d9bd
commit 150b3730ef
215 changed files with 8119 additions and 740 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/modules/policy/architecture.md
View File

@@ -208,8 +208,17 @@ All payloads are immutable and include analyzer fingerprints (`scanner.native@sh
- **Scopes:** Mutations require `policy:*` scopes corresponding to action; `effective:write` restricted to service identity.
- **Tenancy:** All queries filter by `tenant`. Service identity uses `tenant-global` for shared policies; cross-tenant reads prohibited unless `policy:tenant-admin` scope present.
- **Secrets:** Configuration loaded via environment variables or sealed secrets; runtime avoids writing secrets to logs.
- **Determinism guard:** Static analyzer prevents referencing forbidden namespaces; runtime guard intercepts `DateTime.Now`, `Random`, `Guid`, HTTP clients beyond allow-list.
- **Sealed mode:** Global flag disables outbound network except allow-listed internal hosts; watchers fail fast if unexpected egress attempted.
- **Determinism guard:** Static analyzer prevents referencing forbidden namespaces; runtime guard intercepts `DateTime.Now`, `Random`, `Guid`, HTTP clients beyond allow-list.
- **Sealed mode:** Global flag disables outbound network except allow-listed internal hosts; watchers fail fast if unexpected egress attempted.
### Determinism enforcement (DOCS-POLICY-DET-01)
- **Inputs are ordered and frozen:** Selector emits batches sorted deterministically by `(tenant, policyId, vulnerabilityId, productKey, source)` with stable cursors; workers must not resort.
- **No ambient randomness or wall clocks:** Policy code relies on injected `TimeProvider`/`IRandom` shims; guards block `DateTime.Now`, `Guid.NewGuid`, `Random` when not injected.
- **Immutable evidence:** SBOM/VEX inputs carry content hashes; evaluator treats payloads as read-only and surfaces hashes in logs for replay.
- **Side effects prohibited:** Evaluator cannot call external HTTP except allow-listed internal services (Authority, Storage) and must not write files outside temp workspace.
- **Replay hash:** Each batch computes `determinismHash = SHA256(policyVersion + batchCursor + inputsHash)`; included in logs and run exports.
- **Testing:** Determinism tests run the same batch twice with seeded clock/GUID providers and assert identical outputs + determinismHash; add a test per policy package.
---

29
docs/modules/policy/samples/advisory-ai-knobs@draft.json Normal file
View File

@@ -0,0 +1,29 @@
{
"knobs": [
{
"name": "ai_signal_weight",
"default_value": 1.2,
"min": 0.0,
"max": 2.0,
"step": 0.1,
"description": "Weight applied to Advisory AI signal scores"
},
{
"name": "reachability_boost",
"default_value": 0.25,
"min": 0.0,
"max": 1.0,
"step": 0.05,
"description": "Boost when asset is reachable"
},
{
"name": "time_decay_half_life_days",
"default_value": 45,
"min": 1,
"max": 365,
"step": 1,
"description": "Half-life in days for signal decay"
}
],
"profile_hash": "ADVISORYAIHASH"
}

16
docs/modules/policy/samples/orchestrator-job@draft.json Normal file
View File

@@ -0,0 +1,16 @@
{
"job_id": "01HZX1QJP6Z3MNA0Q2T3VCPV5K",
"tenant_id": "acme",
"context_id": "ctx-2025-11-24T10:00:00Z",
"policy_profile_hash": "overlay-hash-123",
"priority": "high",
"requested_at": "2025-11-24T10:00:00Z",
"status": "queued",
"trace_ref": "4E5C2B5E22F928E846B0EFBC58AA53FC3218C8C172199FF52C7C09244E0C0D30",
"determinism_hash": "2C855E80F66D30D5E51C4D9A0441A63C5BB8F04DC1EC537D0ADB7B9357A4C713",
"batch_items": [
{ "component_purl": "pkg:npm/alpha@1.0.0", "advisory_id": "ADV-1" },
{ "component_purl": "pkg:npm/zeta@1.0.0", "advisory_id": "ADV-2" }
],
"callbacks": { "sse": "sse://events", "nats": "policy.jobs" }
}

11
docs/modules/policy/samples/policy-batch-context@draft.json Normal file
View File

@@ -0,0 +1,11 @@
{
"tenant_id": "acme",
"policy_profile_hash": "overlay-hash-123",
"knobs_version": "knobs-v1",
"overlay_hash": "overlay-hash-123",
"items": [
{ "component_purl": "pkg:npm/lodash@4.17.21", "advisory_id": "ADV-2025-0001" },
{ "component_purl": "pkg:npm/left-pad@1.3.0", "advisory_id": "ADV-2025-0002" }
],
"options": { "include_reachability": true }
}

32
docs/modules/policy/samples/policy-conflict@draft.json Normal file
View File

@@ -0,0 +1,32 @@
{
"tenant_id": "acme",
"component_purl": "pkg:npm/alpha@1.0.0",
"advisory_id": "ADV-1",
"conflicts": [
{
"tenant_id": "acme",
"snapshot_id": "01HZX3GN4V6KBW1PXJ0K3VXEGT",
"component_purl": "pkg:npm/alpha@1.0.0",
"advisory_id": "ADV-1",
"severity_fused": "high",
"score": 0.900,
"sources": [
{ "source": "policy-engine", "weight": 1.050, "severity": "high", "score": 0.945 }
],
"reason_codes": ["weights-applied", "deterministic-fusion"]
},
{
"tenant_id": "acme",
"snapshot_id": "01HZX3GN4V6KBW1PXJ0K3VXEGT",
"component_purl": "pkg:npm/alpha@1.0.0",
"advisory_id": "ADV-1",
"severity_fused": "medium",
"score": 0.600,
"sources": [
{ "source": "policy-engine", "weight": 1.050, "severity": "medium", "score": 0.630 }
],
"reason_codes": ["weights-applied", "deterministic-fusion"]
}
],
"resolved_status": null
}

36
docs/modules/policy/samples/policy-ledger-export@draft.json Normal file
View File

@@ -0,0 +1,36 @@
{
"manifest": {
"export_id": "01HZX2KDRT9Q9K5AZXWPRH62VE",
"schema_version": "policy-ledger-export-v1",
"generated_at": "2025-11-24T15:00:00Z",
"record_count": 2,
"sha256": "D4B8C98A2F946D93AFBDE6C4DE6535853A223E108A4A2C389E2C2623D3761C1E"
},
"records": [
{
"tenant_id": "acme",
"job_id": "job-1",
"context_id": "ctx",
"component_purl": "pkg:npm/alpha@1.0.0",
"advisory_id": "ADV-1",
"status": "violation",
"trace_ref": "trace-a",
"occurred_at": "2025-11-24T15:00:00Z"
},
{
"tenant_id": "acme",
"job_id": "job-1",
"context_id": "ctx",
"component_purl": "pkg:npm/zeta@1.0.0",
"advisory_id": "ADV-2",
"status": "ok",
"trace_ref": "trace-b",
"occurred_at": "2025-11-24T15:00:00Z"
}
],
"lines": [
"{\"export_id\":\"01HZX2KDRT9Q9K5AZXWPRH62VE\",\"schema_version\":\"policy-ledger-export-v1\",\"generated_at\":\"2025-11-24T15:00:00Z\",\"record_count\":2,\"sha256\":\"D4B8C98A2F946D93AFBDE6C4DE6535853A223E108A4A2C389E2C2623D3761C1E\"}",
"{\"tenant_id\":\"acme\",\"job_id\":\"job-1\",\"context_id\":\"ctx\",\"component_purl\":\"pkg:npm/alpha@1.0.0\",\"advisory_id\":\"ADV-1\",\"status\":\"violation\",\"trace_ref\":\"trace-a\",\"occurred_at\":\"2025-11-24T15:00:00Z\"}",
"{\"tenant_id\":\"acme\",\"job_id\":\"job-1\",\"context_id\":\"ctx\",\"component_purl\":\"pkg:npm/zeta@1.0.0\",\"advisory_id\":\"ADV-2\",\"status\":\"ok\",\"trace_ref\":\"trace-b\",\"occurred_at\":\"2025-11-24T15:00:00Z\"}"
]
}

30
docs/modules/policy/samples/policy-snapshot@draft.json Normal file
View File

@@ -0,0 +1,30 @@
{
"snapshot_id": "01HZX3GN4V6KBW1PXJ0K3VXEGT",
"tenant_id": "acme",
"ledger_export_id": "01HZX2KDRT9Q9K5AZXWPRH62VE",
"generated_at": "2025-11-24T16:00:00Z",
"overlay_hash": "overlay-1",
"status_counts": { "violation": 1, "ok": 1 },
"records": [
{
"tenant_id": "acme",
"job_id": "job-1",
"context_id": "ctx",
"component_purl": "pkg:npm/alpha@1.0.0",
"advisory_id": "ADV-1",
"status": "violation",
"trace_ref": "trace-a",
"occurred_at": "2025-11-24T15:00:00Z"
},
{
"tenant_id": "acme",
"job_id": "job-1",
"context_id": "ctx",
"component_purl": "pkg:npm/zeta@1.0.0",
"advisory_id": "ADV-2",
"status": "ok",
"trace_ref": "trace-b",
"occurred_at": "2025-11-24T15:00:00Z"
}
]
}

13
docs/modules/policy/samples/policy-violation-event@draft.json Normal file
View File

@@ -0,0 +1,13 @@
{
"event_id": "E7A1F3B0D6F243B4868A6D4B3E7B2AB9",
"tenant_id": "acme",
"snapshot_id": "01HZX3GN4V6KBW1PXJ0K3VXEGT",
"policy_profile_hash": "overlay-hash-123",
"component_purl": "pkg:npm/alpha@1.0.0",
"advisory_id": "ADV-1",
"violation_code": "policy.violation.detected",
"severity": "high",
"status": "violation",
"trace_ref": "trace-a",
"occurred_at": "2025-11-24T16:00:00Z"
}

11
docs/modules/policy/samples/policy-worker-result@draft.json Normal file
View File

@@ -0,0 +1,11 @@
{
"job_id": "01HZX1QJP6Z3MNA0Q2T3VCPV5K",
"worker_id": "worker-stub",
"started_at": "2025-11-24T13:00:00Z",
"completed_at": "2025-11-24T13:00:01Z",
"result_hash": "5E5A4EFA8C7E9952E4E5E5D9E2B9F3A5D46B13E44CB6E0D7292F7D5CB40CF182",
"results": [
{ "component_purl": "pkg:npm/alpha@1.0.0", "advisory_id": "ADV-1", "status": "violation", "trace_ref": "F5D9B8717EAB4B0252BE22325771C4F9F8ABAE4E7728F3221E15C5F24A8E8D9F" },
{ "component_purl": "pkg:npm/zeta@1.0.0", "advisory_id": "ADV-2", "status": "ok", "trace_ref": "3C75CC86A30B6E230D1DE2D5F08F9B0F5CF75AB1931E47372DC7AC2175BE3F6C" }
]
}

12
docs/modules/policy/samples/severity-fusion@draft.json Normal file
View File

@@ -0,0 +1,12 @@
{
"tenant_id": "acme",
"snapshot_id": "01HZX3GN4V6KBW1PXJ0K3VXEGT",
"component_purl": "pkg:npm/alpha@1.0.0",
"advisory_id": "ADV-1",
"severity_fused": "high",
"score": 0.900,
"sources": [
{ "source": "policy-engine", "weight": 1.050, "severity": "high", "score": 0.945 }
],
"reason_codes": ["weights-applied", "deterministic-fusion"]
}

23
docs/modules/policy/samples/trust-weighting@draft.json Normal file
View File

@@ -0,0 +1,23 @@
{
"weights": [
{
"source": "cartographer",
"weight": 1.000,
"justification": "default baseline",
"updated_at": "2025-11-23T12:00:00Z"
},
{
"source": "scanner",
"weight": 0.950,
"justification": "prefer curated SBOM sources",
"updated_at": "2025-11-23T12:00:00Z"
},
{
"source": "concelier",
"weight": 1.050,
"justification": "policy engine override",
"updated_at": "2025-11-23T12:00:00Z"
}
],
"profile_hash": "D1A5F0A0DEFAULTHASH"
}

27
docs/modules/policy/schemas/advisory-ai-knobs@draft.json Normal file
View File

@@ -0,0 +1,27 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "advisory-ai-knobs@draft",
"type": "object",
"properties": {
"knobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"default_value": { "type": "number" },
"min": { "type": "number" },
"max": { "type": "number" },
"step": { "type": "number" },
"description": { "type": "string" }
},
"required": ["name", "default_value", "min", "max", "step", "description"],
"additionalProperties": false
},
"minItems": 1
},
"profile_hash": { "type": "string", "minLength": 1 }
},
"required": ["knobs", "profile_hash"],
"additionalProperties": false
}

51
docs/modules/policy/schemas/orchestrator-job@draft.json Normal file
View File

@@ -0,0 +1,51 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "orchestrator-job@draft",
"type": "object",
"properties": {
"job_id": { "type": "string", "minLength": 1 },
"tenant_id": { "type": "string", "minLength": 1 },
"context_id": { "type": "string", "minLength": 1 },
"policy_profile_hash": { "type": "string", "minLength": 1 },
"priority": { "type": "string", "enum": ["normal", "high", "emergency", "preview"] },
"requested_at": { "type": "string", "format": "date-time" },
"status": { "type": "string", "minLength": 1 },
"trace_ref": { "type": "string", "minLength": 1 },
"determinism_hash": { "type": "string", "minLength": 1 },
"completed_at": { "type": ["string", "null"], "format": "date-time" },
"result_hash": { "type": ["string", "null"] },
"batch_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"component_purl": { "type": "string", "minLength": 1 },
"advisory_id": { "type": "string", "minLength": 1 }
},
"required": ["component_purl", "advisory_id"],
"additionalProperties": false
},
"minItems": 1
},
"callbacks": {
"type": ["object", "null"],
"properties": {
"sse": { "type": ["string", "null"] },
"nats": { "type": ["string", "null"] }
},
"additionalProperties": false
}
},
"required": [
"job_id",
"tenant_id",
"context_id",
"policy_profile_hash",
"priority",
"requested_at",
"status",
"determinism_hash",
"batch_items"
],
"additionalProperties": false
}

41
docs/modules/policy/schemas/policy-batch-context@draft.json Normal file
View File

@@ -0,0 +1,41 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "policy-batch-context@draft",
"type": "object",
"properties": {
"tenant_id": { "type": "string", "minLength": 1 },
"policy_profile_hash": { "type": "string", "minLength": 1 },
"knobs_version": { "type": "string", "minLength": 1 },
"overlay_hash": { "type": "string", "minLength": 1 },
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"component_purl": { "type": "string", "minLength": 1 },
"advisory_id": { "type": "string", "minLength": 1 }
},
"required": ["component_purl", "advisory_id"],
"additionalProperties": false
},
"minItems": 1
},
"options": {
"type": "object",
"properties": {
"include_reachability": { "type": "boolean" }
},
"required": ["include_reachability"],
"additionalProperties": false
}
},
"required": [
"tenant_id",
"policy_profile_hash",
"knobs_version",
"overlay_hash",
"items",
"options"
],
"additionalProperties": false
}

17
docs/modules/policy/schemas/policy-conflict@draft.json Normal file
View File

@@ -0,0 +1,17 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "policy-conflict@draft",
"type": "object",
"properties": {
"tenant_id": { "type": "string", "minLength": 1 },
"component_purl": { "type": "string", "minLength": 1 },
"advisory_id": { "type": "string", "minLength": 1 },
"conflicts": {
"type": "array",
"items": { "$ref": "severity-fusion@draft.json" }
},
"resolved_status": { "type": ["string", "null"] }
},
"required": ["tenant_id", "component_purl", "advisory_id", "conflicts"],
"additionalProperties": false
}

40
docs/modules/policy/schemas/policy-ledger-export@draft.json Normal file
View File

@@ -0,0 +1,40 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "policy-ledger-export@draft",
"type": "object",
"properties": {
"manifest": {
"type": "object",
"properties": {
"export_id": { "type": "string", "minLength": 1 },
"schema_version": { "type": "string", "minLength": 1 },
"generated_at": { "type": "string", "format": "date-time" },
"record_count": { "type": "integer", "minimum": 0 },
"sha256": { "type": "string", "minLength": 1 }
},
"required": ["export_id", "schema_version", "generated_at", "record_count", "sha256"],
"additionalProperties": false
},
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenant_id": { "type": "string", "minLength": 1 },
"job_id": { "type": "string", "minLength": 1 },
"context_id": { "type": "string", "minLength": 1 },
"component_purl": { "type": "string", "minLength": 1 },
"advisory_id": { "type": "string", "minLength": 1 },
"status": { "type": "string", "minLength": 1 },
"trace_ref": { "type": "string", "minLength": 1 },
"occurred_at": { "type": "string", "format": "date-time" }
},
"required": ["tenant_id", "job_id", "context_id", "component_purl", "advisory_id", "status", "trace_ref", "occurred_at"],
"additionalProperties": false
}
},
"lines": { "type": "array", "items": { "type": "string" } }
},
"required": ["manifest", "records", "lines"],
"additionalProperties": false
}

33
docs/modules/policy/schemas/policy-snapshot@draft.json Normal file
View File

@@ -0,0 +1,33 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "policy-snapshot@draft",
"type": "object",
"properties": {
"snapshot_id": { "type": "string", "minLength": 1 },
"tenant_id": { "type": "string", "minLength": 1 },
"ledger_export_id": { "type": "string", "minLength": 1 },
"generated_at": { "type": "string", "format": "date-time" },
"overlay_hash": { "type": "string", "minLength": 1 },
"status_counts": { "type": "object", "additionalProperties": { "type": "integer" } },
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenant_id": { "type": "string" },
"job_id": { "type": "string" },
"context_id": { "type": "string" },
"component_purl": { "type": "string" },
"advisory_id": { "type": "string" },
"status": { "type": "string" },
"trace_ref": { "type": "string" },
"occurred_at": { "type": "string", "format": "date-time" }
},
"required": ["tenant_id", "job_id", "context_id", "component_purl", "advisory_id", "status", "trace_ref", "occurred_at"],
"additionalProperties": false
}
}
},
"required": ["snapshot_id", "tenant_id", "ledger_export_id", "generated_at", "overlay_hash", "status_counts", "records"],
"additionalProperties": false
}

32
docs/modules/policy/schemas/policy-violation-event@draft.json Normal file
View File

@@ -0,0 +1,32 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "policy-violation-event@draft",
"type": "object",
"properties": {
"event_id": { "type": "string", "minLength": 1 },
"tenant_id": { "type": "string", "minLength": 1 },
"snapshot_id": { "type": "string", "minLength": 1 },
"policy_profile_hash": { "type": "string", "minLength": 1 },
"component_purl": { "type": "string", "minLength": 1 },
"advisory_id": { "type": "string", "minLength": 1 },
"violation_code": { "type": "string", "minLength": 1 },
"severity": { "type": "string", "minLength": 1 },
"status": { "type": "string", "minLength": 1 },
"trace_ref": { "type": "string", "minLength": 1 },
"occurred_at": { "type": "string", "format": "date-time" }
},
"required": [
"event_id",
"tenant_id",
"snapshot_id",
"policy_profile_hash",
"component_purl",
"advisory_id",
"violation_code",
"severity",
"status",
"trace_ref",
"occurred_at"
],
"additionalProperties": false
}

29
docs/modules/policy/schemas/policy-worker-result@draft.json Normal file
View File

@@ -0,0 +1,29 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "policy-worker-result@draft",
"type": "object",
"properties": {
"job_id": { "type": "string", "minLength": 1 },
"worker_id": { "type": "string", "minLength": 1 },
"started_at": { "type": "string", "format": "date-time" },
"completed_at": { "type": "string", "format": "date-time" },
"result_hash": { "type": "string", "minLength": 1 },
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"component_purl": { "type": "string", "minLength": 1 },
"advisory_id": { "type": "string", "minLength": 1 },
"status": { "type": "string", "minLength": 1 },
"trace_ref": { "type": "string", "minLength": 1 }
},
"required": ["component_purl", "advisory_id", "status", "trace_ref"],
"additionalProperties": false
},
"minItems": 1
}
},
"required": ["job_id", "worker_id", "started_at", "completed_at", "result_hash", "results"],
"additionalProperties": false
}

30
docs/modules/policy/schemas/severity-fusion@draft.json Normal file
View File

@@ -0,0 +1,30 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "severity-fusion@draft",
"type": "object",
"properties": {
"tenant_id": { "type": "string", "minLength": 1 },
"snapshot_id": { "type": "string", "minLength": 1 },
"component_purl": { "type": "string", "minLength": 1 },
"advisory_id": { "type": "string", "minLength": 1 },
"severity_fused": { "type": "string", "minLength": 1 },
"score": { "type": "number" },
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": { "type": "string", "minLength": 1 },
"weight": { "type": "number" },
"severity": { "type": "string", "minLength": 1 },
"score": { "type": "number" }
},
"required": ["source", "weight", "severity", "score"],
"additionalProperties": false
}
},
"reason_codes": { "type": "array", "items": { "type": "string" } }
},
"required": ["tenant_id", "snapshot_id", "component_purl", "advisory_id", "severity_fused", "score", "sources", "reason_codes"],
"additionalProperties": false
}

25
docs/modules/policy/schemas/trust-weighting@draft.json Normal file
View File

@@ -0,0 +1,25 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "trust-weighting@draft",
"type": "object",
"properties": {
"weights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": { "type": "string", "minLength": 1 },
"weight": { "type": "number" },
"justification": { "type": ["string", "null"] },
"updated_at": { "type": "string", "format": "date-time" }
},
"required": ["source", "weight", "updated_at"],
"additionalProperties": false
},
"minItems": 1
},
"profile_hash": { "type": "string", "minLength": 1 }
},
"required": ["weights", "profile_hash"],
"additionalProperties": false
}