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.

31.9 KB
Raw Blame
"""
Connectors service REST API.

Catalog and schema endpoints are now backed by the
``app.connectors`` registry so adding a connector requires zero changes
here — drop the class in, register it in ``connectors/__init__.py``, and
its schema flows through to the wizard automatically.

This service is a *stateless* microservice. It does not own connector
instance rows (those live in the API service's Postgres) and it does not
manage credentials at rest (that's the API's ``CredentialVault``). Its
job is twofold:

1. Catalog: tell the API service which connector classes this build
   ships and what configuration schema each one expects.
2. Test: instantiate a connector class with caller-supplied (already
   decrypted) credentials, run ``test_connection()``, and return the
   verdict. This lets the API service offer a "Test connection" button
   in the wizard without having to re-implement every vendor SDK.

Production connector polling and ingest happen elsewhere (the
``ConnectorScheduler`` + ``IngestClient`` modules wired into the
service's lifespan), not in this router.
"""

from __future__ import annotations

import re
import uuid
from typing import Any

import structlog
from fastapi import APIRouter, Depends, HTTPException, Query, status
from pydantic import BaseModel
from pydantic import Field as PydField

from app.connectors import CONNECTOR_REGISTRY, list_connector_schemas
from app.connectors.base import Capability
from app.db.connector_repo import fetch_enabled_connector_for_tenant
from app.db.engine import get_engine
from app.federated.query import QueryError, parse_unified_query
from app.security.credential_vault import CredentialVaultError, get_vault
from app.security.egress import EgressRefused, refuse_internal_destinations
from app.security.tenant_scope import (
    TenantPrincipal,
    require_console_or_service_auth,
    scoped_tenant_or_403,
)

logger = structlog.get_logger()
#: Default-deny. Everything on this router either reads the connector
#: catalogue, decrypts a saved instance's credentials to test them, or
#: pushes a case into a customer's ITSM — none of which should answer an
#: anonymous caller. The console reaches these routes directly through a
#: Next rewrite, so the guard accepts a console session as well as a
#: service token declaring the tenant it acts for.
router = APIRouter(dependencies=[Depends(require_console_or_service_auth)])

#: Liveness is deliberately off the guarded router: a probe holds no
#: credential, and an unauthenticated 401 would read as an outage.
health_router = APIRouter()

_CTRL_RE = re.compile(r"[\x00-\x1f\x7f]")

#: Keys stored on a connector instance that are scheduler knobs rather than
#: constructor arguments. Passing them through raises ``TypeError`` and turns a
#: working connector into a 422. Mirrors the filter in ``ConnectorScheduler``.
_SCHEDULER_ONLY_CONFIG_KEYS = frozenset({"poll_interval_seconds", "checkpoint", "filter_rules"})

#: One answer for "no such instance", "not enabled" and "belongs to another
#: tenant", with the requested id deliberately **not** echoed back.
#:
#: Distinguishing those cases is what made this route an existence oracle over
#: every tenant's connector ids: a 403 on a real id beside a 404 on an invented
#: one enumerates the estate without reading a single row. A constant also
#: keeps a caller-supplied string out of the response body, and costs the
#: caller nothing — they already know which id they sent.
_NO_SUCH_INSTANCE = "no enabled connector instance"


def _connector_kwargs(connector_config: dict[str, Any]) -> dict[str, Any]:
    return {k: v for k, v in connector_config.items() if k not in _SCHEDULER_ONLY_CONFIG_KEYS}


def _safe_log_val(value: str) -> str:
    """Strip ASCII control characters (incl. newlines) from a string before logging.

    Prevents log-injection attacks where a user-controlled value such as a
    connector_id could embed newline sequences that forge extra log lines.
    """
    return _CTRL_RE.sub("", value)


