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.

20.1 KB
Raw Blame
"""Per-tenant LLM credential resolution for the explain endpoint (WS-H2).

What this resolves
------------------

The explain endpoint needs to answer a single question on every request:

    "For *this* tenant, do I make a live LLM call right now? If so,
    against which base URL, with which model, and using which API key?"

Up to v1.0 the answer was hard-coded to the process-level env vars
(``OPENAI_API_KEY`` / ``OPENAI_BASE_URL`` / ``OPENAI_MODEL``). The new
BYOK feature (WS-H2) lets each tenant override any of those three
fields by writing a vault-encrypted row to ``tenant_llm_credentials``
in the platform database. This module is the read path that the
agents service uses at request time.

Why we ported this here instead of calling the API service
----------------------------------------------------------

The agents service is already a database client (``investigator/ledger.py``)
and already has the env-vars + air-gap policy locally for the explain
path. Adding a second outbound HTTP hop to ``services/api`` just to
read three columns would:

* widen the explain-path latency budget on every alert,
* introduce an availability cross-dependency for what is a *fallback-
  capable* path (Explain must keep working when the API is down), and
* require a service-to-service auth model (mTLS or a shared secret)
  that we don't otherwise need.

Instead we vendor the read primitives — :class:`CredentialVault` for
ciphertext, plus this resolver — into the agents service. The API
service remains the sole owner of the *write* path, so there is one
place to gate ``settings:write`` RBAC, validation, and audit emission.

Resolution rules (must match :func:`tenant_llm_status` in services/api)
-----------------------------------------------------------------------

For each of the three fields we resolve in this order:

1. Tenant row (when present, ``enabled=true``, and successfully
   decrypted in the ``api_key_vault`` case).
2. Process env vars (``OPENAI_*`` / ``LLM_*``).
3. Platform default — the bundled gateway and the ``summary`` alias when a
   gateway is configured, ``https://api.openai.com`` / ``gpt-4o-mini``
   otherwise — so the explain path always has a deterministic config to log
   against, even when it ultimately decides ``allowed=False``.

Whichever field came from the tenant row is recorded so the resolver
can label the resolved config with a ``source`` of ``"tenant"``,
``"environment"``, or ``"mixed"`` — useful for log-based debugging
of "wait, which key did this request actually use?".

Air-gap policy is the *last* thing we check, after layering. This
mirrors the semantics of the legacy ``_llm_allowed()`` helper so a
tenant who BYOKs a private LiteLLM gateway gets ``allowed=True`` even
when ``AISOC_AIRGAPPED=true``, which is exactly what the air-gap
deployment story promises.

Failure modes
-------------

This module is on the explain hot path, so every failure is best-
effort: a missing ``DATABASE_URL``, an unreachable database, an
unconfigured ``AISOC_CREDENTIAL_KEY``, a corrupt ciphertext, or a
tenant row with ``enabled=false`` all degrade gracefully to the env-
only baseline. The reason for the degradation is logged once at
``warning`` so an operator can spot misconfiguration, but the alert
drawer never errors out — it just renders the deterministic
fallback summary, exactly the same surface analysts already see when
no LLM is configured.
"""

from __future__ import annotations

import os
import uuid
from dataclasses import dataclass
from typing import Any
from urllib.parse import urlparse

import asyncpg
import structlog

from app.llm.routing import gateway_url, is_gateway_alias, resolve_api_key
from app.security.credential_vault import CredentialVaultError, get_vault

# NOTE: ``app.investigator.ledger`` is imported lazily inside
# :func:`resolve_llm_config` rather than at module load time. The
# ``app.investigator`` package's ``__init__`` eagerly imports the LangGraph
# orchestrator, which in turn pulls in heavyweight dependencies that the
# explain unit tests deliberately avoid. Deferring the import to the path
# that actually needs a database pool keeps the explain endpoint testable
# in isolation while still using the canonical pool factory in production.

logger = structlog.get_logger()


# ---------------------------------------------------------------------------
# Defaults
# ---------------------------------------------------------------------------
#
# These mirror the documented "no override" behaviour of the explain
# endpoint. When the resolver decides ``allowed=False`` we still surface
# a fully-formed ``LlmConfig`` so the caller can log "fallback because
# X" with concrete values rather than ``None`` placeholders.

_DEFAULT_OPENAI_BASE = "https://api.openai.com"
_DEFAULT_OPENAI_MODEL = "gpt-4o-mini"
#: The role the explain path's work belongs to. Its alias is the default model
#: when a gateway is configured, because ``gpt-4o-mini`` is not a model the
#: bundled gateway defines and sending it there returns "Invalid model name".
_EXPLAIN_ROLE_ALIAS = "aisoc-summary"


