Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Troubleshooting › AI Preview

AI Preview

AI Preview failures

Status: PREVIEW (off by default). Not dedicated GA AI. Not autonomous enforcement.

EnterpriseAudience: Enterprise administrator, security engineer

Symptom

  • No AI screens or GET /api/v1/ai/status shows disabled
  • Provider connection test fails
  • Analysis/explain refused
  • Recommendation “approved” but no live rule
  • Concern that a provider key appeared in the browser

Community has no AI Preview product path. Do not look for Community AI routes.

Likely verified causes

  1. ai.enabled: false (example default) or license/entitlement missing.
  2. Provider class is not openai_compatible (only supported provider class).
  3. ai.model empty while enabled (validation requires a model when ai.enabled=true).
  4. offline_mode: true (example default): v1 model endpoint validation is loopback-only.
  5. allow_private_provider_networks still false while the endpoint is non-loopback private (high-risk override, default false; requires offline_mode=false).
  6. Hosting sources used as analysis input — Hosting is ineligible for automatic/provider AI.
  7. SSRF / URL policy rejected the endpoint.
  8. Rate limit (rate_limit_per_admin_per_minute: 10, max_concurrent_requests: 2 in example).
  9. Operator expected approval to apply a rule. Approval records review intent only. There is no apply/enforce/create-rule AI route. EnforcementApplied is not a live apply path.
  10. ai.require_human_approval or ai.redact.enabled set false — Manager refuses to enable AI (must be true when ai.enabled=true). Same for mask_usernames, mask_private_ips, mask_hostnames, ai.audit.enabled.

Do not diagnose via internal AI development endpoints. Those exist in source, default off, and are not customer GA features.

Diagnostic commands/endpoints

Admin auth.

GET  /api/v1/ai/status
GET  /api/v1/ai/providers
POST /api/v1/ai/providers
POST /api/v1/ai/providers/:id/test-connection
POST /api/v1/ai/security-logs/:id/explain
POST /api/v1/ai/incidents/analyze
GET  /api/v1/ai/recommendations
POST /api/v1/ai/recommendations/:id/approve
POST /api/v1/ai/recommendations/:id/reject
POST /api/v1/ai/rules/draft

Manual analysis: /api/v1/ai/manual-analysis/*.

Do not call internal AI development endpoints, or publicize credential-custody APIs as unauthenticated website material.

Config example (configs/manager.example.yml):

ai:
  enabled: false
  provider: "openai_compatible"
  base_url: "http://127.0.0.1:8000/v1"
  require_human_approval: true
  offline_mode: true
  allow_private_provider_networks: false
  redact:
    enabled: true
    mask_usernames: true
    mask_private_ips: true
    mask_hostnames: true

Provider keys: Manager-side only (systemd credential / Manager secret source). Browser must not hold the key.

What each result means

Scroll sideways to see the full table. Use the arrow keys when focused.

ResultMeaning
Community / no AI routesEdition. AI Preview is Enterprise.
Status disabled / ai.enabled falseExpected until explicitly enabled after operator approval.
Config fatal ai.require_human_approval must be trueProduct-enforced. Cannot run AI without human approval.
Config fatal ai.redact.enabled must be true (or mask flags)Product-enforced redaction. Do not disable.
Config fatal ai.training_export.enabledDeferred/non-production; runtime rejects it.
Connection test fail on http://127.0.0.1:8000/v1 with no local serverOffline-mode loopback policy: start a local compatible server or complete owner approval to change policy.
Connection test fail to a public HTTPS provider while offline_mode: trueEndpoint is not loopback; policy denies it.
Explain/analyze refused on Hosting eventsHosting sources excluded from automatic/provider analysis.
429 / rate messagesExample 10 requests/admin/minute, 2 concurrent.
Approve 200 but no dataplane changeExpected. Apply a real rule through RULES.
Provider key in browser or in a ticketIncident: stop; keys are Manager-side only.
License 403 LicenseErrorResponseEntitlement gate. Do not invent SKU text.

Safe remediation

  1. Confirm Enterprise Manager and license features (no public SKU names).
  2. Keep AI off until provider, data-handling, and retention are approved.
  3. Use an OpenAI-compatible endpoint. In default offline mode, that is loopback.
  4. Store the key in Manager-side custody, never YAML, never the browser.
  5. Keep require_human_approval: true and redaction flags true.
  6. Analyze eligible (non-Hosting) events.
  7. After approval of a recommendation, create/assign a rule on a Virtualization Agent through the ordinary rule path.
  8. If a provider key was observed in a browser: rotate the provider credential; treat as a security incident.

Do-not-do warnings

  • Do not document internal AI development endpoints as customer features.
  • Do not claim autonomous blocking or “AI-powered SOC.”
  • Do not disable redaction or human approval to “make it work.”
  • Do not send Hosting raw or category events to a provider automatically.
  • Do not put API keys in example curl argv or frontend storage.
  • Do not treat approval as enforcement.
  • Do not enable allow_private_provider_networks without an explicit owner review (SSRF/privacy).
  • Do not document first-class xAI/Claude/Gemini/Azure OpenAI product integrations.

Escalation condition

Escalate when:

  • AI is enabled with a loopback compatible server, redaction on, human approval on, eligible events selected, and test-connection still fails without an SSRF/policy reason in Manager logs (redact secrets before sending logs)
  • a provider key is observed outside Manager-side storage
  • anyone requests documentation of internal AI development endpoints as GA — refuse; those endpoints are not customer features

Edition

ENTERPRISE_ONLY. Community: not applicable.

Status

PREVIEW. Advisory only. Product-enforced: human approval and redaction when enabled. NOT_SUPPORTED: autonomous apply, or treating internal AI development endpoints as customer features.