Enhance risk API documentation and error handling
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled

- Updated API documentation for risk endpoints to include optional caching headers and error catalog references.
- Added a new error catalog JSON file to standardize error responses.
- Improved explainability documentation with sample outputs for console and CLI.
- Added SHA256 checksums for new sample files related to explainability.
- Refined AocGuard tests to utilize a helper method for generating test JSON, improving readability and maintainability.
- Updated runbook references to ensure consistency in sprint documentation.
- Introduced stub implementations for MongoDB storage interfaces and options, laying groundwork for future development.
- Disabled analytics in Angular CLI configuration for privacy considerations.
This commit is contained in:
StellaOps Bot
2025-12-06 00:47:29 +02:00
parent 582a88e8f8
commit 6c1177a6ce
19 changed files with 1403 additions and 1319 deletions

View File

@@ -1,2 +1,3 @@
9408221415b389f6dad1c235de160e88721555b406ab0e2bdbfa3119c6696a4d README.md
00f8dc4e466eb95c06545e6336d7b0866b53ac430335b7fd1b7889da13529b93 error-catalog.json
96926cd81dfb6ff02d62d1fde5d7b2b7b5b3950e50eb651e51b8ae3042ac9506 risk-api-samples.json

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
}
}

View File

@@ -1,2 +1,4 @@
30a64dcc9fb41d06774a9c125456c212a29915a083cd1d2170f16f343bd0764f README.md
4bba11375e9f06942e988dd6cd30e7005fe3b040009b3fffca4e6d36a1875ab3 cli-explain.txt
22c87e16d5a5cd89f60660eeb07b319989c38f2aa0243da88a312bee1841dda6 console-frame.json
1d2e56eebf0a266f80519f073e1db532c4a4f2d7fa604ea5c05d4e208719cc7c explain-trace.json

View File

@@ -0,0 +1,12 @@
stella risk explain job-001 --tenant tenant-default --json false
Finding: finding-123
Profile: default-profile v1.0.0 (hash sha256:profilehash)
Score: 0.85 (high)
Gates: kev_and_reachability
Contributions:
- cvss 0.40 (raw 7.5, source nvd, provenance sha256:cvsshash)
- kev 0.30 (raw true, source cisa, provenance sha256:kevhash)
- reachability 0.30 (raw 0.9, source scanner, provenance 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

View File

@@ -0,0 +1,19 @@
{
"frame_id": "console-explain-001",
"captured_at": "2025-12-05T00:05:00Z",
"finding_id": "finding-123",
"profile_id": "default-profile",
"score": 0.85,
"severity": "high",
"gates": ["kev_and_reachability"],
"top_contributors": [
{"factor": "cvss", "contribution": 0.4, "raw": 7.5, "provenance": "sha256:cvsshash"},
{"factor": "kev", "contribution": 0.3, "raw": true, "provenance": "sha256:kevhash"},
{"factor": "reachability", "contribution": 0.3, "raw": 0.9, "provenance": "sha256:reachhash"}
],
"provenance": {"job_hash": "sha256:jobhash"},
"charts": {
"donut": {"high": 1},
"stacked": [0.4, 0.3, 0.3]
}
}