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
"""Business-context rules in the auto-triage hot path (Phase B4).
The leading AI-SOCs win a lot of their "80% noise reduction" from
*environment-specific* rules: suppress alerts during a known maintenance
window, bump severity for production assets, route cloud alerts to the cloud
team. AiSOC has a Business Context Rules **engine + authoring UI** in
``services/api``, but it was never applied on the live path — it only ran in a
dry-run preview. This module applies it post-fusion → pre-triage.
Placement: the auto-triage worker (``fused_alert_consumer.triage``) is exactly
the post-fusion → pre-triage seam. A **suppress** rule drops the alert before
any (possibly LLM) triage spend; **severity / route / tag** rules mutate the
alert the agent then reasons over.
Why a self-contained evaluator here rather than importing the API engine: the
agents service image ships only its own ``app/`` subtree, so it can't import
``services/api``. This module re-implements the same small, documented
``when`` (dotted-path + comparators + all/any/not) / ``then``
(set_severity / route_to / tag / suppress) semantics, loads rules from a YAML
file (``AISOC_BUSINESS_CONTEXT_RULES_FILE``), and is unit-tested against those
semantics. (Unifying both call sites behind a shared package is a follow-up.)
Everything is fail-soft: a missing/invalid rules file or a bad rule degrades to
"no business context applied", never an error into triage.
"""
from __future__ import annotations
import os
import time
import uuid
from dataclasses import dataclass
from dataclasses import field as dc_field
from pathlib import Path
from typing import Any
import structlog
import yaml
logger = structlog.get_logger()
_ALLOWED_SEVERITIES = {"info", "low", "medium", "high", "critical"}
#: Must match ``ALLOWED_ROUTES`` in
#: ``services/api/app/services/business_context/models.py``. Duplicated rather
#: than imported because the two services ship separate images, and kept in
#: lockstep by ``tests/test_business_context_not_clause.py``. The worker used
#: to accept any string here while the console validated against this set, so
#: the two halves of the same grammar disagreed.
_ALLOWED_ROUTES = frozenset(
{
"tier1",
"tier2",
"tier3",
"ic",
"cloud",
"identity",
"appsec",
"soc-night",
"soc-emea",
}
)
_ENABLED_ENV = "AISOC_BUSINESS_CONTEXT_ENABLED"
_RULES_FILE_ENV = "AISOC_BUSINESS_CONTEXT_RULES_FILE"
def is_enabled() -> bool:
"""Default-on; disable with AISOC_BUSINESS_CONTEXT_ENABLED=0."""
raw = os.environ.get(_ENABLED_ENV)
if raw is None:
return True
return raw.strip().lower() not in {"0", "false", "no", "off"}
# ── Rule model (faithful to services/api business_context) ────────────────────
@dataclass(frozen=True)
class RuleAction:
set_severity: str | None = None
route_to: str | None = None
tag: str | None = None
suppress: bool = False
@dataclass(frozen=True)
class RuleCondition:
field: str | None = None
op: str | None = None
value: Any = None
logical: str | None = None # "all" | "any" | "not"
children: tuple[RuleCondition, ...] = dc_field(default_factory=tuple)
@dataclass(frozen=True)
class BusinessContextRule:
id: str
when: RuleCondition
then: RuleAction
enabled: bool = True
priority: int = 100
def _dotted(alert: dict[str, Any], path: str) -> Any:
cur: Any = alert
for part in path.split("."):
if isinstance(cur, dict):
cur = cur.get(part)
else:
return None
return cur
def _cmp(op: str, actual: Any, expected: Any) -> bool: # noqa: PLR0911
try:
if op == "eq":
return actual == expected
if op == "ne":
return actual != expected
if op == "lt":
return actual < expected
if op == "lte":
return actual <= expected
if op == "gt":
return actual > expected
if op == "gte":
return actual >= expected
if op == "contains":
return expected in actual if actual is not None else False
if op == "startswith":
return isinstance(actual, str) and actual.startswith(str(expected))
if op == "endswith":
return isinstance(actual, str) and actual.endswith(str(expected))
if op == "in":
return actual in expected if isinstance(expected, list) else False
if op == "not_in":
return actual not in expected if isinstance(expected, list) else False
if op == "exists":
return actual is not None
if op == "not_exists":
return actual is None
except TypeError:
return False
return False
def evaluate_condition(cond: RuleCondition, alert: dict[str, Any]) -> bool:
if cond.logical == "all":
return all(evaluate_condition(c, alert) for c in cond.children)
if cond.logical == "any":
return any(evaluate_condition(c, alert) for c in cond.children)
if cond.logical == "not":
return not any(evaluate_condition(c, alert) for c in cond.children)
if cond.field and cond.op:
return _cmp(cond.op, _dotted(alert, cond.field), cond.value)
return False
def _parse_condition(node: Any) -> RuleCondition:
"""Parse one condition node.
``not`` takes a **mapping** — a single negated condition — which is what
the console's authoring grammar accepts and validates
(``services/api/app/services/business_context/models.py``). This parser
used to iterate every aggregator as a list, and iterating a mapping yields
its string keys, so ``_parse_condition("field")`` called ``.get()`` on a
``str`` and raised ``AttributeError``. That propagated into the caller's
catch, which set ``rules = []`` — so one console-accepted ``not`` rule
silently discarded the tenant's entire rule set at triage, suppressions
included, logged at ``warning``.
A list is still accepted for ``not`` and treated as "none of these", which
is what the old evaluator already did with the children it never managed
to build.
"""
if not isinstance(node, dict):
raise ValueError(f"condition must be a mapping, got {type(node).__name__}")
for logical in ("all", "any"):
if logical in node:
kids = node[logical] or []
if not isinstance(kids, list):
raise ValueError(f"'{logical}' must be a list of conditions, got {type(kids).__name__}")
return RuleCondition(logical=logical, children=tuple(_parse_condition(k) for k in kids))
if "not" in node:
negated = node["not"] or {}
kids = negated if isinstance(negated, list) else [negated]
return RuleCondition(logical="not", children=tuple(_parse_condition(k) for k in kids))
return RuleCondition(field=node.get("field"), op=node.get("op"), value=node.get("value"))
def load_rules_from_yaml(source: str) -> list[BusinessContextRule]:
"""Parse rules YAML (single mapping or top-level ``rules:`` list).
A rule that fails to parse is skipped and the rest are kept. It used to
raise, and the caller's catch turned that into ``rules = []`` — so one
malformed rule disabled every other rule the tenant had written,
suppressions included. The blast radius of a bad rule should be that rule.
"""
if not source or not source.strip():
return []
doc = yaml.safe_load(source)
if doc is None:
return []
raw_rules = doc.get("rules", doc) if isinstance(doc, dict) else doc
if isinstance(raw_rules, dict):
raw_rules = [raw_rules]
rules: list[BusinessContextRule] = []
seen: set[str] = set()
for entry in raw_rules or []:
if not isinstance(entry, dict) or "id" not in entry:
continue
rid = str(entry["id"])
if rid in seen:
continue
seen.add(rid)
action = entry.get("then") or {}
sev = action.get("set_severity")
if sev is not None and sev not in _ALLOWED_SEVERITIES:
sev = None
route = action.get("route_to")
if route is not None and route not in _ALLOWED_ROUTES:
# The console validates this; the worker did not, so a route the
# authoring grammar would have rejected could reach the hot path
# if the row was written by anything else.
logger.warning("business_context.rule_route_rejected", rule_id=rid, route_to=route)
route = None
try:
when = _parse_condition(entry.get("when") or {})
except (ValueError, AttributeError, TypeError) as exc:
logger.warning("business_context.rule_skipped", rule_id=rid, error=str(exc))
continue
rules.append(
BusinessContextRule(
id=rid,
when=when,
then=RuleAction(
set_severity=sev,
route_to=route,
tag=action.get("tag"),
suppress=bool(action.get("suppress", False)),
),
enabled=bool(entry.get("enabled", True)),
priority=int(entry.get("priority", 100)),
)
)
return rules
@dataclass
class BusinessContextResult:
alert: dict[str, Any]
matched_rule_ids: list[str]
suppressed: bool
severity_before: Any
severity_after: Any
@property
def changed(self) -> bool:
return self.suppressed or bool(self.matched_rule_ids)
def apply_rules(alert: dict[str, Any], rules: list[BusinessContextRule]) -> BusinessContextResult:
"""Apply enabled rules (priority order) to a copy of ``alert``.
Suppress short-circuits (once suppressed, downstream rules can't un-suppress),
matching the API engine's deterministic contract.
"""
out = dict(alert)
severity_before = out.get("severity")
matched: list[str] = []
for rule in sorted((r for r in rules if r.enabled), key=lambda r: (r.priority, r.id)):
if not evaluate_condition(rule.when, out):
continue
matched.append(rule.id)
act = rule.then
if act.set_severity is not None:
out["severity"] = act.set_severity
if act.route_to is not None:
out["route_to"] = act.route_to
if act.tag is not None:
tags = list(out.get("tags") or [])
if act.tag not in tags:
tags.append(act.tag)
out["tags"] = tags
if act.suppress:
out["__suppressed__"] = True
return BusinessContextResult(out, matched, True, severity_before, out.get("severity"))
return BusinessContextResult(out, matched, False, severity_before, out.get("severity"))
#: How long a tenant's rules are cached before re-reading Postgres. Business
#: context changes rarely and this sits on the hot path for every fused alert.
_TENANT_CACHE_TTL_SECONDS = 30.0
class BusinessContextApplier:
"""Applies business-context rules from Postgres, and from a YAML file.
Rules authored in the console are stored per tenant in
`aisoc_business_context_rule_sets`. This class only ever read a YAML file
whose path comes from `AISOC_BUSINESS_CONTEXT_RULES_FILE` — which nothing
sets — so a tenant could author a rule ("this host is a domain controller,
escalate anything touching it"), see it saved, preview it against their
last 50 alerts, and have it apply to no triage decision ever. The console
and the worker were looking at two different places.
The file path is kept as an operator-level override: an air-gapped install
that ships rules on disk should keep working, and its rules apply to every
tenant. Tenant rules are evaluated first, because a tenant's own statement
about their estate is more specific than a deployment-wide default.
"""
def __init__(self, rules_file: str | None = None) -> None:
self._path = rules_file or os.environ.get(_RULES_FILE_ENV, "")
self._rules: list[BusinessContextRule] = []
self._mtime: float | None = None
self._tenant_rules: dict[str, tuple[float, list[BusinessContextRule]]] = {}
#: Set by `seed_tenant_rules` for the replay path. When present, these
#: replace the Postgres read entirely -- see that method.
self._seeded_rules: list[BusinessContextRule] | None = None
self._load()
# ── tenant rules (Postgres) ───────────────────────────────────────────
async def _load_tenant_rules(self, tenant_id: str) -> list[BusinessContextRule]:
"""Read and cache the tenant's authored rules. Never raises."""
if self._seeded_rules is not None:
return self._seeded_rules
cached = self._tenant_rules.get(tenant_id)
now = time.monotonic()
if cached is not None and now - cached[0] < _TENANT_CACHE_TTL_SECONDS:
return cached[1]
dsn = os.environ.get("DATABASE_DSN") or os.environ.get("DATABASE_URL") or ""
dsn = dsn.strip().replace("postgresql+asyncpg://", "postgresql://")
if not dsn:
return []
try:
import asyncpg # noqa: PLC0415 — optional at import time
conn = await asyncpg.connect(dsn, timeout=5.0)
try:
row = await conn.fetchrow(
"""
SELECT yaml_text, enabled
FROM aisoc_business_context_rule_sets
WHERE tenant_id = $1
""",
uuid.UUID(tenant_id),
)
finally:
await conn.close()
except Exception as exc: # noqa: BLE001 — fail-soft: no tenant rules applied
logger.warning(
"business_context.tenant_load_failed",
tenant_id=tenant_id,
error=str(exc),
)
# Serve the last known rules rather than silently dropping a
# tenant's suppressions during a brief outage.
return cached[1] if cached else []
rules: list[BusinessContextRule] = []
if row is not None and row["enabled"] and row["yaml_text"]:
try:
rules = load_rules_from_yaml(row["yaml_text"])
except Exception as exc: # noqa: BLE001 — a bad rule set applies none
logger.warning(
"business_context.tenant_parse_failed",
tenant_id=tenant_id,
error=str(exc),
)
rules = []
self._tenant_rules[tenant_id] = (now, rules)
return rules
async def apply_for_tenant(self, tenant_id: str | None, alert: dict[str, Any]) -> BusinessContextResult:
"""Apply this tenant's authored rules, then any deployment-wide ones."""
self._load() # cheap mtime check on the file-based rules
tenant_rules = await self._load_tenant_rules(str(tenant_id)) if tenant_id else []
rules = [*tenant_rules, *self._rules]
if not rules:
return BusinessContextResult(dict(alert), [], False, alert.get("severity"), alert.get("severity"))
try:
return apply_rules(alert, rules)
except Exception as exc: # noqa: BLE001 — never break triage
logger.warning("business_context.apply_failed", error=str(exc))
return BusinessContextResult(dict(alert), [], False, alert.get("severity"), alert.get("severity"))
def clear_tenant_cache(self) -> None:
"""Drop cached tenant rules. Used by tests."""
self._tenant_rules.clear()
def seed_tenant_rules(self, rules: list[BusinessContextRule]) -> None:
"""Apply these rules to every tenant, instead of reading Postgres.
For the replay path (fix pass 3.1), which holds a rule set frozen at
the split point and must not re-read the live one: a read would
reintroduce an edit made after the window being graded, which is the
leakage the frozen context exists to prevent.
Seeded under a sentinel rather than per tenant id because a replay
runs one tenant at a time and the applier is constructed per run, so
there is no second tenant whose rules this could reach.
"""
self._seeded_rules = list(rules)
def _load(self) -> None:
if not self._path:
self._rules = []
return
try:
p = Path(self._path)
if not p.exists():
self._rules = []
return
mtime = p.stat().st_mtime
if mtime == self._mtime:
return
self._rules = load_rules_from_yaml(p.read_text(encoding="utf-8"))
self._mtime = mtime
logger.info("business_context.rules_loaded", count=len(self._rules), path=self._path)
except Exception as exc: # noqa: BLE001 — fail-soft: no rules applied
logger.warning("business_context.load_failed", error=str(exc), path=self._path)
self._rules = []
@property
def rule_count(self) -> int:
return len(self._rules)
def apply(self, alert: dict[str, Any]) -> BusinessContextResult:
self._load() # cheap mtime check; reload only when the file changed
if not self._rules:
return BusinessContextResult(dict(alert), [], False, alert.get("severity"), alert.get("severity"))
try:
return apply_rules(alert, self._rules)
except Exception as exc: # noqa: BLE001 — never break triage
logger.warning("business_context.apply_failed", error=str(exc))
return BusinessContextResult(dict(alert), [], False, alert.get("severity"), alert.get("severity"))