class TestConnectionRequest(BaseModel):
    """Stateless test-connection payload.

    The API service decrypts the stored ``auth_config`` before forwarding
    it here; this service never sees vault tokens. ``connector_config``
    carries non-secret runtime knobs (poll interval, region, etc.) that
    some connectors take in their constructor alongside credentials.
    """

    auth_config: dict[str, Any] = PydField(
        default_factory=dict,
        description="Plaintext credential fields for the connector.",
    )
    connector_config: dict[str, Any] = PydField(
        default_factory=dict,
        description="Non-secret runtime config that's passed to the connector constructor.",
    )


class ResourceConfigRequest(BaseModel):
    """Fetch one resource's live configuration (Phase C2).

    Same trust model as ``TestConnectionRequest``: the API service decrypts
    ``auth_config`` before forwarding here. ``resource_id`` is the vendor-native
    id (Okta group/app id, ARN, Azure object id, …); ``at_ts`` is an optional
    point-in-time (ISO-8601) — connectors that can't time-travel return their
    latest and mark ``snapshot_freshness``.
    """

    auth_config: dict[str, Any] = PydField(default_factory=dict)
    connector_config: dict[str, Any] = PydField(default_factory=dict)
    resource_id: str = PydField(..., description="Vendor-native resource id to fetch.")
    at_ts: str = PydField(default="", description="Optional ISO-8601 point-in-time.")


#: A normalize request carrying more rows than this is refused rather than
#: truncated. Truncation would return a short list the caller reads as "these
#: are all of them", and replay would grade a window it did not ask for.
MAX_NORMALIZE_ROWS = 2000


class NormalizeRequest(BaseModel):
    """Map raw vendor rows through a connector's production ``normalize()``.

    Gap-closure Phase 1.2. Replay evaluation runs in ``services/agents`` and
    has to normalize a customer's closed findings exactly as the live pipeline
    does. It cannot import a connector: both services package their code as
    top-level ``app``, so one process can hold one of them. The alternative to
    this route is a second copy of every vendor's field mapping inside the
    agents service, which is the one thing the replay work is not allowed to
    do, because a mapping that drifts would grade the agent on inputs the
    product never produces.

    Carries no ``auth_config``, and that is a property rather than an
    omission: the handler never builds a configured client, so this route
    cannot make an outbound call to a customer's SIEM no matter what it is
    sent.
    """

    rows: list[dict[str, Any]] = PydField(
        ...,
        description="Raw vendor rows, exactly as the vendor returned them.",
    )


class FederatedQueryRequest(BaseModel):
    """Run a unified query against a single connector instance.

    Same trust model as ``TestConnectionRequest``: the API service
    decrypts ``auth_config`` before forwarding here. ``query`` is the
    JSON-shaped ``UnifiedQuery`` (see ``app.federated.query``).
    """

    auth_config: dict[str, Any] = PydField(default_factory=dict)
    connector_config: dict[str, Any] = PydField(default_factory=dict)
    query: dict[str, Any] = PydField(
        ...,
        description="UnifiedQuery payload: free_text, indicators[], since_seconds, limit.",
    )


# ---------------------------------------------------------------------------
# WS8: bidirectional ITSM push.
# ---------------------------------------------------------------------------
#
# These two payloads carry the AiSOC case (already serialized to a dict by
# the API layer) plus the same auth/runtime config envelope as the test and
# query endpoints. Trust model is identical: ``auth_config`` arrives in
# plaintext because the API service decrypted it via ``CredentialVault``
# before forwarding.


class PushCaseRequest(BaseModel):
    """Mint or update an external ticket from an AiSOC case.

    ``case`` is the dict the API layer assembled from the ``aisoc_cases``
    row (id, case_number, title, description, severity, status, plus any
    relevant joins). ``external_ref`` is optional and only set when the
    caller already has a ``case_external_refs`` row to update — the
    connector will treat it as "first-time push" otherwise.
    """

    auth_config: dict[str, Any] = PydField(default_factory=dict)
    connector_config: dict[str, Any] = PydField(default_factory=dict)
    case: dict[str, Any] = PydField(
        ...,
        description="AiSOC case payload to project onto the external ITSM.",
    )
    external_ref: dict[str, Any] | None = PydField(
        default=None,
        description="Existing case_external_refs row for idempotent updates.",
    )


