Local AI & Model Governance

The AI features across the product (candidate scoring, report review, plain-English search of logs and the cloud map, finding explanations, workflow and compliance drafting) run against a local AI engine (Ollama) on your own instance — the prompt and the data in it are not sent to an outside AI service.

The Three Controls

An administrator has three controls over it: which model is active (limited to a fixed list of approved models, so the setting cannot be used to reach an outside server), a switch that turns AI off for the whole instance, and an optional rule that only people who have been given an explicit AI permission may use it. All three are under Security Settings → AI Model.

Why The Model Is A Locked List, Not A Text Field

“The AI runs locally, nothing leaves your server” is only true if the server cannot be told to fetch a model from somewhere else. A model name can point at an outside server — so a free-text model box would let an administrator (or anyone who took over an administrator account) name a model on an attacker-controlled host, and the moment the instance downloaded it, it would have opened an outbound channel to that host. Zonitix closes that door by only accepting a model from a short pre-approved list. Anything else is refused before it reaches the AI engine, and the refusal is written to the audit log.

If something here is not working as you expect, start with When something goes wrong.

Setting The Active Model

The active model is a security setting, changed through the same guarded settings endpoint as MFA and access-control policy. Writing it needs the manage_security permission and a fresh step-up. A step-up counts for 15 minutes. The server reads the window from a stored setting, sudoTimeoutMinutes, and holds any value between 1 and 60 minutes, but no screen and no API route writes that setting, so every instance uses 15 minutes. A missing or expired step-up is refused with "error": "SUDO_REQUIRED" in the response body. The status beside it is 400 on most routes, because the gateway turns a 401 from a service behind it into 400. It stays 401 on the routes the gateway passes through unchanged: removing a passkey, the diagnostics bundle, and in Security Lab starting an aggressive scan, changing a scan scope and archiving findings. Key on the error string, not the status. On this route the status is 400. Reading the setting back is broader: manage_security, view_users, or view_dashboard. Each AI feature is gated separately, on the permission of the feature it belongs to (table below).

Which Permission Each AI Feature Needs

There is no single “use AI” route. Every AI feature has its own route under /api/v1/ai/, and each checks the permission of the screen it serves, so AI never shows a person data that screen would not. Where two permissions are listed, either one is enough. With Require explicit AI permission on, use_ai is needed as well for every feature route, except for people with the administrator role; anyone else is refused with 403. The two AI Model settings routes (/model-status and /model-capability) are not subject to that rule or to the AI off switch, so they still answer when AI is off.

The Allowlist Guard

The allowlist is built once from AI_MODELS (a whitespace-separated env list) plus DEFAULT_AI_MODEL. A submitted activeAiModel is accepted only if it is a non-empty string, carries no slash, whitespace, or scheme (so it is a bare name:tag, never host/path:tag or https://…), and is a member of that set. The check runs before any setting is written, so a bad value never touches the settings store or the AI engine. The same guard covers per-task routing (aiModelRouting): the scoring, calibration and justification tasks can each be pointed at a model, and every routed value must be on the same allowlist.

How An Inspector Verifies It

• Send a hostile model ref and confirm it is refused. A POST with { "activeAiModel": "evil.example.com/x/y:tag" } must return 400 with an “Unsupported AI model” error, and the stored activeAiModel (via GET) must be unchanged. A scheme (https://…) or a slash in the ref is rejected on shape alone, before the set lookup.
• Check the audit trail. Every rejection writes an AI_MODEL_REJECTED log at warning level naming the attempted value — so an attempt to point the model off-box is visible after the fact, not silent.
• Confirm the engine is local. OLLAMA_URL resolves to the compose-internal engine (default http://ollama:11434). Pulls and inference go to that address; there is no hosted-AI credential and no third-party API host in the AI path.
• Confirm the write is step-up gated. A POST to /settings/security without a recent step-up returns 400 with "error": "SUDO_REQUIRED", regardless of the model value.
• Confirm the off switch is enforced server-side. With aiEnabled false, an AI request returns 503 with { aiDisabled: true }. With aiRequireUsePermission true, a non-administrator without use_ai gets 403. Both are checked in the AI service itself, not only hidden in the interface. Only an explicit stored “off” disables AI: if the settings lookup itself fails, AI stays available.