sprints work

2026-01-10 11:15:28 +02:00
parent a21d3dbc1f
commit 701eb6b21c
71 changed files with 10854 additions and 136 deletions
--- a/docs/modules/advisory-ai/guides/ai-attestations.md
+++ b/docs/modules/advisory-ai/guides/ai-attestations.md
@@ -371,3 +371,154 @@ graph LR
 - [Offline Model Bundles](./offline-model-bundles.md)
 - [Attestor Module](../../attestor/architecture.md)
 - [Evidence Locker](../../evidence-locker/architecture.md)
+
+---
+
+## API Reference (Sprint: SPRINT_20260109_011_001)
+
+### Get Run Attestation
+
+```http
+GET /v1/advisory-ai/runs/{runId}/attestation
+Authorization: Bearer <token>
+X-StellaOps-Tenant: <tenant-id>
+```
+
+**Response (200 OK):**
+```json
+{
+  "runId": "run-abc123",
+  "attestation": {
+    "runId": "run-abc123",
+    "tenantId": "tenant-xyz",
+    "userId": "user@example.com",
+    "modelInfo": {
+      "modelId": "gpt-4-turbo",
+      "modelVersion": "2024-04-09",
+      "provider": "azure-openai"
+    },
+    "promptTemplate": {
+      "templateId": "security-explain",
+      "version": "1.2.0"
+    },
+    "turnSummaries": [...],
+    "totalTokens": 2140,
+    "startTime": "2026-01-10T14:29:55Z",
+    "endTime": "2026-01-10T14:30:05Z"
+  },
+  "envelope": { ... },
+  "links": {
+    "claims": "/v1/advisory-ai/runs/run-abc123/claims",
+    "verify": "/v1/advisory-ai/attestations/verify"
+  }
+}
+```
+
+### List Run Claims
+
+```http
+GET /v1/advisory-ai/runs/{runId}/claims
+Authorization: Bearer <token>
+X-StellaOps-Tenant: <tenant-id>
+```
+
+**Response (200 OK):**
+```json
+{
+  "runId": "run-abc123",
+  "count": 3,
+  "claims": [
+    {
+      "claimId": "claim-789",
+      "runId": "run-abc123",
+      "turnId": "turn-001",
+      "claimType": "vulnerability_assessment",
+      "claimText": "CVE-2024-1234 is reachable through /api/users",
+      "confidence": 0.85,
+      "evidence": [...],
+      "timestamp": "2026-01-10T14:30:02Z"
+    }
+  ]
+}
+```
+
+### List Recent Attestations
+
+```http
+GET /v1/advisory-ai/attestations/recent?limit=20
+Authorization: Bearer <token>
+X-StellaOps-Tenant: <tenant-id>
+```
+
+### Verify Attestation
+
+```http
+POST /v1/advisory-ai/attestations/verify
+Authorization: Bearer <token>
+X-StellaOps-Tenant: <tenant-id>
+Content-Type: application/json
+
+{
+  "runId": "run-abc123"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "isValid": true,
+  "runId": "run-abc123",
+  "contentDigest": "sha256:abc...",
+  "verifiedAt": "2026-01-10T15:00:00Z",
+  "signingKeyId": "key-xyz",
+  "digestValid": true,
+  "signatureValid": true
+}
+```
+
+---
+
+## Claim Types
+
+| Type | Description |
+|------|-------------|
+| `vulnerability_assessment` | AI assessment of vulnerability severity or exploitability |
+| `reachability_analysis` | AI analysis of code reachability |
+| `remediation_recommendation` | AI-suggested fix or mitigation |
+| `policy_interpretation` | AI interpretation of security policy |
+| `risk_explanation` | AI explanation of security risk |
+| `prioritization` | AI-based vulnerability prioritization |
+
+---
+
+## Integration Example
+
+```csharp
+// Inject the attestation service
+public class MyService(IAiAttestationService attestationService)
+{
+    public async Task AttestRunAsync(AiRunAttestation attestation)
+    {
+        var result = await attestationService.CreateRunAttestationAsync(
+            attestation, sign: true);
+        
+        if (result.Success)
+        {
+            Console.WriteLine($"Attestation created: {result.ContentDigest}");
+        }
+    }
+    
+    public async Task VerifyAsync(string runId)
+    {
+        var verification = await attestationService.VerifyRunAttestationAsync(runId);
+        if (!verification.Valid)
+        {
+            Console.WriteLine($"Verification failed: {verification.FailureReason}");
+        }
+    }
+}
+```
+
+---
+
+_Last updated: 10-Jan-2026_