AI Analyst
The AI Analyst reads the same deterministic signals AIControls already computes — risk scores, baseline state, content-safety scan results — and writes a short narrative explaining what they mean together. It correlates and explains; it never decides. Every enforcement action in AIControls still comes from the policy engine, never from the AI Analyst.
What it does — and does not do
The AI Analyst is available in these contexts:
| Surface | What it explains |
|---|---|
| A session's Insights tab (AI Analyst summary) | What happened in the session — accomplished, in progress, blocked, and next steps. This summary generates whenever Internal AI Features are configured; it does not depend on the AI Analyst toggle. |
| Inventory → Identities → an identity's Safety tab | Why this identity's risk score is what it is — synthesizing violation rate, blast radius, elevated-tool usage, and skill risk into a short narrative, instead of a generic sentence like "Elevated risk." |
| A session's Security tab | The session's security posture — even when the content-safety scanner finds nothing, which is the common case (see Detections for what that scanner actually inspects). |
| Security → Activity → Correlated findings → an incident | Summarize incident in the incident drawer: a cited summary of what happened, the blast radius, whether a control worked and the recommended next step. One opt-in action per incident; findings and their evidence rows have no Analyst button of their own. |
| Home → Security briefing → Ask Analyst about this window | An optional, cited advisory analysis of the whole window. The security briefing above it is computed from recorded data and needs no model; the Analyst only adds interpretation. If the model call fails, the briefing stays visible. |
| Home → a ranked finding | A cited advisory explanation of one finding within its frozen time window and selected scope. Ask Analyst gathers recorded context and requests analysis in one explicit action when generation is available. |
| Inventory → Workloads → a workload's Security tab or drawer preview | Ask Analyst beside a recorded finding uses the preview's exact recorded workload, cluster, and frozen last-24-hours window. The icon appears on hover or keyboard focus, and remains visible on narrow or touch screens. |
| Security Posture → Kubernetes workload scorecard | An advisory workload assessment grounded in available report facts, collection availability, deployed policy configuration, and enabled supporting signals. It has a separate assessment setting. |
The Safety/Security narratives follow these rules:
- Explicit generation. Select Generate AI Analyst explanation to request a narrative. Opening the page or tab does not generate one. The action uses your configured provider and may incur cost; failed requests are not retried automatically. Identity Safety generation requires an administrator. Session Security generation uses the caller's existing access to that session.
- A confidence level (High, Medium, or Low — never a percentage, since a number would imply a precision the narrative doesn't have).
- A counter-argument — a reason the narrative above might be wrong or incomplete, shown in the same block, not hidden.
- No authority. The AI Analyst cannot approve or deny a request, change a policy, raise a budget, or take any action. If it isn't enabled, or an internal LLM isn't configured, or a generation attempt fails, the page falls back to its existing deterministic content — a risk-band description on the Safety tab, or just the content-safety result on the Security tab. Nothing about the underlying score or scan changes.
The AI Analyst toggle described below gates the Safety/Security narratives and contextual finding explanations; the Insights-tab summary generates independently of that toggle.
Kubernetes assessments show cited evidence, confidence, and explicit evidence gaps alongside an independent Kyverno report baseline. Missing reports do not imply a passing workload: available configuration and collection gaps can still be assessed, without inventing policy verdicts. The assessment never changes report counts, workload verification, or policy decisions; generated ratings and findings are not exposed to policy evaluation. See Kubernetes workload scorecards and assessment setup.
Incident summaries
Summarize incident in an incident drawer leads with a recommendation (close as benign, escalate or contain), a confidence (low, medium or high) and the findings it rests on. It then answers what happened, the blast radius, whether a control worked, and the next step, each citing recorded evidence. Confidence is capped at medium when the summary read only some of the findings or coverage is partial. A close-as-benign recommendation is accepted only when every finding was read, none is high or critical, and the view was not filtered by subject, facet or search, the incident has no findings after the summary's time range (checked against the whole incident, so a summary of a past incident can still qualify), and no recorded coverage gap applies to the findings read (standing gaps such as unpersisted drift evidence count only when the incident has findings from that source), because resolving acts on the whole incident; otherwise the answer is rejected like any invalid one. It is one opt-in action for the whole incident, so cost and consent are decided once per incident rather than once per finding. Selecting it authorizes one provider call, and one automatic retry if the answer fails validation, when generation is available; opening the drawer never calls the provider.
The summary uses recorded metadata only; it does not send captured prompts or responses. The provider receives the incident's counts and time span, and fixed labels for the newest eight member findings: severity, detector, plane, source, time, and the recorded control outcome (denied, blocked, held, redacted, flagged, allowed, withheld, unread or unrecorded). A sequence finding's outcome comes from its persisted audit steps: the strongest recorded decision among the steps read wins, and the provider also gets how many steps recorded an outcome. A finding keeps at most 100 such steps; when it had more, the summary says a stronger outcome may be unread. Withheld means a sequence's steps carry control metadata that a view scoped to a user, agent, session or workload cannot show, so no outcome is established; a step with a policy but no recorded decision is not counted as an outcome. Unread means a sequence's stored steps could not be fully read back, so its outcome is unknown. Unrecorded means the finding carries no control outcome of its own, as with anomaly and baseline findings; neither word means a control failed. It does not receive finding summaries, user or workload names, policy names, or source identifiers. The summary reads at most the newest eight findings and says exactly how many it read, for example "Read 8 of 25 findings, the newest first. The other 17 were not read.", in its facts and under Evidence & coverage. Older findings are not sampled.
Citations are the incident's own findings and the audit event of the step that decided each one's control outcome, one event per finding. The browser holds opaque references, not finding or source IDs; the server resolves a citation to its member under your own access when you open it. Selecting one opens that finding's current evidence, with the incident's time range, without losing the summary. A citation to anything that is not a member of the incident is rejected. A missing control outcome does not prove that no control ran. The coverage panel carries the same unsupported-scope and drift limits as the incident list. Member severities follow the severity rules, including the cap at medium for a finding whose evidence cannot be read back, so a summary never calls an incident high on evidence it cannot show. The summary states the highest severity among the findings it read. When the incident has more findings than the summary read, the incident's recorded severity appears separately under Evidence & coverage, labelled as not verified by the summary, and is not sent to the provider. Summaries are advisory: they do not rescore the incident or change any control. Administrators can generate; viewers can read the recorded context. The same range, subject, source and search filters that produced the incident's findings in the drawer apply to the summary.
Follow-through
Administrators can resolve the incident as benign with the summary's reasoning as the note, which they edit before it is recorded, or escalate it, which assigns it to themselves and acknowledges it. These are the existing incident triage actions, so they are admin-only and appear in the triage history with the person's name. Viewers see them disabled with the reason. The summary reads recorded metadata, so it shows control outcomes and severities, never intent: a close-as-benign recommendation is a proposal to verify, not a finding. Before either action runs, the drawer rechecks that no new findings joined the incident since the summary and asks you to analyze again if they did. Copy summary copies plain text. The Analyst never runs any of them itself.
When the answer is rejected
AIControls validates every answer: the schema, three observations, a recommendation and confidence, and that every citation names a finding of this incident. When an answer fails, it retries once automatically with a stricter prompt that restates the schema and lists the allowed citations. Both attempts share one invocation record and are costed together. If the retry also fails, the drawer keeps the computed facts, the findings read and the control outcomes, names the specific reason in words, and offers Try again as a separate paid request. The same retry applies to window and finding explanations. A provider error or timeout is not retried automatically.
Contextual finding explanations
Ask Analyst gathers recorded context, requests analysis, and reports the result in one flow. Selecting it authorizes a provider call and its potential cost when generation is available. The control appears beside supported individual findings on Home and in the workload Security preview; it analyzes that finding within the displayed scope. Correlated findings has no per-finding control: it offers one Summarize incident action per incident instead. Viewers can read recorded context but cannot generate.
This contextual workflow requires a verified immutable account binding. Local sessions tied to an active account support it; OIDC-only sessions without that binding currently cannot read or generate contextual explanations. Paid generation rechecks the current account role and active status.
Metadata mode receives bounded recorded metadata, including supported anomaly measurements. Active administrators can also analyze authorized retained redacted prompts, responses, MCP or HTTP excerpts, and scoped assessment rationale. Capture-envelope model reasoning is excluded because retention does not establish that it was shown to the client. Reports generated from retained text are not cached in the browser, since generated prose can quote that text. Known administrator sessions use this retained-content mode on Ask Analyst; sessions whose role is not locally known verify server-authorized generation availability and gather retained content before the first provider call. The initial Ask Analyst action authorizes this complete flow. The provider receives only bounded content for the selected finding and scope. Recorded content and omissions shows what was included. Missing captures, unsupported encrypted TLS content, truncation, and delta increments remain explicit; this context does not establish a complete conversation or prove which request caused a finding. Recorded facts remain separate from advisory interpretation and its suggested next action. Burn-rate findings compare the recorded token burn rate with the recorded detector threshold, both in tokens per minute. A retained baseline p95 and a configured detector threshold have different meanings; missing measurements remain unavailable.
Reopening a recent report rechecks authorization and recorded context before reusing it without another model call. This reuse is limited to the current browser session. Retained-content mode revalidates its scoped evidence and bounded content revision; metadata mode does not track payload changes. Captured input text is removed from saved reports. If recorded context or provider configuration changes, select Analyze latest to request a new analysis. An answer that fails validation is retried once automatically with a stricter prompt; other failures do not retry automatically, and the drawer offers a retry for the failed stage. Closing the drawer or changing scope cancels the browser request; a provider call already started may still incur cost.
Citation actions open the original finding’s currently retained evidence in the same scope. This live evidence is not a frozen copy of data sent to the model. Returning to the report preserves its analysis and scope. Recommendations never execute controls.
Each completed attempt shows recorded call count, available token usage and estimated cost. Missing usage or pricing is shown as Unknown, distinct from zero. Aggregate usage is under Settings → AI Features → Usage and cost. The same explicit workflow is available through the admin MCP server.
Enabling it
The AI Analyst is off by default and requires an internal LLM configuration plus the AI Analyst switch under Settings → AI Features. See Explain a security finding for the review and generation workflow.
Both are required — the switch is an explicit opt-in on top of the internal LLM being configured, not a replacement for it. Changes take effect on the next narrative request; no restart is needed. The Analyst uses its own Analyst model role, which you can point at a reasoning model; see Choose models for internal AI features.
Generation failures and unavailable configuration are shown separately while the recorded facts remain available. A failed evidence read names its reason, and retained-content failures offer an explicit metadata-only analysis instead of a bare retry. Switching context or leaving the tab cancels the browser request and prevents a late explanation from appearing in another context. Cancellation cannot guarantee that a provider call already started will incur no charge. For contextual findings, Analyze latest requests a fresh analysis when the drawer identifies changed context. Legacy Safety/Security narratives retain their separate generation controls.
See also
- Identities & Risk Scores — what feeds the risk score the Safety tab's narrative explains.
- Detections — the content-safety scan the Security tab's narrative reads.
Contextual explanations use stable opaque source references so credential-bearing target URLs and source identifiers are not sent in the prompt. AIControls retains the exact identifiers internally for authorized source lookup; audit correlation uses the same opaque group reference as the contextual explanation.