class PushStatusChangeRequest(BaseModel):
    """Project an AiSOC status transition onto an external ticket."""

    auth_config: dict[str, Any] = PydField(default_factory=dict)
    connector_config: dict[str, Any] = PydField(default_factory=dict)
    case: dict[str, Any] = PydField(...)
    old_status: str = PydField(..., description="AiSOC status the case is moving from.")
    new_status: str = PydField(..., description="AiSOC status the case is moving to.")
    external_ref: dict[str, Any] | None = PydField(
        default=None,
        description="Existing case_external_refs row. None falls through to push_case.",
    )


def _instantiate_or_422(cls: type, kwargs: dict[str, Any]) -> Any:
    """Construct ``cls(**kwargs)`` and convert config errors to HTTP 422.

    Pulled out into a helper because four endpoints now share the exact
    same construction path; keeping it inline meant duplicating the
    ``TypeError`` handling four times.

    Destination validation happens here, before the constructor, so every
    route that builds a connector refuses an internal URL the same way
    (GHSA-cq4g-g6wp-4m2w) — a connector object that exists is one a later
    edit can call.
    """
    try:
        refuse_internal_destinations(kwargs)
    except EgressRefused as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=str(exc),
        ) from exc
    try:
        return cls(**kwargs)
    except TypeError as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"connector config does not match schema: {exc}",
        ) from exc


def _require_capability(cls: type, capability: Capability, connector_id: str) -> None:
    """Reject calls to a connector that doesn't declare ``capability``.

    ``BaseConnector`` already raises ``NotImplementedError`` from the
    default ``push_case`` / ``push_status_change`` bodies, but failing
    fast here gives a friendlier 501 with the connector_id pre-filled
    instead of bubbling an opaque exception out of the runtime.
    """
    if capability not in cls.capabilities():
        raise HTTPException(
            status_code=status.HTTP_501_NOT_IMPLEMENTED,
            detail=(f"connector '{connector_id}' does not declare capability '{capability.value}'"),
        )


@router.get("/connectors")
async def list_connectors():
    """List every connector registered with this build."""
    return {
        "connectors": [
            {
                "id": cls.connector_id,
                "name": cls.connector_name,
                "category": cls.connector_category,
            }
            for cls in CONNECTOR_REGISTRY.values()
        ]
    }


@router.get("/connectors/schemas")
async def list_schemas():
    """Bulk fetch every connector's configuration schema.

    Frontend uses this to populate the AddConnector wizard without firing
    one request per connector.
    """
    return {"schemas": list_connector_schemas()}


@router.get("/connectors/{connector_id}/schema")
async def get_connector_schema(connector_id: str):
    """Configuration schema for a single connector."""
    cls = CONNECTOR_REGISTRY.get(connector_id)
    if cls is None:
        raise HTTPException(status_code=404, detail=f"Connector '{connector_id}' not found")
    schema_dict = cls.schema().to_dict()
    # Backfill capabilities from the classmethod when ``schema()`` didn't
    # set them explicitly. See ``list_connector_schemas`` for rationale.
    if not schema_dict.get("capabilities"):
        schema_dict["capabilities"] = [c.value for c in cls.capabilities()]
    return schema_dict


