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
"""Tests for the SOC Insights aggregator endpoint (T3.1).
The endpoint at ``/api/v1/insights/soc`` shapes a one-shot payload for the
SOC Insights dashboard: 7 tiles, each with a current value, a previous-
window comparison, an optional ``delta_pct``, and a 24-point sparkline.
The aggregation logic is a pure mix of SQLAlchemy aggregates plus the
named ``MANUAL_INVESTIGATION_MINUTES`` heuristic. We test it the same
way the rest of the API service tests its endpoint helpers — using a
``MagicMock`` ``AsyncSession`` whose ``scalar`` / ``execute`` return
canned values per call — so the suite stays fast and deterministic.
Coverage targets:
* ``_delta_pct`` — math + the "previous window had no data" branch
(``None`` rather than ``inf``).
* ``_window_to_timedelta`` — clamping to the {24h, 7d, 30d} allowlist.
* End-to-end shape of ``get_soc_insights`` against seeded numbers, so a
schema regression (renamed tile key, missing field, off-by-one in the
ordering) is caught here and not at runtime in the browser.
"""
from __future__ import annotations
import uuid
from datetime import UTC, datetime
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock
import pytest
from app.api.v1.endpoints.insights import (
MANUAL_INVESTIGATION_MINUTES,
SOCInsightsResponse,
_delta_pct,
_window_to_timedelta,
get_soc_insights,
)
from fastapi import HTTPException
# ---------------------------------------------------------------------------
# Pure helpers
# ---------------------------------------------------------------------------
def test_delta_pct_basic() -> None:
# 5 → 10 is +100%
assert _delta_pct(10.0, 5.0) == 100.0
def test_delta_pct_negative_change() -> None:
# 10 → 5 is -50%
assert _delta_pct(5.0, 10.0) == -50.0
def test_delta_pct_no_previous_data_returns_none() -> None:
"""Previous-window zero must be ``None`` (undefined), not infinity.
The UI renders ``None`` as an em-dash; an infinity here would
serialize as ``"Infinity"`` and corrupt JSON parsing on the client.
"""
assert _delta_pct(7.0, 0.0) is None
def test_delta_pct_no_change_is_zero() -> None:
assert _delta_pct(4.5, 4.5) == 0.0
def test_window_to_timedelta_accepts_24h() -> None:
assert _window_to_timedelta("24h").days == 1
def test_window_to_timedelta_accepts_7d() -> None:
assert _window_to_timedelta("7d").days == 7
def test_window_to_timedelta_accepts_30d() -> None:
assert _window_to_timedelta("30d").days == 30
def test_window_to_timedelta_rejects_unknown() -> None:
with pytest.raises(HTTPException) as exc_info:
_window_to_timedelta("1y")
assert exc_info.value.status_code == 400
# ---------------------------------------------------------------------------
# End-to-end endpoint shape
# ---------------------------------------------------------------------------
def _stub_user() -> SimpleNamespace:
"""Minimal ``CurrentUser`` stand-in (only ``tenant_id`` is read)."""
return SimpleNamespace(tenant_id=uuid.uuid4())
class _FakeMappings:
"""Cursor-shaped object that satisfies ``.first()`` and iteration."""
def __init__(self, rows: list[dict] | None = None) -> None:
self._rows = rows or []
def first(self): # noqa: D401 - mirror SQLAlchemy
return self._rows[0] if self._rows else None
def __iter__(self):
return iter(self._rows)
class _FakeResult:
"""Stand-in for ``Result`` exposing ``.all()``, ``.mappings()`` and ``.first()``.
``.first()`` was added when `_mean_hours` began selecting the mean and
its row count in one statement. The double lacking a method the real
``Result`` has is the failure mode this repository keeps finding in the
other direction — a fake *more* capable than the real object — and it
is worth noticing that the reverse also hides work: without it, a
handler using an ordinary SQLAlchemy API cannot be tested at all.
"""
def __init__(
self,
rows: list | None = None,
mappings: list[dict] | None = None,
first: tuple | None = None,
) -> None:
self._rows = rows or []
self._mappings = mappings or []
self._first = first
def all(self) -> list:
return self._rows
def mappings(self) -> _FakeMappings:
return _FakeMappings(self._mappings)
def first(self) -> tuple | None:
if self._first is not None:
return self._first
return self._rows[0] if self._rows else None
def _seeded_db(scalar_value: int = 5) -> MagicMock:
"""Build an AsyncSession-shaped mock that returns deterministic numbers.
The endpoint calls ``db.scalar`` and ``db.execute`` many times. We
return a *fresh* value each call so we can verify the response
builds without exception and that every tile is populated.
Numeric values are deliberately picked so the deltas are easy to
eyeball when the test fails — e.g. current = 10, previous = 5 →
+100%.
"""
db = MagicMock()
# Scalars (current values, then previous-window comparisons + counts).
# We return the same value for every call — the goal is to assert
# the tile shape, not the exact arithmetic. The hours-saved test
# uses a dedicated seed to exercise the heuristic specifically.
db.scalar = AsyncMock(return_value=scalar_value)
# ``execute`` is used three places:
# * sparkline alerts query → ``.all()`` of (timestamp,) tuples
# * sparkline cases query → ``.all()`` of (timestamp,) tuples
# * cost queries (text SQL) → ``.mappings().first()`` / iteration.
# Empty rows + empty mappings is the "nothing seeded" baseline.
async def _execute(*_args, **_kwargs):
return _FakeResult()
db.execute = AsyncMock(side_effect=_execute)
return db
@pytest.mark.asyncio
async def test_get_soc_insights_returns_seven_tiles_with_expected_keys() -> None:
"""The dashboard depends on a stable seven-tile shape — lock it in."""
db = _seeded_db()
user = _stub_user()
response = await get_soc_insights(user=user, db=db, window="24h")
assert isinstance(response, SOCInsightsResponse)
assert response.window == "24h"
assert response.manual_investigation_minutes == MANUAL_INVESTIGATION_MINUTES
assert response.tenant_id == user.tenant_id
assert isinstance(response.generated_at, datetime)
assert response.generated_at.tzinfo == UTC
keys = [tile.key for tile in response.tiles]
assert keys == [
"mtta",
"mttr",
"fp_rate",
"alerts_per_day",
"cases_per_day",
"agent_cost_per_investigation",
"analyst_hours_saved",
]
# Every tile must have a sparkline of exactly 24 points so the SVG
# renderer can rely on the bucket count without a runtime check.
for tile in response.tiles:
assert len(tile.sparkline.points) == 24
# Sparkline points are floats — the frontend formats them with
# ``Number(...)`` so an int would also pass, but locking the
# type prevents accidental Decimal leakage.
for point in tile.sparkline.points:
assert isinstance(point, int | float)
@pytest.mark.asyncio
async def test_get_soc_insights_hours_saved_uses_named_constant() -> None:
"""The hours-saved tile must derive its value from the named heuristic.
Operators expect to be able to tune ``MANUAL_INVESTIGATION_MINUTES``
in one place and have the number ripple through both the JSON
payload (so the docs/tooltip stay accurate) and the tile value.
"""
# Every scalar — including ``_count(... Case.status == 'resolved')``
# — returns 4. 4 auto-closed cases × 45 min = 180 min = 3.0 h saved.
db = _seeded_db(scalar_value=4)
user = _stub_user()
response = await get_soc_insights(user=user, db=db, window="24h")
hours_saved_tile = next(t for t in response.tiles if t.key == "analyst_hours_saved")
expected_hours = round((4 * MANUAL_INVESTIGATION_MINUTES) / 60.0, 2)
assert hours_saved_tile.value == expected_hours
assert hours_saved_tile.unit == "hours_saved"
@pytest.mark.asyncio
async def test_get_soc_insights_rejects_unknown_window() -> None:
"""Tenants can't sneak a 365-day scan past us via the query string."""
db = _seeded_db()
user = _stub_user()
with pytest.raises(HTTPException) as exc_info:
await get_soc_insights(user=user, db=db, window="1y") # type: ignore[arg-type]
assert exc_info.value.status_code == 400
@pytest.mark.asyncio
async def test_get_soc_insights_zero_state_renders_without_500() -> None:
"""Fresh tenant: no alerts, no cases — payload should still render.
The dashboard needs to render the day a tenant onboards, so a 500 or a
blank page is not acceptable. What *is* rendered changed, and the
distinction is the point of the test.
A counting tile with nothing to count is genuinely `0`: zero alerts
arrived, and that is a measurement. An **averaging** tile with nothing
to average publishes `0.0` *with a `sample_count` of 0*, and the pair
is the measurement — the count is what separates "responded instantly"
from "nobody responded".
The mean is deliberately not nullable: that is a breaking response
change for every generated client, and `/metrics/soc` already took
this decision for `mttd_sample_count`. The openapi-breaking gate
caught an earlier attempt here to make it null.
"""
db = _seeded_db(scalar_value=0)
user = _stub_user()
response = await get_soc_insights(user=user, db=db, window="7d")
assert response.window == "7d"
assert len(response.tiles) == 7
by_key = {t.key: t for t in response.tiles}
for key in ("mtta", "mttr"):
tile = by_key[key]
assert tile.sample_count == 0, f"{key} published no denominator, so a reader cannot tell an empty window from a real zero"
for tile in response.tiles:
# Nothing to compare against, so a delta would be invented.
assert tile.delta_pct is None