10 KiB
10 KiB
AdvisoryAI Chat Interface
Sprint: SPRINT_20260107_006_003 Task CH-016 Status: Active Last Updated: 2026-01-09
The AdvisoryAI Chat Interface provides a conversational experience for security operators to investigate vulnerabilities, understand findings, and take remediation actions—all grounded in internal evidence with citations.
Overview
The chat interface enables:
- Multi-turn conversations about vulnerabilities, components, and security posture
- Grounded responses with citations to internal evidence (SBOMs, VEX, attestations)
- Action proposals for risk approval, quarantine, and VEX creation
- Streaming responses for real-time feedback
API Reference
Create Conversation
Creates a new conversation session.
POST /api/v1/advisory-ai/conversations
Content-Type: application/json
Authorization: Bearer <token>
{
"tenantId": "tenant-123",
"context": {
"findingId": "f-456",
"scanId": "s-789",
"cveId": "CVE-2023-44487",
"component": "pkg:npm/lodash@4.17.21"
},
"metadata": {
"source": "ui",
"version": "1.0"
}
}
Response:
{
"conversationId": "conv-abc123",
"tenantId": "tenant-123",
"userId": "user-xyz",
"createdAt": "2026-01-09T12:00:00Z",
"updatedAt": "2026-01-09T12:00:00Z",
"context": {
"currentCveId": "CVE-2023-44487",
"currentComponent": "pkg:npm/lodash@4.17.21"
},
"turnCount": 0
}
Send Message (Streaming)
Sends a user message and streams the AI response.
POST /api/v1/advisory-ai/conversations/{conversationId}/turns
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer <token>
{
"message": "Is CVE-2023-44487 exploitable in our environment?"
}
Response (Server-Sent Events):
event: token
data: {"content": "Based on the reachability analysis "}
event: token
data: {"content": "[reach:api-gateway:grpc.Server], "}
event: citation
data: {"type": "reach", "path": "api-gateway:grpc.Server", "verified": true}
event: token
data: {"content": "this vulnerability **is reachable** in your environment."}
event: action
data: {"type": "approve", "label": "Accept Risk", "enabled": true, "parameters": {"cve_id": "CVE-2023-44487"}}
event: grounding
data: {"score": 0.92, "citations": 3, "claims": 2}
event: done
data: {"turnId": "turn-xyz", "groundingScore": 0.92}
Get Conversation
Retrieves a conversation with its history.
GET /api/v1/advisory-ai/conversations/{conversationId}
Authorization: Bearer <token>
Response:
{
"conversationId": "conv-abc123",
"tenantId": "tenant-123",
"userId": "user-xyz",
"createdAt": "2026-01-09T12:00:00Z",
"updatedAt": "2026-01-09T12:05:00Z",
"context": { ... },
"turns": [
{
"turnId": "turn-001",
"role": "user",
"content": "Is CVE-2023-44487 exploitable?",
"timestamp": "2026-01-09T12:01:00Z"
},
{
"turnId": "turn-002",
"role": "assistant",
"content": "Based on the reachability analysis...",
"timestamp": "2026-01-09T12:01:05Z",
"evidenceLinks": [
{"type": "reach", "uri": "reach://api-gateway:grpc.Server", "label": "Reachability trace"}
],
"groundingScore": 0.92
}
],
"turnCount": 2
}
List Conversations
Lists conversations for a tenant/user.
GET /api/v1/advisory-ai/conversations?tenantId=tenant-123&userId=user-xyz&limit=20
Authorization: Bearer <token>
Delete Conversation
Deletes a conversation and its history.
DELETE /api/v1/advisory-ai/conversations/{conversationId}
Authorization: Bearer <token>
Object Link Format
AI responses include object links that reference internal evidence. These links enable deep navigation to source data.
Supported Link Types
| Type | Format | Example | Description |
|---|---|---|---|
| SBOM | [sbom:{id}] |
[sbom:abc123] |
Link to SBOM document |
| Reachability | [reach:{service}:{function}] |
[reach:api-gateway:grpc.Server] |
Link to reachability trace |
| Runtime | [runtime:{service}:traces] |
[runtime:api-gateway:traces] |
Link to runtime traces |
| VEX | [vex:{issuer}:{digest}] |
[vex:stellaops:sha256:abc] |
Link to VEX statement |
| Attestation | [attest:dsse:{digest}] |
[attest:dsse:sha256:xyz] |
Link to DSSE attestation |
| Authority Key | [auth:keys/{keyId}] |
[auth:keys/gitlab-oidc] |
Link to signing key |
| Documentation | [docs:{path}] |
[docs:scopes/ci-webhook] |
Link to documentation |
Link Resolution
Object links are validated by the grounding system:
- Valid links resolve to existing objects and render as clickable chips
- Invalid links are flagged as grounding issues and may lower the grounding score
- Links must be within
MaxLinkDistancecharacters of related claims to count as grounding
Example Response with Links
The vulnerability **CVE-2023-44487** affects your deployment.
**Evidence:**
- The component is present in your SBOM [sbom:scan-2026-01-09-abc123]
- Reachability analysis shows the vulnerable function is called [reach:api-gateway:grpc.Server]
- No VEX statement currently exists for this product
**Recommendation:** Consider creating a VEX statement to document your assessment.
Action Types
The AI can propose actions that users can execute directly from the chat interface. Actions are permission-gated and require explicit confirmation.
Available Actions
| Action | Required Role | Parameters | Description |
|---|---|---|---|
approve |
approver |
cve_id, rationale?, expiry? |
Accept risk for a vulnerability |
quarantine |
operator |
image_digest |
Block an image from deployment |
defer |
triage |
cve_id, assignee? |
Mark for later investigation |
generate_manifest |
admin |
integration_type |
Create integration manifest |
create_vex |
issuer |
product, vulnerability, status |
Draft VEX statement |
Action Button Format
Actions appear in responses using this format:
[Action Label]{action:type,param1=value1,param2=value2}
Example:
You may want to accept this risk: [Accept Risk]{action:approve,cve_id=CVE-2023-44487,rationale=tested}
Action Execution Flow
- Parsing: ActionProposalParser extracts actions from model output
- Permission Check: User roles are validated against required role
- Display: Allowed actions render as buttons; blocked actions show disabled with reason
- Confirmation: User clicks button and confirms in modal
- Execution: Backend executes action with audit trail
- Result: Success/failure displayed in chat
Blocked Actions
When a user lacks permission for an action:
{
"actionType": "approve",
"label": "Accept Risk",
"isAllowed": false,
"blockedReason": "Requires 'approver' role. You have: viewer, triage"
}
Grounding System
All AI responses are validated for proper grounding—ensuring claims are backed by evidence.
Grounding Score
The grounding score (0.0-1.0) measures response quality:
| Score Range | Quality | Description |
|---|---|---|
| 0.90-1.00 | Excellent | All claims cited, all links valid |
| 0.70-0.89 | Good | Most claims cited, minor issues |
| 0.50-0.69 | Acceptable | Some claims uncited |
| < 0.50 | Rejected | Response regenerated |
Grounding Validation
The validator checks:
- Link Validity: Do object links resolve to real objects?
- Claim Grounding: Are security claims near valid citations?
- Citation Density: Are there enough citations for the response length?
Claim Detection
Claims requiring grounding include:
- Vulnerability status: "is affected", "is not affected", "is vulnerable"
- Fix status: "has been fixed", "is patched", "is mitigated"
- Severity assessments: "CVSS score is 9.8", "severity is critical"
- Investigation status: "is under investigation"
Grounding Issues
| Issue Type | Severity | Description |
|---|---|---|
InvalidLink |
Error | Object link does not resolve |
UngroundedClaim |
Warning | Security claim without nearby citation |
BelowThreshold |
Critical | Overall score below minimum |
Configuration
AdvisoryAI:
Chat:
Grounding:
MinGroundingScore: 0.5 # Minimum acceptable score
MaxLinkDistance: 200 # Max chars between claim and citation
Example Flows
Vulnerability Investigation
Assistant: CVE-2023-44487 (HTTP/2 Rapid Reset) **is reachable** in your environment
[reach:api-gateway:grpc.Server].
**Status:** AFFECTED
- Component: grpc-go v1.56.0 [sbom:scan-abc123]
- Reachable path: api-gateway -> grpc.Server.handleStream()
- No VEX statement exists
**Recommended actions:**
[Accept Risk]{action:approve,cve_id=CVE-2023-44487}
[Create VEX]{action:create_vex,product=api-gateway,vulnerability=CVE-2023-44487,status=affected}
```n
---
### Action Execution
```n User: Please create a VEX statement marking CVE-2023-44487 as affected for api-gateway.
Assistant: I will create a VEX statement with the following details:
- **Product:** api-gateway
- **Vulnerability:** CVE-2023-44487
- **Status:** affected
- **Justification:** Vulnerable code is reachable
[Create VEX Statement]{action:create_vex,product=api-gateway,vulnerability=CVE-2023-44487,status=affected,justification=vulnerable_code_present}
```n
---
## Configuration
```yaml
AdvisoryAI:
Chat:
ConversationRetention: '7.00:00:00' # 7 days
MaxTurnsPerConversation: 50
TokenBudget: 8192
StreamingEnabled: true
Grounding:
MinGroundingScore: 0.5
MaxLinkDistance: 200
Actions:
RequireConfirmation: true
AuditAllExecutions: true```n
---
## Error Handling
| Status Code | Error | Description |
|-------------|-------|-------------|
| 400 | InvalidRequest | Malformed request body |
| 401 | Unauthorized | Missing or invalid token |
| 403 | Forbidden | Insufficient permissions |
| 404 | ConversationNotFound | Conversation does not exist |
| 429 | RateLimited | Too many requests |
| 500 | InternalError | Server error |
---
## See Also
- [AdvisoryAI Architecture](architecture.md)
- [Deployment Guide](deployment.md)
- [Security Guardrails](/docs/security/assistant-guardrails.md)