@router.post("/connectors/{connector_id}/test")
async def test_connector_connection(connector_id: str, payload: TestConnectionRequest):
    """Run a stateless ``test_connection()`` for the given connector.

    The API service is expected to:

    1. Look up the stored connector instance row (or accept fresh creds
       from the wizard's "Test connection" button before the row exists).
    2. Decrypt ``auth_config`` via the credential vault.
    3. POST the resulting plaintext blob here, alongside ``connector_config``.

    We then construct the connector class with the merged keyword
    arguments and call its ``test_connection()`` coroutine. The connector
    is responsible for catching its own network errors and returning a
    structured ``{"success": bool, ...}`` payload — we do not synthesise
    that ourselves so the wizard surface always shows the connector's
    own diagnostic message (e.g. "401 Unauthorized" vs "DNS lookup
    failed").
    """
    cls = CONNECTOR_REGISTRY.get(connector_id)
    if cls is None:
        raise HTTPException(status_code=404, detail=f"Connector '{connector_id}' not found")

    # Merge auth + non-secret config into kwargs. We keep them in this order
    # because a malicious ``connector_config`` mustn't be able to overwrite
    # a legitimate ``auth_config`` field — but in practice the API service
    # validates both blobs against the schema before we ever see them, so
    # this ordering is defensive belt-and-braces rather than a real
    # boundary.
    #
    # Exception: the scheduler-owned runtime state keys must not reach the
    # constructor. ``record_checkpoint`` persists the ingest cursor into
    # ``connector_config.checkpoint``, and the scheduler strips it (plus the
    # other scheduler-only keys) before construction — while this route
    # merged the blob verbatim, so once any poll had recorded a checkpoint,
    # EVERY saved-connector test raised TypeError -> 422 ("unexpected
    # keyword argument 'checkpoint'") on every connector whose __init__
    # does not take it. One exclusion set, owned by ``_connector_kwargs``
    # above: a second hand-written list here is how ``filter_rules`` would
    # have been missed, and how the next scheduler-only key drifts.
    kwargs = {**payload.auth_config, **_connector_kwargs(payload.connector_config)}

    # Before the constructor, and before any socket could open: a tenant-set
    # base_url pointing at cloud metadata, loopback or an internal service is
    # refused here rather than fetched and reflected (GHSA-cq4g-g6wp-4m2w —
    # this exact route was the reproduced entry point).
    try:
        refuse_internal_destinations(kwargs)
    except EgressRefused as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=str(exc),
        ) from exc

    try:
        connector = cls(**kwargs)
    except TypeError as exc:
        # Almost always "missing 1 required positional argument" or "got
        # unexpected keyword argument", i.e. caller passed a config that
        # doesn't match this connector's schema. Surface as 422 so the
        # frontend can highlight the offending field.
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"connector config does not match schema: {exc}",
        ) from exc
    except Exception as exc:  # pragma: no cover - last-ditch
        logger.exception("connector.test.constructor_error", connector_id=_safe_log_val(connector_id))
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="Failed to construct connector. Check your configuration.",
        ) from exc

    try:
        result = await connector.test_connection()
    except Exception:  # pragma: no cover - connector misbehaving
        # A well-behaved connector swallows its own errors and returns
        # {"success": False, "error": ...}. If one raises anyway, we
        # convert to the same shape so the wizard UI doesn't have two
        # error formats to deal with.
        logger.exception("connector.test.runtime_error", connector_id=_safe_log_val(connector_id))
        result = {"success": False, "connector": connector_id, "error": "Connection test failed"}

    if not isinstance(result, dict):
        # Defensive: some connectors might return None on success. Coerce.
        result = {"success": bool(result), "connector": connector_id}
    return result