@dataclass(frozen=True)
class LlmConfig:
    """Effective LLM configuration for a single explain request.

    Attributes:
        allowed: ``True`` when an outbound LLM call is permitted *right
            now*. ``False`` means the explain path must use the
            deterministic synthesizer.
        base_url: The base URL to POST chat completions against. Always
            populated, even when ``allowed=False``, so callers can log
            it.
        model: The model identifier to send in the request body. Same
            "always populated" guarantee as ``base_url``.
        api_key: The plaintext API key. Only present when
            ``allowed=True``. Never logged, never returned to clients.
        source: One of ``"tenant"``, ``"environment"``, ``"mixed"``,
            ``"none"`` — describes where the layered config came from.
            ``"none"`` indicates neither the tenant row nor the env
            baseline contributed any usable values (which forces
            ``allowed=False``).
        reason: When ``allowed=False``, a short human-readable note
            explaining the reason. Empty when ``allowed=True``.
    """

    allowed: bool
    base_url: str
    model: str
    api_key: str | None
    source: str
    reason: str
    # Per-field provenance. ``source`` collapses the whole config into one
    # word, which is enough to log and not enough to act on: the auto-triage
    # worker binds this config as a per-tenant BYOK *override*, and without
    # knowing which fields the tenant actually set it overrode the task role's
    # model with whatever ``OPENAI_MODEL`` happened to be — shipped in
    # .env.example as `gpt-4-turbo-preview`, which no gateway here defines. An
    # env baseline is a default, never an override.
    model_from_tenant: bool = False
    base_url_from_tenant: bool = False
    api_key_from_tenant: bool = False


# ---------------------------------------------------------------------------
# Env-var baseline
# ---------------------------------------------------------------------------


def _env_baseline() -> tuple[str, str, str | None]:
    """Return the ``(base_url, model, api_key)`` triple from process env.

    Mirrors :func:`services.api.app.api.v1.endpoints.llm_status._env_baseline`
    so the agents-side resolver and the API-side status indicator can
    never disagree about what "the env baseline" actually is. We
    intentionally accept both the modern ``LLM_*`` names and the legacy
    ``OPENAI_*`` / ``AISOC_LLM_MODEL`` names — every deployment in the
    field today uses some mix of the two.
    """
    base_url = os.getenv("OPENAI_BASE_URL", "").strip() or os.getenv("LLM_BASE_URL", "").strip()
    model = os.getenv("OPENAI_MODEL", "").strip() or os.getenv("LLM_MODEL", "").strip() or os.getenv("AISOC_LLM_MODEL", "").strip()
    if not base_url and gateway_url() and is_gateway_alias(model or _EXPLAIN_ROLE_ALIAS):
        # The compose-provided gateway, under the same rule every other caller
        # uses (``app.llm.routing``): adopted for an alias, never for a concrete
        # model. Without this the explain path was the one consumer that could
        # not reach the gateway at all — it defaulted straight to
        # ``https://api.openai.com`` and took an alias there.
        base_url = gateway_url() or ""
        model = model or _EXPLAIN_ROLE_ALIAS
    api_key = resolve_api_key(model) or ""
    return base_url, model, (api_key or None)


# ---------------------------------------------------------------------------
# Air-gap policy
# ---------------------------------------------------------------------------


def _airgap_blocks(base_url: str) -> tuple[bool, str]:
    """Return ``(blocked, reason)`` under the current air-gap policy.

    Replicates the semantics of the legacy ``_llm_allowed`` helper:

    * ``AISOC_AIRGAPPED`` off  → never blocks.
    * ``AISOC_AIRGAPPED`` on:
        * empty ``base_url`` would default to ``api.openai.com`` → blocked.
        * ``base_url`` containing ``api.openai.com`` → blocked.
        * any other host (private LiteLLM/Ollama/vLLM proxy) → allowed.

    Note that we deliberately do *not* call into ``services/api/app/core/airgap``
    here — that helper performs IP/CIDR allowlist checks that the
    agents service does not need (the request is already in-process,
    and the LLM host shape is enough to gate egress for explain).
    """
    airgapped = os.getenv("AISOC_AIRGAPPED", "").lower() in ("1", "true", "yes")
    if not airgapped:
        return False, ""

    base = (base_url or "").strip()
    if not base:
        return (
            True,
            "AISOC_AIRGAPPED is on and no base_url is configured (would default to api.openai.com).",
        )
    try:
        parsed = urlparse(base)
        hostname = (parsed.hostname or "").lower()
    except Exception:  # noqa: BLE001
        hostname = ""
    # Check hostname exactly or as a subdomain to avoid substring-match bypass
    # (e.g. evil.com/api.openai.com or api.openai.com.evil.com).
    if hostname == "api.openai.com" or hostname.endswith(".api.openai.com"):
        return True, "AISOC_AIRGAPPED is on and base_url points at api.openai.com."
    return False, ""


