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
"""Gap-closure Phase 8.3: the API half of the hunting agent.
``services/agents`` decides what a model may *propose*. This decides what that
proposal *becomes*, and it is the only half that runs on the path reaching the
warehouse. The compiler says so itself: a boundary enforced only on the far
side of a network hop is not a boundary. So the agents-side suite proving the
vocabulary is closed proves nothing about this file, and these tests exist
because that suite passing is not evidence this one is safe.
``scripts/check_hunt_agent_boundary.py`` reads both files as source and fails
when the vocabularies drift or when a predicate interpolates a value. It
cannot tell whether the statement the compiler *runs* scopes to a tenant, puts
every model-supplied byte in a parameter, or reports an unreachable lake as a
gap rather than as zero sightings. Those are behaviours, and they are here.
"""
from __future__ import annotations
import uuid
from typing import Any
import pytest
from app.api.v1.deps import CurrentUser, get_current_user
from app.api.v1.endpoints import agent_tools
from app.services.retro_hunt.hunt_plan_sql import (
LAKE_TABLE,
MAX_ROWS,
HuntPlanCompileError,
compile_plan,
)
from fastapi import FastAPI
from fastapi.testclient import TestClient
TENANT = uuid.UUID("11111111-1111-1111-1111-111111111111")
OTHER_TENANT = "22222222-2222-2222-2222-222222222222"
USER = uuid.UUID("33333333-3333-3333-3333-333333333333")
def _clause(field: str, operator: str, value: str) -> dict[str, str]:
return {"field": field, "operator": operator, "value": value}
# ------------------------------------------------------------ tenant scoping
def test_the_tenant_predicate_is_generated_and_bound() -> None:
"""Structural, not rewritten in afterwards, and never interpolated.
``rewrite_for_tenant`` constrains SQL an operator wrote and cannot help a
caller who forgets to call it, which is how every fresh tenant once read
the same global figures off the funnel.
"""
compiled = compile_plan([_clause("user_name", "eq", "svc_deploy")], tenant_id=str(TENANT))
assert "tenant_id = %(tenant_id)s" in compiled.sql
assert compiled.params["tenant_id"] == str(TENANT)
assert str(TENANT) not in compiled.sql
def test_a_window_predicate_is_always_present() -> None:
"""A plan with no time bound is a full-history scan nobody budgeted for."""
compiled = compile_plan([_clause("user_name", "eq", "a")], tenant_id=str(TENANT))
assert "event_time >= now() - INTERVAL %(hours)s HOUR" in compiled.sql
assert compiled.params["hours"] == 168
# ------------------------------------------------------- values stay values
@pytest.mark.parametrize(
"hostile",
[
"'; DROP TABLE aisoc.raw_events; --",
"a' OR 1=1 --",
"\\' UNION ALL SELECT tenant_id FROM aisoc.raw_events --",
"%(tenant_id)s",
],
)
def test_a_value_shaped_like_sql_travels_as_a_parameter(hostile: str) -> None:
"""The value is the one thing a model fully controls.
A hypothesis can be lifted from an advisory or a customer email, so the
string reaching this function is attacker-influenceable even when the
field and operator are not.
"""
compiled = compile_plan([_clause("user_name", "eq", hostile)], tenant_id=str(TENANT))
benign = compile_plan([_clause("user_name", "eq", "benign")], tenant_id=str(TENANT))
# Compared against a benign compile rather than asserting the value is
# simply absent from the SQL: one of these payloads is `%(tenant_id)s`,
# which the compiler legitimately emits for its own tenant binding, so a
# bare `not in` would fail on a string the compiler put there itself.
# Identical SQL is the stronger claim anyway — whatever the value is, it
# does not reach the statement at all, only the parameter map.
assert compiled.sql == benign.sql
assert compiled.params["c0"] == hostile
def test_every_clause_gets_its_own_placeholder() -> None:
compiled = compile_plan(
[
_clause("user_name", "eq", "svc_deploy"),
_clause("process_name", "eq", "powershell.exe"),
_clause("dst_port", "gte", "1024"),
],
tenant_id=str(TENANT),
)
assert compiled.params["c0"] == "svc_deploy"
assert compiled.params["c1"] == "powershell.exe"
assert compiled.params["c2"] == 1024
assert compiled.fields_searched == ("user_name", "process_name", "dst_port")
def test_contains_cannot_smuggle_a_wildcard() -> None:
"""``position`` rather than ``LIKE``.
Under a ``LIKE`` a model-supplied ``%`` is a wildcard the analyst never
asked for, and the scan it provokes is charged to the customer.
"""
compiled = compile_plan([_clause("file_path", "contains", "%secret%")], tenant_id=str(TENANT))
assert "position(file_path, %(c0)s) > 0" in compiled.sql
assert "LIKE" not in compiled.sql.upper()
assert compiled.params["c0"] == "%secret%"
def test_an_address_is_normalised_the_way_the_writer_stored_it() -> None:
"""The lake holds an IPv4 address in its IPv4-mapped form.
Comparing the needle as text matches nothing, which reads as "not present"
rather than as "compared wrongly".
"""
compiled = compile_plan([_clause("source_ip", "eq", "203.0.113.9")], tenant_id=str(TENANT))
assert "source_ip = toIPv6(%(c0)s)" in compiled.sql
assert compiled.params["c0"] == "203.0.113.9"
def test_a_numeric_field_binds_a_number_rather_than_its_text() -> None:
compiled = compile_plan([_clause("severity_id", "gte", "4")], tenant_id=str(TENANT))
assert compiled.params["c0"] == 4
assert compiled.params["c0"] != "4"
# ------------------------------------------------------------- what it refuses
def test_a_field_outside_the_vocabulary_is_refused() -> None:
with pytest.raises(HuntPlanCompileError, match="raw_payload"):
compile_plan([_clause("raw_payload", "eq", "x")], tenant_id=str(TENANT))
def test_an_operator_outside_the_vocabulary_is_refused() -> None:
with pytest.raises(HuntPlanCompileError, match="regex"):
compile_plan([_clause("user_name", "regex", ".*")], tenant_id=str(TENANT))
def test_the_compiler_refuses_independently_of_the_agent_side_validator() -> None:
"""A clause the agents-side validator would have caught still gets caught.
The agents service cannot import this module and this module cannot import
it, so the two checks are genuinely independent. That is the point: a
caller reaching this route directly with a credential is not going through
the validator at all.
"""
with pytest.raises(HuntPlanCompileError):
compile_plan([_clause("mitre_techniques", "contains", "T1059")], tenant_id=str(TENANT))
with pytest.raises(HuntPlanCompileError):
compile_plan([_clause("source_ip", "starts_with", "203.")], tenant_id=str(TENANT))
def test_a_plan_with_no_clauses_is_refused_rather_than_matching_the_window() -> None:
with pytest.raises(HuntPlanCompileError, match="whole window"):
compile_plan([], tenant_id=str(TENANT))
def test_a_numeric_field_refuses_a_value_it_cannot_hold() -> None:
with pytest.raises(HuntPlanCompileError, match="not a number"):
compile_plan([_clause("dst_port", "eq", "eighty")], tenant_id=str(TENANT))
# -------------------------------------------------------------------- bounds
def test_the_row_cap_and_the_window_are_clamped_rather_than_trusted() -> None:
compiled = compile_plan(
[_clause("user_name", "eq", "a")],
tenant_id=str(TENANT),
lookback_hours=99_999,
limit=10_000,
)
assert f"LIMIT {MAX_ROWS}" in compiled.sql
assert compiled.params["hours"] == 2160
def test_the_projection_is_explicit() -> None:
"""Never ``SELECT *``.
It bounds warehouse cost, and it bounds how much connector-supplied text
reaches a prompt, which is the half that matters here.
"""
compiled = compile_plan([_clause("user_name", "eq", "a")], tenant_id=str(TENANT))
assert "SELECT *" not in compiled.sql
assert compiled.sql.startswith("SELECT event_time,")
assert f"FROM {LAKE_TABLE}" in compiled.sql
# --------------------------------------------------------------------- route
class _Result:
def __init__(self, columns: list[str], rows: list[tuple[Any, ...]]) -> None:
self.columns = columns
self.rows = rows
def _app(user: CurrentUser | None = None) -> FastAPI:
app = FastAPI()
# `/api/v1` only: the router already declares `prefix="/agent-tools"`, so
# repeating it here mounted everything a level deeper than production and
# every request in this file 404'd. This mirrors what router.py does.
app.include_router(agent_tools.router, prefix="/api/v1")
app.dependency_overrides[get_current_user] = lambda: user or _agent_user()
return app
def _agent_user() -> CurrentUser:
return CurrentUser(
user_id=USER,
tenant_id=TENANT,
role="analyst",
email="[email protected]",
scopes=["lake:query"],
)
def test_the_tenant_comes_from_the_credential_and_not_from_the_body(monkeypatch: pytest.MonkeyPatch) -> None:
"""There is no tenant field on the request model, and a smuggled one is dropped.
``additionalProperties`` is not the control here; the control is that the
only tenant this route can reach is the one the credential resolved.
"""
seen: dict[str, Any] = {}
async def _fake(sql: str, **kwargs: Any) -> _Result:
seen["sql"] = sql
seen["params"] = kwargs.get("params")
return _Result(["event_time"], [])
monkeypatch.setattr(agent_tools, "execute_lake_query", _fake)
response = TestClient(_app()).post(
"/api/v1/agent-tools/hunt-plan/execute",
json={
"clauses": [_clause("user_name", "eq", "svc_deploy")],
"tenant_id": OTHER_TENANT,
},
)
assert response.status_code == 200
assert seen["params"]["tenant_id"] == str(TENANT)
assert OTHER_TENANT not in seen["sql"]
assert OTHER_TENANT not in str(seen["params"])
def test_a_refused_clause_is_a_422_with_the_reason(monkeypatch: pytest.MonkeyPatch) -> None:
"""Not an empty result.
A model that reads "your clause was wrong" as "nothing matched" reports an
estate clean on a question nobody asked the warehouse.
"""
async def _never(*_args: Any, **_kwargs: Any) -> _Result:
raise AssertionError("the lake must not be queried when the plan was refused")
monkeypatch.setattr(agent_tools, "execute_lake_query", _never)
response = TestClient(_app()).post(
"/api/v1/agent-tools/hunt-plan/execute",
json={"clauses": [_clause("raw_payload", "eq", "x")]},
)
assert response.status_code == 422
assert "raw_payload" in response.json()["detail"]
@pytest.mark.parametrize(
("raised", "because"),
[
(agent_tools.LakeQueryNotConfiguredError, "No event lake is configured"),
(agent_tools.LakeQueryTimeoutError, "time budget"),
(agent_tools.LakeQueryError, "refused or failed"),
],
)
def test_a_lake_that_could_not_answer_is_a_gap_and_not_zero_findings(
monkeypatch: pytest.MonkeyPatch,
raised: type[Exception],
because: str,
) -> None:
"""Three outcomes, kept apart: findings, no findings, could not check.
The response carries no ``rows`` key at all in this branch, so a caller
reading ``rows`` without checking ``available`` gets a KeyError rather
than an empty list it would report as a clean estate.
"""
async def _fail(*_args: Any, **_kwargs: Any) -> _Result:
raise raised("boom")
monkeypatch.setattr(agent_tools, "execute_lake_query", _fail)
body = (
TestClient(_app())
.post(
"/api/v1/agent-tools/hunt-plan/execute",
json={"clauses": [_clause("user_name", "eq", "a")]},
)
.json()
)
assert body["available"] is False
assert because in body["reason"]
assert "NOT" in body["reason"]
assert "rows" not in body
def test_rows_come_back_keyed_by_the_projection(monkeypatch: pytest.MonkeyPatch) -> None:
async def _rows(*_args: Any, **_kwargs: Any) -> _Result:
return _Result(["event_time", "user_name"], [("2026-09-01T00:00:00Z", "svc_deploy")])
monkeypatch.setattr(agent_tools, "execute_lake_query", _rows)
body = (
TestClient(_app())
.post(
"/api/v1/agent-tools/hunt-plan/execute",
json={"clauses": [_clause("user_name", "eq", "svc_deploy")]},
)
.json()
)
assert body["available"] is True
assert body["row_count"] == 1
assert body["rows"] == [{"event_time": "2026-09-01T00:00:00Z", "user_name": "svc_deploy"}]
assert body["fields_searched"] == ["user_name"]
assert body["truncated"] is False
def test_a_full_page_is_reported_as_truncated(monkeypatch: pytest.MonkeyPatch) -> None:
"""Otherwise a capped hunt reads as an exhaustive one."""
async def _rows(*_args: Any, **_kwargs: Any) -> _Result:
return _Result(["user_name"], [("u",), ("v",)])
monkeypatch.setattr(agent_tools, "execute_lake_query", _rows)
body = (
TestClient(_app())
.post(
"/api/v1/agent-tools/hunt-plan/execute",
json={"clauses": [_clause("user_name", "eq", "u")], "limit": 2},
)
.json()
)
assert body["truncated"] is True
def test_the_route_refuses_a_caller_without_the_lake_permission() -> None:
"""``lake:query``, the permission the operator-facing lake API already uses."""
unscoped = CurrentUser(
user_id=USER,
tenant_id=TENANT,
role="analyst",
email="[email protected]",
scopes=["alerts:read"],
)
response = TestClient(_app(unscoped)).post(
"/api/v1/agent-tools/hunt-plan/execute",
json={"clauses": [_clause("user_name", "eq", "a")]},
)
assert response.status_code == 403