@router.get("/connectors/instances/{instance_id}/resource-config")
async def get_instance_resource_config(
    instance_id: str,
    resource_id: str = Query(..., description="Vendor-native resource id"),
    ts: str | None = Query(None, description="Point in time (RFC 3339)"),
    principal: TenantPrincipal = Depends(require_console_or_service_auth),
):
    """Fetch a resource's configuration for a **saved connector instance**.

    The POST route below takes credentials in the body, which works for the
    API service — it owns the vault — and cannot work for `services/ingest`.
    The Go config-snapshotter has no credentials to send, so it called a GET
    endpoint that did not exist; a 404 maps to `ErrNotImplemented`, which the
    snapshotter treats as a soft skip. An operator therefore saw
    "snapshots enabled" and zero Configuration nodes, with nothing logged.

    This route resolves the instance and decrypts `auth_config` the same way
    `ConnectorScheduler` does at poll time, so the caller needs no secrets.
    That also means the ingest service never handles credentials, which is the
    reason the original contract could not simply be renamed into place.

    Because it decrypts a stored credential and spends it on an authenticated
    vendor call, the instance has to be resolved **inside the caller's tenant**
    (GHSA-h4g5-39vv-pqfv). ``principal`` is declared as a parameter rather than
    left to the router-level dependency: the router's ``Depends`` authenticates
    either way, but a dependency whose result is never bound hands it nowhere,
    which is how the tenant came to be known and then not used.
    """
    tenant_id = scoped_tenant_or_403(principal)

    try:
        wanted = uuid.UUID(instance_id)
    except ValueError:
        # Not a UUID, so it identifies nothing. Answered exactly as "no such
        # instance" rather than 422, so malformed, absent and someone else's
        # are one answer — see the comment on ``_NO_SUCH_INSTANCE``.
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=_NO_SUCH_INSTANCE) from None

    try:
        engine = get_engine()
        async with engine.begin() as conn:
            target = await fetch_enabled_connector_for_tenant(conn, wanted, tenant_id)
    except Exception as exc:  # noqa: BLE001 — surfaced as 503, never silent
        logger.exception("connector.resource_config.instance_load_failed")
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="could not load connector instances",
        ) from exc

    if target is None:
        logger.info(
            "connector.resource_config.not_found tenant=%s instance=%s subject=%s",
            _safe_log_val(str(tenant_id)),
            _safe_log_val(instance_id),
            _safe_log_val(principal.subject),
        )
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=_NO_SUCH_INSTANCE)

    cls = CONNECTOR_REGISTRY.get(target.connector_type)
    if cls is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"connector type '{_safe_log_val(target.connector_type)}' is not in this build",
        )

    try:
        auth = get_vault().decrypt_dict(target.auth_config or {})
    except CredentialVaultError as exc:
        logger.error("connector.resource_config.decrypt_failed instance=%s", _safe_log_val(instance_id))
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail="could not decrypt stored credentials",
        ) from exc

    kwargs = {**auth, **_connector_kwargs(target.connector_config or {})}
    try:
        connector = cls(**kwargs)
    except TypeError as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"connector config does not match schema: {exc}",
        ) from exc

    try:
        config = await connector.get_resource_config(resource_id, ts)
    except NotImplementedError as exc:
        # 501 rather than an error: most connectors legitimately cannot
        # time-travel a resource's configuration, and the snapshotter skips
        # them without counting a failure.
        raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail=str(exc)) from exc
    except Exception as exc:  # noqa: BLE001
        logger.exception("connector.resource_config.runtime_error instance=%s", _safe_log_val(instance_id))
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail="Resource-config fetch failed. Check connector configuration and connectivity.",
        ) from exc

    return config


@router.post("/connectors/{connector_id}/resource_config")
async def get_resource_config(connector_id: str, payload: ResourceConfigRequest):
    """Fetch one resource's live configuration (Phase C2 posture collection).

    Trust boundary matches ``/test`` and ``/query``: the API service has
    already decrypted ``auth_config`` against the vault; the connector instance
    lives only for this request. Connectors that don't implement
    ``get_resource_config`` return 501.
    """
    cls = CONNECTOR_REGISTRY.get(connector_id)
    if cls is None:
        raise HTTPException(status_code=404, detail=f"Connector '{connector_id}' not found")

    kwargs = {**payload.auth_config, **payload.connector_config}
    try:
        connector = cls(**kwargs)
    except TypeError as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"connector config does not match schema: {exc}",
        ) from exc

    try:
        config = await connector.get_resource_config(payload.resource_id, payload.at_ts)
    except NotImplementedError as exc:
        raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail=str(exc)) from exc
    except Exception as exc:  # noqa: BLE001
        logger.exception("connector.resource_config.runtime_error", connector_id=_safe_log_val(connector_id))
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail="Resource-config fetch failed. Check connector configuration and connectivity.",
        ) from exc

    return {"connector_id": connector_id, "resource_id": payload.resource_id, "config": config}


