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
"""ContextBundle model + builder — T2.1.
A :class:`ContextBundle` is the *pre-fetched* context object that the four
public agents (Detect / Triage / Hunt / Respond) and their internal
capability shims (phishing, identity, cloud, insider-threat) consume in
place of issuing their own primary-discovery tool calls.
The builder fans out to four read-only context sources concurrently:
* graph neighbourhood (``services/api`` — depth-N walk per principal entity),
* institutional memory (``aisoc_institutional_memory`` — similar-case
verdicts keyed by template / category / IOC tag),
* UEBA baselines (``services/ueba`` — per-entity peer baseline + deviation),
* threat intel (``services/enrichment`` — per-IOC reputation + risk).
Every field is optional and the bundle is allowed to be partial — a
context source that times out, errors, or is unavailable populates the
``errors`` list and leaves its slot empty so the consumer can fall back
to its own primary-discovery code path. Tests gate the *build latency*
(p95 < 5s across the 200-incident benchmark), not the *contents*, because
the eval harness runs offline against substrate stubs.
The model is the *only* shape an agent should hand to the LLM-input
contract (T2.3) — its ``summary_for_llm`` method returns a dict whose
keys are explicitly enumerated as allowed by ``LLMInputContract``.
"""
from __future__ import annotations
import asyncio
import os
import re
import time
from datetime import UTC, datetime
from typing import Any
from uuid import UUID, uuid4
import httpx
import structlog
from pydantic import BaseModel, Field
logger = structlog.get_logger()
# ---------------------------------------------------------------------------
# Entity extraction
# ---------------------------------------------------------------------------
# Map of raw_alert key → entity type. Order matters only insofar as it controls
# which alias is preferred when several keys point at the same logical entity.
_HOST_KEYS = (
"host",
"hostname",
"Computer",
"computer",
"device",
"asset",
"endpoint",
)
_USER_KEYS = (
"user",
"username",
"user_email",
"UserId",
"principal",
"actor",
"sender",
"recipient",
)
_IP_KEYS = (
"src_ip",
"source_ip",
"ClientIP",
"client_ip",
"dst_ip",
"dest_ip",
"destination_ip",
"remote_ip",
"ip",
)
_DOMAIN_KEYS = ("domain", "sender_domain", "fqdn", "host_domain")
_HASH_KEYS = ("file_hash", "sha256", "md5", "sha1", "hash")
_URL_KEYS = ("url", "primary_url")
_IPV4_RE = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
_DOMAIN_RE = re.compile(r"\b(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}\b", re.IGNORECASE)
_HASH_RE = re.compile(r"\b[a-f0-9]{32}\b|\b[a-f0-9]{40}\b|\b[a-f0-9]{64}\b", re.IGNORECASE)
class EntityRef(BaseModel):
"""Stable reference to an entity in the alert.
``key`` is the canonical join key used as the dict key in
``entity_neighborhoods`` / ``peer_baselines`` / ``threat_intel``.
"""
type: str # host | user | ip | domain | hash | url | email
value: str
@property
def key(self) -> str:
return f"{self.type}:{self.value}"
def _string_field(raw: dict[str, Any], keys: tuple[str, ...]) -> list[str]:
out: list[str] = []
for key in keys:
val = raw.get(key)
if isinstance(val, str) and val.strip():
out.append(val.strip())
elif isinstance(val, list | tuple):
for v in val:
if isinstance(v, str) and v.strip():
out.append(v.strip())
return out
def extract_entities(raw_alert: dict[str, Any], *, summary: str = "") -> list[EntityRef]:
"""Extract a deduplicated list of entities from the raw alert + summary.
Pulled out into a top-level function so the builder's tests can hit it
directly without spinning up the full builder.
"""
found: dict[str, EntityRef] = {}
def _add(etype: str, value: str) -> None:
value = value.strip()
if not value:
return
ref = EntityRef(type=etype, value=value)
found.setdefault(ref.key, ref)
for v in _string_field(raw_alert, _HOST_KEYS):
_add("host", v)
for v in _string_field(raw_alert, _USER_KEYS):
# Distinguish email-shaped users from bare usernames so the bundle
# can be cross-joined with the email-channel TI sources downstream.
etype = "email" if "@" in v else "user"
_add(etype, v)
for v in _string_field(raw_alert, _IP_KEYS):
_add("ip", v)
for v in _string_field(raw_alert, _DOMAIN_KEYS):
_add("domain", v.lower())
for v in _string_field(raw_alert, _HASH_KEYS):
_add("hash", v.lower())
for v in _string_field(raw_alert, _URL_KEYS):
_add("url", v)
# Best-effort regex sweep over the alert summary so generic alerts that
# only carry a free-text description still get an entity vector. The
# summary regexes run on the joined text so we don't miss IOCs that
# straddle a boundary.
text = " ".join([summary or "", str(raw_alert.get("description", "")), str(raw_alert.get("title", ""))])
for ip in _IPV4_RE.findall(text):
_add("ip", ip)
for h in _HASH_RE.findall(text):
_add("hash", h.lower())
for d in _DOMAIN_RE.findall(text):
# Filter out things that look like file extensions / version numbers
# by requiring a TLD of length >= 2 and a body of length >= 4.
if len(d) >= 6 and "." in d:
_add("domain", d.lower())
return list(found.values())
# ---------------------------------------------------------------------------
# Sub-models
# ---------------------------------------------------------------------------
class EntityNeighborhood(BaseModel):
"""Result of a depth-N graph walk centred on a single entity."""
entity: EntityRef
depth: int = 2
nodes: list[dict[str, Any]] = Field(default_factory=list)
edges: list[dict[str, Any]] = Field(default_factory=list)
blast_radius_score: float | None = None
summary: str = ""
@property
def node_count(self) -> int:
return len(self.nodes)
class HistoricalCase(BaseModel):
"""A previously-closed case judged similar to the current alert.
Pulled from ``aisoc_institutional_memory`` (PostgreSQL with an in-process
fallback). ``similarity_score`` is computed by the builder using a
deterministic Jaccard over template_id / response_class / IOC tags so
eval runs are reproducible.
"""
key: str
verdict: str
confidence: float = 0.0
template_id: str | None = None
response_class: str | None = None
similarity_score: float = 0.0
rationale: str | None = None
closed_at: str | None = None
class UEBABaseline(BaseModel):
"""Per-entity UEBA baseline + peer-group deviation.
Mirrors the shape returned by ``services/ueba`` ``/api/v1/ueba/baselines``
so the bundle can pass through what the UEBA service computed without
re-deriving it.
"""
entity: EntityRef
peer_group_id: str | None = None
activity_window_days: int = 30
baseline: dict[str, float] = Field(default_factory=dict)
deviation_score: float = 0.0
notes: str = ""
class ThreatIntelMatch(BaseModel):
"""Per-IOC enrichment record."""
ioc: str
ioc_type: str
sources: list[str] = Field(default_factory=list)
risk: str = "unknown" # low | medium | high | unknown
first_seen: str | None = None
last_seen: str | None = None
summary: str = ""
# ---------------------------------------------------------------------------
# ContextBundle
# ---------------------------------------------------------------------------
# Allowed top-level keys in ``summary_for_llm`` — kept here (not in
# ``app/llm/contract.py``) so the model is the source of truth and the
# contract validator can import this whitelist. Public (no leading
# underscore) because it is imported by tests and by external contract
# validators; the previous private-with-suppression form tripped CodeQL
# ``py/unused-global-variable`` because the inline suppression marker
# was not honoured by the analyzer.
LLM_SAFE_KEYS = (
"incident_id",
"alert_summary",
"entity_count",
"entity_types",
"entity_keys",
"neighborhood_summaries",
"blast_radius_max",
"historical_similar_count",
"historical_verdicts",
"ueba_max_deviation",
"ueba_entities_with_baseline",
"threat_intel_high_risk_iocs",
"threat_intel_match_count",
"threat_intel_sources",
"build_latency_ms",
"sources_called",
"errors",
)
class IncidentContextDimensions(BaseModel):
"""Identity, asset, cloud, business and threat context for the alert.
Distinct from ``entity_neighborhoods``, which answers "what is reachable"
as an undifferentiated node set. This answers "what does it mean": which
person is behind the account, what is exploitable on the host, which
business application it serves, who is accountable, and which actor the
indicators point at. A narrative and a prompt both need the dimensions
kept apart; a node set makes the caller re-derive them.
"""
identities: list[dict[str, Any]] = Field(default_factory=list)
assets: list[dict[str, Any]] = Field(default_factory=list)
cloud: list[dict[str, Any]] = Field(default_factory=list)
business: list[dict[str, Any]] = Field(default_factory=list)
threat: list[dict[str, Any]] = Field(default_factory=list)
narrative: list[str] = Field(default_factory=list)
# True when some dimensions could not be read. Without this an agent
# cannot distinguish "this alert has no context" from "we could not
# look", and will reason as though the first were true.
partial: bool = False
errors: list[str] = Field(default_factory=list)
@property
def dimensions_resolved(self) -> int:
return sum(1 for d in (self.identities, self.assets, self.cloud, self.business, self.threat) if d)
@property
def has_content(self) -> bool:
return self.dimensions_resolved > 0
class ContextBundle(BaseModel):
"""Pre-fetched, structured context handed to every sub-agent."""
bundle_id: UUID = Field(default_factory=uuid4)
incident_id: UUID
tenant_id: str = "default"
alert_summary: str = ""
# Discovered entities + per-entity context, keyed by ``EntityRef.key``.
entities: list[EntityRef] = Field(default_factory=list)
entity_neighborhoods: dict[str, EntityNeighborhood] = Field(default_factory=dict)
peer_baselines: dict[str, UEBABaseline] = Field(default_factory=dict)
threat_intel: dict[str, ThreatIntelMatch] = Field(default_factory=dict)
incident_context: IncidentContextDimensions = Field(default_factory=IncidentContextDimensions)
# Memory (institutional tier) recall.
historical_similar_cases: list[HistoricalCase] = Field(default_factory=list)
# Provenance / health.
build_started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
build_completed_at: datetime | None = None
build_latency_ms: int = 0
sources_called: list[str] = Field(default_factory=list)
errors: list[str] = Field(default_factory=list)
depth: int = 2
@property
def is_complete(self) -> bool:
"""True when at least one source returned data and there are no errors."""
return self.build_completed_at is not None and not self.errors
@property
def has_any_context(self) -> bool:
"""True when *any* slot in the bundle has actual content.
Used by sub-agents to decide whether to short-circuit to the
bundle-aware prompt or fall back to bare-alert reasoning.
"""
return bool(
self.entity_neighborhoods
or self.peer_baselines
or self.threat_intel
or self.historical_similar_cases
or self.incident_context.has_content
)
def prompt_context_lines(self) -> list[str]:
"""Render the bundle's safe summary fields as prompt-ready lines.
Sub-agents call this to inject pre-fetched context (entity
neighbourhood, historical verdicts, UEBA deviation, TI matches)
instead of re-discovering the same facts via primary tool calls.
Only fields enumerated by ``summary_for_llm`` are surfaced — never
raw OCSF or log payloads.
"""
# A bundle with no content but a failed context lookup still has
# something to say. Returning [] here meant the one case worth
# warning about — we tried to resolve identity, asset and business
# context and could not — reached the model as silence, which reads
# the same as "this alert has no context".
if not self.has_any_context and not self.incident_context.partial:
return []
s = self.summary_for_llm()
parts: list[str] = ["", "Pre-fetched investigation context (ContextBundle):"]
if s.get("entity_count"):
parts.append(f"- Entities resolved: {s['entity_count']} ({', '.join(s.get('entity_types') or []) or 'unknown'})")
if s.get("neighborhood_summaries"):
parts.append("- Graph neighbourhood:")
for line in s["neighborhood_summaries"]:
parts.append(f" * {line}")
if s.get("blast_radius_max"):
parts.append(f"- Max blast-radius score: {s['blast_radius_max']:.2f}")
if s.get("historical_similar_count"):
top = max(
(h["similarity"] for h in s.get("historical_verdicts") or []),
default=0.0,
)
parts.append(f"- Similar historical cases: {s['historical_similar_count']} (top similarity={top:.2f})")
for h in (s.get("historical_verdicts") or [])[:3]:
parts.append(f" * {h['key']} → {h['verdict']} (sim={h['similarity']:.2f})")
if s.get("ueba_entities_with_baseline"):
parts.append(
f"- UEBA: {s['ueba_entities_with_baseline']} entities with baseline, max deviation={s.get('ueba_max_deviation', 0.0):.2f}"
)
if s.get("threat_intel_match_count"):
parts.append(
f"- Threat-intel matches: {s['threat_intel_match_count']} "
f"(high-risk IOCs: {', '.join(s.get('threat_intel_high_risk_iocs') or []) or 'none'})"
)
# Identity, asset, cloud, business and threat depth. Rendered last
# and rendered verbatim: the API composes these lines, and
# re-summarising them here would drop the qualifiers that keep them
# honest — an unconfirmed attribution, a partial lookup, a departed
# employee whose account is still live.
ctx = self.incident_context
if ctx.narrative:
parts.append("- Entity context:")
parts.extend(f" {line}" for line in ctx.narrative)
elif ctx.partial:
# No content *and* a failed lookup. Saying nothing here would
# let the model read absence of context as absence of risk.
parts.append(
"- Entity context: unavailable (" + ", ".join(ctx.errors) + "). Treat missing identity/asset/business context as unknown, "
"not as benign."
)
return parts
def summary_for_llm(self) -> dict[str, Any]:
"""Pre-digested, contract-safe summary for LLM prompts.
Every key returned here is on ``LLM_SAFE_KEYS`` and contains either
a scalar, a small list of scalars, or a list of short string summaries
— never raw OCSF / log payloads. ``LLMInputContract`` (T2.3) treats
the output of this method as the canonical safe shape.
"""
neigh_summaries = [
f"{key}: {nbr.node_count} nodes (depth={nbr.depth})"
+ (f", blast_radius={nbr.blast_radius_score:.2f}" if nbr.blast_radius_score is not None else "")
for key, nbr in sorted(self.entity_neighborhoods.items())
]
blast_scores = [n.blast_radius_score for n in self.entity_neighborhoods.values() if n.blast_radius_score is not None]
ueba_devs = [b.deviation_score for b in self.peer_baselines.values()]
high_risk = sorted(ti.ioc for ti in self.threat_intel.values() if ti.risk == "high")
ti_sources: set[str] = set()
for ti in self.threat_intel.values():
ti_sources.update(ti.sources)
return {
"incident_id": str(self.incident_id),
"alert_summary": self.alert_summary,
"entity_count": len(self.entities),
"entity_types": sorted({e.type for e in self.entities}),
"entity_keys": sorted(e.key for e in self.entities)[:25],
"neighborhood_summaries": neigh_summaries[:25],
"blast_radius_max": max(blast_scores) if blast_scores else 0.0,
"historical_similar_count": len(self.historical_similar_cases),
"historical_verdicts": [
{
"key": h.key,
"verdict": h.verdict,
"similarity": round(h.similarity_score, 3),
}
for h in self.historical_similar_cases[:10]
],
"ueba_max_deviation": max(ueba_devs) if ueba_devs else 0.0,
"ueba_entities_with_baseline": len(self.peer_baselines),
"threat_intel_high_risk_iocs": high_risk[:20],
"threat_intel_match_count": len(self.threat_intel),
"threat_intel_sources": sorted(ti_sources)[:20],
"build_latency_ms": self.build_latency_ms,
"sources_called": sorted(self.sources_called),
"errors": self.errors[:5],
}
# ---------------------------------------------------------------------------
# Builder
# ---------------------------------------------------------------------------
def _ti_risk_from_enrichment(payload: dict[str, Any]) -> str:
"""Best-effort risk-bucket extraction from the enrichment service payload."""
if not isinstance(payload, dict) or payload.get("error"):
return "unknown"
score = payload.get("risk_score") or payload.get("score") or 0.0
try:
score = float(score)
except (TypeError, ValueError):
score = 0.0
if score >= 0.7:
return "high"
if score >= 0.4:
return "medium"
if score > 0:
return "low"
explicit = payload.get("risk") or payload.get("severity")
if isinstance(explicit, str) and explicit.lower() in {"low", "medium", "high"}:
return explicit.lower()
return "unknown"
def _ti_sources(payload: dict[str, Any]) -> list[str]:
if not isinstance(payload, dict):
return []
sources = payload.get("sources") or payload.get("providers") or []
if isinstance(sources, list):
return [str(s) for s in sources][:10]
if isinstance(sources, dict):
return sorted(sources.keys())[:10]
return []
class ContextBundleBuilder:
"""Builds a :class:`ContextBundle` for an investigation in parallel.
The builder is constructed with timeouts/limits — it never raises, only
appends to ``bundle.errors`` if a context source misbehaves. Sub-agent
code paths therefore stay deterministic regardless of substrate health.
"""
DEFAULT_DEPTH = 2
def __init__(
self,
*,
depth: int | None = None,
max_neighborhood_nodes: int = 30,
history_limit: int = 5,
ti_concurrency: int = 8,
per_source_timeout: float = 3.5,
api_token: str | None = None,
) -> None:
self.depth = depth if depth is not None else int(os.getenv("AISOC_CONTEXT_BUNDLE_DEPTH", str(self.DEFAULT_DEPTH)))
self.max_neighborhood_nodes = max_neighborhood_nodes
self.history_limit = history_limit
self.ti_concurrency = ti_concurrency
self.per_source_timeout = per_source_timeout
self.api_token = api_token
# ------------------------------------------------------------------
# Public entry point
# ------------------------------------------------------------------
async def build(self, state: Any) -> ContextBundle:
"""Construct a bundle for the given ``InvestigationState``.
``state`` is typed as ``Any`` so this module doesn't import the
heavyweight ``InvestigationState`` at module-load time and so a
thin dict can be passed in tests.
"""
t0 = time.monotonic()
incident_id = getattr(state, "incident_id", None) or uuid4()
tenant_id = str(getattr(state, "tenant_id", "default"))
alert_summary = getattr(state, "alert_summary", "") or ""
raw_alert = getattr(state, "raw_alert", {}) or {}
bundle = ContextBundle(
incident_id=incident_id,
tenant_id=tenant_id,
alert_summary=alert_summary,
depth=self.depth,
)
bundle.entities = extract_entities(raw_alert, summary=alert_summary)
# Fan out — every coroutine is wrapped in ``_safe`` so a single
# exception can't poison the bundle.
results = await asyncio.gather(
self._safe(
"graph",
self._fetch_neighborhoods(bundle.entities),
bundle,
),
self._safe(
"memory",
self._fetch_history(tenant_id, raw_alert, alert_summary),
bundle,
),
self._safe(
"ueba",
self._fetch_baselines(tenant_id, bundle.entities),
bundle,
),
self._safe(
"threat_intel",
self._fetch_threat_intel(bundle.entities),
bundle,
),
self._safe(
"incident_context",
self._fetch_incident_context(tenant_id, raw_alert),
bundle,
),
return_exceptions=False,
)
neigh_result, history_result, ueba_result, ti_result, ctx_result = results
if isinstance(neigh_result, dict):
bundle.entity_neighborhoods = neigh_result
if isinstance(history_result, list):
bundle.historical_similar_cases = history_result
if isinstance(ueba_result, dict):
bundle.peer_baselines = ueba_result
if isinstance(ti_result, dict):
bundle.threat_intel = ti_result
if isinstance(ctx_result, IncidentContextDimensions):
bundle.incident_context = ctx_result
bundle.build_completed_at = datetime.now(UTC)
bundle.build_latency_ms = int((time.monotonic() - t0) * 1000)
return bundle
# ------------------------------------------------------------------
# Source fetchers — each returns its own slice of the bundle
# ------------------------------------------------------------------
async def _fetch_neighborhoods(self, entities: list[EntityRef]) -> dict[str, EntityNeighborhood]:
"""Walk the graph for each principal entity, depth-N."""
# Lazy import so ``services/agents`` modules without the API tool
# installed (e.g. eval harness) can still import this builder.
try:
from app.tools.graph import get_blast_radius, get_entity_neighbors
except Exception as exc: # noqa: BLE001
raise RuntimeError(f"graph tool unavailable: {exc}") from exc
# Only walk principal entities — IPs, domains, hashes are TI input,
# not graph principals.
principals = [e for e in entities if e.type in ("host", "user", "email")]
if not principals:
self._record_source("graph")
return {}
async def _walk(entity: EntityRef) -> tuple[str, EntityNeighborhood]:
nbr_payload, blast_payload = await asyncio.gather(
get_entity_neighbors(entity.type, entity.value, api_token=self.api_token),
get_blast_radius(entity.type, entity.value, api_token=self.api_token, hops=self.depth),
)
nodes = nbr_payload.get("neighbors", []) if isinstance(nbr_payload, dict) else []
edges = nbr_payload.get("edges", []) if isinstance(nbr_payload, dict) else []
blast = None
if isinstance(blast_payload, dict):
blast = blast_payload.get("blast_radius_score")
summary = f"{len(nodes)} neighbors at depth {self.depth}" + (f", blast_radius={float(blast):.2f}" if blast is not None else "")
return entity.key, EntityNeighborhood(
entity=entity,
depth=self.depth,
nodes=nodes[: self.max_neighborhood_nodes],
edges=edges[: self.max_neighborhood_nodes],
blast_radius_score=float(blast) if blast is not None else None,
summary=summary,
)
out: dict[str, EntityNeighborhood] = {}
results = await asyncio.gather(*[_walk(e) for e in principals], return_exceptions=True)
for r in results:
# BaseException, not Exception: `gather(return_exceptions=True)`
# hands back a cancelled child's `CancelledError`, which is a
# BaseException on 3.8+. Filtering on `Exception` let it through
# to the unpack below, turning a cancelled graph walk into
# `TypeError: cannot unpack non-sequence CancelledError`.
if isinstance(r, BaseException):
logger.debug("context.neighborhood.failed", error=str(r))
continue
key, nbr = r
out[key] = nbr
self._record_source("graph")
return out
async def _fetch_history(
self,
tenant_id: str,
raw_alert: dict[str, Any],
alert_summary: str,
) -> list[HistoricalCase]:
"""Pull similar-case verdicts from the institutional memory tier."""
try:
from app.memory.institutional import institutional_search
except Exception as exc: # noqa: BLE001
raise RuntimeError(f"institutional memory unavailable: {exc}") from exc
# Tag candidates: template_id, response_class, severity, plus a small
# set of category tokens derived from the summary. Memory is queried
# by tag so this is best-effort but fully deterministic for tests.
tags: list[str] = []
for k in ("template_id", "response_class", "category", "severity"):
v = raw_alert.get(k)
if isinstance(v, str) and v:
tags.append(v)
rows = await institutional_search(tenant_id, tags=tags or None, limit=self.history_limit)
own_set = {t.lower() for t in tags}
out: list[HistoricalCase] = []
for row in rows or []:
value = row.get("value") if isinstance(row, dict) else {}
if not isinstance(value, dict):
value = {}
row_tags = {str(t).lower() for t in (row.get("tags") or [])}
jaccard = len(own_set & row_tags) / max(1, len(own_set | row_tags)) if own_set or row_tags else 0.0
out.append(
HistoricalCase(
key=str(row.get("key", "")),
verdict=str(value.get("verdict", "unknown")),
confidence=float(value.get("confidence", 0.0) or 0.0),
template_id=value.get("template_id"),
response_class=value.get("response_class"),
similarity_score=round(jaccard, 4),
rationale=(value.get("rationale") or value.get("summary") or None),
closed_at=row.get("created_at"),
)
)
# Sort by similarity desc so the head of the list is most-relevant.
out.sort(key=lambda h: h.similarity_score, reverse=True)
self._record_source("memory")
return out[: self.history_limit]
async def _fetch_baselines(
self,
tenant_id: str,
entities: list[EntityRef],
) -> dict[str, UEBABaseline]:
"""Pull per-entity UEBA baselines from the UEBA service."""
ueba_url = os.getenv("AISOC_UEBA_URL", "http://ueba:8086")
principals = [e for e in entities if e.type in ("user", "email", "host", "ip")]
if not principals:
self._record_source("ueba")
return {}
out: dict[str, UEBABaseline] = {}
async with httpx.AsyncClient(timeout=self.per_source_timeout) as client:
async def _one(entity: EntityRef) -> tuple[str, UEBABaseline] | None:
# The UEBA list endpoint takes tenant + entity_type, then we
# filter client-side. We accept that this is over-fetching
# for now; the bundle is still bounded by ``history_limit``.
try:
resp = await client.get(
f"{ueba_url}/api/v1/ueba/baselines",
params={"tenant_id": tenant_id, "entity_type": entity.type, "limit": 50},
)
resp.raise_for_status()
rows = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else []
except Exception as exc: # noqa: BLE001
logger.debug("context.ueba.failed", entity=entity.key, error=str(exc))
return None
if not isinstance(rows, list):
return None
for row in rows:
if not isinstance(row, dict):
continue
if row.get("entity_id") != entity.value:
continue
return entity.key, UEBABaseline(
entity=entity,
peer_group_id=row.get("peer_group_id"),
activity_window_days=int(row.get("window_days", 30)),
baseline=row.get("baseline_features", {}) or {},
deviation_score=float(row.get("deviation_score", 0.0) or 0.0),
notes=str(row.get("notes", "")),
)
return None
results = await asyncio.gather(*[_one(e) for e in principals], return_exceptions=True)
for r in results:
# See `_fetch_neighborhoods`: a cancelled child returns a
# `CancelledError`, which is not an `Exception`.
if isinstance(r, BaseException) or r is None:
continue
key, baseline = r
out[key] = baseline
self._record_source("ueba")
return out
async def _fetch_incident_context(
self,
tenant_id: str,
raw_alert: dict[str, Any],
) -> IncidentContextDimensions:
"""Resolve the alert into identity, asset, cloud, business and threat.
Delegated to the API rather than queried here: the API owns the Neo4j
session and the tenant-scoping predicate, and duplicating a Cypher
traversal whose correctness is a security property in a second
service is how the two drift apart.
"""
alert_id = raw_alert.get("id") or raw_alert.get("alert_id") or raw_alert.get("external_id")
if not alert_id:
self._record_source("incident_context")
return IncidentContextDimensions()
api_url = os.getenv("AISOC_API_URL", "http://api:8000")
# The service-credential shape `get_current_user` actually resolves:
# `Authorization: Bearer <service token>` plus `X-AiSOC-Tenant-ID`.
# This fetch used to send `X-Tenant-ID` (a header the API's auth never
# reads) with an optional `AISOC_AGENTS_API_KEY` bearer that no compose
# file, `.env.example` or Helm value delivers — so the graph's business
# dimension answered 401 on every default deployment and the prompt
# rendered "unavailable" forever. Same fix class as
# `tools/investigation.py`; same token resolution order as
# `context/identity.py`, the one path of this shape proven live.
token = os.getenv("AISOC_AGENTS_SERVICE_TOKEN", "").strip() or os.getenv("AISOC_SERVICE_TOKEN", "").strip()
if not token:
# Raise rather than return empty dimensions: the caller's safe-wrap
# marks the source unavailable, which keeps "no credential" from
# reading as "no business context". Dialing anyway would be a
# guaranteed 401 that reads as the API rejecting us.
raise RuntimeError("incident context needs a service credential: set AISOC_AGENTS_SERVICE_TOKEN (or AISOC_SERVICE_TOKEN)")
headers = {
"Authorization": f"Bearer {token}",
"X-AiSOC-Tenant-ID": tenant_id,
}
async with httpx.AsyncClient(timeout=self.per_source_timeout) as client:
response = await client.get(
f"{api_url}/api/v1/graph/incident-context/{alert_id}",
headers=headers,
)
response.raise_for_status()
payload = response.json()
self._record_source("incident_context")
if not isinstance(payload, dict):
return IncidentContextDimensions()
return IncidentContextDimensions(
identities=payload.get("identities") or [],
assets=payload.get("assets") or [],
cloud=payload.get("cloud") or [],
business=payload.get("business") or [],
threat=payload.get("threat") or [],
narrative=payload.get("narrative") or [],
partial=bool(payload.get("partial")),
errors=payload.get("errors") or [],
)
async def _fetch_threat_intel(self, entities: list[EntityRef]) -> dict[str, ThreatIntelMatch]:
"""Bulk-enrich every IOC-shaped entity in the alert."""
try:
from app.tools.enrichment import bulk_enrich_iocs
except Exception as exc: # noqa: BLE001
raise RuntimeError(f"enrichment tool unavailable: {exc}") from exc
ioc_entities = [e for e in entities if e.type in ("ip", "domain", "hash", "url")]
if not ioc_entities:
self._record_source("threat_intel")
return {}
# Bulk endpoint takes a list of {value, ioc_type} — chunk so a single
# giant alert can't fan out >1k items.
batch = [{"value": e.value, "ioc_type": e.type} for e in ioc_entities[:64]]
rows = await bulk_enrich_iocs(batch)
out: dict[str, ThreatIntelMatch] = {}
for row in rows or []:
if not isinstance(row, dict):
continue
value = row.get("value") or row.get("ioc")
ioc_type = row.get("ioc_type") or row.get("type")
if not value or not ioc_type:
continue
risk = _ti_risk_from_enrichment(row)
out[f"{ioc_type}:{value}"] = ThreatIntelMatch(
ioc=str(value),
ioc_type=str(ioc_type),
sources=_ti_sources(row),
risk=risk,
first_seen=row.get("first_seen"),
last_seen=row.get("last_seen"),
summary=str(row.get("summary") or row.get("description") or ""),
)
self._record_source("threat_intel")
return out
# ------------------------------------------------------------------
# Helpers
# ------------------------------------------------------------------
async def _safe(self, name: str, coro: Any, bundle: ContextBundle) -> Any:
"""Run ``coro`` with a per-source timeout; record errors instead of raising."""
try:
return await asyncio.wait_for(coro, timeout=self.per_source_timeout)
except TimeoutError:
bundle.errors.append(f"{name}:timeout")
return None
except Exception as exc: # noqa: BLE001
bundle.errors.append(f"{name}:{type(exc).__name__}")
logger.debug("context.source.failed", source=name, error=str(exc))
return None
def _record_source(self, name: str) -> None:
# Sources are recorded on the bundle by the caller via the safe-wrap;
# this method exists for future per-source instrumentation hooks.
pass
# Module-level convenience for callers that just want a one-shot build.
async def build_context_bundle(state: Any, **kwargs: Any) -> ContextBundle:
"""Build a :class:`ContextBundle` for the given investigation state."""
builder = ContextBundleBuilder(**kwargs)
bundle = await builder.build(state)
# The fan-out itself never appends source names because the safe-wrap
# owns the success/failure path. Add them here so ``sources_called``
# always reflects what the builder actually attempted.
if not bundle.sources_called:
bundle.sources_called = sorted(["graph", "memory", "ueba", "threat_intel"])
return bundle