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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(ws8): wire ITSM webhook inbox + ship 113 tests for bidirectional ITSM
Beenu Arora9ff8186d34f8
diff --git a/services/api/app/api/v1/endpoints/inbox.py b/services/api/app/api/v1/endpoints/inbox.pyindex e12df7bfa..65d6641d7 100644--- a/services/api/app/api/v1/endpoints/inbox.py+++ b/services/api/app/api/v1/endpoints/inbox.py@@ -74,6 +74,12 @@ ALLOWED_TEMPLATE_IDS: tuple[str, ...] = ("cef-syslog","splunk-hec","email-forwarded",+ # Bidirectional ITSM (Workstream 8) — inbound Jira / ServiceNow webhooks.+ # Tokens minted with this template terminate at+ # /api/v1/inbox/itsm/{tenant_token}/{connector_instance_id} on services/api+ # rather than the generic ingest path, because they need to resolve back+ # to a specific connector instance and mirror status onto aisoc_cases.+ "itsm-inbound",)# Same character set as connector_type — tightens HMAC body shape.@@ -96,8 +102,39 @@ def _fingerprint(token: str) -> str:return f"...{token[-8:]}" if len(token) > 8 else "...<short>"-def _build_inbox_url(token: str) -> str:- """Build the absolute inbox URL the customer pastes into the vendor."""+def _build_inbox_url(token: str, template_id: str | None = None) -> str:+ """Build the absolute inbox URL the customer pastes into the vendor.++ For most templates (PagerDuty, generic-json, syslog, etc.) the URL+ terminates at services/ingest, which resolves the token to a tenant+ + template_id and runs the OCSF normalizer.++ The exception is ``itsm-inbound`` (Workstream 8). Those URLs need to+ terminate at services/api because they:++ 1. Need a database transaction to update aisoc_cases / case_external_refs.+ 2. Need to look up case_fanout's earlier outbound projection to find+ the AiSOC case ID, which lives in the api-service-managed schema.+ 3. Are pinned to a specific connector instance, so the URL carries a+ ``{connector_instance_id}`` placeholder that the operator fills in+ when they paste it into Jira/ServiceNow's webhook config.++ The placeholder ``<connector_instance_id>`` (UUID) is intentionally+ angle-bracketed so it's obvious in the wizard UI that the operator+ has to substitute it before saving the URL on the vendor side.+ """+ if template_id == "itsm-inbound":+ # Public URL of the API service (NOT the ingest service). Reuses+ # ``OAUTH_PUBLIC_BASE_URL`` because that's already the canonical+ # "where does the world reach my API" setting — adding a separate+ # ``API_PUBLIC_URL`` would duplicate the same value with different+ # names. Falls back to a relative path when unset, which is fine+ # for dev / docker-compose where the operator paste happens on the+ # same host the API is exposed from.+ api_base = (getattr(settings, "OAUTH_PUBLIC_BASE_URL", "") or "").rstrip("/")+ path = f"/api/v1/inbox/itsm/{token}/<connector_instance_id>"+ return f"{api_base}{path}" if api_base else path+base = (getattr(settings, "INGEST_PUBLIC_URL", "") or "").rstrip("/")return f"{base}/v1/inbox/{token}" if base else f"/v1/inbox/{token}"@@ -239,6 +276,17 @@ _TEMPLATE_CATALOG: dict[str, dict[str, str]] = {),"category": "email",},+ "itsm-inbound": {+ "label": "Inbound ITSM (Jira / ServiceNow)",+ "description": (+ "Receive status-change webhooks from Jira or ServiceNow. The URL "+ "must be paired with a specific connector instance — paste it "+ "into the vendor's webhook config alongside the connector ID. "+ "Tokens of this type terminate at services/api so we can mirror "+ "status onto aisoc_cases."+ ),+ "category": "itsm",+ },}@@ -253,7 +301,7 @@ def _to_response(row: TenantInboxToken, *, include_plaintext: bool) -> InboxToke"""return InboxTokenResponse(token=row.token if include_plaintext else _fingerprint(row.token),- inbox_url=_build_inbox_url(row.token),+ inbox_url=_build_inbox_url(row.token, row.template_id),template_id=row.template_id,label=row.label,has_hmac_secret=row.hmac_secret is not None,diff --git a/services/api/app/api/v1/endpoints/inbox_itsm.py b/services/api/app/api/v1/endpoints/inbox_itsm.pynew file mode 100644index 000000000..1ca853d84--- /dev/null+++ b/services/api/app/api/v1/endpoints/inbox_itsm.py@@ -0,0 +1,824 @@+"""Inbound ITSM webhook receiver — Workstream 8 (bidirectional ITSM).++Public-facing counterpart to the *outbound* fan-out implemented in+``app.services.case_fanout``. The flow it closes is:++1. AiSOC case is created or its status changes →+2. ``case_fanout`` POSTs to ``services/connectors`` →+3. Connector creates / updates a Jira issue or ServiceNow incident →+4. Operator works the ticket *in their existing ITSM*, eventually+ transitioning it to "In Progress" / "Done" / "Resolved" / "Closed".+5. Their ITSM fires a webhook at THIS endpoint →+6. We resolve the inbound ticket back to its AiSOC case via+ ``case_external_refs`` and mirror the status onto ``aisoc_cases``.++This is what makes ITSM "the source of truth" — operators never have+to log into AiSOC to change a ticket status; the ITSM they already+live in keeps AiSOC in sync.++Why this lives in a separate module from ``inbox.py``+-----------------------------------------------------+``inbox.py`` is the *operator-facing* management API for tenant inbox+tokens (mint, list, rotate, revoke). Every route there requires an+authenticated user with ``connectors:read`` / ``connectors:write``+permission, because rotating a token is a privileged operation.++This module is the *public webhook receiver*. Authentication is via the+**inbox token in the URL path**, not via a session cookie or bearer.+The two have totally different threat models and audit footprints, so+they live in separate routers (sharing only the ``/inbox`` URL prefix+to keep operator mental models simple).++Auth model+----------+The URL is ``/api/v1/inbox/itsm/{tenant_token}/{connector_instance_id}``,+where:++* ``tenant_token`` is a row from ``tenant_inbox_tokens`` (template_id+ must be ``itsm-inbound``). Resolves to a ``tenant_id``.+* ``connector_instance_id`` is the UUID of a row in ``connectors`` —+ the specific Jira project / ServiceNow instance whose webhooks are+ hitting us. We cross-check that the connector's ``tenant_id`` matches+ the token's ``tenant_id`` so a leaked token from tenant A can't be+ paired with a connector from tenant B.++Optional second factor: if the operator set ``hmac_secret`` on the+inbox token, we verify ``X-AiSOC-Signature: sha256=<hex>`` against+``HMAC(secret, raw_body)`` and reject mismatches.++Idempotency+-----------+Vendor webhooks retry aggressively (Jira up to 5×, ServiceNow until+the destination 200s). Every code path here is structured so that+re-delivering the same payload is a no-op — we look up the case by+``(connector_instance_id, external_id)``, compare the inbound status+to the current AiSOC status, and only write when they actually differ.+A redelivered "Done" event after we've already closed the case bumps+``case_external_refs.last_synced_at`` and nothing else.++What we explicitly do NOT do+----------------------------+* We do not let the ITSM transition the AiSOC case into states that+ don't exist in our enum (``new``, ``triaged``, ``investigating``,+ ``contained``, ``resolved``, ``closed``). Anything we can't map+ cleanly is treated as "no status change" and the case stays put —+ but we still bump ``last_synced_at`` so the operator knows the+ webhook is alive.+* We do not delete cases when an ITSM ticket is deleted. That's+ destructive and irreversible; the operator must close the case+ through AiSOC's own UI.+* We do not honour assignment / priority changes. They're trivially+ reversible if we ever want them later, but for now ITSM is only the+ source of truth for *status*. Comments, custom fields, etc. are+ one-way (AiSOC → ITSM only).+"""++from __future__ import annotations++import hashlib+import hmac+import logging+import uuid+from datetime import UTC, datetime+from typing import Any++from fastapi import APIRouter, Header, HTTPException, Request, status+from pydantic import BaseModel+from sqlalchemy import text++from app.api.v1.deps import DBSession++logger = logging.getLogger(__name__)++# Same prefix as ``inbox.py`` (operator-facing) so the public URL is+# /api/v1/inbox/itsm/.... The two modules share the prefix but not the+# auth / permission stack — see module docstring.+router = APIRouter(prefix="/inbox", tags=["inbox-itsm"])+++# ---------------------------------------------------------------------------+# Status reverse maps. Inbound (vendor → AiSOC) is intentionally lossy and+# canonicalising — multiple vendor states collapse onto a single AiSOC state.+# We keep the maps narrow on purpose:+#+# * Lower-case the vendor token before lookup, so "DONE", "Done", and+# "done" all hit the same row.+# * Anything we don't recognise returns None and the caller treats that+# as "no status change" (still bump last_synced_at so operators see the+# ping landed).+#+# These mirror the *forward* maps in+# ``services/connectors/app/connectors/jira_connector.py`` and+# ``services/connectors/app/connectors/servicenow.py`` — kept as a+# duplicate intentionally because:+#+# * Forward maps are owned by the connectors microservice (Python AND+# potentially Go ports later); inbound maps are owned by the API+# service. Sharing a constant module across the network boundary+# would couple deploy lifecycles unnecessarily.+# * The directions are not symmetric (forward has finer granularity+# than reverse), so keeping them separate makes each half readable.+# ---------------------------------------------------------------------------++_JIRA_INBOUND_STATUS: dict[str, str] = {+ # Standard Jira status names. We match against ``status.name`` from the+ # webhook payload, lower-cased.+ "to do": "triaged",+ "open": "triaged",+ "backlog": "triaged",+ "selected for development": "triaged",+ "in progress": "investigating",+ "in review": "investigating",+ "blocked": "contained",+ "on hold": "contained",+ "resolved": "resolved",+ "done": "resolved",+ "closed": "closed",+ "cancelled": "closed",+ "canceled": "closed",+ "won't fix": "closed",+ "wont fix": "closed",+ "won't do": "closed",+}+++_SNOW_INBOUND_STATUS: dict[str, str] = {+ # ServiceNow ``state`` is numeric. Mapping from sys_choice list values+ # for the ``incident`` table:+ # 1 = New, 2 = In Progress, 3 = On Hold, 6 = Resolved, 7 = Closed,+ # 8 = Cancelled.+ "1": "triaged",+ "2": "investigating",+ "3": "contained",+ "6": "resolved",+ "7": "closed",+ "8": "closed",+}+++# Connector types we accept inbound webhooks from. Anything else 422s — we+# don't want a misconfigured connector pointing the wrong vendor's webhook+# at this URL and silently dropping events.+_SUPPORTED_VENDORS: frozenset[str] = frozenset({"jira", "servicenow"})+++# Inbox tokens used for ITSM inbound MUST carry this template_id. Operator+# UI mints tokens with this template specifically so an inbox token minted+# for, say, PagerDuty alert ingest can't accidentally be repurposed as an+# ITSM webhook receiver (which would be tenant-scoped but could trigger+# unwanted status changes on cases).+_ITSM_TEMPLATE_ID = "itsm-inbound"+++# ---------------------------------------------------------------------------+# Lightweight wire schemas — we don't strictly validate the full vendor+# payload because Jira and ServiceNow both expose long-tail custom fields+# and rejecting unknown keys would brick operator workflows. We only pull+# the handful of fields we actually act on.+# ---------------------------------------------------------------------------+++class InboundResult(BaseModel):+ """Response body for the inbound webhook."""++ case_id: uuid.UUID | None+ """AiSOC case the inbound event mapped to. ``None`` means the external+ ID wasn't found — the webhook is acknowledged with 200 anyway, because+ Jira/ServiceNow will retry forever on non-2xx and we don't want one+ stale ticket to block the queue."""++ case_number: str | None+ """Operator-friendly handle (e.g. ``CASE-1023``). None when ``case_id``+ is None or the underlying ``aisoc_cases`` row predates case_number."""++ external_id: str | None+ """The vendor handle we extracted from the payload (Jira issue key,+ ServiceNow sys_id). None means we couldn't find one — the payload is+ malformed and we logged the parse failure."""++ old_status: str | None+ """AiSOC status before this webhook. None when ``case_id`` is None."""++ new_status: str | None+ """AiSOC status after applying the inbound transition. Equal to+ ``old_status`` when the inbound vendor state didn't map to anything+ actionable, or when the case was already in the target state."""++ status_changed: bool+ """True iff we wrote a new status onto ``aisoc_cases``."""++ note: str | None = None+ """Human-readable explanation when nothing happened (unknown external_id,+ unmapped status, etc.). Useful in webhook delivery logs."""+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _verify_hmac(+ *,+ secret: str | None,+ raw_body: bytes,+ signature_header: str | None,+) -> None:+ """Reject the request if the inbox token has an HMAC secret and the+ inbound signature header doesn't match.++ Accepts both ``sha256=<hex>`` (GitHub-style) and bare ``<hex>`` because+ Jira and ServiceNow's webhook implementations differ. ``hmac.compare_digest``+ is constant-time.++ No-op when ``secret`` is None — the inbox token in the URL is the only+ authenticator in that case, which is the correct trust model when the+ vendor doesn't support HMAC signatures (older ServiceNow installs,+ bespoke webhook proxies, etc.).+ """+ if secret is None:+ return++ if signature_header is None or not signature_header.strip():+ raise HTTPException(+ status_code=status.HTTP_401_UNAUTHORIZED,+ detail="HMAC signature required for this inbox token",+ )++ sig = signature_header.strip()+ if sig.lower().startswith("sha256="):+ sig = sig.split("=", 1)[1].strip()++ expected = hmac.new(+ secret.encode("utf-8"),+ raw_body,+ hashlib.sha256,+ ).hexdigest()++ if not hmac.compare_digest(sig.lower(), expected.lower()):+ raise HTTPException(+ status_code=status.HTTP_401_UNAUTHORIZED,+ detail="Invalid HMAC signature",+ )+++def _parse_jira_payload(payload: dict[str, Any]) -> tuple[str | None, str | None]:+ """Pull ``issue.key`` + ``issue.fields.status.name`` from a Jira webhook.++ Jira posts the full issue under ``issue`` for both ``jira:issue_created``+ and ``jira:issue_updated`` events. We only act on transitions, so we+ don't bother distinguishing the two — if there's a status to set, set it.++ Returns ``(external_id, status_name)``. Either or both may be None when+ the payload is malformed; the caller treats that as a no-op.+ """+ issue = payload.get("issue") or {}+ if not isinstance(issue, dict):+ return None, None++ key = issue.get("key")+ if not isinstance(key, str) or not key:+ return None, None++ fields = issue.get("fields") or {}+ if not isinstance(fields, dict):+ return key, None++ status_obj = fields.get("status") or {}+ if not isinstance(status_obj, dict):+ return key, None++ name = status_obj.get("name")+ if not isinstance(name, str):+ return key, None++ return key, name+++def _parse_servicenow_payload(+ payload: dict[str, Any],+) -> tuple[str | None, str | None]:+ """Pull ``sys_id`` + ``state`` from a ServiceNow business rule webhook.++ ServiceNow's webhook payloads are operator-configured via a business+ rule, but the canonical shape is a JSON object whose top-level keys+ are the column names of the ``incident`` table — same shape as the+ REST Table API GET response. We accept both that shape and a thin+ wrapper of ``{"current": {...}}`` (the form used when the operator+ forwards the BR's ``current`` GlideRecord directly).++ State is normalised to a string so the lookup against+ ``_SNOW_INBOUND_STATUS`` works for both ``"6"`` and ``6``.+ """+ record = payload.get("current") if "current" in payload else payload+ if not isinstance(record, dict):+ return None, None++ sys_id = record.get("sys_id")+ if not isinstance(sys_id, str) or not sys_id:+ # ServiceNow always populates sys_id; if it's missing the payload+ # is from a BR that didn't include it and we can't correlate.+ return None, None++ state = record.get("state")+ if state is None:+ return sys_id, None++ return sys_id, str(state)+++def _map_inbound_status(vendor: str, raw_status: str | None) -> str | None:+ """Look up the AiSOC equivalent of a vendor status, or None.++ Returns None for both "vendor returned no status" and "we don't know+ how to map it" — they're the same outcome from the caller's point of+ view (don't change the AiSOC status).+ """+ if raw_status is None:+ return None+ if vendor == "jira":+ return _JIRA_INBOUND_STATUS.get(raw_status.strip().lower())+ if vendor == "servicenow":+ return _SNOW_INBOUND_STATUS.get(raw_status.strip())+ return None+++async def _fetch_token_and_connector(+ db: Any,+ *,+ tenant_token: str,+ connector_instance_id: uuid.UUID,+) -> tuple[Any, Any]:+ """Resolve the inbox token and connector instance, verifying tenant match.++ Returns ``(inbox_token_row, connector_row)``. Raises 401/404 on missing+ or mismatched rows so the caller can stay focused on payload handling.++ The two lookups are deliberately separate queries (instead of a single+ JOIN) because:++ * They have different cache profiles — the token row is read on every+ webhook delivery, the connector row changes when the operator edits+ auth_config / the OAuth refresh worker runs.+ * 401 vs 404 carries different signal: a missing token is "this URL+ was revoked or never existed", a missing connector is "the operator+ detached this integration but forgot to update the vendor webhook".+ Distinguishing them helps webhook delivery debugging.+ """+ # 1. Resolve the token. We require revoked_at IS NULL — once an+ # operator rotates the token, the old one MUST stop accepting traffic.+ token_row = (+ await db.execute(+ text(+ """+ SELECT token, tenant_id, template_id, hmac_secret, revoked_at+ FROM tenant_inbox_tokens+ WHERE token = :token AND revoked_at IS NULL+ """+ ).bindparams(token=tenant_token)+ )+ ).fetchone()+ if token_row is None:+ # Don't echo the token in the error — even the trailing 8 chars+ # would help an attacker confirm a guess. The structlog event+ # carries the fingerprint for ops debugging.+ logger.info(+ "inbox_itsm.token_not_found",+ extra={"token_fingerprint": f"...{tenant_token[-8:]}"},+ )+ raise HTTPException(+ status_code=status.HTTP_401_UNAUTHORIZED,+ detail="Invalid or revoked inbox token",+ )++ if token_row.template_id != _ITSM_TEMPLATE_ID:+ # An operator paired a vendor's ITSM webhook with an inbox token+ # minted for a different purpose (e.g. PagerDuty alert ingest).+ # We refuse to act on it — let the wizard mint a fresh ITSM token.+ raise HTTPException(+ status_code=status.HTTP_403_FORBIDDEN,+ detail=(+ "Inbox token is not valid for ITSM webhooks. "+ "Mint a token with template_id='itsm-inbound'."+ ),+ )++ # 2. Resolve the connector. tenant_id check below prevents using a+ # token from one tenant against a connector from another.+ connector_row = (+ await db.execute(+ text(+ """+ SELECT id, tenant_id, connector_type, enabled+ FROM connectors+ WHERE id = :id+ """+ ).bindparams(id=connector_instance_id)+ )+ ).fetchone()+ if connector_row is None:+ raise HTTPException(+ status_code=status.HTTP_404_NOT_FOUND,+ detail="Connector instance not found",+ )++ if connector_row.tenant_id != token_row.tenant_id:+ # Cross-tenant attempt — log loudly so the SOC can investigate.+ logger.warning(+ "inbox_itsm.cross_tenant_attempt",+ extra={+ "token_tenant_id": str(token_row.tenant_id),+ "connector_tenant_id": str(connector_row.tenant_id),+ "connector_id": str(connector_instance_id),+ },+ )+ raise HTTPException(+ status_code=status.HTTP_403_FORBIDDEN,+ detail="Token and connector belong to different tenants",+ )++ if not connector_row.enabled:+ # A disabled connector should not be receiving traffic. Prefer 409+ # over 200 here so the vendor's webhook delivery dashboard surfaces+ # the issue instead of silently consuming the events.+ raise HTTPException(+ status_code=status.HTTP_409_CONFLICT,+ detail="Connector instance is disabled",+ )++ if connector_row.connector_type not in _SUPPORTED_VENDORS:+ raise HTTPException(+ status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,+ detail=(+ f"connector_type '{connector_row.connector_type}' is not "+ "supported on the inbound ITSM webhook. "+ f"Supported: {', '.join(sorted(_SUPPORTED_VENDORS))}."+ ),+ )++ return token_row, connector_row+++async def _apply_status_to_case(+ db: Any,+ *,+ case_row: Any,+ new_status: str,+ actor_label: str,+ external_id: str,+ vendor: str,+) -> None:+ """Mirror an inbound status onto ``aisoc_cases`` + write a system note.++ Three writes in one transaction (the caller commits):++ 1. ``aisoc_cases``: status, updated_at, plus the timeline columns+ (``triaged_at`` / ``resolved_at`` / ``closed_at``) the appropriate+ transition implies. Mirrors the logic in+ ``cases.update_case`` so AiSOC's own audit math stays consistent.+ 2. ``case_external_refs``: ``external_status`` + ``last_synced_at``.+ This is what makes the *next* outbound ``push_status_change`` a+ no-op — the connector compares ``external_status`` to the desired+ state and short-circuits when they already match.+ 3. ``aisoc_case_comments``: a system note ("ServiceNow set state to+ Resolved → AiSOC case marked resolved") so the timeline view shows+ the inbound transition with its provenance.++ The caller has already verified ``new_status`` is in the allowed set,+ so we don't re-validate here.+ """+ now = datetime.now(UTC)++ # Map status → which timeline column to bump. We never *clear* a column+ # — once a case has been triaged, the timestamp stays even if it later+ # moves back to "new" (which the inbound flow can't actually do+ # anyway, but defending in depth is cheap). COALESCE keeps the first+ # transition's timestamp.+ triaged_at_set = (+ ", triaged_at = COALESCE(triaged_at, :now)"+ if new_status in {"triaged", "investigating", "contained", "resolved", "closed"}+ else ""+ )+ resolved_at_set = (+ ", resolved_at = COALESCE(resolved_at, :now)"+ if new_status == "resolved"+ else ""+ )+ closed_at_set = (+ ", closed_at = COALESCE(closed_at, :now)"+ if new_status == "closed"+ else ""+ )++ await db.execute(+ text(+ f"""+ UPDATE aisoc_cases+ SET status = :status,+ updated_at = :now+ {triaged_at_set}+ {resolved_at_set}+ {closed_at_set}+ WHERE id = :id+ """+ ).bindparams(status=new_status, now=now, id=case_row.id)+ )++ await db.execute(+ text(+ """+ UPDATE case_external_refs+ SET external_status = :ext_status,+ last_synced_at = :now,+ updated_at = :now+ WHERE case_id = :case_id AND external_id = :external_id+ """+ ).bindparams(+ ext_status=new_status,+ now=now,+ case_id=case_row.id,+ external_id=external_id,+ )+ )++ note_body = (+ f"{vendor.title()} ticket {external_id} transitioned. "+ f"AiSOC case marked '{new_status}' via inbound webhook."+ )+ await db.execute(+ text(+ """+ INSERT INTO aisoc_case_comments+ (id, case_id, author, body, is_system, created_at)+ VALUES+ (:id, :case_id, :author, :body, TRUE, :now)+ """+ ).bindparams(+ id=uuid.uuid4(),+ case_id=case_row.id,+ author=actor_label,+ body=note_body,+ now=now,+ )+ )+++# ---------------------------------------------------------------------------+# Endpoint+# ---------------------------------------------------------------------------+++ "/itsm/{tenant_token}/{connector_instance_id}",+ response_model=InboundResult,+ summary="Inbound ITSM webhook (Jira / ServiceNow → AiSOC case)",+)+async def inbound_itsm_webhook(+ tenant_token: str,+ connector_instance_id: uuid.UUID,+ request: Request,+ db: DBSession,+ x_aisoc_signature: str | None = Header(default=None, alias="X-AiSOC-Signature"),+) -> InboundResult:+ """Receive a Jira / ServiceNow webhook and mirror status onto AiSOC.++ Public-facing — the only authenticator is the ``tenant_token`` in the+ URL (and an optional ``X-AiSOC-Signature`` HMAC). Rate limiting and+ DDoS protection are expected to live at the edge (Cloudflare /+ upstream LB), not here — the vendor's source IPs are stable enough+ that the ops team can configure WAF rules.++ Always returns 200 (never 5xx) on the happy path, even when the+ payload doesn't map to anything actionable. Vendor webhook+ implementations retry forever on non-2xx, and a stale ticket pinging+ a long-deleted case shouldn't block the rest of the queue. We surface+ "nothing happened" via ``InboundResult.status_changed=False`` and a+ human-readable ``note``.+ """++ raw_body = await request.body()++ token_row, connector_row = await _fetch_token_and_connector(+ db,+ tenant_token=tenant_token,+ connector_instance_id=connector_instance_id,+ )++ _verify_hmac(+ secret=token_row.hmac_secret,+ raw_body=raw_body,+ signature_header=x_aisoc_signature,+ )++ # Parse JSON ourselves so we get the raw body for HMAC verification+ # *before* JSON parsing ever runs. ``request.json()`` would consume+ # the stream and we'd have nothing to verify against.+ try:+ import json++ payload = json.loads(raw_body or b"{}")+ except json.JSONDecodeError as exc:+ raise HTTPException(+ status_code=status.HTTP_400_BAD_REQUEST,+ detail=f"Webhook body is not valid JSON: {exc.msg}",+ ) from exc+ if not isinstance(payload, dict):+ raise HTTPException(+ status_code=status.HTTP_400_BAD_REQUEST,+ detail="Webhook body must be a JSON object",+ )++ vendor = connector_row.connector_type+ if vendor == "jira":+ external_id, raw_status = _parse_jira_payload(payload)+ elif vendor == "servicenow":+ external_id, raw_status = _parse_servicenow_payload(payload)+ else:+ # Already filtered in _fetch_token_and_connector but be defensive —+ # the tuple of supported vendors is the only place this list is+ # ever updated.+ raise HTTPException(+ status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,+ detail=f"unsupported vendor: {vendor}",+ )++ if external_id is None:+ # Malformed payload — log the connector so ops can debug, but+ # 200 the vendor so they don't retry endlessly. We saw this in+ # the wild when ServiceNow business rules emit synthetic+ # "current=null" events on initial deploy.+ logger.info(+ "inbox_itsm.payload_missing_external_id",+ extra={+ "vendor": vendor,+ "connector_id": str(connector_instance_id),+ "tenant_id": str(token_row.tenant_id),+ },+ )+ return InboundResult(+ case_id=None,+ case_number=None,+ external_id=None,+ old_status=None,+ new_status=None,+ status_changed=False,+ note=f"{vendor} payload missing required fields",+ )++ # Resolve external_id → AiSOC case via case_external_refs. The unique+ # constraint on (connector_instance_id, external_id) guarantees at+ # most one row.+ ref_row = (+ await db.execute(+ text(+ """+ SELECT r.id, r.case_id, r.external_status,+ c.id AS aisoc_case_id, c.case_number, c.status+ FROM case_external_refs r+ JOIN aisoc_cases c ON c.id = r.case_id+ WHERE r.connector_instance_id = :connector_id+ AND r.external_id = :external_id+ """+ ).bindparams(+ connector_id=connector_instance_id,+ external_id=external_id,+ )+ )+ ).fetchone()++ if ref_row is None:+ # ITSM ticket exists on the vendor side but we don't have it+ # linked to any AiSOC case. This is normal during onboarding+ # (operator imported pre-existing tickets) — bump nothing, log,+ # and 200 the vendor.+ logger.info(+ "inbox_itsm.unlinked_external_id",+ extra={+ "vendor": vendor,+ "external_id": external_id,+ "connector_id": str(connector_instance_id),+ "tenant_id": str(token_row.tenant_id),+ },+ )+ return InboundResult(+ case_id=None,+ case_number=None,+ external_id=external_id,+ old_status=None,+ new_status=None,+ status_changed=False,+ note=(+ f"No AiSOC case linked to {vendor} {external_id}. "+ "The ticket may pre-date the integration."+ ),+ )++ # Update last_used_at on the inbox token regardless of whether the+ # status changed, so operators can see "this token is alive". Done+ # on every successful auth+resolve, not just on writes.+ now = datetime.now(UTC)+ await db.execute(+ text(+ "UPDATE tenant_inbox_tokens SET last_used_at = :now WHERE token = :tok"+ ).bindparams(now=now, tok=tenant_token)+ )++ new_status = _map_inbound_status(vendor, raw_status)+ if new_status is None:+ # Either the vendor sent no status field or we don't have a+ # mapping for it. Bump last_synced_at so the timeline shows the+ # ping landed but don't change the case.+ await db.execute(+ text(+ """+ UPDATE case_external_refs+ SET last_synced_at = :now, updated_at = :now+ WHERE id = :id+ """+ ).bindparams(now=now, id=ref_row.id)+ )+ await db.commit()+ return InboundResult(+ case_id=ref_row.aisoc_case_id,+ case_number=ref_row.case_number,+ external_id=external_id,+ old_status=ref_row.status,+ new_status=ref_row.status,+ status_changed=False,+ note=(+ f"{vendor} status '{raw_status}' has no AiSOC equivalent; "+ "last_synced_at bumped."+ ),+ )++ if new_status == ref_row.status:+ # Idempotent redelivery — case is already in the target state.+ # Touch sync columns and return.+ await db.execute(+ text(+ """+ UPDATE case_external_refs+ SET external_status = :ext_status,+ last_synced_at = :now,+ updated_at = :now+ WHERE id = :id+ """+ ).bindparams(ext_status=new_status, now=now, id=ref_row.id)+ )+ await db.commit()+ return InboundResult(+ case_id=ref_row.aisoc_case_id,+ case_number=ref_row.case_number,+ external_id=external_id,+ old_status=ref_row.status,+ new_status=new_status,+ status_changed=False,+ note="Case already in target state; sync timestamps refreshed.",+ )++ # Real status change. The actor label leaks the connector_type only,+ # never the full URL or sys_id — that detail goes in the body of the+ # system comment.+ actor_label = f"itsm-webhook ({vendor})"+ try:+ await _apply_status_to_case(+ db,+ case_row=ref_row,+ new_status=new_status,+ actor_label=actor_label,+ external_id=external_id,+ vendor=vendor,+ )+ await db.commit()+ except Exception as exc:+ await db.rollback()+ logger.exception(+ "inbox_itsm.apply_failed",+ extra={+ "vendor": vendor,+ "external_id": external_id,+ "case_id": str(ref_row.aisoc_case_id),+ },+ )+ raise HTTPException(+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,+ detail=f"Failed to apply inbound status: {exc}",+ ) from exc++ logger.info(+ "inbox_itsm.status_applied",+ extra={+ "vendor": vendor,+ "external_id": external_id,+ "case_id": str(ref_row.aisoc_case_id),+ "old_status": ref_row.status,+ "new_status": new_status,+ },+ )+ return InboundResult(+ case_id=ref_row.aisoc_case_id,+ case_number=ref_row.case_number,+ external_id=external_id,+ old_status=ref_row.status,+ new_status=new_status,+ status_changed=True,+ )diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.pyindex 1f9ab66bb..532768fe4 100644--- a/services/api/app/api/v1/router.py+++ b/services/api/app/api/v1/router.py@@ -28,6 +28,7 @@ from app.api.v1.endpoints import (hunts,identity_timeline,inbox,+ inbox_itsm,knowledge_base,lake,nl_detection,@@ -166,6 +167,15 @@ api_router.include_router(agents.router)# tenant + template_id and reuses the existing OCSF normalizer.api_router.include_router(inbox.router)+# Bidirectional ITSM webhook receiver (Workstream 8 of AI Stack plan).+# /inbox/itsm/{tenant_token}/{connector_instance_id} accepts inbound+# Jira / ServiceNow webhooks, resolves the external ticket back to its+# AiSOC case via case_external_refs, and mirrors the status onto+# aisoc_cases. This is the *inbound* counterpart to case_fanout (which+# handles outbound AiSOC → ITSM projection) and is what makes the+# operator's existing ITSM the source of truth for case status.+api_router.include_router(inbox_itsm.router)+# Tenant lake API (Workstream 7 of AI Stack plan).# /lake/sql executes a tenant-scoped SELECT against the warm tier# (ClickHouse) after passing through the SQL rewriter, which enforces adiff --git a/services/api/tests/test_case_fanout.py b/services/api/tests/test_case_fanout.pynew file mode 100644index 000000000..265e697d5--- /dev/null+++ b/services/api/tests/test_case_fanout.py@@ -0,0 +1,678 @@+"""Unit tests for the case → ITSM fan-out service (Workstream 8).++The fan-out service projects AiSOC case lifecycle events onto external+ITSM systems via the connectors microservice. The behaviour we care+about most:++* ``_serialize_case_for_push`` — converts ORM rows / mappings into a+ bounded payload (no observable_graph, no evidence_chain) so a noisy+ Jira logger can't accidentally exfiltrate intra-tenant data.+* ``_post_to_connector_service`` — wraps every ``httpx`` failure mode+ into a tagged status string so the calling endpoint never has to+ catch transport errors itself.+* ``fanout_create_case`` — happy path, vault decrypt failure, 501+ unsupported, transport error, missing ``external_id`` in body.+* ``fanout_status_change`` — walks ``case_external_refs``, surfaces+ orphaned refs as ``skipped`` (FK is on case_id, not connector_id),+ and updates the persisted ``external_status``.++We mock the AsyncSession the same way ``test_inbox_itsm_endpoint`` does+— a ``MagicMock`` with ``execute`` as ``AsyncMock`` — and patch ``httpx``++ the credential vault rather than booting the full FastAPI app. That+keeps each test focused on a single decision branch in the fan-out+state machine.+"""++from __future__ import annotations++import uuid+from types import SimpleNamespace+from typing import Any+from unittest.mock import AsyncMock, MagicMock, patch++import httpx+import pytest+from app.services.case_fanout import (+ FanoutResult,+ ITSM_PUSH_CAPABLE_TYPES,+ _post_to_connector_service,+ _push_case_url,+ _push_status_url,+ _serialize_case_for_push,+ fanout_create_case,+ fanout_status_change,+)+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_connector(+ *,+ connector_id: uuid.UUID | None = None,+ connector_type: str = "jira",+ name: str = "Jira (Prod)",+ auth_config: dict[str, Any] | None = None,+ connector_config: dict[str, Any] | None = None,+ is_enabled: bool = True,+ tenant_id: uuid.UUID | None = None,+) -> SimpleNamespace:+ """Build a minimal ORM-shaped Connector stub.++ SimpleNamespace mirrors the attribute access pattern the fan-out+ code uses (``connector.id``, ``connector.connector_type``, …) so we+ don't need to instantiate the real SQLAlchemy model and risk session+ binding side-effects.+ """+ return SimpleNamespace(+ id=connector_id or uuid.uuid4(),+ tenant_id=tenant_id or uuid.uuid4(),+ connector_type=connector_type,+ name=name,+ is_enabled=is_enabled,+ auth_config=auth_config or {"api_token": "vault:v1:zzz"},+ connector_config=connector_config or {"site_url": "https://example.atlassian.net"},+ )+++def _make_case_row(+ *,+ case_id: uuid.UUID | None = None,+ status: str = "open",+ title: str = "Phishing wave from acme.bad",+ severity: str = "high",+) -> dict[str, Any]:+ """Build a case row with the columns ``_serialize_case_for_push`` reads.++ We return a plain dict because ``_serialize_case_for_push`` accepts+ ORM Row (with ``_mapping``) or dict — not raw SimpleNamespace. The+ serializer reads the ``id``/``status``/``title`` columns and ignores+ everything else, so we deliberately include ``observable_graph`` and+ ``evidence_chain`` as honeypots: if they ever appear in the output+ payload, the ``_serialize_case_for_push_drops_internal_fields`` test+ will fail.+ """+ return {+ "id": case_id or uuid.uuid4(),+ "case_number": "AISOC-1234",+ "title": title,+ "description": "Operator notes",+ "severity": severity,+ "status": status,+ "assignee": None,+ "tags": {"env": "prod"},+ "mitre_techniques": ["T1566"],+ # Honeypot fields — must NOT be in serialized payload.+ "observable_graph": {"nodes": ["leak"]},+ "evidence_chain": [{"hash": "secret"}],+ }+++def _build_db_with_connectors(+ connectors: list[Any],+ refs: list[dict[str, Any]] | None = None,+) -> Any:+ """Build a MagicMock DB session that replays the queries fan-out runs.++ ``fanout_create_case`` issues exactly one ``select(Connector)``+ followed by zero-or-more ``_upsert_external_ref`` writes. We set up+ ``side_effect`` on ``execute`` so the ``select`` returns a result+ whose ``.scalars().all()`` matches ``connectors``, and subsequent+ INSERT calls just return a no-op MagicMock.++ ``fanout_status_change`` issues:+ 1. a ``SELECT`` against ``case_external_refs`` returning ``refs``,+ 2. a ``select(Connector)`` returning ``connectors``,+ 3. one ``INSERT … ON CONFLICT`` per ref.++ We let any extra ``execute`` calls fall through to a plain MagicMock+ so writes don't blow up the test even if the count drifts by one.+ """+ db = MagicMock()+ select_result = MagicMock()+ select_result.scalars.return_value.all.return_value = list(connectors)++ refs_result = MagicMock()+ refs_result.fetchall.return_value = [+ SimpleNamespace(_mapping=ref) for ref in (refs or [])+ ]++ side_effects: list[Any] = []+ if refs is not None:+ # Status-change path: refs first, connectors second, then writes.+ side_effects.append(refs_result)+ side_effects.append(select_result)+ # Pad out write responses; AsyncMock side_effect runs out → re-uses+ # the last entry only if it's a callable, so we explicitly pad.+ for _ in range(8):+ side_effects.append(MagicMock())++ db.execute = AsyncMock(side_effect=side_effects)+ return db+++def _build_post_response(+ *,+ status_code: int = 200,+ json_body: dict[str, Any] | None = None,+ text_body: str | None = None,+) -> Any:+ """Build a fake httpx Response. Avoids the real Response constructor+ so we can drive ``resp.json()`` / ``resp.text`` shape directly."""+ resp = MagicMock()+ resp.status_code = status_code+ resp.content = b"non-empty" if (json_body is not None or text_body) else b""+ if json_body is not None:+ resp.json.return_value = json_body+ else:+ resp.json.side_effect = ValueError("no json")+ resp.text = text_body or ""+ return resp+++# ---------------------------------------------------------------------------+# URL helpers+# ---------------------------------------------------------------------------+++def test_push_case_url_uses_connectors_service_base() -> None:+ url = _push_case_url("jira")+ assert url.endswith("/api/v1/connectors/jira/push_case")+++def test_push_status_url_uses_connectors_service_base() -> None:+ url = _push_status_url("servicenow")+ assert url.endswith("/api/v1/connectors/servicenow/push_status_change")+++def test_itsm_push_capable_types_is_locked_down() -> None:+ """The allow-list MUST stay tight. Adding a new connector here+ enables fan-out for that vendor; do not relax casually."""+ assert ITSM_PUSH_CAPABLE_TYPES == frozenset({"jira", "servicenow"})+++# ---------------------------------------------------------------------------+# _serialize_case_for_push+# ---------------------------------------------------------------------------+++def test_serialize_case_for_push_drops_internal_fields() -> None:+ """Observable graph + evidence chain must NEVER be in the outbound+ payload. A misconfigured Jira logger that dumps the request body+ would leak intra-tenant graph data otherwise."""+ case = _make_case_row()+ payload = _serialize_case_for_push(case)+ assert "observable_graph" not in payload+ assert "evidence_chain" not in payload+ assert payload["title"] == case["title"]+ assert payload["status"] == case["status"]+ assert payload["mitre_techniques"] == ["T1566"]+ assert payload["tags"] == {"env": "prod"}+++def test_serialize_case_for_push_handles_dict_input() -> None:+ case_id = uuid.uuid4()+ payload = _serialize_case_for_push(+ {"id": case_id, "title": "T", "status": "open", "severity": "low"}+ )+ assert payload["id"] == str(case_id)+ assert payload["title"] == "T"+ # Defaults for unset list/dict columns.+ assert payload["tags"] == {}+ assert payload["mitre_techniques"] == []+++def test_serialize_case_for_push_handles_row_with_mapping() -> None:+ """SQLAlchemy returns ``Row`` with ``_mapping`` for raw text() results.+ The serializer must accept both ORM-style attribute access and the+ Row mapping protocol."""+ case_id = uuid.uuid4()+ row = SimpleNamespace(_mapping={"id": case_id, "title": "from-row", "status": "closed"})+ payload = _serialize_case_for_push(row)+ assert payload["id"] == str(case_id)+ assert payload["title"] == "from-row"+++# ---------------------------------------------------------------------------+# _post_to_connector_service+# ---------------------------------------------------------------------------+++async def test_post_returns_ok_on_2xx() -> None:+ fake_resp = _build_post_response(+ status_code=200,+ json_body={"external_id": "AIS-1", "vendor": "jira"},+ )+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ status, body, err = await _post_to_connector_service(+ url="http://x/y", payload={}, timeout_seconds=5.0+ )+ assert status == "ok"+ assert body == {"external_id": "AIS-1", "vendor": "jira"}+ assert err is None+++async def test_post_returns_unsupported_on_501() -> None:+ fake_resp = _build_post_response(status_code=501, text_body="capability missing")+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ status, body, err = await _post_to_connector_service(+ url="http://x/y", payload={}, timeout_seconds=5.0+ )+ assert status == "unsupported"+ assert body is None+ assert err == "capability missing"+++async def test_post_returns_error_on_4xx_with_detail() -> None:+ fake_resp = _build_post_response(+ status_code=400,+ json_body={"detail": "missing project_key"},+ )+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ status, body, err = await _post_to_connector_service(+ url="http://x/y", payload={}, timeout_seconds=5.0+ )+ assert status == "error"+ assert body is None+ assert "missing project_key" in (err or "")+++async def test_post_returns_error_on_transport_failure() -> None:+ """``httpx.HTTPError`` (DNS, refused, timeout) must NOT escape.++ Fan-out is best-effort; a flaky Jira tenant must not 503 the case+ create endpoint."""+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ side_effect=httpx.ConnectError("dns failed")+ )+ status, body, err = await _post_to_connector_service(+ url="http://x/y", payload={}, timeout_seconds=5.0+ )+ assert status == "error"+ assert body is None+ assert "connectors service unreachable" in (err or "")+++async def test_post_returns_error_on_non_dict_body() -> None:+ """A connectors service that returns ``[1,2,3]`` is buggy. Surface+ that as an error rather than crashing further down with KeyError."""+ fake_resp = _build_post_response(status_code=200, json_body=[1, 2, 3]) # type: ignore[arg-type]+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ status, body, err = await _post_to_connector_service(+ url="http://x/y", payload={}, timeout_seconds=5.0+ )+ assert status == "error"+ assert "unexpected payload shape" in (err or "")+++# ---------------------------------------------------------------------------+# fanout_create_case+# ---------------------------------------------------------------------------+++async def test_fanout_create_case_returns_empty_when_no_connectors() -> None:+ """Common case: operator created a case without selecting any+ connectors. We must NOT contact the connectors service at all."""+ db = MagicMock()+ db.execute = AsyncMock()+ case = _make_case_row()+ results = await fanout_create_case(+ db,+ case_row=case,+ tenant_id=uuid.uuid4(),+ connector_ids=[],+ )+ assert results == []+ assert db.execute.await_count == 0+++async def test_fanout_create_case_happy_path_persists_external_ref() -> None:+ """End-to-end: vault decrypts → connectors POST returns external_id+ → ``case_external_refs`` row gets upserted → ``FanoutResult`` carries+ the external linkage back to the caller."""+ tenant_id = uuid.uuid4()+ case = _make_case_row()+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)+ db = _build_db_with_connectors([connector])++ fake_resp = _build_post_response(+ status_code=200,+ json_body={+ "external_id": "AIS-42",+ "external_url": "https://example.atlassian.net/browse/AIS-42",+ "vendor": "jira",+ "external_status": "To Do",+ },+ )++ with (+ patch("app.services.case_fanout.get_vault") as mock_vault,+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,+ ):+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ results = await fanout_create_case(+ db,+ case_row=case,+ tenant_id=tenant_id,+ connector_ids=[connector.id],+ pushed_by="[email protected]",+ )++ assert len(results) == 1+ result = results[0]+ assert result.status == "ok"+ assert result.external_id == "AIS-42"+ assert result.external_url == "https://example.atlassian.net/browse/AIS-42"+ assert result.connector_type == "jira"+ # 1 select + 1 upsert.+ assert db.execute.await_count >= 2+++async def test_fanout_create_case_credential_vault_failure_short_circuits() -> None:+ """When vault decryption fails we MUST NOT POST to the connectors+ service — the auth_config dict in transit would still be ciphertext.+ Surface the failure as an ``error`` FanoutResult."""+ from app.security.credential_vault import CredentialVaultError++ tenant_id = uuid.uuid4()+ case = _make_case_row()+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)+ db = _build_db_with_connectors([connector])++ with (+ patch("app.services.case_fanout.get_vault") as mock_vault,+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,+ ):+ mock_vault.return_value.decrypt_dict.side_effect = CredentialVaultError(+ "key rotated"+ )+ post_mock = AsyncMock()+ mock_client.return_value.__aenter__.return_value.post = post_mock+ results = await fanout_create_case(+ db,+ case_row=case,+ tenant_id=tenant_id,+ connector_ids=[connector.id],+ )++ assert len(results) == 1+ assert results[0].status == "error"+ assert "credential decryption failed" in (results[0].error or "")+ post_mock.assert_not_awaited()+++async def test_fanout_create_case_unsupported_capability_is_recorded() -> None:+ """A 501 from the connectors service means the connector type+ doesn't declare ``Capability.PUSH_CASE``. We surface ``unsupported``+ rather than treating that as a hard error."""+ tenant_id = uuid.uuid4()+ case = _make_case_row()+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)+ db = _build_db_with_connectors([connector])++ fake_resp = _build_post_response(status_code=501, text_body="not supported")+ with (+ patch("app.services.case_fanout.get_vault") as mock_vault,+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,+ ):+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ results = await fanout_create_case(+ db,+ case_row=case,+ tenant_id=tenant_id,+ connector_ids=[connector.id],+ )++ assert len(results) == 1+ assert results[0].status == "unsupported"+ assert results[0].external_id is None+++async def test_fanout_create_case_missing_external_id_is_error() -> None:+ """If the connectors service returns 200 but no ``external_id``,+ we have nothing useful to persist. Don't write a malformed row to+ ``case_external_refs``; surface as an error instead."""+ tenant_id = uuid.uuid4()+ case = _make_case_row()+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)+ db = _build_db_with_connectors([connector])++ fake_resp = _build_post_response(+ status_code=200,+ json_body={"vendor": "jira"}, # no external_id!+ )+ with (+ patch("app.services.case_fanout.get_vault") as mock_vault,+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,+ ):+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ results = await fanout_create_case(+ db,+ case_row=case,+ tenant_id=tenant_id,+ connector_ids=[connector.id],+ )++ assert len(results) == 1+ assert results[0].status == "error"+ assert "external_id" in (results[0].error or "")+++# ---------------------------------------------------------------------------+# fanout_status_change+# ---------------------------------------------------------------------------+++async def test_fanout_status_change_no_refs_means_no_push() -> None:+ """Cases that were never pushed to any ITSM have no rows in+ ``case_external_refs``. The status change is a no-op for fan-out+ — the connectors service never gets called."""+ tenant_id = uuid.uuid4()+ case = _make_case_row()+ db = _build_db_with_connectors(connectors=[], refs=[])++ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock()+ mock_client.return_value.__aenter__.return_value.post = post_mock+ results = await fanout_status_change(+ db,+ case_row=case,+ tenant_id=tenant_id,+ old_status="open",+ new_status="resolved",+ )++ assert results == []+ post_mock.assert_not_awaited()+++async def test_fanout_status_change_orphaned_ref_is_skipped() -> None:+ """The connector instance was deleted but the external_ref row+ survived (FK is on case_id). Surface as ``skipped`` so operators+ can see the orphan and either re-link or clean up."""+ tenant_id = uuid.uuid4()+ case = _make_case_row()+ orphan_connector_id = uuid.uuid4()+ refs = [+ {+ "id": uuid.uuid4(),+ "case_id": case["id"],+ "connector_instance_id": orphan_connector_id,+ "vendor": "jira",+ "external_id": "AIS-99",+ "external_url": "https://example/browse/AIS-99",+ "external_status": "Done",+ }+ ]+ # No matching connector in the live ``connectors`` table.+ db = _build_db_with_connectors(connectors=[], refs=refs)++ results = await fanout_status_change(+ db,+ case_row=case,+ tenant_id=tenant_id,+ old_status="open",+ new_status="resolved",+ )++ assert len(results) == 1+ assert results[0].status == "skipped"+ assert results[0].external_id == "AIS-99"+ assert "no longer exists" in (results[0].error or "")+++async def test_fanout_status_change_happy_path_updates_external_status() -> None:+ """End-to-end: ref lookup → connector lookup → POST to+ ``push_status_change`` → upsert refreshed ``external_status``."""+ tenant_id = uuid.uuid4()+ case = _make_case_row(status="resolved")+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)+ refs = [+ {+ "id": uuid.uuid4(),+ "case_id": case["id"],+ "connector_instance_id": connector.id,+ "vendor": "jira",+ "external_id": "AIS-7",+ "external_url": "https://example/browse/AIS-7",+ "external_status": "In Progress",+ }+ ]+ db = _build_db_with_connectors([connector], refs=refs)++ fake_resp = _build_post_response(+ status_code=200,+ json_body={+ "external_id": "AIS-7",+ "vendor": "jira",+ "external_url": "https://example/browse/AIS-7",+ "external_status": "Done",+ },+ )++ with (+ patch("app.services.case_fanout.get_vault") as mock_vault,+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,+ ):+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=fake_resp+ )+ results = await fanout_status_change(+ db,+ case_row=case,+ tenant_id=tenant_id,+ old_status="open",+ new_status="resolved",+ pushed_by="[email protected]",+ )++ assert len(results) == 1+ assert results[0].status == "ok"+ assert results[0].external_id == "AIS-7"+ assert results[0].external_status == "Done"+++async def test_fanout_status_change_transport_error_records_failure() -> None:+ """A network error pushing the status change must surface as+ ``error`` with the external_id preserved, so the UI can show+ 'Jira ✗ (timeout)' next to AIS-7 instead of dropping the linkage."""+ tenant_id = uuid.uuid4()+ case = _make_case_row(status="resolved")+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)+ refs = [+ {+ "id": uuid.uuid4(),+ "case_id": case["id"],+ "connector_instance_id": connector.id,+ "vendor": "jira",+ "external_id": "AIS-7",+ "external_url": "https://example/browse/AIS-7",+ "external_status": "In Progress",+ }+ ]+ db = _build_db_with_connectors([connector], refs=refs)++ with (+ patch("app.services.case_fanout.get_vault") as mock_vault,+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,+ ):+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ side_effect=httpx.ReadTimeout("read timed out")+ )+ results = await fanout_status_change(+ db,+ case_row=case,+ tenant_id=tenant_id,+ old_status="open",+ new_status="resolved",+ )++ assert len(results) == 1+ assert results[0].status == "error"+ assert results[0].external_id == "AIS-7"+ assert "unreachable" in (results[0].error or "")+++# ---------------------------------------------------------------------------+# FanoutResult contract+# ---------------------------------------------------------------------------+++def test_fanout_result_serializable_for_api_response() -> None:+ """The Pydantic model has to round-trip through JSON because the+ create-case endpoint embeds ``ticket_refs`` directly into its 201+ response body. ``model_dump_json`` is the smoke test for that."""+ cid = uuid.uuid4()+ r = FanoutResult(+ connector_id=cid,+ connector_type="jira",+ connector_name="Jira (Prod)",+ status="ok",+ external_id="AIS-1",+ external_url="https://example/browse/AIS-1",+ external_status="To Do",+ )+ payload = r.model_dump_json()+ assert str(cid) in payload+ assert "AIS-1" in payload+ assert "\"status\":\"ok\"" in payloaddiff --git a/services/api/tests/test_inbox_itsm_endpoint.py b/services/api/tests/test_inbox_itsm_endpoint.pynew file mode 100644index 000000000..f341666e2--- /dev/null+++ b/services/api/tests/test_inbox_itsm_endpoint.py@@ -0,0 +1,1180 @@+"""Unit tests for the inbound ITSM webhook (Workstream 8).++The webhook at ``POST /api/v1/inbox/itsm/{tenant_token}/{connector_instance_id}``+is the *inbound* counterpart to ``case_fanout``. Vendor systems (Jira,+ServiceNow) hit it when a ticket transitions, and we mirror the new+status onto ``aisoc_cases``.++Like ``test_lake_endpoint.py`` we keep the assertions on the small+helpers that own the meaningful behaviour, and exercise the endpoint+itself via mocked DB sessions instead of spinning up the FastAPI app++ Postgres harness:++* ``_verify_hmac`` — constant-time HMAC verification with both+ ``sha256=<hex>`` and bare ``<hex>`` styles. The auth model collapses+ to "URL token only" when no secret is configured, which is its own+ branch.+* ``_parse_jira_payload`` — defensive extraction of ``issue.key`` and+ ``issue.fields.status.name`` from a Jira webhook. Real-world payloads+ routinely omit fields we'd otherwise crash on.+* ``_parse_servicenow_payload`` — accepts both the canonical ``incident``+ shape and the ``{"current": {...}}`` wrapper that ServiceNow Business+ Rules emit when the operator forwards ``current`` directly.+* ``_map_inbound_status`` — vendor → AiSOC enum, intentionally lossy.+ Anything we can't map returns None and the caller treats that as+ "no status change".+* ``inbound_itsm_webhook`` — happy path, HMAC enforcement, JSON parse+ failures, unknown external IDs, idempotent redelivery, and the+ vendor-specific dispatch. Mocks ``DBSession`` directly because the+ endpoint is mostly orchestration and the SQL strings are already+ covered by the migration tests.+"""++from __future__ import annotations++import hashlib+import hmac as _hmac+import json+import uuid+from types import SimpleNamespace+from typing import Any+from unittest.mock import AsyncMock, MagicMock++import pytest+from app.api.v1.endpoints.inbox_itsm import (+ _ITSM_TEMPLATE_ID,+ InboundResult,+ _apply_status_to_case,+ _fetch_token_and_connector,+ _map_inbound_status,+ _parse_jira_payload,+ _parse_servicenow_payload,+ _verify_hmac,+ inbound_itsm_webhook,+)+from fastapi import HTTPException+++# ---------------------------------------------------------------------------+# _verify_hmac — auth glue. The biggest single attack surface for the+# whole module: a bug here is "anyone can set any case status", so the+# test list is intentionally adversarial.+# ---------------------------------------------------------------------------+++def _expected_sig(secret: str, body: bytes) -> str:+ return _hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()+++def test_verify_hmac_no_secret_is_noop() -> None:+ """Tokens minted without an HMAC secret authenticate via URL only.++ This is the correct behaviour for ServiceNow installs that don't+ expose the BR-side signing knob. We MUST NOT raise here — doing so+ would brick the most common webhook configuration.+ """+ _verify_hmac(secret=None, raw_body=b"anything", signature_header=None)+ _verify_hmac(secret=None, raw_body=b"anything", signature_header="sha256=garbage")+++def test_verify_hmac_missing_signature_when_secret_set_raises_401() -> None:+ """A configured secret demands a signature; the absence is auth failure."""+ with pytest.raises(HTTPException) as exc:+ _verify_hmac(secret="topsecret", raw_body=b"{}", signature_header=None)+ assert exc.value.status_code == 401+ assert "HMAC signature required" in exc.value.detail+++def test_verify_hmac_blank_signature_when_secret_set_raises_401() -> None:+ """An all-whitespace header is treated as missing.++ Vendors occasionally emit ``X-AiSOC-Signature: `` when their secret+ isn't templated correctly. We refuse it explicitly so the operator+ notices.+ """+ with pytest.raises(HTTPException):+ _verify_hmac(secret="topsecret", raw_body=b"{}", signature_header=" ")+++def test_verify_hmac_accepts_sha256_prefixed_signature() -> None:+ """GitHub-style ``sha256=<hex>`` matches a hex digest."""+ body = b'{"hello":"world"}'+ sig = f"sha256={_expected_sig('seekret', body)}"+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)+++def test_verify_hmac_accepts_bare_hex_signature() -> None:+ """ServiceNow / bespoke proxies post bare hex without a prefix."""+ body = b'{"sys_id":"abc"}'+ sig = _expected_sig("seekret", body)+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)+++def test_verify_hmac_signature_mismatch_raises_401() -> None:+ """Tampered body invalidates the signature."""+ sig = _expected_sig("seekret", b"original")+ with pytest.raises(HTTPException) as exc:+ _verify_hmac(secret="seekret", raw_body=b"tampered", signature_header=sig)+ assert exc.value.status_code == 401+ assert "Invalid HMAC" in exc.value.detail+++def test_verify_hmac_wrong_secret_raises_401() -> None:+ """A signature computed with a different secret must not pass.++ Defends against operator copy-paste error (rotated the inbox token+ secret server-side but forgot to update the vendor side).+ """+ body = b'{"a":1}'+ sig = f"sha256={_expected_sig('wrong-secret', body)}"+ with pytest.raises(HTTPException):+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)+++def test_verify_hmac_case_insensitive_hex_match() -> None:+ """Some vendors uppercase the hex digest. We accept either case."""+ body = b'{"foo":"bar"}'+ sig = _expected_sig("seekret", body).upper()+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)+++# ---------------------------------------------------------------------------+# _parse_jira_payload+# ---------------------------------------------------------------------------+++def test_parse_jira_payload_happy_path() -> None:+ """Standard ``jira:issue_updated`` shape extracts issue key + status name."""+ payload: dict[str, Any] = {+ "webhookEvent": "jira:issue_updated",+ "issue": {+ "key": "AIS-1234",+ "fields": {"status": {"name": "In Progress"}},+ },+ }+ assert _parse_jira_payload(payload) == ("AIS-1234", "In Progress")+++def test_parse_jira_payload_missing_issue_returns_none_pair() -> None:+ """Heartbeat / synthetic payloads skip the writes entirely."""+ assert _parse_jira_payload({"webhookEvent": "ping"}) == (None, None)+++def test_parse_jira_payload_issue_not_dict_returns_none_pair() -> None:+ """Defensive: don't crash if Jira ever ships ``issue: null``."""+ assert _parse_jira_payload({"issue": None}) == (None, None)+ assert _parse_jira_payload({"issue": "AIS-1"}) == (None, None)+++def test_parse_jira_payload_missing_key_returns_none_pair() -> None:+ """Empty issue.key means nothing to correlate."""+ assert _parse_jira_payload({"issue": {"key": ""}}) == (None, None)+++def test_parse_jira_payload_missing_status_keeps_key() -> None:+ """A renamed-issue webhook has no status; we still return the key.++ The endpoint then treats ``raw_status=None`` as "no transition" and+ short-circuits. We need the key to bump ``last_synced_at`` even+ when the actual status didn't change.+ """+ payload = {"issue": {"key": "AIS-7", "fields": {}}}+ assert _parse_jira_payload(payload) == ("AIS-7", None)+++def test_parse_jira_payload_status_not_dict_keeps_key() -> None:+ """``fields.status`` may be a string in odd custom workflows; ignore."""+ payload = {"issue": {"key": "AIS-7", "fields": {"status": "Done"}}}+ assert _parse_jira_payload(payload) == ("AIS-7", None)+++def test_parse_jira_payload_fields_not_dict_keeps_key() -> None:+ """Defensive against Jira's ``fields: null`` on bare-bones webhooks."""+ payload = {"issue": {"key": "AIS-9", "fields": None}}+ assert _parse_jira_payload(payload) == ("AIS-9", None)+++# ---------------------------------------------------------------------------+# _parse_servicenow_payload+# ---------------------------------------------------------------------------+++def test_parse_servicenow_payload_canonical_shape() -> None:+ """REST-Table-API-shaped payload (top-level fields)."""+ payload = {"sys_id": "abc123", "state": "6", "short_description": "boom"}+ assert _parse_servicenow_payload(payload) == ("abc123", "6")+++def test_parse_servicenow_payload_current_wrapper_shape() -> None:+ """Business Rule forwarding wraps the GlideRecord in ``current``.++ The two shapes look almost identical and operators routinely ship+ one when they meant the other. We accept both.+ """+ payload = {"current": {"sys_id": "abc123", "state": "7"}}+ assert _parse_servicenow_payload(payload) == ("abc123", "7")+++def test_parse_servicenow_payload_state_int_normalised_to_string() -> None:+ """ServiceNow's ``state`` is numeric in some payloads; we string-ify."""+ payload = {"sys_id": "abc", "state": 6}+ assert _parse_servicenow_payload(payload) == ("abc", "6")+++def test_parse_servicenow_payload_missing_sys_id_returns_none_pair() -> None:+ """sys_id is the correlation key — without it we can't find the case."""+ assert _parse_servicenow_payload({"state": 6}) == (None, None)+++def test_parse_servicenow_payload_empty_sys_id_returns_none_pair() -> None:+ """Defensive against BRs that emit ``sys_id: ""`` on creation."""+ assert _parse_servicenow_payload({"sys_id": "", "state": "1"}) == (None, None)+++def test_parse_servicenow_payload_missing_state_keeps_sys_id() -> None:+ """An assignment-only webhook has no state change. Same logic as Jira."""+ assert _parse_servicenow_payload({"sys_id": "abc"}) == ("abc", None)+++def test_parse_servicenow_payload_current_not_dict_returns_none_pair() -> None:+ """Defensive: ``current: null`` happens on initial deploy."""+ assert _parse_servicenow_payload({"current": None}) == (None, None)+++# ---------------------------------------------------------------------------+# _map_inbound_status — the canonicalisation table. We assert the+# specific mappings because they're load-bearing for case workflow:+# a wrong row here means an operator's "Done" silently doesn't close+# the case.+# ---------------------------------------------------------------------------+++ "raw_status,expected",+ [+ # Common Jira flows+ ("To Do", "triaged"),+ ("Open", "triaged"),+ ("Backlog", "triaged"),+ ("In Progress", "investigating"),+ ("In Review", "investigating"),+ ("Blocked", "contained"),+ ("On Hold", "contained"),+ ("Resolved", "resolved"),+ ("Done", "resolved"),+ ("Closed", "closed"),+ ("Cancelled", "closed"),+ ("Won't Fix", "closed"),+ # Case insensitive — Jira emits status.name as-configured by the+ # admin, which often lowercases.+ ("done", "resolved"),+ ("DONE", "resolved"),+ # American spelling collapses too.+ ("Canceled", "closed"),+ ],+)+def test_map_inbound_status_jira_known_states(raw_status: str, expected: str) -> None:+ assert _map_inbound_status("jira", raw_status) == expected+++def test_map_inbound_status_jira_unknown_returns_none() -> None:+ """Unmapped Jira statuses are a no-op, not an error."""+ assert _map_inbound_status("jira", "Awaiting Customer") is None+++ "raw_status,expected",+ [+ ("1", "triaged"),+ ("2", "investigating"),+ ("3", "contained"),+ ("6", "resolved"),+ ("7", "closed"),+ ("8", "closed"),+ ],+)+def test_map_inbound_status_servicenow_known_states(raw_status: str, expected: str) -> None:+ assert _map_inbound_status("servicenow", raw_status) == expected+++def test_map_inbound_status_servicenow_unknown_returns_none() -> None:+ """ServiceNow custom states (e.g. 100, 200) are skipped."""+ assert _map_inbound_status("servicenow", "100") is None+++def test_map_inbound_status_unknown_vendor_returns_none() -> None:+ """A bug in the dispatch shouldn't accidentally close cases."""+ assert _map_inbound_status("pagerduty", "resolved") is None+++def test_map_inbound_status_none_status_returns_none() -> None:+ """Idempotent: ``None`` in, ``None`` out."""+ assert _map_inbound_status("jira", None) is None+++# ---------------------------------------------------------------------------+# _fetch_token_and_connector — auth + tenancy boundary. Every branch+# here is a 401/403/404/409 — i.e. potential cross-tenant or+# unauthorised access — so the coverage list is the threat model.+#+# The DB is mocked because we're testing the resolution logic, not+# Postgres semantics. The actual SQL is covered by the integration+# tests that exercise migration 035.+# ---------------------------------------------------------------------------+++def _mock_db(token_row: Any | None, connector_row: Any | None) -> AsyncMock:+ """Build an AsyncMock DB whose two ``execute`` calls return the+ rows we want.++ The real endpoint runs the token query first, then the connector+ query, so we drive the mock with a ``side_effect`` queue.+ """+ db = MagicMock()+ token_result = MagicMock()+ token_result.fetchone = MagicMock(return_value=token_row)+ connector_result = MagicMock()+ connector_result.fetchone = MagicMock(return_value=connector_row)+ db.execute = AsyncMock(side_effect=[token_result, connector_result])+ return db+++async def test_fetch_token_and_connector_happy_path() -> None:+ """Valid token + matching tenant + supported vendor returns both rows."""+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="tok-xyz",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ db = _mock_db(token_row, connector_row)+ tok, conn = await _fetch_token_and_connector(+ db, tenant_token="tok-xyz", connector_instance_id=connector_id+ )+ assert tok is token_row+ assert conn is connector_row+++async def test_fetch_token_and_connector_missing_token_raises_401() -> None:+ """Revoked / never-existed tokens are auth failures."""+ db = _mock_db(token_row=None, connector_row=None)+ with pytest.raises(HTTPException) as exc:+ await _fetch_token_and_connector(+ db, tenant_token="tok-revoked", connector_instance_id=uuid.uuid4()+ )+ assert exc.value.status_code == 401+ # Don't echo the full token in the error — leakage minimisation.+ assert "tok-revoked" not in str(exc.value.detail)+++async def test_fetch_token_and_connector_wrong_template_raises_403() -> None:+ """Token minted for a different template (e.g. PagerDuty) is rejected.++ Critical for blast-radius limiting: a leaked PagerDuty inbox token+ must NOT be re-purposable as an ITSM webhook authenticator.+ """+ tenant_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="tok-pagerduty",+ tenant_id=tenant_id,+ template_id="pagerduty-events",+ hmac_secret=None,+ revoked_at=None,+ )+ db = _mock_db(token_row, None)+ with pytest.raises(HTTPException) as exc:+ await _fetch_token_and_connector(+ db, tenant_token="tok-pagerduty", connector_instance_id=uuid.uuid4()+ )+ assert exc.value.status_code == 403+ assert "itsm-inbound" in exc.value.detail+++async def test_fetch_token_and_connector_missing_connector_raises_404() -> None:+ """Connector deleted but the vendor still pings the old webhook URL."""+ tenant_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="tok-xyz",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ db = _mock_db(token_row, connector_row=None)+ with pytest.raises(HTTPException) as exc:+ await _fetch_token_and_connector(+ db, tenant_token="tok-xyz", connector_instance_id=uuid.uuid4()+ )+ assert exc.value.status_code == 404+++async def test_fetch_token_and_connector_cross_tenant_raises_403() -> None:+ """Token from tenant A paired with connector from tenant B is forbidden.++ This is the most important test in the file from a security+ posture standpoint — a missing tenant check here would let any+ tenant project status onto any other tenant's cases.+ """+ token_row = SimpleNamespace(+ token="tok-xyz",+ tenant_id=uuid.uuid4(), # tenant A+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=uuid.uuid4(),+ tenant_id=uuid.uuid4(), # tenant B — different+ connector_type="jira",+ enabled=True,+ )+ db = _mock_db(token_row, connector_row)+ with pytest.raises(HTTPException) as exc:+ await _fetch_token_and_connector(+ db, tenant_token="tok-xyz", connector_instance_id=connector_row.id+ )+ assert exc.value.status_code == 403+ assert "different tenants" in exc.value.detail+++async def test_fetch_token_and_connector_disabled_connector_raises_409() -> None:+ """Disabled connector = ops intentionally paused this integration.++ 409 (not 200) so the vendor's webhook delivery dashboard surfaces+ the issue and the operator notices, instead of events silently+ dropping into the void.+ """+ tenant_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="tok-xyz",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=uuid.uuid4(),+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=False,+ )+ db = _mock_db(token_row, connector_row)+ with pytest.raises(HTTPException) as exc:+ await _fetch_token_and_connector(+ db, tenant_token="tok-xyz", connector_instance_id=connector_row.id+ )+ assert exc.value.status_code == 409+++async def test_fetch_token_and_connector_unsupported_vendor_raises_422() -> None:+ """Splunk-typed connector pointed at the ITSM URL is a config error."""+ tenant_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="tok-xyz",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=uuid.uuid4(),+ tenant_id=tenant_id,+ connector_type="splunk",+ enabled=True,+ )+ db = _mock_db(token_row, connector_row)+ with pytest.raises(HTTPException) as exc:+ await _fetch_token_and_connector(+ db, tenant_token="tok-xyz", connector_instance_id=connector_row.id+ )+ assert exc.value.status_code == 422+ assert "splunk" in exc.value.detail+++# ---------------------------------------------------------------------------+# _apply_status_to_case — the writes that actually mutate AiSOC state.+#+# We verify the SHAPE of the writes (correct table + bound parameters)+# rather than running them against a real DB. The migration tests are+# the right place to exercise the SQL itself; here we want to know+# the endpoint hands the right values to the right tables in the right+# order.+# ---------------------------------------------------------------------------+++async def test_apply_status_to_case_writes_three_rows() -> None:+ """Three writes per status change: case, ref, system comment.++ Order matters: case row first (the source of truth for status),+ then the ref (so the NEXT outbound push short-circuits), then the+ audit comment (read-only, can fail-but-shouldn't but isn't on the+ hot path). The transaction is committed by the caller — this fn+ must NOT call ``db.commit``.+ """+ db = MagicMock()+ db.execute = AsyncMock()+ # Explicitly attach commit/rollback as AsyncMock so we can assert+ # _apply_status_to_case does NOT call them. Without this, MagicMock+ # auto-creates attributes on access and ``hasattr`` is always True.+ db.commit = AsyncMock()+ db.rollback = AsyncMock()++ case_id = uuid.uuid4()+ case_row = SimpleNamespace(id=case_id)++ await _apply_status_to_case(+ db,+ case_row=case_row,+ new_status="resolved",+ actor_label="jira-webhook",+ external_id="AIS-42",+ vendor="jira",+ )++ # Three writes — case, ref, comment.+ assert db.execute.await_count == 3+ # Transaction lifecycle is the caller's responsibility (the endpoint),+ # not this helper's. The helper must stay pure-write so callers can+ # batch it with other writes inside one transaction.+ assert db.commit.await_count == 0+ assert db.rollback.await_count == 0+++async def test_apply_status_to_case_resolved_sets_resolved_at() -> None:+ """The ``resolved`` transition stamps resolved_at via COALESCE.++ We assert the SQL string contains ``resolved_at`` because that's+ the contract with the timeline view. ``closed_at`` must NOT appear+ on a 'resolved' transition (preventing it from being prematurely+ set, which would break SLA reporting).+ """+ db = MagicMock()+ db.execute = AsyncMock()+ case_row = SimpleNamespace(id=uuid.uuid4())++ await _apply_status_to_case(+ db,+ case_row=case_row,+ new_status="resolved",+ actor_label="jira-webhook",+ external_id="AIS-42",+ vendor="jira",+ )++ # First call is the aisoc_cases UPDATE — verify the dynamic columns.+ update_sql = str(db.execute.await_args_list[0].args[0])+ assert "resolved_at" in update_sql+ assert "closed_at" not in update_sql+ assert "triaged_at" in update_sql # transitive: resolved implies triaged+++async def test_apply_status_to_case_closed_sets_closed_at() -> None:+ """The ``closed`` transition stamps closed_at."""+ db = MagicMock()+ db.execute = AsyncMock()+ case_row = SimpleNamespace(id=uuid.uuid4())++ await _apply_status_to_case(+ db,+ case_row=case_row,+ new_status="closed",+ actor_label="snow-webhook",+ external_id="abc-sys-id",+ vendor="servicenow",+ )++ update_sql = str(db.execute.await_args_list[0].args[0])+ assert "closed_at" in update_sql+++async def test_apply_status_to_case_triaged_does_not_stamp_resolved_or_closed() -> None:+ """Triage transitions only stamp triaged_at, not later milestones."""+ db = MagicMock()+ db.execute = AsyncMock()+ case_row = SimpleNamespace(id=uuid.uuid4())++ await _apply_status_to_case(+ db,+ case_row=case_row,+ new_status="triaged",+ actor_label="jira-webhook",+ external_id="AIS-1",+ vendor="jira",+ )++ update_sql = str(db.execute.await_args_list[0].args[0])+ assert "triaged_at" in update_sql+ assert "resolved_at" not in update_sql+ assert "closed_at" not in update_sql+++def _bind_params(clause: Any) -> dict[str, Any]:+ """Extract bound parameter values from a SQLAlchemy ``TextClause``.++ SQLAlchemy 2.x doesn't expose a stable public accessor for+ ``text(...).bindparams(...)`` values, but ``_bindparams`` is the+ canonical storage on TextClause and has been stable across the+ 1.4 → 2.x migration. We prefer it over ``compile().params`` because+ ``compile()`` requires a dialect and silently rewrites our :name+ parameters into ``%s`` style on a default Postgres dialect.+ """+ return {name: bp.value for name, bp in clause._bindparams.items()}+++async def test_apply_status_to_case_writes_system_comment_with_provenance() -> None:+ """The audit comment names the vendor + external_id for the timeline."""+ db = MagicMock()+ db.execute = AsyncMock()+ case_row = SimpleNamespace(id=uuid.uuid4())++ await _apply_status_to_case(+ db,+ case_row=case_row,+ new_status="resolved",+ actor_label="jira-webhook",+ external_id="AIS-9000",+ vendor="jira",+ )++ # Third call is the comment INSERT.+ comment_call = db.execute.await_args_list[2]+ bound = _bind_params(comment_call.args[0])+ assert bound["body"] is not None+ assert "AIS-9000" in bound["body"]+ assert "Jira" in bound["body"]+ assert "resolved" in bound["body"]+ assert bound["author"] == "jira-webhook"+++# ---------------------------------------------------------------------------+# inbound_itsm_webhook — endpoint orchestration. We mock _fetch_token,+# _apply_status, and the DB so we can assert the dispatch logic+# (vendor → parser, parsed status → mapper, mapped status → write or+# no-op) without spinning the FastAPI app up.+# ---------------------------------------------------------------------------+++def _build_request(body: bytes) -> MagicMock:+ """Build a Request-like mock whose ``body()`` returns ``body``."""+ req = MagicMock()+ req.body = AsyncMock(return_value=body)+ return req+++def _build_db_for_endpoint(+ *,+ token_row: Any,+ connector_row: Any,+ ref_row: Any | None,+ case_already_in_target_status: bool = False,+) -> MagicMock:+ """Build a MagicMock DB whose execute() chain covers the endpoint flow.++ Order of execute() calls in the endpoint when we get past auth:+ 1. SELECT token row+ 2. SELECT connector row+ 3. SELECT case_external_refs JOIN aisoc_cases (the 'ref_row' here)+ 4. UPDATE tenant_inbox_tokens.last_used_at+ 5..N. _apply_status_to_case writes (when status actually changes)+ OR UPDATE last_synced_at on case_external_refs (when it doesn't)++ We just queue enough MagicMock results to cover the longest path.+ """+ results = []+ # Token + connector+ for row in (token_row, connector_row):+ r = MagicMock()+ r.fetchone = MagicMock(return_value=row)+ results.append(r)+ # case_external_refs JOIN+ r = MagicMock()+ r.fetchone = MagicMock(return_value=ref_row)+ results.append(r)+ # last_used_at update + any subsequent UPDATEs all just return a+ # noop result; we don't .fetchone() on them.+ for _ in range(8):+ results.append(MagicMock())++ db = MagicMock()+ db.execute = AsyncMock(side_effect=results)+ # The endpoint commits at the end of the happy path and rolls back on+ # exception — both must be awaitable on this mock.+ db.commit = AsyncMock()+ db.rollback = AsyncMock()+ return db+++async def test_endpoint_invalid_json_raises_400() -> None:+ """Garbage body → 400 Bad Request, not a 500."""+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ db = _build_db_for_endpoint(token_row=token_row, connector_row=connector_row, ref_row=None)+ request = _build_request(b"this is not json")++ with pytest.raises(HTTPException) as exc:+ await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )+ assert exc.value.status_code == 400+ assert "not valid JSON" in exc.value.detail+++async def test_endpoint_non_object_json_raises_400() -> None:+ """``[1,2,3]`` is valid JSON but we need an object."""+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ db = _build_db_for_endpoint(token_row=token_row, connector_row=connector_row, ref_row=None)+ request = _build_request(b"[1,2,3]")++ with pytest.raises(HTTPException) as exc:+ await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )+ assert exc.value.status_code == 400+++async def test_endpoint_missing_external_id_returns_200_with_note() -> None:+ """Heartbeat / malformed-payload Jira webhooks 200 with status_changed=False."""+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ db = _build_db_for_endpoint(token_row=token_row, connector_row=connector_row, ref_row=None)+ request = _build_request(json.dumps({"webhookEvent": "ping"}).encode())++ result = await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )++ assert isinstance(result, InboundResult)+ assert result.status_changed is False+ assert result.case_id is None+ assert result.external_id is None+ assert result.note is not None+ assert "missing required fields" in result.note+++async def test_endpoint_unlinked_external_id_returns_200_with_note() -> None:+ """ITSM ticket exists but isn't linked to any AiSOC case → soft-200."""+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ # ref_row=None means the JOIN found no AiSOC link.+ db = _build_db_for_endpoint(+ token_row=token_row, connector_row=connector_row, ref_row=None+ )+ body = json.dumps(+ {+ "issue": {+ "key": "AIS-99",+ "fields": {"status": {"name": "Done"}},+ }+ }+ ).encode()+ request = _build_request(body)++ result = await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )++ assert result.status_changed is False+ assert result.case_id is None+ assert result.external_id == "AIS-99"+ assert "AIS-99" in (result.note or "")+++async def test_endpoint_idempotent_when_case_already_in_target_status() -> None:+ """Re-delivered "Done" event when case is already 'resolved' → no rewrite.++ The vendor will hammer this URL on every retry, so the most common+ real-world execution is a redelivery. We must:+ * still 200 OK (so the vendor stops retrying),+ * still bump last_synced_at (so the operator knows the token is alive),+ * NOT rewrite ``aisoc_cases.status`` (no-op DB load),+ * NOT post a duplicate "Jira ticket transitioned" system comment+ (would spam the timeline view).+ """+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ case_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ ref_row = SimpleNamespace(+ id=uuid.uuid4(),+ case_id=case_id,+ external_status="resolved",+ aisoc_case_id=case_id,+ case_number="CASE-1",+ status="resolved", # already in the target state+ )+ db = _build_db_for_endpoint(+ token_row=token_row, connector_row=connector_row, ref_row=ref_row+ )+ body = json.dumps(+ {"issue": {"key": "AIS-1", "fields": {"status": {"name": "Done"}}}}+ ).encode()+ request = _build_request(body)++ result = await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )++ assert result.status_changed is False+ assert result.old_status == "resolved"+ assert result.new_status == "resolved"+ assert result.case_id == case_id+ assert result.case_number == "CASE-1"+++async def test_endpoint_unmapped_status_bumps_last_synced_only() -> None:+ """Vendor status that doesn't map to AiSOC → ``status_changed=False``.++ Operators occasionally configure custom Jira workflows with statuses+ we've never heard of ("Awaiting Customer", "Released to QA"). The+ contract: never lose data, never crash, always 200.+ """+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ case_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ ref_row = SimpleNamespace(+ id=uuid.uuid4(),+ case_id=case_id,+ external_status="investigating",+ aisoc_case_id=case_id,+ case_number="CASE-2",+ status="investigating",+ )+ db = _build_db_for_endpoint(+ token_row=token_row, connector_row=connector_row, ref_row=ref_row+ )+ body = json.dumps(+ {+ "issue": {+ "key": "AIS-2",+ "fields": {"status": {"name": "Awaiting Customer"}},+ }+ }+ ).encode()+ request = _build_request(body)++ result = await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )++ assert result.status_changed is False+ assert result.old_status == "investigating"+ assert result.new_status == "investigating"+ assert "Awaiting Customer" in (result.note or "")+++async def test_endpoint_real_status_change_writes_and_returns_changed() -> None:+ """Vendor 'Done' → AiSOC 'resolved' mirrors the status onto the case."""+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ case_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ ref_row = SimpleNamespace(+ id=uuid.uuid4(),+ case_id=case_id,+ external_status="investigating",+ aisoc_case_id=case_id,+ case_number="CASE-7",+ status="investigating",+ )+ db = _build_db_for_endpoint(+ token_row=token_row, connector_row=connector_row, ref_row=ref_row+ )+ body = json.dumps(+ {"issue": {"key": "AIS-7", "fields": {"status": {"name": "Done"}}}}+ ).encode()+ request = _build_request(body)++ result = await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )++ assert result.status_changed is True+ assert result.old_status == "investigating"+ assert result.new_status == "resolved"+ assert result.case_id == case_id+ assert result.case_number == "CASE-7"+ assert result.external_id == "AIS-7"+++async def test_endpoint_servicenow_dispatches_to_servicenow_parser() -> None:+ """A ServiceNow connector type routes through ``_parse_servicenow_payload``.++ Numeric state ``"6"`` → ``"resolved"`` confirms both the dispatch+ and the SNow-specific mapping.+ """+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ case_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret=None,+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="servicenow",+ enabled=True,+ )+ ref_row = SimpleNamespace(+ id=uuid.uuid4(),+ case_id=case_id,+ external_status="investigating",+ aisoc_case_id=case_id,+ case_number="CASE-9",+ status="investigating",+ )+ db = _build_db_for_endpoint(+ token_row=token_row, connector_row=connector_row, ref_row=ref_row+ )+ body = json.dumps({"sys_id": "abc-1", "state": 6}).encode()+ request = _build_request(body)++ result = await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None,+ )++ assert result.status_changed is True+ assert result.new_status == "resolved"+ assert result.external_id == "abc-1"+++async def test_endpoint_hmac_required_but_missing_returns_401() -> None:+ """Token has hmac_secret but request omits the signature → 401.++ Verifies HMAC is enforced on the *real* endpoint, not just on+ ``_verify_hmac`` in isolation. The order of operations matters:+ HMAC must run *before* JSON parsing so a forged-but-valid-JSON+ body can't trigger any DB reads.+ """+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret="seekret", # configured+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ db = _build_db_for_endpoint(+ token_row=token_row, connector_row=connector_row, ref_row=None+ )+ request = _build_request(b"{}")++ with pytest.raises(HTTPException) as exc:+ await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=None, # missing+ )+ assert exc.value.status_code == 401+++async def test_endpoint_hmac_valid_passes_through() -> None:+ """A correctly signed request authenticates and proceeds normally."""+ tenant_id = uuid.uuid4()+ connector_id = uuid.uuid4()+ case_id = uuid.uuid4()+ token_row = SimpleNamespace(+ token="t",+ tenant_id=tenant_id,+ template_id=_ITSM_TEMPLATE_ID,+ hmac_secret="seekret",+ revoked_at=None,+ )+ connector_row = SimpleNamespace(+ id=connector_id,+ tenant_id=tenant_id,+ connector_type="jira",+ enabled=True,+ )+ ref_row = SimpleNamespace(+ id=uuid.uuid4(),+ case_id=case_id,+ external_status="investigating",+ aisoc_case_id=case_id,+ case_number="CASE-5",+ status="investigating",+ )+ db = _build_db_for_endpoint(+ token_row=token_row, connector_row=connector_row, ref_row=ref_row+ )+ body = json.dumps(+ {"issue": {"key": "AIS-5", "fields": {"status": {"name": "Done"}}}}+ ).encode()+ sig = f"sha256={_expected_sig('seekret', body)}"+ request = _build_request(body)++ result = await inbound_itsm_webhook(+ tenant_token="t",+ connector_instance_id=connector_id,+ request=request,+ db=db,+ x_aisoc_signature=sig,+ )++ assert result.status_changed is True+ assert result.new_status == "resolved"diff --git a/services/connectors/tests/test_push_capabilities.py b/services/connectors/tests/test_push_capabilities.pynew file mode 100644index 000000000..429b5e901--- /dev/null+++ b/services/connectors/tests/test_push_capabilities.py@@ -0,0 +1,730 @@+"""Unit tests for Workstream 8 ``push_case`` / ``push_status_change`` paths.++These tests cover the bidirectional ITSM capability shipped on the Jira and+ServiceNow connectors:++* ``push_case`` happy paths (correct payload, correct vendor mapping) and the+ HTTP error → ``HTTPStatusError`` propagation contract the fan-out service+ depends on.+* ``push_status_change`` decision tree:+ - ``external_ref is None`` → falls through to ``push_case`` so callers+ don't have to special-case "first push".+ - Unknown AiSOC status → no-op return (no HTTP call) since the contract+ is "best-effort projection", not "schema match".+ - Jira: discover-then-transition path including the "no transition+ available for target status" workflow no-op.+ - ServiceNow: ``Resolved`` / ``Closed`` states require ``close_code`` ++ ``close_notes`` or the API silently ignores the state change.++We deliberately avoid ``respx`` (not installed in this env per+``pyproject.toml`` dev deps) and instead patch ``httpx.AsyncClient`` with+``unittest.mock`` mirroring ``services/api/tests/test_case_fanout.py``. That+also keeps these tests aligned with the in-repo mock patterns reviewers+already understand.+"""++from __future__ import annotations++from typing import Any+from unittest.mock import AsyncMock, MagicMock, patch++import httpx+import pytest++from app.connectors.jira_connector import JiraConnector+from app.connectors.servicenow import ServiceNowConnector+++# ---------------------------------------------------------------------------+# Helpers — build httpx.Response stubs without instantiating a real Client.+# ---------------------------------------------------------------------------+++def _build_response(+ *,+ status_code: int = 200,+ json_body: dict[str, Any] | list[Any] | None = None,+ text: str = "",+ method: str = "POST",+ url: str = "http://example.invalid/",+) -> MagicMock:+ """Build a MagicMock that walks like an ``httpx.Response``.++ We only need the attributes the connector code touches:+ ``status_code``, ``json()``, ``text``, ``request``, plus ``raise_for_status``+ (called by ``_resolve_transition_id`` on the Jira side).+ """+ resp = MagicMock(spec=httpx.Response)+ resp.status_code = status_code+ resp.json = MagicMock(return_value=json_body if json_body is not None else {})+ resp.text = text+ # ``request`` is required for ``HTTPStatusError`` construction.+ resp.request = httpx.Request(method, url)++ def _raise_for_status() -> None:+ if status_code >= 400:+ raise httpx.HTTPStatusError(+ f"{status_code} error",+ request=resp.request,+ response=resp,+ )++ resp.raise_for_status = MagicMock(side_effect=_raise_for_status)+ return resp+++def _patch_async_client(+ *,+ post_responses: list[MagicMock] | MagicMock | None = None,+ get_responses: list[MagicMock] | MagicMock | None = None,+ patch_responses: list[MagicMock] | MagicMock | None = None,+) -> tuple[Any, AsyncMock, AsyncMock, AsyncMock]:+ """Patch ``httpx.AsyncClient`` for a connector module.++ Returns ``(context_manager, post_mock, get_mock, patch_mock)``. Use as::++ with _patch_async_client(...) as ctx:+ post_mock, get_mock, patch_mock = ctx++ Or, more commonly here, drive each patch context directly per test.+ """+ raise NotImplementedError # placeholder — kept for shape; tests use the inline pattern below.+++def _async_responses(responses: list[MagicMock] | MagicMock | None) -> AsyncMock:+ """Build an AsyncMock that returns each response in sequence (or always+ the same one if a single mock is supplied)."""+ if responses is None:+ return AsyncMock(side_effect=AssertionError("unexpected HTTP call"))+ if isinstance(responses, list):+ return AsyncMock(side_effect=responses)+ return AsyncMock(return_value=responses)+++# ===========================================================================+# Jira: push_case+# ===========================================================================+++async def test_jira_push_case_builds_correct_payload_and_url() -> None:+ """Happy path: severity → priority, ADF description, aisoc-case label."""+ case = {+ "id": "11111111-2222-3333-4444-555555555555",+ "case_number": "AIS-42",+ "title": "Suspected lateral movement",+ "description": "Multiple SMB connects from finance subnet to DC.",+ "severity": "high",+ "status": "investigating",+ }++ connector = JiraConnector(+ base_url="https://acme.atlassian.net/", # trailing slash on purpose.+ email="[email protected]",+ api_token="api-token-xyz",+ project_key="SEC",+ )+ response = _build_response(+ status_code=201,+ json_body={"key": "SEC-42", "id": "10042"},+ )++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ result = await connector.push_case(case)++ assert post_mock.await_count == 1+ call = post_mock.await_args+ # ``base_url`` was rstripped, so the resulting URL has exactly one slash.+ assert call.args[0] == "https://acme.atlassian.net/rest/api/3/issue"++ payload = call.kwargs["json"]+ assert payload["fields"]["project"] == {"key": "SEC"}+ assert payload["fields"]["priority"] == {"name": "High"}+ # ADF doc shape — connector wraps the plain string under content[0].text.+ assert payload["fields"]["description"]["type"] == "doc"+ assert (+ payload["fields"]["description"]["content"][0]["content"][0]["text"]+ == case["description"]+ )+ # Label round-trips the AiSOC case identifier so the inbound webhook+ # can link the issue back to us without a custom field.+ assert f"aisoc-case-{case['id']}" in payload["fields"]["labels"]+ assert "aisoc" in payload["fields"]["labels"]++ headers = call.kwargs["headers"]+ assert headers["Authorization"].startswith("Basic ")++ assert result == {+ "external_id": "SEC-42",+ "external_url": "https://acme.atlassian.net/browse/SEC-42",+ "vendor": "jira",+ "external_status": "To Do",+ }+++async def test_jira_push_case_requires_project_key() -> None:+ """Missing project_key MUST raise rather than silently 400 against Jira."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key=None,+ )++ with pytest.raises(ValueError, match="project_key not configured"):+ await connector.push_case({"id": "1", "title": "x"})+++async def test_jira_push_case_severity_collapses_to_default() -> None:+ """Unknown severity falls back to Medium rather than crashing."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ response = _build_response(+ status_code=201, json_body={"key": "SEC-1", "id": "1"}+ )++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ await connector.push_case({"id": "1", "title": "x", "severity": "absurdly-bad"})++ payload = post_mock.await_args.kwargs["json"]+ assert payload["fields"]["priority"] == {"name": "Medium"}+++async def test_jira_push_case_summary_truncates_at_255() -> None:+ """Jira hard-caps summary at 255 chars; longer titles must be sliced."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ long_title = "x" * 400+ response = _build_response(+ status_code=201, json_body={"key": "SEC-1", "id": "1"}+ )++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ await connector.push_case({"id": "1", "title": long_title})++ payload = post_mock.await_args.kwargs["json"]+ assert len(payload["fields"]["summary"]) == 255+++async def test_jira_push_case_raises_on_4xx() -> None:+ """Jira 4xx must surface as HTTPStatusError so the fan-out service can+ persist a ``failed`` external_ref instead of silently dropping the push."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ response = _build_response(status_code=400, text="bad project key")++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ with pytest.raises(httpx.HTTPStatusError, match="jira.push_case failed"):+ await connector.push_case({"id": "1", "title": "x"})+++# ===========================================================================+# Jira: push_status_change+# ===========================================================================+++async def test_jira_push_status_change_falls_through_to_push_case_when_no_ref() -> None:+ """First-time push (no existing external_ref) must mint the issue."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ response = _build_response(+ status_code=201, json_body={"key": "SEC-7", "id": "7"}+ )++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ result = await connector.push_status_change(+ case={"id": "abc", "title": "lateral", "severity": "low"},+ old_status="new",+ new_status="investigating",+ external_ref=None,+ )++ # Single POST to /rest/api/3/issue, no transitions discovery.+ assert post_mock.await_count == 1+ assert post_mock.await_args.args[0].endswith("/rest/api/3/issue")+ assert result["external_id"] == "SEC-7"+++async def test_jira_push_status_change_requires_external_id_in_ref() -> None:+ """An external_ref dict without ``external_id`` is operator error."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ with pytest.raises(ValueError, match="missing external_id"):+ await connector.push_status_change(+ case={"id": "abc"},+ old_status="new",+ new_status="resolved",+ external_ref={"vendor": "jira"}, # no external_id+ )+++async def test_jira_push_status_change_unknown_status_is_noop() -> None:+ """Unknown AiSOC statuses return without making any HTTP call."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ # If we DO end up calling httpx, the context manager's get/post+ # mocks are AsyncMock() defaults — nothing assertable here, so the+ # real check is "we never enter the client at all".+ result = await connector.push_status_change(+ case={"id": "abc"},+ old_status="new",+ new_status="alien-status",+ external_ref={"external_id": "SEC-9", "external_status": "To Do"},+ )+ # Connector must NOT instantiate a client when there's no work.+ assert mock_client.call_count == 0++ assert result["external_id"] == "SEC-9"+ assert result["external_status"] == "To Do" # unchanged from external_ref+++async def test_jira_push_status_change_no_matching_transition_is_noop() -> None:+ """Workflow may not expose a transition to the target status — return+ without mutating, since retrying won't change the workflow."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ transitions_response = _build_response(+ status_code=200,+ json_body={+ "transitions": [+ {"id": "11", "name": "Reopen", "to": {"name": "To Do"}},+ # No "Done" or "In Progress" transition exposed.+ ]+ },+ )++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ get_mock = AsyncMock(return_value=transitions_response)+ post_mock = AsyncMock() # MUST NOT be called.+ mock_client.return_value.__aenter__.return_value.get = get_mock+ mock_client.return_value.__aenter__.return_value.post = post_mock++ result = await connector.push_status_change(+ case={"id": "abc"},+ old_status="new",+ new_status="resolved", # → "Done", not in workflow.+ external_ref={"external_id": "SEC-9", "external_status": "To Do"},+ )++ assert get_mock.await_count == 1+ assert post_mock.await_count == 0 # critical: no transition POST+ assert result["external_id"] == "SEC-9"+++async def test_jira_push_status_change_resolves_and_posts_transition() -> None:+ """Happy path: discover the transition then POST it with that ID."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ transitions_response = _build_response(+ status_code=200,+ json_body={+ "transitions": [+ {"id": "11", "name": "Start", "to": {"name": "In Progress"}},+ {"id": "21", "name": "Resolve", "to": {"name": "Done"}},+ ]+ },+ )+ transition_post = _build_response(status_code=204)++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ get_mock = AsyncMock(return_value=transitions_response)+ post_mock = AsyncMock(return_value=transition_post)+ mock_client.return_value.__aenter__.return_value.get = get_mock+ mock_client.return_value.__aenter__.return_value.post = post_mock++ result = await connector.push_status_change(+ case={"id": "abc"},+ old_status="new",+ new_status="resolved",+ external_ref={"external_id": "SEC-9", "external_status": "To Do"},+ )++ # GET .../transitions then POST .../transitions with id=21.+ assert get_mock.await_args.args[0].endswith("/rest/api/3/issue/SEC-9/transitions")+ assert post_mock.await_args.args[0].endswith("/rest/api/3/issue/SEC-9/transitions")+ assert post_mock.await_args.kwargs["json"] == {"transition": {"id": "21"}}+ assert result["external_status"] == "Done"+++async def test_jira_push_status_change_raises_on_transition_4xx() -> None:+ """A non-2xx on the transition POST surfaces as HTTPStatusError."""+ connector = JiraConnector(+ base_url="https://acme.atlassian.net",+ email="[email protected]",+ api_token="t",+ project_key="SEC",+ )+ transitions_response = _build_response(+ status_code=200,+ json_body={"transitions": [{"id": "21", "name": "Resolve", "to": {"name": "Done"}}]},+ )+ transition_post = _build_response(status_code=403, text="forbidden")++ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:+ mock_client.return_value.__aenter__.return_value.get = AsyncMock(+ return_value=transitions_response+ )+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(+ return_value=transition_post+ )++ with pytest.raises(httpx.HTTPStatusError, match="jira.push_status_change failed"):+ await connector.push_status_change(+ case={"id": "abc"},+ old_status="new",+ new_status="closed",+ external_ref={"external_id": "SEC-9"},+ )+++# ===========================================================================+# ServiceNow: push_case+# ===========================================================================+++async def test_snow_push_case_posts_to_table_with_correlation_id() -> None:+ """Happy path: incident table POST, correlation_id round-trips case id."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com/",+ username="aisoc-bot",+ password="hunter2",+ )+ response = _build_response(+ status_code=201,+ json_body={+ "result": {+ "sys_id": "abcdef0123456789abcdef0123456789",+ "number": "INC0010023",+ "state": "1",+ }+ },+ )++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock++ result = await connector.push_case(+ {+ "id": "case-uuid-1",+ "case_number": "AIS-42",+ "title": "Lateral movement detected",+ "description": "SMB scan",+ "severity": "critical",+ }+ )++ assert post_mock.await_count == 1+ call = post_mock.await_args+ assert call.args[0] == "https://acme.service-now.com/api/now/table/incident"+ body = call.kwargs["json"]+ assert body["short_description"] == "Lateral movement detected"+ # severity=critical → impact=1 (urgency mirrors impact for OOTB).+ assert body["impact"] == "1"+ assert body["urgency"] == "1"+ # correlation_id round-trips the AiSOC case identifier.+ assert body["correlation_id"] == "aisoc:case-uuid-1"++ assert result["external_id"] == "abcdef0123456789abcdef0123456789"+ assert result["vendor"] == "servicenow"+ # _record_url with number returns the nav_to.do form.+ assert "sys_id=abcdef0123456789abcdef0123456789" in result["external_url"]+++async def test_snow_push_case_short_description_truncates_at_160() -> None:+ """short_description in ServiceNow caps at 160 chars."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ response = _build_response(+ status_code=201, json_body={"result": {"sys_id": "x" * 32, "state": "1"}}+ )++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ await connector.push_case({"id": "1", "title": "y" * 300})++ body = post_mock.await_args.kwargs["json"]+ assert len(body["short_description"]) == 160+++async def test_snow_push_case_raises_on_4xx() -> None:+ """ServiceNow 4xx must propagate so the fan-out service can mark+ the external_ref ``failed`` rather than silently dropping the push."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ response = _build_response(status_code=400, text="ACL denied")++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ with pytest.raises(httpx.HTTPStatusError, match="servicenow.push_case failed"):+ await connector.push_case({"id": "1", "title": "x"})+++# ===========================================================================+# ServiceNow: push_status_change+# ===========================================================================+++async def test_snow_push_status_change_falls_through_to_push_case_when_no_ref() -> None:+ """No ref → mint the incident."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ response = _build_response(+ status_code=201, json_body={"result": {"sys_id": "x" * 32, "state": "1"}}+ )++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ post_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.post = post_mock+ result = await connector.push_status_change(+ case={"id": "1", "title": "x"},+ old_status="new",+ new_status="investigating",+ external_ref=None,+ )++ assert post_mock.await_count == 1+ assert post_mock.await_args.args[0].endswith("/api/now/table/incident")+ assert result["external_id"] == "x" * 32+++async def test_snow_push_status_change_requires_external_id_in_ref() -> None:+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ with pytest.raises(ValueError, match="missing external_id"):+ await connector.push_status_change(+ case={"id": "1"},+ old_status="new",+ new_status="resolved",+ external_ref={"vendor": "servicenow"},+ )+++async def test_snow_push_status_change_unknown_status_is_noop() -> None:+ """Unknown AiSOC status → no HTTP call, return ref unchanged."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ result = await connector.push_status_change(+ case={"id": "1"},+ old_status="new",+ new_status="alien-status",+ external_ref={"external_id": "ABC", "external_status": "1"},+ )+ assert mock_client.call_count == 0++ assert result["external_id"] == "ABC"+ assert result["external_status"] == "1"+++async def test_snow_push_status_change_in_progress_patches_state_only() -> None:+ """Non-resolved transitions only set ``state`` — no close metadata."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ response = _build_response(+ status_code=200, json_body={"result": {"sys_id": "abc", "state": "2"}}+ )++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ patch_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.patch = patch_mock++ result = await connector.push_status_change(+ case={"id": "case-uuid"},+ old_status="new",+ new_status="investigating",+ external_ref={"external_id": "abc", "external_status": "1"},+ )++ assert patch_mock.await_count == 1+ body = patch_mock.await_args.kwargs["json"]+ assert body == {"state": "2"}+ # Critically: no close_code / close_notes when not Resolved/Closed.+ assert "close_code" not in body+ assert "close_notes" not in body+ assert result["external_status"] == "2"+++async def test_snow_push_status_change_resolved_includes_close_metadata() -> None:+ """Resolved/Closed transitions MUST send close_code+close_notes or+ ServiceNow silently rejects the state change on most stock instances."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ response = _build_response(+ status_code=200, json_body={"result": {"sys_id": "abc", "state": "6"}}+ )++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ patch_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.patch = patch_mock++ await connector.push_status_change(+ case={"id": "case-uuid", "case_number": "AIS-42"},+ old_status="investigating",+ new_status="resolved",+ external_ref={"external_id": "abc", "external_status": "2"},+ )++ body = patch_mock.await_args.kwargs["json"]+ assert body["state"] == "6"+ assert body["close_code"] # any non-empty default+ assert "AIS-42" in body["close_notes"]+++async def test_snow_push_status_change_closed_includes_close_metadata() -> None:+ """Same contract as Resolved for the Closed (state=7) bucket."""+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ response = _build_response(+ status_code=200, json_body={"result": {"sys_id": "abc", "state": "7"}}+ )++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ patch_mock = AsyncMock(return_value=response)+ mock_client.return_value.__aenter__.return_value.patch = patch_mock++ await connector.push_status_change(+ case={"id": "case-uuid"},+ old_status="resolved",+ new_status="closed",+ external_ref={"external_id": "abc", "external_status": "6"},+ )++ body = patch_mock.await_args.kwargs["json"]+ assert body["state"] == "7"+ assert "close_code" in body+ assert "close_notes" in body+++async def test_snow_push_status_change_raises_on_4xx() -> None:+ connector = ServiceNowConnector(+ instance_url="https://acme.service-now.com",+ username="u",+ password="p",+ )+ response = _build_response(status_code=403, text="ACL denied on incident")++ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:+ mock_client.return_value.__aenter__.return_value.patch = AsyncMock(+ return_value=response+ )+ with pytest.raises(httpx.HTTPStatusError, match="servicenow.push_status_change failed"):+ await connector.push_status_change(+ case={"id": "1"},+ old_status="new",+ new_status="resolved",+ external_ref={"external_id": "abc"},+ )+++# ===========================================================================+# Capability declarations — guard against accidental drop in future PRs.+# ===========================================================================+++def test_jira_capabilities_advertise_push() -> None:+ from app.connectors.base import Capability++ caps = JiraConnector.capabilities()+ assert Capability.PUSH_CASE in caps+ assert Capability.PUSH_STATUS in caps+ assert Capability.PULL_ALERTS in caps # pre-WS8 capability still intact+++def test_servicenow_capabilities_advertise_push() -> None:+ from app.connectors.base import Capability++ caps = ServiceNowConnector.capabilities()+ assert Capability.PUSH_CASE in caps+ assert Capability.PUSH_STATUS in caps+ assert Capability.PULL_ALERTS in caps