# ---------------------------------------------------------------------------
# Tenant-row lookup
# ---------------------------------------------------------------------------


async def _resolve_tenant_uuid(conn: asyncpg.Connection, tenant_ref: str) -> uuid.UUID | None:
    """Resolve a tenant reference (UUID, slug, or name) to a UUID.

    Inlined rather than imported from
    :mod:`app.investigator.ledger` so the resolver does not depend on
    that module's private helpers. Logic must stay in lockstep with
    :func:`app.investigator.ledger._resolve_tenant_id` — change one,
    change both.
    """
    try:
        return uuid.UUID(tenant_ref)
    except (ValueError, TypeError):
        pass

    row = await conn.fetchrow(
        """
        SELECT id FROM tenants
        WHERE slug = $1 OR name = $1
        LIMIT 1
        """,
        tenant_ref,
    )
    return row["id"] if row else None


async def _set_rls_context(conn: asyncpg.Connection, tenant_id: uuid.UUID) -> None:
    """Set the RLS GUC so policies on ``tenant_llm_credentials`` admit us.

    ``app.current_tenant_id`` is the variable that table's policy reads; this
    said ``app.tenant_id`` until 2026-09. See ``app/investigator/ledger.py``.
    """
    await conn.execute("SELECT set_config('app.current_tenant_id', $1, true)", str(tenant_id))


async def _fetch_tenant_credential(pool: asyncpg.Pool, tenant_ref: str) -> dict[str, Any] | None:
    """Resolve ``tenant_ref`` and fetch the ``tenant_llm_credentials`` row.

    Returns ``None`` when:

    * the tenant reference cannot be resolved (unknown slug/name/UUID),
    * no row exists for the tenant,
    * the row exists but ``enabled=false`` (treated as "no override" so
      operators can pause BYOK without deleting the row), or
    * any database error occurs (logged once at ``warning``).

    A non-None return is always a sane dict with the columns this
    resolver consumes.
    """
    try:
        async with pool.acquire() as conn:
            tenant_id = await _resolve_tenant_uuid(conn, tenant_ref)
            if tenant_id is None:
                return None
            await _set_rls_context(conn, tenant_id)
            row = await conn.fetchrow(
                """
                SELECT
                    provider,
                    base_url,
                    model,
                    api_key_vault,
                    settings,
                    enabled
                FROM tenant_llm_credentials
                WHERE tenant_id = $1
                """,
                tenant_id,
            )
    except Exception as exc:  # noqa: BLE001
        logger.warning(
            "explain.llm_resolve_db_failed",
            tenant=tenant_ref,
            error=str(exc),
        )
        return None

    if row is None or not row["enabled"]:
        return None
    return dict(row)


# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------


