audit, advisories and doctors/setup work
This commit is contained in:
master
@@ -20,6 +20,7 @@ Advisory AI is the retrieval-augmented assistant that synthesizes advisory and V
|
||||
- Preserve determinism and provenance in all derived outputs.
|
||||
- Document offline/air-gap pathways for any new feature.
|
||||
- Update telemetry/observability assets alongside feature work.
|
||||
- Chat gateway must enforce quotas, scrubber rules, tool allowlists, and audit logging.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/advisory-ai/README.md`
|
||||
|
||||
@@ -153,3 +153,13 @@ All endpoints accept `profile` parameter (default `fips-local`) and return `outp
|
||||
- **Remote inference toggle.** Set `AdvisoryAI:Inference:Mode` (env: `ADVISORYAI__AdvisoryAI__Inference__Mode`) to `Remote` when you want prompts to be executed by an external inference tier. Provide `AdvisoryAI:Inference:Remote:BaseAddress` and, optionally, `...:ApiKey`. When remote calls fail the executor falls back to the sanitized prompt and sets `inference.fallback_*` metadata so CLI/Console surface a warning.
|
||||
- **Scalability.** Start with 1 web replica + 1 worker for up to ~10 requests/minute. For higher throughput, scale `advisory-ai-worker` horizontally; each worker is CPU-bound (2 vCPU / 4 GiB RAM recommended) while the web front end is I/O-bound (1 vCPU / 1 GiB). Because the queue/plan/output stores are content-addressed files, ensure the shared volume delivers ≥500 IOPS and <5 ms latency; otherwise queue depth will lag.
|
||||
- **Offline & air-gapped stance.** The Compose/Helm manifests avoid external network calls by default and the Offline Kit now publishes the `advisory-ai-web` and `advisory-ai-worker` images alongside their SBOMs/provenance. Operators can rehydrate the RWX volume from the kit to pre-prime cache directories before enabling the service.
|
||||
|
||||
## 14) Controlled conversational interface and tool gating
|
||||
|
||||
- **Chat Gateway controls.** Chat endpoints enforce Authority auth, per-tenant/user quotas, token budgets, and PII/secret scrubbing before any model invocation.
|
||||
- **Sanctioned tools only.** Tool calls are schema-bound and allowlisted (read-only by default). Action tools require explicit user confirmation plus policy allow.
|
||||
- **Policy lattice.** Tool permissions are evaluated against policy rules (scope, tenant, role, resource) before invocation.
|
||||
- **Audit log.** Persist prompt hash, redaction metadata, tool calls, policy decisions, and model identifiers to Postgres; optional DSSE signatures capture evidence integrity.
|
||||
- **Offline parity.** Local model profiles are the default; remote inference is opt-in and blocked in sealed mode.
|
||||
|
||||
See `docs/modules/advisory-ai/chat-interface.md` and `docs-archived/product/advisories/13-Jan-2026 - Controlled Conversational Interface.md`.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> **Sprint:** SPRINT_20260107_006_003 Task CH-016
|
||||
> **Status:** Active
|
||||
> **Last Updated:** 2026-01-09
|
||||
> **Last Updated:** 2026-01-13
|
||||
|
||||
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.
|
||||
|
||||
@@ -14,6 +14,17 @@ The chat interface enables:
|
||||
- **Action proposals** for risk approval, quarantine, and VEX creation
|
||||
- **Streaming responses** for real-time feedback
|
||||
|
||||
## Controlled Gateway and Budgets
|
||||
- **Chat Gateway** enforces Authority auth, quotas, and token budgets per user/org.
|
||||
- **Settings overrides**: quotas and tool allowlists are configurable via UI/CLI settings; env values are defaults.
|
||||
- **Doctor action** reports quota/tool limits and last denial for troubleshooting.
|
||||
- **Scrubber** removes secrets and PII using regex + entropy filters + allowlists.
|
||||
- **Tool gating** runs policy checks before any tool invocation; read-only by default.
|
||||
|
||||
## Sanctioned Tools (v1)
|
||||
- Read-only: `vex.query`, `sbom.read`, `scanner.findings.topk`.
|
||||
- Action tools require explicit confirmation plus policy allow.
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
@@ -22,18 +33,23 @@ The chat interface enables:
|
||||
|
||||
Creates a new conversation session.
|
||||
|
||||
Required headers: `X-StellaOps-User`, `X-StellaOps-Client`, and either `X-StellaOps-Roles` (`chat:user` or `chat:admin`) or `X-StellaOps-Scopes` (`advisory:chat` or `advisory:run`).
|
||||
|
||||
```http
|
||||
POST /api/v1/advisory-ai/conversations
|
||||
POST /v1/advisory-ai/conversations
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer <token>
|
||||
X-StellaOps-User: user-xyz
|
||||
X-StellaOps-Roles: chat:user
|
||||
X-StellaOps-Client: ui
|
||||
|
||||
{
|
||||
"tenantId": "tenant-123",
|
||||
"context": {
|
||||
"findingId": "f-456",
|
||||
"currentCveId": "CVE-2023-44487",
|
||||
"currentComponent": "pkg:npm/lodash@4.17.21",
|
||||
"currentImageDigest": "sha256:abc123",
|
||||
"scanId": "s-789",
|
||||
"cveId": "CVE-2023-44487",
|
||||
"component": "pkg:npm/lodash@4.17.21"
|
||||
"sbomId": "sbom-123"
|
||||
},
|
||||
"metadata": {
|
||||
"source": "ui",
|
||||
@@ -50,11 +66,7 @@ Authorization: Bearer <token>
|
||||
"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
|
||||
"turns": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -63,13 +75,16 @@ Authorization: Bearer <token>
|
||||
Sends a user message and streams the AI response.
|
||||
|
||||
```http
|
||||
POST /api/v1/advisory-ai/conversations/{conversationId}/turns
|
||||
POST /v1/advisory-ai/conversations/{conversationId}/turns
|
||||
Content-Type: application/json
|
||||
Accept: text/event-stream
|
||||
Authorization: Bearer <token>
|
||||
X-StellaOps-User: user-xyz
|
||||
X-StellaOps-Roles: chat:user
|
||||
X-StellaOps-Client: ui
|
||||
|
||||
{
|
||||
"message": "Is CVE-2023-44487 exploitable in our environment?"
|
||||
"content": "Is CVE-2023-44487 exploitable in our environment?",
|
||||
"stream": true
|
||||
}
|
||||
```
|
||||
|
||||
@@ -155,6 +170,24 @@ DELETE /api/v1/advisory-ai/conversations/{conversationId}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### Chat Settings
|
||||
|
||||
Read or update chat quota/tool settings (defaults come from env).
|
||||
|
||||
```http
|
||||
GET /api/v1/chat/settings
|
||||
PUT /api/v1/chat/settings?scope=tenant
|
||||
DELETE /api/v1/chat/settings?scope=tenant
|
||||
```
|
||||
|
||||
### Chat Doctor
|
||||
|
||||
Returns quota and tool access status to diagnose limits.
|
||||
|
||||
```http
|
||||
GET /api/v1/chat/doctor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Object Link Format
|
||||
@@ -225,10 +258,11 @@ You may want to accept this risk: [Accept Risk]{action:approve,cve_id=CVE-2023-4
|
||||
|
||||
1. **Parsing**: ActionProposalParser extracts actions from model output
|
||||
2. **Permission Check**: User roles are validated against required role
|
||||
3. **Display**: Allowed actions render as buttons; blocked actions show disabled with reason
|
||||
4. **Confirmation**: User clicks button and confirms in modal
|
||||
5. **Execution**: Backend executes action with audit trail
|
||||
6. **Result**: Success/failure displayed in chat
|
||||
3. **Policy Check**: Tool lattice rules allow/deny the action in this context
|
||||
4. **Display**: Allowed actions render as buttons; blocked actions show disabled with reason
|
||||
5. **Confirmation**: User clicks button and confirms in modal
|
||||
6. **Execution**: Backend executes action with audit trail
|
||||
7. **Result**: Success/failure displayed in chat
|
||||
|
||||
### Blocked Actions
|
||||
|
||||
@@ -244,6 +278,20 @@ When a user lacks permission for an action:
|
||||
|
||||
---
|
||||
|
||||
## Audit Log
|
||||
|
||||
Every chat session records an immutable audit trail:
|
||||
- Prompt hash, redaction metadata, and model identifier
|
||||
- Tool calls (inputs/outputs hashes) and policy decisions
|
||||
- Evidence links surfaced in responses
|
||||
- Action confirmations and results
|
||||
|
||||
Audit records live in Postgres with optional DSSE signatures for evidence export.
|
||||
Apply `src/AdvisoryAI/StellaOps.AdvisoryAI/Storage/Migrations/001_chat_audit.sql`
|
||||
to create the tables (adjust schema if needed).
|
||||
|
||||
---
|
||||
|
||||
## Grounding System
|
||||
|
||||
All AI responses are validated for proper grounding—ensuring claims are backed by evidence.
|
||||
@@ -333,17 +381,40 @@ Assistant: I will create a VEX statement with the following details:
|
||||
|
||||
```yaml
|
||||
AdvisoryAI:
|
||||
Guardrails:
|
||||
EntropyThreshold: 3.5
|
||||
EntropyMinLength: 20
|
||||
AllowlistFile: "data/advisory-ai/allowlist.txt"
|
||||
Chat:
|
||||
ConversationRetention: '7.00:00:00' # 7 days
|
||||
MaxTurnsPerConversation: 50
|
||||
TokenBudget: 8192
|
||||
StreamingEnabled: true
|
||||
Quotas:
|
||||
RequestsPerMinute: 60
|
||||
RequestsPerDay: 500
|
||||
TokensPerDay: 100000
|
||||
ToolCallsPerDay: 10000
|
||||
Tools:
|
||||
AllowAll: false
|
||||
AllowedTools:
|
||||
- "vex.query"
|
||||
- "sbom.read"
|
||||
- "scanner.findings.topk"
|
||||
Audit:
|
||||
Enabled: true
|
||||
ConnectionString: "Host=localhost;Database=stellaops;Username=stellaops;Password=changeme"
|
||||
SchemaName: "advisoryai"
|
||||
IncludeEvidenceBundle: false
|
||||
RetentionPeriod: '90.00:00:00'
|
||||
Grounding:
|
||||
MinGroundingScore: 0.5
|
||||
MaxLinkDistance: 200
|
||||
Actions:
|
||||
RequireConfirmation: true
|
||||
AuditAllExecutions: true```n
|
||||
RequirePolicyAllow: true
|
||||
AuditAllExecutions: true
|
||||
```
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
@@ -364,4 +435,5 @@ AdvisoryAI:
|
||||
- [AdvisoryAI Architecture](architecture.md)
|
||||
- [Deployment Guide](deployment.md)
|
||||
- [Security Guardrails](/docs/security/assistant-guardrails.md)
|
||||
- [Controlled Conversational Interface Advisory](../../../docs-archived/product/advisories/13-Jan-2026%20-%20Controlled%20Conversational%20Interface.md)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user