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
#!/usr/bin/env python3
"""The hunting agent must not be able to write a query.
Why this exists
---------------
A hunt is a question about a whole estate's history, and the hypothesis that
prompts one comes from an advisory, a ticket, or something a customer sent in.
All of those are attacker-influenceable, so a model relaying one into a query
language is one injected instruction away from an arbitrary read across every
row a tenant can see. A read at that scale exfiltrates telemetry and, on a
metered licence, costs money.
Phase 4 drew this boundary for the SIEM search and ``check_agent_read_tools.py``
keeps it. This is the same boundary for the hunting agent, and it is checked
the same way: **on the JSON schema the model is handed**, not on the validator
behind it. The schema is what actually constrains a model. A permissive schema
with a strict validator still lets the model spend a turn producing something
that gets rejected, and more importantly it means the only thing standing
between an injected instruction and a query is code somebody could relax
without noticing the schema already allowed it.
What it checks
--------------
``query-shaped-property``
A property the model can populate whose name suggests it carries query
text. The list is the one ``check_agent_read_tools.py`` uses, so the two
agent surfaces refuse the same vocabulary.
``unconstrained-string``
A property typed ``string`` with no ``enum`` where one is required. ``field``
and ``operator`` are the two that decide what the compiler does, and an
open string in either is a query language with extra steps.
``field-not-in-lake``
A field offered to the model that the ClickHouse DDL does not create. This
is the reachability rule the rest of this program keeps relearning: a plan
over a column nothing records returns zero while looking like it worked.
``vocabulary-drift``
The agents-side vocabulary and the API-side compiler disagree. The two
services package their code as a top-level ``app`` and cannot import each
other, so the sets are written twice and this reads both. A field the
agent may propose and the compiler refuses is a turn wasted on every run;
a field the compiler accepts and the agent never offers is dead surface.
``compiler-interpolates``
The compiler builds a predicate with an f-string carrying the *value*
rather than a placeholder. Read as source, because this is the one
property no amount of vocabulary checking substitutes for.
"""
from __future__ import annotations
import ast
import re
import sys
import types
from dataclasses import dataclass
from pathlib import Path
from gate_toolkit import repo_root, self_test_if_requested
self_test_if_requested(__file__)
_PLAN = Path("services/agents/app/hunt/plan.py")
_COMPILER = Path("services/api/app/services/retro_hunt/hunt_plan_sql.py")
_DDL = Path("services/api/clickhouse/001_init.sql")
_AGENT = Path("services/agents/app/hunt/agent.py")
REQUIRED = (_PLAN, _COMPILER, _DDL, _AGENT)
#: Property names that would mean the model is supplying query text. The same
#: vocabulary ``check_agent_read_tools.py`` refuses on the Phase 4 tools.
_QUERY_SHAPED = frozenset(
{
"query",
"search",
"spl",
"kql",
"esql",
"sql",
"free_text",
"freetext",
"filter",
"where",
"index",
"expression",
"statement",
"raw",
}
)
#: Properties that must be closed enums. These two decide what the compiler
#: emits; everything else is a bound value.
_MUST_BE_ENUM = ("field", "operator")
@dataclass
class Finding:
kind: str
detail: str
def __str__(self) -> str:
return f" [{self.kind}] {self.detail}"
def _load_plan_module(root: Path): # noqa: ANN202
"""Load ``plan.py`` by path, leaving ``sys.modules`` as it found it.
Registration is needed because ``@dataclass`` resolves annotations through
``sys.modules``; removal is needed because a synthetic name left behind
has previously broken 21 unrelated tests in this repository.
"""
import importlib.util # noqa: PLC0415
alias = "_aisoc_gate_hunt_plan"
created: list[str] = []
for name in ("app", "app.hunt"):
if name not in sys.modules:
module = types.ModuleType(name)
module.__path__ = [] # type: ignore[attr-defined]
sys.modules[name] = module
created.append(name)
spec = importlib.util.spec_from_file_location(alias, root / _PLAN)
if spec is None or spec.loader is None:
raise RuntimeError(f"cannot load {_PLAN}")
module = importlib.util.module_from_spec(spec)
sys.modules[alias] = module
try:
spec.loader.exec_module(module)
return module
finally:
sys.modules.pop(alias, None)
for name in created:
sys.modules.pop(name, None)
def _ddl_columns(root: Path) -> set[str]:
sql = (root / _DDL).read_text(encoding="utf-8")
match = re.search(r"CREATE TABLE IF NOT EXISTS aisoc\.raw_events\s*\((.*?)\n\)", sql, re.DOTALL)
if not match:
return set()
out: set[str] = set()
for line in match.group(1).splitlines():
stripped = line.strip().rstrip(",")
if not stripped or stripped.startswith(("--", "INDEX", "PRIMARY", "CONSTRAINT")):
continue
parts = stripped.split(None, 1)
if len(parts) == 2:
out.add(parts[0])
return out
def _compiler_sets(root: Path) -> tuple[set[str], set[str]]:
"""``(fields, operators)`` the API-side compiler accepts."""
tree = ast.parse((root / _COMPILER).read_text(encoding="utf-8"))
found: dict[str, set[str]] = {}
for node in ast.walk(tree):
if not isinstance(node, ast.Assign):
continue
names = [t.id for t in node.targets if isinstance(t, ast.Name)]
if not names:
continue
value = node.value
if isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id == "frozenset" and value.args:
value = value.args[0]
if isinstance(value, ast.Set | ast.List | ast.Tuple):
found[names[0]] = {e.value for e in value.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)}
return found.get("_FIELDS", set()), found.get("_OPERATORS", set())
def judge(root: Path) -> list[Finding]:
findings: list[Finding] = []
plan = _load_plan_module(root)
schema = plan.plan_json_schema()
clause_schema = schema.get("properties", {}).get("clauses", {}).get("items", {})
properties: dict = dict(schema.get("properties", {}))
properties.update(clause_schema.get("properties", {}))
for name in sorted(properties):
if name.lower() in _QUERY_SHAPED:
findings.append(
Finding(
"query-shaped-property",
f"the plan schema offers a property named {name!r}; a model can put query text in it",
)
)
for name in _MUST_BE_ENUM:
spec = clause_schema.get("properties", {}).get(name)
if spec is None:
findings.append(Finding("unconstrained-string", f"the clause schema has no {name!r} property at all"))
continue
if not spec.get("enum"):
findings.append(
Finding(
"unconstrained-string",
f"{name!r} is not a closed enum in the schema the model is handed; "
"an open string here is a query language with extra steps",
)
)
# Every property the model can populate must be a scalar. A nested object
# is structure a model can smuggle meaning into.
for name, spec in sorted(clause_schema.get("properties", {}).items()):
if spec.get("type") not in {"string", "integer"}:
findings.append(
Finding(
"unconstrained-string", f"clause property {name!r} is typed {spec.get('type')!r}; only string and integer are allowed"
)
)
ddl = _ddl_columns(root)
if not ddl:
return [Finding("unreadable", f"could not read the raw_events DDL from {_DDL}")]
agent_fields = set(plan.HUNT_FIELDS)
for name in sorted(agent_fields - ddl):
findings.append(
Finding(
"field-not-in-lake",
f"the agent may propose {name!r}, which the raw_events DDL does not create, "
"so a plan using it returns zero while looking like it worked",
)
)
compiler_fields, compiler_operators = _compiler_sets(root)
if not compiler_fields or not compiler_operators:
return [Finding("unreadable", f"could not read the accepted sets from {_COMPILER}")]
for name in sorted(agent_fields - compiler_fields):
findings.append(
Finding("vocabulary-drift", f"the agent may propose field {name!r} and the compiler refuses it; every such plan wastes a turn")
)
for name in sorted(compiler_fields - agent_fields):
findings.append(Finding("vocabulary-drift", f"the compiler accepts field {name!r} that the agent is never offered; dead surface"))
agent_operators = set(plan.HUNT_OPERATORS)
for name in sorted(agent_operators ^ compiler_operators):
findings.append(Finding("vocabulary-drift", f"operator {name!r} is accepted on one side of the boundary and not the other"))
# The one property no vocabulary check substitutes for.
compiler_source = (root / _COMPILER).read_text(encoding="utf-8")
for match in re.finditer(r'f"[^"]*\{value\}[^"]*"', compiler_source):
findings.append(Finding("compiler-interpolates", f"the compiler formats a value into a statement: {match.group(0)[:80]}"))
return findings
def _self_test() -> int:
from gate_toolkit import self_test_main # noqa: PLC0415
root = repo_root()
extra: list[tuple[str, bool]] = []
clean = judge(root)
extra.append(("the tree as committed has no findings", not clean))
for finding in clean:
print(f" {finding}")
plan = _load_plan_module(root)
schema = plan.plan_json_schema()
clause = schema["properties"]["clauses"]["items"]["properties"]
extra.append(("the schema's field property is a closed enum", bool(clause["field"].get("enum"))))
extra.append(("the schema's operator property is a closed enum", bool(clause["operator"].get("enum"))))
extra.append(
(
"no property the model can populate is named like query text",
not ({*schema["properties"], *clause} & _QUERY_SHAPED),
)
)
# The validator refuses what the schema forbids, proven by trying.
refused = 0
# Annotated on the tuple rather than the loop variable so the empty-clause
# case is inferred as the same list type as the others rather than as
# list[Never], which no annotation on `bad` alone can reconcile.
rejected: tuple[dict[str, list[dict[str, str]]], ...] = (
{"clauses": [{"field": "raw_payload", "operator": "contains", "value": "x"}]},
{"clauses": [{"field": "user_name", "operator": "regex", "value": ".*"}]},
{"clauses": [{"field": "user_name", "operator": "eq", "value": "x"}] * (plan.MAX_CLAUSES + 1)},
{"clauses": []},
)
for bad in rejected:
try:
plan.validate_plan(bad, hypothesis="probe")
except plan.HuntPlanError:
refused += 1
extra.append(("the validator refuses an out-of-vocabulary field, operator, an over-long plan and an empty one", refused == 4))
return self_test_main(Path(__file__).name, ["--check"], extra=extra)
def main(argv: list[str] | None = None) -> int:
args = list(argv if argv is not None else sys.argv[1:])
if "--self-test" in args:
return _self_test()
root = repo_root()
missing = [str(rel) for rel in REQUIRED if not (root / rel).exists()]
if missing:
print("check_hunt_agent_boundary: refusing to render a verdict — these files are missing:")
for path in missing:
print(f" {path}")
return 2
findings = judge(root)
if findings:
print(f"check_hunt_agent_boundary: {len(findings)} finding(s)\n")
for finding in findings:
print(finding)
print("\nA model that can name its own field or supply its own operator can compose a query,")
print("and the hypothesis it was given is attacker-influenceable text.")
return 1
plan = _load_plan_module(root)
print(
f"check_hunt_agent_boundary: OK — the model chooses from {len(plan.HUNT_FIELDS)} recorded fields and "
f"{len(plan.HUNT_OPERATORS)} operators, both closed enums in the schema it is handed, and every value it "
f"supplies is a bound parameter."
)
return 0
if __name__ == "__main__":
raise SystemExit(main())