@router.post("/connectors/{connector_id}/normalize")
async def normalize_rows(connector_id: str, payload: NormalizeRequest):
    """Run a connector's own ``normalize()`` over raw vendor rows.

    The instance is built with ``__new__`` and no ``__init__``. That is
    deliberate on two counts. ``normalize`` is a pure mapping in every
    connector in this tree, so a configured client is not needed; and not
    building one means this route holds no credential and has nothing to make
    an outbound call with.

    A connector whose ``normalize`` does reach for instance state raises
    ``AttributeError``, and that becomes a 422 naming the connector rather
    than a partially-mapped row. A half-normalized envelope would flow into
    replay looking like a real one and quietly change what the agent was
    graded on.
    """
    cls = CONNECTOR_REGISTRY.get(connector_id)
    if cls is None:
        raise HTTPException(status_code=404, detail=f"Connector '{connector_id}' not found")
    if len(payload.rows) > MAX_NORMALIZE_ROWS:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"{len(payload.rows)} rows exceeds the {MAX_NORMALIZE_ROWS}-row limit for one normalize request",
        )

    connector = cls.__new__(cls)
    normalized: list[dict[str, Any]] = []
    for index, row in enumerate(payload.rows):
        try:
            normalized.append(cls.normalize(connector, dict(row)))
        except AttributeError as exc:
            raise HTTPException(
                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
                detail=(
                    f"connector '{connector_id}' cannot normalize without a configured instance ({exc}); "
                    f"row {index} was not mapped and none are returned"
                ),
            ) from exc
        except Exception as exc:
            logger.exception("connector.normalize.runtime_error", connector_id=_safe_log_val(connector_id))
            raise HTTPException(
                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
                detail=f"connector '{connector_id}' failed to normalize row {index}: {type(exc).__name__}",
            ) from exc

    return {
        "connector_id": connector_id,
        "row_count": len(normalized),
        "rows": normalized,
    }


@router.post("/connectors/{connector_id}/query")
async def run_federated_query(connector_id: str, payload: FederatedQueryRequest):
    """Translate a ``UnifiedQuery`` and run it against the connector's backend.

    Trust boundary mirrors ``/connectors/{id}/test``: the API service has
    already decrypted ``auth_config`` against the credential vault before
    we see it, and the connector instance lives only for the duration of
    this request — we never persist credentials in the connectors
    microservice.

    Connectors that haven't opted into federated search return 501 via
    the ``NotImplementedError`` raised by ``BaseConnector.query``'s
    default. Translation failures (un-translatable operator, malformed
    payload) become 422 so the API layer can surface the offending field.
    """
    cls = CONNECTOR_REGISTRY.get(connector_id)
    if cls is None:
        raise HTTPException(status_code=404, detail=f"Connector '{connector_id}' not found")

    if not getattr(cls, "supports_federated_search", False):
        raise HTTPException(
            status_code=status.HTTP_501_NOT_IMPLEMENTED,
            detail=f"connector '{connector_id}' does not support federated search",
        )

    try:
        unified = parse_unified_query(payload.query)
    except QueryError as exc:
        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc

    kwargs = {**payload.auth_config, **payload.connector_config}
    try:
        connector = cls(**kwargs)
    except TypeError as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"connector config does not match schema: {exc}",
        ) from exc

    try:
        rows = await connector.query(unified)
    except NotImplementedError as exc:
        # Defensive: a connector class can advertise supports_federated_search
        # but a future refactor could leave query() unimplemented. Map to
        # the same 501 we'd return up top.
        raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail=str(exc)) from exc
    except QueryError as exc:
        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
    except Exception as exc:
        logger.exception("connector.query.runtime_error", connector_id=_safe_log_val(connector_id))
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail="Backend query failed. Check connector configuration and connectivity.",
        ) from exc

    return {
        "connector_id": connector_id,
        "row_count": len(rows),
        "rows": rows,
    }


