Enhance risk API documentation and error handling
- 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:
@@ -1,2 +1,3 @@
|
||||
9408221415b389f6dad1c235de160e88721555b406ab0e2bdbfa3119c6696a4d README.md
|
||||
00f8dc4e466eb95c06545e6336d7b0866b53ac430335b7fd1b7889da13529b93 error-catalog.json
|
||||
96926cd81dfb6ff02d62d1fde5d7b2b7b5b3950e50eb651e51b8ae3042ac9506 risk-api-samples.json
|
||||
|
||||
13
docs/risk/samples/api/error-catalog.json
Normal file
13
docs/risk/samples/api/error-catalog.json
Normal 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
|
||||
}
|
||||
}
|
||||
@@ -1,2 +1,4 @@
|
||||
30a64dcc9fb41d06774a9c125456c212a29915a083cd1d2170f16f343bd0764f README.md
|
||||
4bba11375e9f06942e988dd6cd30e7005fe3b040009b3fffca4e6d36a1875ab3 cli-explain.txt
|
||||
22c87e16d5a5cd89f60660eeb07b319989c38f2aa0243da88a312bee1841dda6 console-frame.json
|
||||
1d2e56eebf0a266f80519f073e1db532c4a4f2d7fa604ea5c05d4e208719cc7c explain-trace.json
|
||||
|
||||
12
docs/risk/samples/explain/cli-explain.txt
Normal file
12
docs/risk/samples/explain/cli-explain.txt
Normal 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
|
||||
19
docs/risk/samples/explain/console-frame.json
Normal file
19
docs/risk/samples/explain/console-frame.json
Normal 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]
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user