AI Features

uControl Insight ships an AI assistant layer that uses your asset inventory, topology graph and flow data to help operators investigate, troubleshoot and document. This page describes each capability, where you'll see it in the product, and how to turn it on.

Overview — what AI adds to uControl Insight

With AI enabled you get:

• A natural-language assistant for asking questions about your estate — "show me Windows servers in London not seen in a month".
• Automated explanations for failing discovery scans, with recommended actions delivered both in the UI and on Microsoft Teams.
• Per-asset narration — AI-generated impact analyses ("what would break if this host went offline") and operational runbooks.
• Inventory hygiene help — AI suggestions for classifying unknown endpoints and proposing missing topology relationships.
• A monitoring layer on top of NetFlow/IPFIX data — alerts when an asset starts talking to a peer it has never talked to before, with a one-sentence rationale.
• An executive summary and daily digest — a paragraph-and-bullets description of the state of the estate, optionally posted to Teams every morning.

Prerequisites

• An API key from one of the supported providers, OR a self-hosted Ollama instance:
  • OpenAI — create at platform.openai.com/api-keys
  • Anthropic — create at console.anthropic.com/settings/keys
  • Ollama — install locally per ollama.com/download and pull a model (e.g. ollama pull llama3.1)
• Network egress from the uControl server to the chosen provider (port 443).
• An account with the ADMINISTRATOR role to change Settings.

How to enable

