audit, advisories and doctors/setup work

docs-archived/product/advisories/13-Jan-2026 - Controlled Conversational Interface.md

@@ -0,0 +1,76 @@
+# Controlled Conversational Interface for Stella Ops
+
+**Status:** ANALYZED - Sprints Created
+**Date:** 2026-01-13
+**Type:** Product Advisory (Advisory AI / Assistant)
+
+## Executive Summary
+- Provide an "Ask Stella" conversational interface that is evidence-first and policy-gated.
+- Enforce guardrails: no secret exfiltration, token and rate budgets, audited actions.
+- Keep offline parity: local models, deterministic citations, no external calls.
+
+## New Topics vs Existing Work
+- Chat Gateway with quotas, scrubber, and policy checks before tool use.
+- Sanctioned tool registry (read-only default) with explicit confirmation for actions.
+- Immutable audit log of prompts, redactions, tool calls, and model fingerprints.
+- CLI parity: `stella advise "<question>" --evidence --no-action`.
+- Policy lattice for tool permissions and action approvals.
+
+## Safe Default Architecture
+- **Chat Gateway (API):** Authority auth, quotas (user/org), scrubber, policy check, action confirmation.
+- **Local LLM Orchestrator:** tool schema only, no free-form shell, deterministic defaults.
+- **Sanctioned Plugins:** read-only by default; action tools require confirmation + policy allow.
+- **Audit Log:** Postgres system of record; optional DSSE signatures; Valkey for ephemeral cache.
+
+## Minimal Plugin Surface (v1)
+- Read-only tools: `vex.query`, `sbom.read`, `scanner.findings.topk`.
+- Explain tools: `explain.finding`, `prioritize`, `suggest.fix` (no execution).
+- Action tools (opt-in): `scanner.rescan`, `orchestrator.create.ticket` (require confirmation + policy allow).
+
+## Policy and Safety Requirements
+- No secrets ever: vault metadata only, scrubber strips tokens/keys/ASN, entropy filter, allowlist.
+- Budgets: tokens, requests/min, tool invocations/day per user/org.
+- Tool least-privilege: separate roles per plugin, read vs write paths.
+- Offline-ready: local models only; no external calls.
+- Deterministic windows: low temperature for factual responses; narrow expansions for drafts.
+
+## Data Contracts (Sketch)
+- Tool I/O is JSON with stable schemas.
+- Each tool result includes `object_ref`, `hash`, and `evidence[]`.
+
+Example tool response:
+```json
+{
+  "tool": "vex.query",
+  "object_ref": "vex:issuer:sha256:abc123",
+  "hash": "sha256:deadbeef...",
+  "evidence": [
+    { "type": "vex", "ref": "vex:issuer:sha256:abc123" }
+  ]
+}
+```
+
+## Example Flow (Why a CVE still appears)
+1. Gateway scrubs input -> orchestrator calls `vex.query`, `sbom.read`, `reachability.graph.query`.
+2. Policy check allows read-only tools.
+3. Response cites evidence (attestation, diff sig, VEX status, reachability).
+
+## First Cut (1 Week)
+1. Gateway: auth, quotas, scrubber, audit log.
+2. Orchestrator: three read-only plugins (`vex.query`, `sbom.read`, `scanner.findings.topk`).
+3. Advisor UI panel with citations; CLI `stella advise` (no action by default).
+4. Policy v0: deny all actions; allow read-only tools in a sample namespace.
+5. One curated intent: "Explain why this CVE still appears" with evidence chain.
+
+## Defaults to Apply
+- Hybrid reachability posture (graph DSSE required; edge-bundle DSSE optional).
+- Deterministic outputs only.
+- Offline-friendly operation with frozen feeds.
+
+## De-duplication
+Extends (not supersedes):
+- `docs-archived/product/advisories/26-Dec-2025 - AI Assistant as Proof-Carrying Evidence Engine.md`
+- `docs-archived/product/advisories/30-Dec-2025 - Evidence-Gated AI Explanations.md`
+- `docs-archived/product/advisories/26-Dec-2025 - AI Surfacing UX Patterns.md`
+
+Overlap: evidence-grounded outputs, UI patterns. New content: chat gateway quotas, tool sanctions, audit log schema, CLI parity, policy lattice for tool access.