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

docs consolidation and others

Browse Source
This commit is contained in:
master
2026-01-06 19:02:21 +02:00
parent d7bdca6d97
commit 4789027317
849 changed files with 16551 additions and 66770 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/modules/risk-engine/samples/INGEST_CHECKLIST.md Normal file
View File

@@ -0,0 +1,8 @@
# Risk Samples Ingest Checklist (use when payloads arrive)
1) Drop payloads into the correct folder (`profiles/`, `factors/`, `explain/`, `api/`).
2) Normalize JSON deterministically (e.g., `jq -S .`) before hashing; keep UTC timestamps.
3) Run `sha256sum * > SHA256SUMS` in the target folder; keep file sorted.
4) Verify hashes: `sha256sum -c SHA256SUMS`.
5) Add a short README snippet in the sprint Execution Log noting files added and hashes updated.
6) Keep fixtures offline-only; no external calls or redactions after hashing.

26
docs/modules/risk-engine/samples/README.md Normal file
View File

@@ -0,0 +1,26 @@
# Risk Samples (fixtures layout)
Use this folder for frozen, deterministic fixtures once schemas and payloads arrive.
Structure (proposed):
- `profiles/` — profile JSON (DSSE-wrapped where applicable) + `SHA256SUMS`
- `factors/` — factor input payloads grouped by source (epss/, kev/, reachability/, runtime/), each with `SHA256SUMS`
- `explain/` — explainability outputs paired with inputs; include `SHA256SUMS`
- `api/` — request/response examples for risk endpoints; include `SHA256SUMS`
Rules:
- UTC timestamps; stable ordering of arrays/objects.
- No live calls; fixtures only.
- Record hashes via `sha256sum` and keep manifests alongside samples.
Quick receipt checklist (see `INGEST_CHECKLIST.md` for detail):
1) Normalize JSON with `jq -S .`
2) Update `SHA256SUMS` in the target folder
3) Verify with `sha256sum -c`
4) Log files + hashes in the sprint Execution Log
Manifests created:
- `profiles/SHA256SUMS`
- `factors/SHA256SUMS`
- `explain/SHA256SUMS`
- `api/SHA256SUMS`

3
docs/modules/risk-engine/samples/api/README.md Normal file
View File

@@ -0,0 +1,3 @@
Use the root `INGEST_CHECKLIST.md`.
Place request/response examples here; normalize with `jq -S .`, update `SHA256SUMS`, verify with `sha256sum -c`.
Include required headers; redact secrets; UTC timestamps only.

3
docs/modules/risk-engine/samples/api/SHA256SUMS Normal file
View File

@@ -0,0 +1,3 @@
fe460af2699ce335199f6e26597bab4530c6f3f476d4b1f93526175597565d10 README.md
00f8dc4e466eb95c06545e6336d7b0866b53ac430335b7fd1b7889da13529b93 error-catalog.json
96926cd81dfb6ff02d62d1fde5d7b2b7b5b3950e50eb651e51b8ae3042ac9506 risk-api-samples.json

13
docs/modules/risk-engine/samples/api/error-catalog.json Normal file
View File

@@ -0,0 +1,13 @@
{
"errors": [
{"code": "risk.job.not_found", "message": "Risk job not found", "http_status": 404, "remediation": "Verify job_id"},
{"code": "risk.profile.invalid_signature", "message": "Profile DSSE signature failed", "http_status": 400, "remediation": "Re-sign profile and retry"},
{"code": "risk.job.rate_limited", "message": "Rate limit exceeded", "http_status": 429, "remediation": "Retry after backoff", "retry_after": 5},
{"code": "risk.tenant.scope_denied", "message": "Tenant scope not authorized", "http_status": 403, "remediation": "Provide required scope header"}
],
"headers": {
"etag": "\"risk-api-sample-etag\"",
"x-ratelimit-remaining": 99,
"retry-after": 5
}
}

61
docs/modules/risk-engine/samples/api/risk-api-samples.json Normal file
View 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"
}
}
}

3
docs/modules/risk-engine/samples/explain/README.md Normal file
View File

@@ -0,0 +1,3 @@
Use the root `INGEST_CHECKLIST.md`.
Store explainability outputs paired with their inputs; normalize with `jq -S .`, update `SHA256SUMS`, verify with `sha256sum -c`.
Maintain ordering and UTC timestamps; no live data.

4
docs/modules/risk-engine/samples/explain/SHA256SUMS Normal file
View File

@@ -0,0 +1,4 @@
fe460af2699ce335199f6e26597bab4530c6f3f476d4b1f93526175597565d10 README.md
abcacb431d35d649a0deae81aecce9996b28304da6342a083f9616af6b1ca6a2 cli-explain.txt
f3f1b41f5261f50f3fc104ebeeb2649cc9866d04f9634228778551e6c3364cb8 console-frame.json
1d2e56eebf0a266f80519f073e1db532c4a4f2d7fa604ea5c05d4e208719cc7c explain-trace.json