1. Log in as an administrator.
2. From the sidebar, click Settings.
3. On the AI tab:
   1. Tick AI features enabled.
   2. Choose a Provider (OpenAI, Anthropic, or Ollama).
   3. Enter the model name for that provider (defaults: gpt-4o-mini, claude-haiku-4-5, llama3.1).
   4. Paste the API key for the chosen provider (Ollama: set the base URL instead, default http://localhost:11434).
   5. Optionally adjust request timeout (default 30s) and log tail lines (default 150) used for scan diagnoses.
   6. Leave the feature toggles (Scan-failure diagnosis / Ask uControl / Daily digest) at their defaults unless you want to disable specific features.
4. Click Save AI settings.
5. Restart the service: sudo systemctl restart ucontrolinsight (or your operating system's equivalent). API keys, provider and model changes only take effect after restart.

How to verify it's working

• From the sidebar → AI Chat: ask "how many active assets do you have?". A response within ~10 seconds means the chat path and provider connection are working.
• Open any asset's detail page: four purple buttons (Impact Analysis, Generate Runbook, Classify for unknown endpoints, Suggest Links) should appear in the header.
• Open AI → Insights: the executive summary card and per-insight narration rows should render with their narrations on first generate.

Capabilities reference

1. Ask uControl — natural-language assistant

What it does: Answer free-text questions about your assets, topology and discovery runs by calling read-only tools (search assets, list runs, get topology, etc.) and narrating the answer in plain English.

Where: Sidebar → AI Chat. Conversations are kept in memory for the duration of the session.

Try: "show me hypervisors in DR", "which scans failed yesterday and why", "list the AWS accounts I have onboarded".

2. Smart Search

What it does: Turns free-text on the Assets page into structured filter parameters (category, type, site, status). The AI's interpretation is shown above the results so operators can see how their query was parsed.

Where: Top of the Assets page, in the purple bar marked "Smart search".

Try: "windows hosts in London", "vmware esxi servers not seen in a week", "network devices in primary DC".

3. AI Scan-failure Diagnosis

What it does: When a discovery scan finishes with errors, an AI diagnosis is generated automatically. It includes: a one-paragraph summary, root-cause categorisation, recommended actions, and a confidence score.

Where:

• On the discovery run detail page — the AI Diagnosis card.
• On the Discovery Runs list — rows with diagnosis available show a purple AI Diagnosis pill.
• In Microsoft Teams alerts — the diagnosis is included in the Adaptive Card if Teams notifications are enabled.

4. Impact Analysis — "what would break if…"

What it does: Reads the asset's structural relationships (HOSTS_VM, USES_DATASTORE, etc.) and flow peers from the last 24 hours, then narrates which other assets depend on it, calls out single points of failure, and proposes recovery steps. Severity is rated CRITICAL / HIGH / MEDIUM / LOW / MINIMAL.

Where: Asset detail page → purple Impact Analysis button in the header. Opens a modal.

5. Asset Runbook

What it does: Generates a copy-pasteable operational runbook for the asset: overview, monitoring touchpoints, backup expectations, restart procedure, common failures.

Where: Asset detail page → purple Generate Runbook button. Click Copy markdown in the result modal to capture the text.

6. Suggest Links — AI-proposed topology relationships

What it does: Proposes relationships the deterministic topology graph may have missed (e.g. a VM that probably belongs to a hypervisor based on hostname patterns and shared site). Each suggestion has a type, direction, confidence and rationale.

Where: Asset detail page → Suggest Links button.

Note: v1 is suggest-only — create the relationship manually if you agree with the suggestion. Direct apply will land in a future release.

7. Classify endpoint — AI asset-type suggestion

What it does: For an UNKNOWN_ENDPOINT asset (typically a host discovered by IP scan but not credentialled), uses the open-ports profile, SSH banner, SNMP sysDescr, MAC OUI vendor and hostname pattern to suggest a specific asset type plus the connector + credential type operators should set up to scan it properly.

Where: Asset detail page (for UNKNOWN_ENDPOINT only) → Classify button. Apply suggestion updates the asset's type fields directly.

8. AI Insights — per-insight narration + executive summary

What it does: The Aha Engine v2 detects patterns (stale assets, cost opportunities, lifecycle issues, etc.) and the AI layer narrates each one with a plain-English rationale, recommended action and urgency. A separate executive summary correlates across all current insights.

Where: Sidebar → AI Insights page.

9. Daily AI Digest (Microsoft Teams)

What it does: Once a day (default 08:00), uControl posts an Adaptive Card to the configured Teams webhook summarising the state of the estate — headline, highlights bullet list, and recommended actions. Operators can also fire it on demand.

Where: Microsoft Teams (the channel where your uControl bot is installed). On-demand button: AI Insights page → Send now.

Prerequisite: Microsoft Teams Integration must be configured — see the "Microsoft Teams Integration" page in the documentation.

10. Flow-Anomaly Detection

What it does: Every hour, uControl scans the last hour of NetFlow/IPFIX data for new communication patterns — (asset, peer, destination port, protocol) tuples not seen in the previous 7 days on well-known service ports (SSH, HTTPS, SMB, RDP, WinRM, SNMP, etc.). Each new conversation is flagged and narrated ("Previously-unseen RDP from an external host — possible administrative attempt from outside the normal pattern").

Where: Asset detail page → ✨ New flow peers card. Click Acknowledge to clear an entry once you've checked it.

Prerequisites: Network Flow Monitoring must be configured — see that documentation page. Without flow data the card will simply stay empty.

Choosing a provider

Switching providers is a one-line change in the Settings → AI panel followed by a service restart. Existing AI features will use the new provider for their next call.

Cost & limits

• Most features make one call per click (Impact, Runbook, Classify, Insight narration). Daily digest is one call per day. Smart search is one call per query.
• Scan diagnoses run once per failing discovery run.
• Flow-anomaly narrations run only when a new anomaly is detected — typically a handful per day on a steady estate.
• If you want to cap exposure, set the Request timeout low or use a lower-tier model.

11. Risk Scoring

What it does: Ranks every asset in your inventory by a combined risk score out of 100 — exposure (flow peer count + distinct service ports observed in the last 7 days) plus impact (how critical the asset role is — hypervisors, virtualisation managers, clusters and storage rate highest) plus lifecycle (STALE, INACTIVE or repeated scan failures add risk; DECOMMISSIONED reduces it). Use it to spot where to focus hardening, monitoring or remediation effort.

Where: Sidebar → AI Risk. The top-20 risky assets are shown by default; bump the limit query parameter for more.

Prerequisites: Asset inventory (any), plus — for the exposure score to be meaningful — some NetFlow / IPFIX data flowing in (see Network Flow Monitoring). Aging contributions need the Asset Aging sweeper to have run at least once.

Note: v1 shows a heuristic "Reason" string per row.

---

AI usage & cost tracking

Every chat call uControl Insight makes is recorded automatically — timestamp, provider, model, prompt tokens, completion tokens, total tokens, latency, success/failure. Nothing the operator has to switch on; it just works as soon as the AI features are enabled.

Where you see it: Sidebar → Settings → AI tab. Below the configuration form you'll find:

• This-month totals (calls, prompt tokens, completion tokens, total tokens).
• A 30-day daily breakdown table.

Combine these with your provider's per-token pricing for cost estimates — OpenAI and Anthropic publish current rates on their pricing pages.

How it works under the hood: a Spring AI BaseAdvisor implementation registered as a default advisor on the shared ChatClient bean. Every call routes through it transparently — no per-feature instrumentation needed. Writes happen on virtual threads so a slow DB never blocks the chat response.