# AI Copilot Implementation Blueprint **Audience:** Innovexus engineering team. This is the design-and-build blueprint for the in-app AI Copilot feature. Not customer-facing. **Status:** Pre-implementation design. Target ship: Q3 2026. The current `/trust/ai-data` public page describes the controls below as design commitments, not shipped features — the public copy must remain accurate as this is built. **Purpose of this document:** Make sure the user-level opt-out, the per-tenant isolation, the audit trail integration, and the data-flow boundaries are designed in from day one — not bolted on after a customer trust review forces them. --- ## 1. Feature scope The AI Copilot is an in-app, natural-language assistant scoped to the operator's authenticated pod. Three primary use cases: ### 1.1 Log Q&A Operator asks: *"Show me every privileged session that touched VLAN 200 last week."* Copilot returns: a structured query result drawn from the per-tenant audit chain, plus an explanation of the query it ran. ### 1.2 Runbook synthesis Operator asks: *"Walk me through how to rotate the TACACS+ shared key on our core fleet."* Copilot returns: a step-by-step runbook drawn from Innovexus documentation + the operator's specific device inventory (sanitised), with executable Innovexus commands inline. ### 1.3 Configuration draft review Operator pastes a config snippet and asks: *"Will this break our drift baseline?"* Copilot returns: a structural diff against the stored baseline, an annotated risk assessment, and (if applicable) suggested fixes. **Out of scope for v1:** - Auto-execution of any privileged action. Copilot suggests; humans authorise. - Cross-tenant pattern matching. Each pod's Copilot is tenant-isolated. - Real-time threat hunting (that's a SOC workspace feature, separately scoped). - Code generation outside narrow runbook contexts. --- ## 2. Architecture overview ``` ┌────────────────────────────────────────────────────────────┐ │ Engineer endpoint (browser) │ └──────────────────────────────────┬─────────────────────────┘ │ HTTPS, FIDO2 session ▼ ┌────────────────────────────────────────────────────────────┐ │ Per-tenant Innovexus pod │ │ ┌────────────────────────────────────────────────────┐ │ │ │ Copilot Gateway │ │ │ │ - Per-user opt-out check │ │ │ │ - Pod-level kill-switch check │ │ │ │ - Prompt sanitisation (strip vault refs etc) │ │ │ │ - Context selector (audit, inventory, baseline) │ │ │ │ - Audit log entry creation │ │ │ └─────────────────────┬──────────────────────────────┘ │ │ │ │ │ ┌──────────────┼──────────────┐ │ │ │ │ │ │ │ ┌──────▼──────┐ ┌───▼────┐ ┌──────▼──────┐ │ │ │ Audit chain │ │Inventory│ │ Baseline │ │ │ │ (read) │ │ (read) │ │ (read) │ │ │ └─────────────┘ └─────────┘ └─────────────┘ │ └──────────────────────────────────┬─────────────────────────┘ │ HTTPS, scoped API key ▼ ┌────────────────────────────────────────────────────────────┐ │ Anthropic Claude API │ │ - Receives sanitised prompt + selected context │ │ - Per Commercial Terms: 30-day retention, no training │ └────────────────────────────────────────────────────────────┘ ``` ### Critical architectural invariants These must be true for every Copilot invocation: 1. **Vault contents never enter the prompt.** Even credential names referenced in the prompt are converted to opaque IDs before the LLM call. The vault ID resolves back to a credential name on the way back, but the LLM only ever sees the ID. 2. **Full session bodies never enter the prompt.** Session metadata (start time, duration, user, target, command count) is fair game. Full session text is not. 3. **Cross-tenant isolation is structural, not policy.** The Copilot Gateway runs inside the per-tenant pod. There is no shared Copilot service that sees data from multiple tenants. Each pod has its own Anthropic API key and rate limit budget. 4. **Every invocation is audit-logged before the LLM call.** If the audit log write fails, the Copilot call fails closed. No invocation should ever succeed without an audit record. --- ## 3. Opt-out controls (the key design ask) ### 3.1 Three layers of disable **Layer 1: Org-wide kill-switch.** Organisation admin can disable AI Copilot for the entire pod in Settings → AI. When disabled, the Copilot UI does not render and the gateway returns 403 to all invocation attempts. Default: off (admin must opt the org in). **Layer 2: Role-based enable.** Within an opted-in org, admins can scope Copilot access to specific roles (e.g., "engineers can use it; auditors cannot"). Implementation: a new `ai_copilot.invoke` permission added to the existing RBAC permission set. **Layer 3: Per-user opt-out.** Within a role that has `ai_copilot.invoke`, individual users can toggle off in their own user preferences. The opt-out is sticky across sessions and devices. Implementation: a boolean column on the `users` table; checked at the gateway before any LLM call. ### 3.2 Opt-out enforcement The Copilot Gateway checks all three in order: ```python def can_invoke_copilot(user, org): # Layer 1: Org-wide if not org.ai_copilot_enabled: return (False, 'org_kill_switch') # Layer 2: RBAC if not user.has_permission('ai_copilot.invoke'): return (False, 'rbac_denied') # Layer 3: User opt-out if user.preferences.ai_copilot_optout: return (False, 'user_optout') return (True, None) ``` Every gate failure produces an audit log entry — admins can see who attempted to use Copilot when it was disabled. ### 3.3 UI implications When a user is opted out (or in an opted-out org), the Copilot UI element does not render at all. Not greyed out, not "click to upgrade" — entirely absent. This is the principle: "if you opted out, you should never see the feature." For users who can use Copilot but choose not to, the entry point is a clearly-labelled button or slash command (`/ask`) that the user explicitly invokes. Copilot is never proactively volunteered. --- ## 4. Audit log schema Every Copilot invocation creates an audit log entry. Schema: ```sql copilot_invocations ( id UUID PRIMARY KEY, pod_id UUID NOT NULL REFERENCES pods(id), user_id UUID NOT NULL REFERENCES users(id), invocation_at TIMESTAMP NOT NULL, -- Request prompt_hash CHAR(64) NOT NULL, -- sha256 of the prompt prompt_summary TEXT NOT NULL, -- LLM-generated 1-line summary stored separately prompt_token_count INT NOT NULL, context_objects JSONB NOT NULL, -- list of object IDs the prompt referenced -- Provider call provider VARCHAR(32) NOT NULL, -- 'anthropic' for v1 model_id VARCHAR(64) NOT NULL, -- e.g., 'claude-3-5-sonnet-20241022' api_call_at TIMESTAMP, -- null if gate failed before call api_status_code INT, api_latency_ms INT, -- Response response_token_count INT, response_action_suggested BOOLEAN NOT NULL DEFAULT FALSE, response_action_executed BOOLEAN NOT NULL DEFAULT FALSE, response_action_executed_by UUID REFERENCES users(id), -- Gate decision gate_outcome VARCHAR(32) NOT NULL, -- 'allowed', 'org_kill_switch', 'rbac_denied', 'user_optout' -- Integrity audit_chain_signature TEXT NOT NULL -- signed by per-tenant pod identity key ) ``` The `prompt_hash` allows audit search ("did anyone invoke Copilot with a prompt about [topic]?") without storing the prompt text long-term. `prompt_summary` is a brief (LLM-generated) one-line summary suitable for audit review. The `audit_chain_signature` is signed by the same per-tenant key that signs the rest of the audit chain — Copilot invocations join the existing audit integrity guarantee. --- ## 5. Public messaging requirements When this feature ships, the following copy updates must happen simultaneously: ### Update `/trust/ai-data` Move all `[TBD] AI COPILOT · Q3 2026` controls from "roadmap" to "shipped" status. Update the Anthropic provider section from "Planned · Q3 2026 target" to "Active · processing customer data". Customer notification email goes out 30 days before this update. ### Update `/components/antichromatic/features-data.tsx` Change the AI Copilot feature card from `name: 'AI Copilot · Roadmap'` back to `name: 'AI Copilot'`. Remove the "Currently in development" suffix. Caps and highlights become accurate descriptions of shipped behaviour. ### Customer notification email 30 days before ship: "AI Copilot is shipping in your pod on [date]. Default state: org-wide kill-switch ON (i.e., disabled). Admins must explicitly opt the org in. Per-user opt-out also available. Full data-flow documentation at /trust/ai-data." ### Sub-processors page update `/trust/sub-processors`: change Anthropic entry from "Active · for Inno chat" to "Active · for AI Copilot in-pod". Update data-scope description. --- ## 6. Build sequence Recommended order (assuming a 2-engineer team, 8–10 week build): ### Sprint 1 (weeks 1–2): Schema + gate - Add `copilot_invocations` table migration - Add `users.preferences.ai_copilot_optout` column migration - Add `org.ai_copilot_enabled` column migration (default false) - Add `ai_copilot.invoke` RBAC permission - Implement Copilot Gateway as a stub (always returns 403, but exercises all three gates and produces audit log entries) ### Sprint 2 (weeks 3–4): Anthropic integration - Per-tenant Anthropic API key provisioning - Prompt sanitisation library (strip vault references, replace with opaque IDs) - Context selector for the three v1 use cases (Log Q&A, Runbook synthesis, Config review) - Wire gateway to Anthropic; first end-to-end smoke test ### Sprint 3 (weeks 5–6): UI - Copilot panel component (slide-in from right side of dashboard) - Settings → AI page for org admins (kill-switch + RBAC scoping) - User preferences page (per-user opt-out toggle) - Slash-command entry point (`/ask` from any dashboard view) ### Sprint 4 (weeks 7–8): Hardening + observability - Rate limiting per pod (default: 100 invocations/hour, configurable) - Cost monitoring per pod (Anthropic token spend dashboard) - Failure modes (Anthropic API down, prompt too long, response timeout) - Audit search UI integration ("show me Copilot invocations matching X") ### Sprint 5 (weeks 9–10): Trust update + ship - Update `/trust/ai-data` to reflect shipped status - Update features-data.tsx - Customer notification email blast (30 days advance was earlier in build, but reminder at ship) - Public ship announcement (blog post + social) --- ## 7. Failure modes What happens when things break: ### 7.1 Anthropic API unreachable - Gateway returns a structured error to the UI: "Copilot is temporarily unavailable. Try again in a few minutes." - Audit log entry recorded with `gate_outcome='allowed'` and `api_status_code=NULL`. - Pod-level health metric updates; if 5+ consecutive failures, the pod's status changes to "Copilot degraded" and the org admin is notified via email + dashboard banner. - The rest of the platform (PAM, NOC, SOC) is completely unaffected. ### 7.2 Anthropic API returns degraded response - If response is empty / malformed / refused: surface to the user as "Copilot couldn't process that. Please rephrase." with a feedback button. - Audit log entry records the `api_status_code` and a flag for "non-helpful response". ### 7.3 Per-pod rate limit exceeded - Return a clear error: "Copilot rate limit reached for this pod (100 invocations/hour). Try again at [timestamp]." - Org admins can request a higher limit via the trust mailbox. ### 7.4 Prompt sanitisation rejects the prompt - Rare but possible. Surface: "Copilot can't process prompts that reference specific credentials. Rephrase using device names instead." - Audit log entry recorded with `gate_outcome='allowed'` (the gates passed) but `api_call_at=NULL`. ### 7.5 Customer reports a privacy concern with a specific Copilot interaction - Direct customers to email `trust@innovexus.io`. - Audit log allows reconstruction of: who invoked, when, what context was sent, what response was returned. - If a remediation is needed (e.g., we discover a sanitisation gap that allowed a vault reference through), it's a Critical-severity bug; immediate fix and customer notification. --- ## 8. Things explicitly NOT in v1 To keep the v1 ship focused, these are explicitly deferred: - **OpenAI fallback.** Anthropic primary; OpenAI / other models are roadmap. - **Self-hosted model option.** Air-gapped customers will need their own Llama-class model deployment; that's a v2+ scope. - **Customer-managed Anthropic key.** Right now Innovexus pays for the Anthropic API; customer-key option is a future capability. - **Cross-pod pattern matching.** The Copilot is strictly pod-scoped. Federated insights across a customer's multiple pods (if any) is v2+. - **Voice interaction.** Text-only for v1. - **Mobile app.** Web app only for v1. - **Auto-execution of suggested actions.** Always human-confirmed in v1. Auto-execution is a v2+ scope, gated behind explicit per-action opt-in. --- ## 9. Pre-ship customer engagement Before this feature ships, design partner feedback should validate: 1. **Three actual operators in three actual customer pods** trial the feature for 2 weeks pre-GA. We collect: feature usefulness ratings, false-positive incidents (cases where Copilot said something wrong), prompt patterns that broke sanitisation, and any privacy concerns. 2. **One trusted security advisor** reviews the architecture documents (this blueprint plus `/trust/ai-data`) and provides written feedback. 3. **Legal review** of the data-flow boundaries against the existing customer DPA template. 4. **Customer notification at least 30 days before ship.** No "surprise" deployment of a feature that processes customer data. If any of these checkpoints raise blocking concerns, the ship slips. We'd rather miss the Q3 target than ship a privacy regression. --- ## 10. Source This blueprint lives at: [innovexus.io/resources/innovexus-ai-copilot-blueprint.md](https://innovexus.io/resources/innovexus-ai-copilot-blueprint.md) Updates are tracked in version control alongside the public-facing `/trust/ai-data` page. When the implementation lands and the public page transitions controls from "roadmap" to "shipped", this blueprint should be updated to "v1.0 — shipped" with a new revision date.