15
docs/modules/risk-engine/samples/explain/cli-explain.txt Normal file
View File

@@ -0,0 +1,15 @@
stella risk explain job-001 --tenant tenant-default
==================================================
Finding: finding-123
Profile: default-profile v1.0.0 (hash sha256:profilehash)
Score: 0.85 (HIGH)
Gates: kev_and_reachability
Contributions (ordered)
- cvss 0.40 raw=7.5 source=nvd prov=sha256:cvsshash
- kev 0.30 raw=true source=cisa prov=sha256:kevhash
- reachability 0.30 raw=0.9 source=scanner prov=sha256:reachhash
Overrides: kev-boost (Known Exploited Vulnerability)
Provenance: job sha256:jobhash | fixtures [sha256:cvsshash, sha256:kevhash, sha256:reachhash]
Timestamp: 2025-12-05T00:00:02Z

22
docs/modules/risk-engine/samples/explain/console-frame.json Normal file
View File

@@ -0,0 +1,22 @@
{
"frame_id": "console-explain-001",
"captured_at": "2025-12-05T00:05:00Z",
"ui_version": "1.0.0",
"tenant_id": "tenant-default",
"finding_id": "finding-123",
"profile_id": "default-profile",
"profile_hash": "sha256:profilehash",
"score": 0.85,
"severity": "high",
"gates": ["kev_and_reachability"],
"top_contributors": [
{"factor": "cvss", "contribution": 0.4, "raw": 7.5, "source": "nvd", "provenance": "sha256:cvsshash"},
{"factor": "kev", "contribution": 0.3, "raw": true, "source": "cisa", "provenance": "sha256:kevhash"},
{"factor": "reachability", "contribution": 0.3, "raw": 0.9, "source": "scanner", "provenance": "sha256:reachhash"}
],
"charts": {
"donut": {"critical": 0, "high": 1, "medium": 0, "low": 0, "informational": 0},
"stacked": [0.4, 0.3, 0.3]
},
"provenance": {"job_hash": "sha256:jobhash", "fixtures": ["sha256:cvsshash", "sha256:kevhash", "sha256:reachhash"]}
}

34
docs/modules/risk-engine/samples/explain/explain-trace.json Normal file
View 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"
]
}
}

3
docs/modules/risk-engine/samples/factors/README.md Normal file
View File

@@ -0,0 +1,3 @@
Use the root `INGEST_CHECKLIST.md`.
Drop factor payloads by source (epss/, kev/, reachability/, runtime/), normalize with `jq -S .`, update `SHA256SUMS`, verify with `sha256sum -c`.
Keep UTC timestamps and no live data.

2
docs/modules/risk-engine/samples/factors/SHA256SUMS Normal file
View File

@@ -0,0 +1,2 @@
fe460af2699ce335199f6e26597bab4530c6f3f476d4b1f93526175597565d10 README.md
13cf45be5a287a38d000aff4db266616e765fc1acdc1df9f37b2e03eb729d1d2 factors-normalized.json

44
docs/modules/risk-engine/samples/factors/factors-normalized.json Normal file
View 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
}

8
docs/modules/risk-engine/samples/intake-log-template.md Normal file
View File

@@ -0,0 +1,8 @@
| Date (UTC) | Folder | Files added | SHA256SUMS updated | Notes |
| --- | --- | --- | --- | --- |
| 2025-__-__ | profiles/ | | yes/no | source + checklist step refs |
| 2025-__-__ | factors/ | | yes/no | source + checklist step refs |
| 2025-__-__ | explain/ | | yes/no | source + checklist step refs |
| 2025-__-__ | api/ | | yes/no | source + checklist step refs |
Instructions: copy a row per drop, fill actual date, list filenames, mark whether `SHA256SUMS` was updated, and note evidence source. Keep this file sorted by date for determinism.

3
docs/modules/risk-engine/samples/profiles/README.md Normal file
View File

@@ -0,0 +1,3 @@
Use the root `INGEST_CHECKLIST.md`.
Place profile JSON/DSSE here, normalize with `jq -S .`, update `SHA256SUMS`, and verify with `sha256sum -c`.
UTC timestamps only; no live data.

2
docs/modules/risk-engine/samples/profiles/SHA256SUMS Normal file
View File

@@ -0,0 +1,2 @@
fe460af2699ce335199f6e26597bab4530c6f3f476d4b1f93526175597565d10 README.md
c8242d4051232152d024dd37324b346dcf019a5e46b7b82fae8349ad802affab default-profile.json

18
docs/modules/risk-engine/samples/profiles/default-profile.json Normal file
View 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 }
}