async def resolve_llm_config(tenant_ref: str | None) -> LlmConfig:
    """Resolve the effective LLM configuration for ``tenant_ref``.

    Args:
        tenant_ref: The tenant identifier carried on the explain request
            (UUID, slug, or name). When ``None`` or ``"default"`` we
            skip the database lookup and return the env-only baseline,
            matching the behaviour of the rest of the agents service.

    Returns:
        An :class:`LlmConfig` describing whether a live LLM call is
        permitted and which base URL / model / key the explain path
        should use. The resolver never raises — every failure path
        returns an ``allowed=False`` config with a populated ``reason``.

    Telemetry:
        Successful resolutions are not logged (would dominate the
        explain log). Failures (db error, decrypt error, vault key
        missing) are logged at ``warning`` with the tenant ref so an
        operator can find the offending row.
    """
    env_base_url, env_model, env_key = _env_baseline()

    base_url = env_base_url
    model = env_model
    api_key = env_key
    tenant_contributed_base_url = False
    tenant_contributed_model = False
    tenant_contributed_key = False

    skip_db_lookup = tenant_ref is None or not tenant_ref.strip() or tenant_ref == "default"
    if not skip_db_lookup:
        # Lazy import: see module-level NOTE. We only reach this branch
        # when the request carries a real tenant ref. Importing the
        # investigator package transitively loads the LangGraph
        # orchestrator, which is an optional dependency in slim
        # deployments and in unit tests that exercise the explain
        # endpoint in isolation. Treat a missing dependency the same way
        # we treat a missing DATABASE_URL: log once and fall through to
        # the environment baseline rather than failing the request.
        pool = None
        try:
            from app.investigator import ledger as _ledger  # noqa: PLC0415

            pool = await _ledger.get_pool()
        except Exception as exc:  # noqa: BLE001
            logger.warning(
                "explain.llm_resolve_ledger_unavailable",
                tenant=tenant_ref,
                error=str(exc),
            )

        if pool is not None:
            row = await _fetch_tenant_credential(pool, tenant_ref)
            if row is not None:
                if row.get("base_url"):
                    base_url = row["base_url"]
                    tenant_contributed_base_url = True
                if row.get("model"):
                    model = row["model"]
                    tenant_contributed_model = True
                vault_token = row.get("api_key_vault")
                if vault_token:
                    api_key = _decrypt_vault_token(vault_token, tenant_ref)
                    if api_key is not None:
                        tenant_contributed_key = True
                    else:
                        # Decrypt failed (already logged) — fall back to
                        # the env key so a corrupt tenant ciphertext
                        # doesn't break a tenant that also has a working
                        # env baseline.
                        api_key = env_key

    source = _classify_source(
        env_base_url=env_base_url,
        env_model=env_model,
        env_key=env_key,
        tenant_contributed_base_url=tenant_contributed_base_url,
        tenant_contributed_model=tenant_contributed_model,
        tenant_contributed_key=tenant_contributed_key,
    )

    final_base = base_url or _DEFAULT_OPENAI_BASE
    final_model = model or _DEFAULT_OPENAI_MODEL

    if not api_key:
        return LlmConfig(
            allowed=False,
            base_url=final_base,
            model=final_model,
            api_key=None,
            source=source if source != "none" else "none",
            reason="no API key configured (neither tenant BYOK nor env)",
            model_from_tenant=tenant_contributed_model,
            base_url_from_tenant=tenant_contributed_base_url,
            api_key_from_tenant=tenant_contributed_key,
        )

    blocked, reason = _airgap_blocks(base_url)
    if blocked:
        return LlmConfig(
            allowed=False,
            base_url=final_base,
            model=final_model,
            api_key=api_key,  # safe: caller does not log this on failure
            source=source,
            reason=reason,
            model_from_tenant=tenant_contributed_model,
            base_url_from_tenant=tenant_contributed_base_url,
            api_key_from_tenant=tenant_contributed_key,
        )

    return LlmConfig(
        allowed=True,
        base_url=final_base,
        model=final_model,
        api_key=api_key,
        source=source,
        reason="",
        model_from_tenant=tenant_contributed_model,
        base_url_from_tenant=tenant_contributed_base_url,
        api_key_from_tenant=tenant_contributed_key,
    )


# ---------------------------------------------------------------------------
# Internal helpers
# ---------------------------------------------------------------------------


def _decrypt_vault_token(vault_token: str, tenant_ref: str) -> str | None:
    """Decrypt a stored ``vault:v1:<base64>`` token. Returns ``None`` on failure.

    The vault may be unconfigured (``AISOC_CREDENTIAL_KEY`` not set) on
    operator boxes that haven't migrated to BYOK yet — that's a
    legitimate configuration, so we log once and fall back rather than
    treating it as an error.
    """
    vault = get_vault()
    if vault is None:
        logger.warning(
            "explain.llm_resolve_vault_disabled",
            tenant=tenant_ref,
            reason=("AISOC_CREDENTIAL_KEY not set; tenant BYOK key cannot be decrypted, falling back to environment baseline"),
        )
        return None
    try:
        return vault.decrypt(vault_token)
    except CredentialVaultError as exc:
        logger.warning(
            "explain.llm_resolve_decrypt_failed",
            tenant=tenant_ref,
            error=str(exc),
        )
        return None


def _classify_source(
    *,
    env_base_url: str,
    env_model: str,
    env_key: str | None,
    tenant_contributed_base_url: bool,
    tenant_contributed_model: bool,
    tenant_contributed_key: bool,
) -> str:
    """Label the merge result. Mirrors ``tenant_llm_status`` in services/api.

    The three flags say which fields the *tenant row* contributed. The
    env values say which fields the environment *would have*
    contributed if the tenant didn't. If both contributed something to
    the final config, the merge is "mixed" — exactly what the API-side
    status endpoint reports.
    """
    tenant_contributed = tenant_contributed_base_url or tenant_contributed_model or tenant_contributed_key
    env_contributed = (
        (not tenant_contributed_base_url and bool(env_base_url))
        or (not tenant_contributed_model and bool(env_model))
        or (not tenant_contributed_key and bool(env_key))
    )

    if tenant_contributed and env_contributed:
        return "mixed"
    if tenant_contributed:
        return "tenant"
    if env_contributed:
        return "environment"
    return "none"