@router.post("/connectors/{connector_id}/push_case")
async def push_case(connector_id: str, payload: PushCaseRequest):
    """Mint or upsert an external ITSM ticket from an AiSOC case.

    Idempotency is the connector's responsibility: when ``external_ref``
    is set, the connector should patch the existing ticket; when it's
    None, it should create one and return enough metadata for the caller
    to persist a ``case_external_refs`` row (``external_id``,
    ``external_url``, ``vendor``, ``external_status``).

    Returns the connector's ``{"external_id", "external_url", "vendor",
    "external_status"}`` envelope. The API service maps that into the
    ``case_external_refs`` table; we never persist anything here.
    """
    cls = CONNECTOR_REGISTRY.get(connector_id)
    if cls is None:
        raise HTTPException(status_code=404, detail=f"Connector '{connector_id}' not found")
    _require_capability(cls, Capability.PUSH_CASE, connector_id)

    kwargs = {**payload.auth_config, **payload.connector_config}
    connector = _instantiate_or_422(cls, kwargs)

    try:
        result = await connector.push_case(payload.case)
    except NotImplementedError as exc:
        raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail=str(exc)) from exc
    except Exception as exc:
        # Don't leak vendor errors verbatim — they sometimes echo request
        # headers / payload fragments. The connector logs the full detail
        # via structlog; the API service just sees a generic 502.
        logger.exception(
            "connector.push_case.runtime_error",
            connector_id=_safe_log_val(connector_id),
        )
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail="Push to external ITSM failed. Check connector configuration and connectivity.",
        ) from exc

    if not isinstance(result, dict):
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail=f"connector '{connector_id}' returned unexpected push_case payload",
        )
    return result


@router.post("/connectors/{connector_id}/push_status_change")
async def push_status_change(connector_id: str, payload: PushStatusChangeRequest):
    """Project an AiSOC status transition onto a previously-pushed ticket.

    If ``external_ref`` is None we delegate to ``push_case`` (i.e. the
    case is being reported to this ITSM for the first time as part of
    the same status update). Otherwise we patch the existing ticket.
    The connector decides which fields to map (state code, resolution,
    close notes, etc.).
    """
    cls = CONNECTOR_REGISTRY.get(connector_id)
    if cls is None:
        raise HTTPException(status_code=404, detail=f"Connector '{connector_id}' not found")
    _require_capability(cls, Capability.PUSH_STATUS, connector_id)

    kwargs = {**payload.auth_config, **payload.connector_config}
    connector = _instantiate_or_422(cls, kwargs)

    try:
        result = await connector.push_status_change(
            payload.case,
            payload.old_status,
            payload.new_status,
            external_ref=payload.external_ref,
        )
    except NotImplementedError as exc:
        raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail=str(exc)) from exc
    except ValueError as exc:
        # e.g. servicenow.push_status_change rejecting a missing sys_id.
        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
    except Exception as exc:
        logger.exception(
            "connector.push_status_change.runtime_error",
            connector_id=_safe_log_val(connector_id),
        )
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail="Status sync to external ITSM failed. Check connector configuration and connectivity.",
        ) from exc

    if not isinstance(result, dict):
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail=f"connector '{connector_id}' returned unexpected push_status_change payload",
        )
    return result


@health_router.get("/health")
async def health():
    return {"status": "healthy", "service": "aisoc-connectors"}