Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(settings): add Deployment & AI panel for air-gap + LLM visibility

beenu77e76d0731c3
diff --git a/apps/docs/docs/operations/airgap.md b/apps/docs/docs/operations/airgap.md
index 8c3339edb..30dd1dda2 100644
--- a/apps/docs/docs/operations/airgap.md
+++ b/apps/docs/docs/operations/airgap.md
@@ -132,6 +132,51 @@ The endpoint returns no secrets — only the boolean `enabled` flag, the
operator-supplied allowlist, the implicit private suffixes, and a
human-readable `policy` field suitable for embedding in audit reports.
+### LLM provider snapshot
+
+There is a companion endpoint at `GET /api/v1/llm/status` that returns the
+live LLM provider snapshot — model, base URL, host, whether an API key is
+set, whether the host would be permitted by the egress gate at request
+time, and whether Explain would currently take the live path or the
+deterministic OCSF/MITRE fallback path. The endpoint mirrors the same
+classification function the runtime uses, so the indicator cannot drift
+from real behaviour:
+
+```bash
+curl -s http://aisoc-api.internal/api/v1/llm/status | jq
+{
+ "provider": "local-ollama",
+ "model": "llama3.1:8b",
+ "base_url": "http://ollama:11434/v1",
+ "host": "ollama",
+ "key_set": true,
+ "airgap_enabled": true,
+ "airgap_compliant": true,
+ "is_local": true,
+ "effective_path": "live",
+ "policy_note": "Local LLM in use; air-gap policy is satisfied."
+}
+```
+
+The API key itself is **never** returned — not even partially redacted.
+Only the boolean `key_set` flag is surfaced.
+
+### Settings UI surface
+
+The same two endpoints back the read-only **Settings → Deployment & AI**
+panel in the AiSOC web UI. Operators and auditors can use that panel
+during a walk-through to confirm at a glance:
+
+- Air-gap is enabled on this pod.
+- The configured LLM host is air-gap compliant (in the allowlist or
+ classified as private).
+- Explain would currently take the live LLM path, not the deterministic
+ fallback.
+
+Mutations are deliberately not exposed there — air-gap and LLM
+configuration is deploy-time only, set via environment variables and a
+service restart.
+
## Plugging in a local LLM
AiSOC's investigator agent, NL detection authoring, NL query, phishing
diff --git a/apps/web/src/components/settings/SettingsView.tsx b/apps/web/src/components/settings/SettingsView.tsx
index 1349d0903..d8fa3dc31 100644
--- a/apps/web/src/components/settings/SettingsView.tsx
+++ b/apps/web/src/components/settings/SettingsView.tsx
@@ -24,11 +24,20 @@ import { clsx } from 'clsx';
import { motion, AnimatePresence } from 'framer-motion';
import { format, formatDistanceToNow } from 'date-fns';
import toast from 'react-hot-toast';
-import { connectorsApi, type Connector, type ConnectorStatus } from '@/lib/api';
+import {
+ connectorsApi,
+ deploymentApi,
+ type AirgapStatus,
+ type Connector,
+ type ConnectorStatus,
+ type LlmProvider,
+ type LlmStatus,
+} from '@/lib/api';
import { Skeleton } from '@/components/ui/Skeleton';
import { ErrorState } from '@/components/ui/ErrorState';
import { EmptyState } from '@/components/ui/EmptyState';
import { AutonomyPolicyPanel } from '@/components/settings/AutonomyPolicy';
+import { useTheme, type ThemePreference } from '@/components/theme/ThemeProvider';
// ─── Types ────────────────────────────────────────────────────────────────────
@@ -40,6 +49,7 @@ type TabId =
| 'api-keys'
| 'notifications'
| 'appearance'
+ | 'deployment'
| 'audit'
| 'about';
@@ -324,6 +334,12 @@ const TABS: { id: TabId; label: string; description: string }[] = [
label: 'Appearance',
description: 'Theme, density, animations.',
},
+ {
+ id: 'deployment',
+ label: 'Deployment & AI',
+ description:
+ 'Live air-gap policy and LLM provider snapshot for this AiSOC pod.',
+ },
{
id: 'audit',
label: 'Audit log',
@@ -402,6 +418,7 @@ export function SettingsView() {
{tab === 'api-keys' && <ApiKeysPanel />}
{tab === 'notifications' && <NotificationsPanel />}
{tab === 'appearance' && <AppearancePanel />}
+ {tab === 'deployment' && <DeploymentAIPanel />}
{tab === 'audit' && <AuditPanel />}
{tab === 'about' && <AboutPanel />}
</motion.div>
@@ -1169,6 +1186,8 @@ function NotificationsPanel() {
function AppearancePanel() {
const [prefs, setPrefs] = useState<Preferences>(DEFAULT_PREFS);
+ const { preference: themePreference, setPreference: setThemePreference } =
+ useTheme();
useEffect(() => {
setPrefs(loadPreferences());
@@ -1182,6 +1201,16 @@ function AppearancePanel() {
});
};
+ // Theme is owned by the global ThemeProvider (it sets `data-theme` on
+ // <html>, primes the FOUC script, and persists to its own storage key).
+ // We mirror it into the legacy `prefs.theme` slot so settings exports stay
+ // accurate, but `useTheme()` is the source of truth for what the operator
+ // sees on screen.
+ const onThemeSelect = (next: ThemePreference) => {
+ setThemePreference(next);
+ update('theme', next);
+ };
+
return (
<div>
<PanelHeader
@@ -1193,24 +1222,23 @@ function AppearancePanel() {
<div>
<p className="text-sm font-medium text-gray-300">Theme</p>
<p className="mt-1 text-xs text-gray-500">
- AiSOC ships dark-first; light mode coming soon.
+ Pick the palette this browser uses. Stored locally — no server
+ round-trip.
</p>
<div className="mt-3 grid grid-cols-3 gap-3">
- {(['system', 'dark', 'light'] as const).map((t) => {
- const active = prefs.theme === t;
- const disabled = t === 'light';
+ {(['system', 'dark', 'light'] as const satisfies readonly ThemePreference[]).map((t) => {
+ const active = themePreference === t;
return (
<button
key={t}
type="button"
- disabled={disabled}
- onClick={() => update('theme', t)}
+ onClick={() => onThemeSelect(t)}
+ aria-pressed={active}
className={clsx(
'rounded-xl border p-3 text-left transition-colors',
active
? 'border-blue-500/60 bg-blue-500/10'
: 'border-gray-800 bg-gray-950/40 hover:border-gray-700',
- disabled && 'cursor-not-allowed opacity-40',
)}
>
<span className="block text-sm font-medium capitalize text-gray-100">
@@ -1221,7 +1249,7 @@ function AppearancePanel() {
? 'Match OS preference'
: t === 'dark'
? 'Operations-room dark'
- : 'Coming soon'}
+ : 'High-contrast light'}
</span>
</button>
);
@@ -1273,6 +1301,338 @@ function AppearancePanel() {
);
}
+// ─── Panel: Deployment & AI ───────────────────────────────────────────────────
+//
+// Read-only operator visibility for two questions that are always asked during
+// security review:
+//
+// 1. "Is air-gap actually engaged on this pod?" → /api/v1/airgap/status
+// 2. "Where will my AI calls actually go?" → /api/v1/llm/status
+//
+// Both endpoints are server-rendered snapshots that mirror the same code paths
+// the runtime uses to gate egress (``app.core.airgap.is_host_allowed_for_airgap``)
+// and to pick the LLM transport (``services/agents/app/api/explain.py``). That
+// is deliberate: the indicator the operator sees here CANNOT drift from runtime
+// behaviour — there is no second source of truth.
+//
+// This panel never accepts input. It is purely a diagnostic surface; mutations
+// happen out-of-band (env vars, deploy-time config, BYOK rotation).
+
+const PROVIDER_LABEL: Record<LlmProvider, string> = {
+ openai: 'OpenAI',
+ anthropic: 'Anthropic',
+ 'azure-openai': 'Azure OpenAI',
+ 'local-ollama': 'Local Ollama',
+ 'local-vllm': 'Local vLLM',
+ 'local-litellm': 'Local LiteLLM',
+ custom: 'Custom endpoint',
+ none: 'Not configured',
+};
+
+function DeploymentAIPanel() {
+ const airgap = useSWR(
+ 'settings:airgap-status',
+ () => deploymentApi.getAirgapStatus(),
+ { revalidateOnFocus: false, shouldRetryOnError: false },
+ );
+ const llm = useSWR(
+ 'settings:llm-status',
+ () => deploymentApi.getLlmStatus(),
+ { revalidateOnFocus: false, shouldRetryOnError: false },
+ );
+
+ const isLoading = airgap.isLoading || llm.isLoading;
+ const error = airgap.error ?? llm.error;
+ const onRetry = () => {
+ airgap.mutate();
+ llm.mutate();
+ };
+
+ return (
+ <div>
+ <PanelHeader
+ title="Deployment & AI"
+ description="Live air-gap policy and LLM provider snapshot for this AiSOC pod. Read-only."
+ />
+ <div className="space-y-5 px-6 py-5">
+ {isLoading && !airgap.data && !llm.data ? (
+ <div className="space-y-3">
+ {Array.from({ length: 3 }).map((_, i) => (
+ <Skeleton key={i} className="h-24 w-full rounded-lg" />
+ ))}
+ </div>
+ ) : error ? (
+ <ErrorState
+ title="Could not load deployment status"
+ error={error}
+ onRetry={onRetry}
+ />
+ ) : (
+ <>
+ {airgap.data ? <AirgapCard status={airgap.data} /> : null}
+ {llm.data ? (
+ <LlmCard llm={llm.data} airgap={airgap.data ?? null} />
+ ) : null}
+ <p className="text-xs text-gray-500">
+ These values are sampled live from this pod and mirror the egress
+ gate exactly. To change them, update environment variables and
+ redeploy. See{' '}
+ <a
+ href="https://beenuar.github.io/AiSOC/docs/operations/airgap/"
+ target="_blank"
+ rel="noreferrer"
+ className="text-blue-400 hover:text-blue-300 hover:underline"
+ >
+ Air-gapped deployments
+ </a>
+ .
+ </p>
+ </>
+ )}
+ </div>
+ </div>
+ );
+}
+
+function AirgapCard({ status }: { status: AirgapStatus }) {
+ return (
+ <section
+ className="rounded-xl border border-gray-800 bg-gray-950/40 p-5"
+ aria-label="Air-gap policy"
+ >
+ <header className="flex items-start justify-between gap-3">
+ <div>
+ <h3 className="text-sm font-semibold text-gray-100">Air-gap policy</h3>
+ <p className="mt-1 text-xs text-gray-500">
+ Enforced by the egress gate before any outbound HTTP request.
+ </p>
+ </div>
+ <StatusPill
+ tone={status.enabled ? 'emerald' : 'gray'}
+ label={status.enabled ? 'Enabled' : 'Disabled'}
+ />
+ </header>
+
+ <dl className="mt-4 grid grid-cols-1 gap-3 sm:grid-cols-2">
+ <KeyValue label="Policy">{status.policy}</KeyValue>
+ <KeyValue label="Operator allowlist">
+ {status.allowlist.length > 0 ? (
+ <div className="flex flex-wrap gap-1.5">
+ {status.allowlist.map((host) => (
+ <code
+ key={host}
+ className="rounded bg-gray-900 px-1.5 py-0.5 font-mono text-[11px] text-gray-200"
+ >
+ {host}
+ </code>
+ ))}
+ </div>
+ ) : (
+ <span className="text-gray-500">— none configured —</span>
+ )}
+ </KeyValue>
+ <KeyValue label="Always-allowed private suffixes">
+ <div className="flex flex-wrap gap-1.5">
+ {status.implicit_private_suffixes.map((suffix) => (
+ <code
+ key={suffix}
+ className="rounded bg-gray-900 px-1.5 py-0.5 font-mono text-[11px] text-gray-400"
+ >
+ {suffix}
+ </code>
+ ))}
+ </div>
+ </KeyValue>
+ </dl>
+ </section>
+ );
+}
+
+function LlmCard({
+ llm,
+ airgap,
+}: {
+ llm: LlmStatus;
+ airgap: AirgapStatus | null;
+}) {
+ const providerLabel = PROVIDER_LABEL[llm.provider] ?? llm.provider;
+ const isFallback = llm.effective_path === 'fallback';
+ const blockedByAirgap = llm.airgap_enabled && !llm.airgap_compliant;
+
+ return (
+ <section
+ className="rounded-xl border border-gray-800 bg-gray-950/40 p-5"
+ aria-label="LLM provider"
+ >
+ <header className="flex items-start justify-between gap-3">
+ <div>
+ <h3 className="text-sm font-semibold text-gray-100">LLM provider</h3>
+ <p className="mt-1 text-xs text-gray-500">
+ Where Explain, triage, and other AI features will call out to.
+ </p>
+ </div>
+ <div className="flex flex-wrap items-center gap-2">
+ {llm.is_local ? (
+ <StatusPill tone="emerald" label="Local" />
+ ) : llm.provider === 'none' ? (
+ <StatusPill tone="gray" label="Unconfigured" />
+ ) : (
+ <StatusPill tone="amber" label="Cloud" />
+ )}
+ {isFallback ? (
+ <StatusPill tone="amber" label="Fallback path" />
+ ) : (
+ <StatusPill tone="emerald" label="Live" />
+ )}
+ </div>
+ </header>
+
+ {blockedByAirgap ? (
+ <div
+ role="alert"
+ className="mt-4 rounded-lg border border-red-500/40 bg-red-500/10 p-3 text-xs text-red-200"
+ >
+ <p className="font-semibold text-red-100">
+ Air-gap policy is blocking this LLM host.
+ </p>
+ <p className="mt-1">
+ <code className="font-mono">{llm.host || '—'}</code> is not in the
+ operator allowlist. Live AI calls will refuse and Explain will fall
+ back to the deterministic OCSF/MITRE summary. Add the host to{' '}
+ <code className="font-mono">AISOC_AIRGAP_ALLOWLIST</code> or switch
+ to a private LLM endpoint.
+ </p>
+ </div>
+ ) : isFallback && llm.provider !== 'none' ? (
+ <div
+ role="alert"
+ className="mt-4 rounded-lg border border-amber-500/40 bg-amber-500/10 p-3 text-xs text-amber-200"
+ >
+ <p className="font-semibold text-amber-100">
+ Falling back to deterministic summaries.
+ </p>
+ <p className="mt-1">{llm.policy_note}</p>
+ </div>
+ ) : null}
+
+ <dl className="mt-4 grid grid-cols-1 gap-3 sm:grid-cols-2">
+ <KeyValue label="Provider">{providerLabel}</KeyValue>
+ <KeyValue label="Model">
+ {llm.model ? (
+ <code className="font-mono text-xs text-gray-100">{llm.model}</code>
+ ) : (
+ <span className="text-gray-500">—</span>
+ )}
+ </KeyValue>
+ <KeyValue label="Base URL">
+ {llm.base_url ? (
+ <code className="break-all font-mono text-xs text-gray-200">
+ {llm.base_url}
+ </code>
+ ) : (
+ <span className="text-gray-500">—</span>
+ )}
+ </KeyValue>
+ <KeyValue label="Host">
+ {llm.host ? (
+ <code className="font-mono text-xs text-gray-200">{llm.host}</code>
+ ) : (
+ <span className="text-gray-500">—</span>
+ )}
+ </KeyValue>
+ <KeyValue label="API key">
+ <span
+ className={clsx(
+ 'inline-flex items-center gap-1.5 text-xs',
+ llm.key_set ? 'text-emerald-300' : 'text-gray-400',
+ )}
+ >
+ <span
+ aria-hidden
+ className={clsx(
+ 'inline-block h-1.5 w-1.5 rounded-full',
+ llm.key_set ? 'bg-emerald-400' : 'bg-gray-600',
+ )}
+ />
+ {llm.key_set ? 'Set' : 'Not set'}
+ </span>
+ </KeyValue>
+ <KeyValue label="Air-gap compliant">
+ <span
+ className={clsx(
+ 'inline-flex items-center gap-1.5 text-xs',
+ llm.airgap_compliant ? 'text-emerald-300' : 'text-red-300',
+ )}
+ >
+ <span
+ aria-hidden
+ className={clsx(
+ 'inline-block h-1.5 w-1.5 rounded-full',
+ llm.airgap_compliant ? 'bg-emerald-400' : 'bg-red-400',
+ )}
+ />
+ {airgap && !airgap.enabled
+ ? 'N/A — air-gap off'
+ : llm.airgap_compliant
+ ? 'Yes'
+ : 'No'}
+ </span>
+ </KeyValue>
+ </dl>
+
+ {!blockedByAirgap && !isFallback && llm.policy_note ? (
+ <p className="mt-4 text-xs text-gray-500">{llm.policy_note}</p>
+ ) : null}
+ </section>
+ );
+}
+
+function KeyValue({
+ label,
+ children,
+}: {
+ label: string;
+ children: React.ReactNode;
+}) {
+ return (
+ <div className="flex flex-col gap-1">
+ <dt className="text-[11px] uppercase tracking-wide text-gray-500">
+ {label}
+ </dt>
+ <dd className="text-sm text-gray-200">{children}</dd>
+ </div>
+ );
+}
+
+function StatusPill({
+ tone,
+ label,
+}: {
+ tone: 'emerald' | 'amber' | 'red' | 'gray';
+ label: string;
+}) {
+ const cls = clsx(
+ 'inline-flex items-center gap-1.5 rounded-full border px-2.5 py-0.5 text-[11px] font-medium',
+ tone === 'emerald' && 'border-emerald-500/40 bg-emerald-500/10 text-emerald-200',
+ tone === 'amber' && 'border-amber-500/40 bg-amber-500/10 text-amber-200',
+ tone === 'red' && 'border-red-500/40 bg-red-500/10 text-red-200',
+ tone === 'gray' && 'border-gray-700 bg-gray-900 text-gray-300',
+ );
+ const dotCls = clsx(
+ 'inline-block h-1.5 w-1.5 rounded-full',
+ tone === 'emerald' && 'bg-emerald-400',
+ tone === 'amber' && 'bg-amber-400',
+ tone === 'red' && 'bg-red-400',
+ tone === 'gray' && 'bg-gray-500',
+ );
+ return (
+ <span className={cls}>
+ <span aria-hidden className={dotCls} />
+ {label}
+ </span>
+ );
+}
+
// ─── Panel: Audit ─────────────────────────────────────────────────────────────
function AuditPanel() {
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index 3b8973ea0..1d3b36bd2 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -2901,6 +2901,78 @@ export const feedbackApi = {
summary: () => request<OverrideSummary>('/api/v1/feedback/summary'),
};
+// ─── Deployment & AI (air-gap + LLM provider snapshot) ───────────────────────
+//
+// Read-only operator visibility for "where will my AI calls actually go?" and
+// "is air-gap actually engaged on this pod?". Both endpoints are unauthenticated
+// snapshots that mirror the same code paths the runtime uses to gate egress
+// (``app.core.airgap.is_host_allowed_for_airgap``) and pick the LLM transport
+// (``services/agents/app/api/explain.py``), so the indicator the operator sees
+// in the Settings → "Deployment & AI" panel cannot drift from runtime behaviour.
+
+export interface AirgapStatus {
+ /** True when AISOC_AIRGAPPED is set; the egress gate is enforcing. */
+ enabled: boolean;
+ /** Operator-supplied AISOC_AIRGAP_ALLOWLIST entries. */
+ allowlist: string[];
+ /** Always-allowed private/internal suffixes (.local, .internal, ...). */
+ implicit_private_suffixes: string[];
+ /** Human-readable summary suitable for audit reports. */
+ policy: string;
+}
+
+export type LlmProvider =
+ | 'openai'
+ | 'anthropic'
+ | 'azure-openai'
+ | 'local-ollama'
+ | 'local-vllm'
+ | 'local-litellm'
+ | 'custom'
+ | 'none';
+
+export type LlmEffectivePath = 'live' | 'fallback';
+
+export interface LlmStatus {
+ /** Stable provider id classified from the configured base URL. */
+ provider: LlmProvider;
+ /** LLM_MODEL / OPENAI_MODEL / AISOC_LLM_MODEL — empty string when unset. */
+ model: string;
+ /** Configured base URL (LLM_BASE_URL or OPENAI_BASE_URL). Empty when unset. */
+ base_url: string;
+ /** Hostname extracted from base_url (lowercased), or "" when no base_url. */
+ host: string;
+ /**
+ * Whether ``OPENAI_API_KEY`` / ``LLM_API_KEY`` is set. The key itself is
+ * never returned — even partially redacted.
+ */
+ key_set: boolean;
+ /** Mirrors AirgapStatus.enabled. */
+ airgap_enabled: boolean;
+ /**
+ * Whether the configured LLM host would be permitted by the egress gate at
+ * request time. Always true when air-gap is OFF or no LLM is configured.
+ */
+ airgap_compliant: boolean;
+ /** Best-effort "this is clearly a local LLM" hint for the UI badge. */
+ is_local: boolean;
+ /**
+ * Which branch the Explain endpoint would actually take right now:
+ * ``live`` = real LLM call, ``fallback`` = deterministic OCSF/MITRE summary.
+ */
+ effective_path: LlmEffectivePath;
+ /** Operator-readable explanation of the current state. */
+ policy_note: string;
+}
+
+export const deploymentApi = {
+ /** Live air-gap policy snapshot for this pod. Safe to poll. */
+ getAirgapStatus: () => request<AirgapStatus>('/api/v1/airgap/status'),
+
+ /** Live LLM provider snapshot. Mirrors the egress gate's classification. */
+ getLlmStatus: () => request<LlmStatus>('/api/v1/llm/status'),
+};
+
// ─── Realtime / WebSocket helpers ────────────────────────────────────────────
export const realtimeApi = {
@@ -2943,4 +3015,5 @@ export default {
passkey: passkeyApi,
autonomyPolicy: autonomyPolicyApi,
feedback: feedbackApi,
+ deployment: deploymentApi,
};
diff --git a/services/api/app/api/v1/endpoints/llm_status.py b/services/api/app/api/v1/endpoints/llm_status.py
new file mode 100644
index 000000000..1fc909fac
--- /dev/null
+++ b/services/api/app/api/v1/endpoints/llm_status.py
@@ -0,0 +1,246 @@
+"""LLM provider status endpoint — Tier 3.1 (operator visibility).
+
+Exposes a redacted snapshot of the active LLM configuration so operators
+and auditors can verify the runtime LLM provider, model, and air-gap
+compliance without shelling into a pod or grepping ``.env``. The
+endpoint mirrors the shape of ``/api/v1/airgap/status`` and is paired
+with the new "Deployment & AI" Settings panel in the web app
+(WS-H2 visibility slice / WS-H4 air-gap operator UX).
+
+Contract
+--------
+
+* **Read-only.** No knobs to flip, no secrets returned. The API key
+ itself is never serialized — only ``key_set: bool``.
+* **Best-effort.** When the operator hasn't set ``OPENAI_API_KEY`` /
+ ``OPENAI_BASE_URL``, the endpoint reports ``provider="none"`` and
+ ``effective_path="fallback"`` so the UI can clearly say
+ "running on deterministic fallback".
+* **Air-gap aware.** Reuses ``app.core.airgap.is_host_allowed_for_airgap``
+ so the answer to "would my LLM call actually leave the pod under the
+ current air-gap policy?" comes from the *same* code path that gates
+ egress at request time. No drift between the indicator and reality.
+
+Why we don't reuse ``deployment.get_airgap_status``
+---------------------------------------------------
+
+``app.api.v1.endpoints.deployment.get_airgap_status`` is an in-memory
+mock for a UI that hasn't shipped yet. This endpoint deliberately reads
+the *real* env-var-driven config so the indicator the operator sees in
+Settings matches the policy the gateway enforces. They will eventually
+converge once per-tenant overrides exist (v1.1 BYOK).
+"""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import urlparse
+
+from fastapi import APIRouter
+
+from app.core.airgap import is_host_allowed_for_airgap
+from app.core.config import settings
+
+router = APIRouter(prefix="/llm", tags=["llm"])
+
+# Map known hostnames → human-readable provider names so the UI doesn't
+# have to do its own substring matching. Order matters only for the
+# substring tier (entries earlier in the tuple win).
+_HOSTED_PROVIDERS: dict[str, str] = {
+ "api.openai.com": "openai",
+ "api.anthropic.com": "anthropic",
+}
+
+_HOSTED_SUBSTRINGS: tuple[tuple[str, str], ...] = (
+ (".openai.azure.com", "azure-openai"),
+ (".azureapi.net", "azure-openai"),
+ (".anthropic.com", "anthropic"),
+ ("ollama", "local-ollama"),
+ ("vllm", "local-vllm"),
+ ("litellm", "local-litellm"),
+)
+
+
+def _classify_provider(base_url: str) -> str:
+ """Return a stable provider id for the given base URL.
+
+ Returns ``"none"`` when the operator hasn't configured a base URL
+ *and* hasn't set ``OPENAI_API_KEY`` (i.e. the explain path is
+ forced onto the deterministic fallback).
+ """
+ if not base_url:
+ # No explicit base — treat as the OpenAI default, unless the
+ # caller has also blanked the API key (handled by ``provider``
+ # logic below).
+ return "openai"
+
+ host = (urlparse(base_url).hostname or "").lower()
+ if not host:
+ return "custom"
+
+ if host in _HOSTED_PROVIDERS:
+ return _HOSTED_PROVIDERS[host]
+
+ for needle, provider in _HOSTED_SUBSTRINGS:
+ if needle in host:
+ return provider
+
+ return "custom"
+
+
+def _is_loopback_or_private_host(host: str) -> bool:
+ """Cheap "is this clearly a local LLM" classifier for the UI badge.
+
+ We don't want to claim "running locally" for a host the operator
+ just happened to put in ``AISOC_AIRGAP_ALLOWLIST`` (e.g. an internal
+ SaaS gateway), so this is intentionally narrower than the full
+ air-gap host classifier.
+ """
+ if not host:
+ return False
+ host = host.lower().strip()
+ if host in {"localhost", "127.0.0.1", "::1"}:
+ return True
+ # Bare service name with no dots (docker-compose: "ollama") is local.
+ if "." not in host:
+ return True
+ if host.endswith(".local") or host.endswith(".internal") or host.endswith(".lan"):
+ return True
+ return False
+
+
+def llm_status() -> dict[str, object]:
+ """Return the live LLM provider snapshot.
+
+ Shape::
+
+ {
+ "provider": "local-ollama",
+ "model": "llama3.1:8b",
+ "base_url": "http://ollama:11434/v1",
+ "host": "ollama",
+ "key_set": false,
+ "airgap_enabled": true,
+ "airgap_compliant": true,
+ "is_local": true,
+ "effective_path": "live",
+ "policy_note": "...",
+ }
+
+ Notes:
+ * ``base_url`` is returned verbatim (no path-stripping) because
+ operators sometimes encode the model behind the path on
+ single-tenant LiteLLM gateways and stripping it confuses
+ troubleshooting.
+ * ``key_set`` is the *only* signal we expose for the API key.
+ We never return the key itself, even partially redacted.
+ """
+ base_url = os.getenv("LLM_BASE_URL") or os.getenv("OPENAI_BASE_URL") or ""
+ model = (
+ os.getenv("LLM_MODEL")
+ or os.getenv("OPENAI_MODEL")
+ or os.getenv("AISOC_LLM_MODEL")
+ or ""
+ )
+ key_set = bool(os.getenv("OPENAI_API_KEY") or os.getenv("LLM_API_KEY"))
+ airgap_enabled = bool(settings.AISOC_AIRGAPPED)
+
+ # If neither base_url nor key are set, the operator is running on
+ # the deterministic fallback. Surface that explicitly so the
+ # Settings UI can say "no LLM configured" rather than implying the
+ # default OpenAI path is wired up.
+ if not base_url and not key_set:
+ provider = "none"
+ else:
+ provider = _classify_provider(base_url)
+
+ host = (urlparse(base_url).hostname or "").lower() if base_url else ""
+
+ # Air-gap compliance: when air-gap is OFF this is always True (the
+ # check is moot). When ON, we ask the same classifier the egress
+ # gate uses so the answer matches what would actually happen at
+ # request time.
+ if not airgap_enabled:
+ airgap_compliant = True
+ elif provider == "none":
+ # No outbound call would happen anyway — fallback path is
+ # always air-gap compliant.
+ airgap_compliant = True
+ elif not host:
+ # base_url unset but key is set → would default to api.openai.com
+ # which is never compliant under air-gap.
+ airgap_compliant = False
+ else:
+ airgap_compliant = is_host_allowed_for_airgap(
+ host, settings.AISOC_AIRGAP_ALLOWLIST
+ )
+
+ is_local = _is_loopback_or_private_host(host)
+
+ # Effective path tells the UI which branch the explain endpoint
+ # would actually take right now. Mirrors ``_llm_allowed`` in
+ # ``services/agents/app/api/explain.py`` semantics so the indicator
+ # cannot drift from runtime behaviour.
+ if not key_set:
+ effective_path = "fallback"
+ elif airgap_enabled and not airgap_compliant:
+ effective_path = "fallback"
+ else:
+ effective_path = "live"
+
+ if provider == "none":
+ policy_note = (
+ "No LLM is configured. The Explain endpoint will return "
+ "deterministic OCSF + MITRE summaries and skip natural-language "
+ "narration. Set OPENAI_BASE_URL + OPENAI_API_KEY (or LLM_BASE_URL "
+ "+ LLM_API_KEY) to enable LLM-backed summaries."
+ )
+ elif airgap_enabled and not airgap_compliant:
+ policy_note = (
+ f"Air-gapped mode is ON and host '{host or 'api.openai.com'}' is "
+ "not allowed by the egress policy. The Explain endpoint will "
+ "fall back to deterministic summaries until the LLM points at a "
+ "host in AISOC_AIRGAP_ALLOWLIST or a private/internal endpoint."
+ )
+ elif effective_path == "fallback":
+ # key_set is False but base_url may be set — uncommon but possible.
+ policy_note = (
+ "OPENAI_API_KEY (or LLM_API_KEY) is unset, so LLM calls are "
+ "disabled and Explain falls back to deterministic summaries."
+ )
+ elif is_local:
+ policy_note = (
+ f"LLM calls are routed to a local provider ({provider}). No "
+ "external network egress is required for the Explain path."
+ )
+ else:
+ policy_note = (
+ f"LLM calls are routed to {provider} at {host}. Outbound HTTP "
+ "is required."
+ )
+
+ return {
+ "provider": provider,
+ "model": model,
+ "base_url": base_url,
+ "host": host,
+ "key_set": key_set,
+ "airgap_enabled": airgap_enabled,
+ "airgap_compliant": airgap_compliant,
+ "is_local": is_local,
+ "effective_path": effective_path,
+ "policy_note": policy_note,
+ }
+
+
[email protected]("/status", summary="Current LLM provider configuration")
+async def get_llm_status() -> dict[str, object]:
+ """Return the live LLM provider snapshot for this pod.
+
+ The response is safe to surface in operator UIs: secrets are never
+ included (we only return ``key_set: bool``) and the body is
+ deterministic for a given environment so the same payload renders
+ identically across pods. Pair with ``/api/v1/airgap/status`` to
+ show operators a full picture of "where will my AI calls go".
+ """
+ return llm_status()
diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.py
index 532768fe4..e4af8ddf6 100644
--- a/services/api/app/api/v1/router.py
+++ b/services/api/app/api/v1/router.py
@@ -31,6 +31,7 @@ from app.api.v1.endpoints import (
inbox_itsm,
knowledge_base,
lake,
+ llm_status,
nl_detection,
nl_query,
oauth,
@@ -141,6 +142,12 @@ api_router.include_router(reports.router)
# Air-gap status snapshot for operators — Tier 3.1 (air-gapped certification)
api_router.include_router(airgap.router)
+# LLM provider visibility for the "Deployment & AI" Settings panel.
+# Mirrors /airgap/status: read-only env-var snapshot, never returns the
+# API key itself. Same code path the egress gate uses, so the indicator
+# in the UI cannot drift from runtime behaviour (WS-H2/H4 visibility).
+api_router.include_router(llm_status.router)
+
# STIX/TAXII threat intelligence publishing (Tier 4)
api_router.include_router(stix_taxii.router)
diff --git a/services/api/tests/test_llm_status.py b/services/api/tests/test_llm_status.py
new file mode 100644
index 000000000..7a2df0776
--- /dev/null
+++ b/services/api/tests/test_llm_status.py
@@ -0,0 +1,235 @@
+"""Tests for ``/api/v1/llm/status`` (WS-H2/H4 operator visibility).
+
+Pins the contract the Settings → Deployment & AI panel relies on:
+
+* Provider classification matches the operator's actual env vars,
+ not a hard-coded default.
+* The API key itself is *never* surfaced — only ``key_set: bool``.
+* Air-gap compliance is computed from the same classifier the egress
+ gate uses, so the badge in the UI cannot drift from what would
+ actually happen at request time.
+* When neither key nor base URL is set we report ``provider="none"``
+ and ``effective_path="fallback"`` so operators don't see a
+ misleading "OpenAI" indicator on the deterministic fallback path.
+"""
+
+from __future__ import annotations
+
+import pytest
+from app.api.v1.endpoints.llm_status import llm_status
+from app.core import airgap as airgap_module
+
+
[email protected](autouse=True)
+def _clear_llm_env(monkeypatch: pytest.MonkeyPatch):
+ """Strip LLM-related env vars so each test starts from a known state.
+
+ We have to clear *all* the aliases we read (LLM_* and OPENAI_*) so
+ operator-side env contamination from a real shell doesn't bleed
+ into the test.
+ """
+ for var in (
+ "LLM_BASE_URL",
+ "LLM_API_KEY",
+ "LLM_MODEL",
+ "OPENAI_BASE_URL",
+ "OPENAI_API_KEY",
+ "OPENAI_MODEL",
+ "AISOC_LLM_MODEL",
+ ):
+ monkeypatch.delenv(var, raising=False)
+ monkeypatch.setattr(airgap_module.settings, "AISOC_AIRGAPPED", False)
+ monkeypatch.setattr(airgap_module.settings, "AISOC_AIRGAP_ALLOWLIST", [])
+ yield
+
+
+class TestNoConfiguration:
+ """No env at all → fallback path, never claim OpenAI is wired up."""
+
+ def test_provider_none_when_nothing_set(self):
+ snap = llm_status()
+ assert snap["provider"] == "none"
+ assert snap["effective_path"] == "fallback"
+ assert snap["key_set"] is False
+ assert snap["base_url"] == ""
+ # Always compliant when no outbound call would happen.
+ assert snap["airgap_compliant"] is True
+
+ def test_policy_note_explains_fallback(self):
+ snap = llm_status()
+ assert "deterministic" in str(snap["policy_note"]).lower()
+
+
+class TestKeyHandling:
+ """The key itself must never leave the process."""
+
+ def test_key_set_true_when_openai_api_key_present(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ # NB: the value is intentionally fake; the assertion is that
+ # we report the *presence* of a key, not the value.
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-test-not-a-real-key")
+ snap = llm_status()
+ assert snap["key_set"] is True
+ # And the value never appears anywhere in the snapshot.
+ assert "sk-test-not-a-real-key" not in str(snap)
+
+ def test_key_set_true_when_llm_api_key_alias_present(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ monkeypatch.setenv("LLM_API_KEY", "anything")
+ snap = llm_status()
+ assert snap["key_set"] is True
+
+
+class TestProviderClassification:
+ """``provider`` should match what the operator set, not OpenAI by default."""
+
+ def test_openai_default_when_key_set_no_base_url(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ snap = llm_status()
+ assert snap["provider"] == "openai"
+
+ def test_explicit_openai_host(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+ snap = llm_status()
+ assert snap["provider"] == "openai"
+
+ def test_anthropic(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv("OPENAI_BASE_URL", "https://api.anthropic.com")
+ snap = llm_status()
+ assert snap["provider"] == "anthropic"
+
+ def test_azure_openai(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv(
+ "OPENAI_BASE_URL", "https://my-resource.openai.azure.com/openai"
+ )
+ snap = llm_status()
+ assert snap["provider"] == "azure-openai"
+
+ def test_local_ollama(self, monkeypatch: pytest.MonkeyPatch):
+ # Local ollama: no key required by the backend, but the
+ # operator may still have set one as a placeholder.
+ monkeypatch.setenv("OPENAI_API_KEY", "ollama-placeholder")
+ monkeypatch.setenv("OPENAI_BASE_URL", "http://ollama:11434/v1")
+ snap = llm_status()
+ assert snap["provider"] == "local-ollama"
+ assert snap["is_local"] is True
+
+ def test_local_vllm_with_localhost(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv("OPENAI_BASE_URL", "http://localhost:8000/v1")
+ snap = llm_status()
+ # localhost without the "vllm" substring lands in custom; the
+ # `is_local` badge is what we actually care about for the UI.
+ assert snap["provider"] in {"custom", "local-vllm"}
+ assert snap["is_local"] is True
+
+ def test_local_vllm_with_explicit_hostname(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv("OPENAI_BASE_URL", "http://vllm-gateway.local:8000/v1")
+ snap = llm_status()
+ assert snap["provider"] == "local-vllm"
+ assert snap["is_local"] is True
+
+ def test_lm_alias_takes_precedence_over_openai_alias(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ # If both are set, LLM_BASE_URL wins to match the precedence in
+ # ``services/api/app/core/config.py``.
+ monkeypatch.setenv("LLM_BASE_URL", "http://ollama:11434/v1")
+ monkeypatch.setenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+ monkeypatch.setenv("LLM_API_KEY", "x")
+ snap = llm_status()
+ assert snap["provider"] == "local-ollama"
+ assert snap["base_url"] == "http://ollama:11434/v1"
+
+
+class TestAirgapCompliance:
+ """The ``airgap_compliant`` flag must match the egress classifier."""
+
+ def test_airgap_off_always_compliant(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+ snap = llm_status()
+ assert snap["airgap_enabled"] is False
+ assert snap["airgap_compliant"] is True
+
+ def test_airgap_on_blocks_openai(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(airgap_module.settings, "AISOC_AIRGAPPED", True)
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+ snap = llm_status()
+ assert snap["airgap_enabled"] is True
+ assert snap["airgap_compliant"] is False
+ assert snap["effective_path"] == "fallback"
+ assert "AISOC_AIRGAP_ALLOWLIST" in str(snap["policy_note"])
+
+ def test_airgap_on_allows_local_ollama(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(airgap_module.settings, "AISOC_AIRGAPPED", True)
+ monkeypatch.setenv("OPENAI_API_KEY", "ollama")
+ monkeypatch.setenv("OPENAI_BASE_URL", "http://ollama:11434/v1")
+ snap = llm_status()
+ assert snap["airgap_enabled"] is True
+ assert snap["airgap_compliant"] is True
+ assert snap["effective_path"] == "live"
+ assert snap["is_local"] is True
+
+ def test_airgap_on_allows_allowlisted_external_mirror(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ monkeypatch.setattr(airgap_module.settings, "AISOC_AIRGAPPED", True)
+ monkeypatch.setattr(
+ airgap_module.settings,
+ "AISOC_AIRGAP_ALLOWLIST",
+ ["llm-mirror.acme-internal.example.com"],
+ )
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ monkeypatch.setenv(
+ "OPENAI_BASE_URL", "https://llm-mirror.acme-internal.example.com/v1"
+ )
+ snap = llm_status()
+ assert snap["airgap_compliant"] is True
+ assert snap["effective_path"] == "live"
+ # Not classified as "local" — it's an internal SaaS mirror.
+ assert snap["is_local"] is False
+
+ def test_airgap_on_no_config_is_compliant(self, monkeypatch: pytest.MonkeyPatch):
+ # Air-gap on, no key, no base — fallback path is implicitly
+ # compliant because nothing leaves the pod.
+ monkeypatch.setattr(airgap_module.settings, "AISOC_AIRGAPPED", True)
+ snap = llm_status()
+ assert snap["airgap_enabled"] is True
+ assert snap["airgap_compliant"] is True
+ assert snap["provider"] == "none"
+ assert snap["effective_path"] == "fallback"
+
+
+class TestEffectivePath:
+ """``effective_path`` must mirror the explain agent's _llm_allowed semantics."""
+
+ def test_live_when_key_set_and_no_airgap(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ snap = llm_status()
+ assert snap["effective_path"] == "live"
+
+ def test_fallback_when_key_unset(self, monkeypatch: pytest.MonkeyPatch):
+ snap = llm_status()
+ assert snap["effective_path"] == "fallback"
+
+ def test_fallback_when_key_set_but_airgap_blocks(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ monkeypatch.setattr(airgap_module.settings, "AISOC_AIRGAPPED", True)
+ monkeypatch.setenv("OPENAI_API_KEY", "x")
+ # No base_url + airgap on → would default to api.openai.com → blocked.
+ snap = llm_status()
+ assert snap["effective_path"] == "fallback"
+ assert snap["airgap_compliant"] is False