ti2dac 0.1.0__py3-none-any.whl

ti2dac/__init__.py

@@ -0,0 +1,3 @@
+"""ti2dac - Threat Intelligence to Detection-as-Code."""
+
+__version__ = "0.1.0"

ti2dac/aistatus.py

@@ -0,0 +1,169 @@
+"""AI provider health: limit detection, circuit breaker and request counting.
+
+Shared by the CLI and the web UI through <state_dir>/ai_status.json, so that once a provider says
+"quota exhausted" (or our own daily cap is reached) NO process sends further requests until the reset
+time. Hammering a provider after it refused is wasteful and can look like abuse to the provider.
+
+States per provider:
+  ok               last call succeeded
+  rate_limited     short-term limit (per-minute); calls resume after retry_at
+  quota_exhausted  daily/monthly quota, credit or spend limit; calls blocked until retry_at (or manual reset)
+  daily_cap        our own `ai.daily_request_limit` reached; resets at local midnight
+  auth_error       key missing/invalid; blocked until reset
+  refused          the model declined a request (informational; does not block)
+  unavailable      provider down/overloaded after retries (informational; does not block)
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from .locks import file_lock
+
+BLOCKING = {"rate_limited", "quota_exhausted", "daily_cap", "auth_error"}
+DAILY_COUNTERS = ("requests_today", "input_tokens_today", "output_tokens_today", "cache_read_tokens_today", "cost_today_usd")
+TOTAL_COUNTERS = ("input_tokens_total", "output_tokens_total", "cost_total_usd")
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _path(state_dir: str | Path) -> Path:
+    return Path(state_dir) / "ai_status.json"
+
+
+def _locked(state_dir: str | Path):
+    """Read-modify-write of ai_status.json: the server, its job workers and the CLI all count requests."""
+    return file_lock(Path(state_dir) / "ai_status.lock")
+
+
+def load(state_dir: str | Path) -> dict:
+    try:
+        return json.loads(_path(state_dir).read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def _save(state_dir: str | Path, data: dict) -> None:
+    p = _path(state_dir)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(f".{os.getpid()}.tmp")
+    tmp.write_text(json.dumps(data, indent=1))
+    tmp.replace(p)
+
+
+def provider_status(state_dir: str | Path, provider: str) -> dict:
+    s = load(state_dir).get(provider, {})
+    today = datetime.now().date().isoformat()
+    if s.get("day") != today:
+        s = {**s, "day": today, **{k: 0 for k in DAILY_COUNTERS}}
+        if s.get("state") == "daily_cap":
+            s["state"] = "ok"
+    return s
+
+
+def update(state_dir: str | Path, provider: str, **fields) -> dict:
+    with _locked(state_dir):
+        data = load(state_dir)
+        cur = provider_status(state_dir, provider) if provider in data else {
+            "day": datetime.now().date().isoformat(), "requests_today": 0}
+        cur.update(fields)
+        cur["updated_at"] = _now().isoformat(timespec="seconds")
+        data[provider] = cur
+        _save(state_dir, data)
+        return cur
+
+
+def count_request(state_dir: str | Path, provider: str) -> int:
+    with _locked(state_dir):
+        data = load(state_dir)
+        cur = provider_status(state_dir, provider)
+        cur["requests_today"] = int(cur.get("requests_today", 0)) + 1
+        data[provider] = cur
+        _save(state_dir, data)
+        return cur["requests_today"]
+
+
+def add_usage(state_dir: str | Path, provider: str, input_tokens: int, output_tokens: int,
+              cache_read_tokens: int, cost_usd: float) -> None:
+    """Token accounting per provider: today (resets at local midnight) and since the state dir was created."""
+    with _locked(state_dir):
+        data = load(state_dir)
+        cur = provider_status(state_dir, provider)
+        for key, val in (("input_tokens", input_tokens), ("output_tokens", output_tokens)):
+            cur[f"{key}_today"] = int(cur.get(f"{key}_today", 0)) + val
+            cur[f"{key}_total"] = int(cur.get(f"{key}_total", 0)) + val
+        cur["cache_read_tokens_today"] = int(cur.get("cache_read_tokens_today", 0)) + cache_read_tokens
+        cur["cost_today_usd"] = round(float(cur.get("cost_today_usd", 0)) + cost_usd, 4)
+        cur["cost_total_usd"] = round(float(cur.get("cost_total_usd", 0)) + cost_usd, 4)
+        data[provider] = cur
+        _save(state_dir, data)
+
+
+def record_ok(state_dir: str | Path, provider: str) -> None:
+    update(state_dir, provider, state="ok", message="", retry_at="", last_success=_now().isoformat(timespec="seconds"))
+
+
+def record_block(state_dir: str | Path, provider: str, state: str, message: str, retry_after_s: float | None) -> None:
+    retry_at = (_now() + timedelta(seconds=retry_after_s)).isoformat(timespec="seconds") if retry_after_s else ""
+    update(state_dir, provider, state=state, message=message[:500], retry_at=retry_at)
+
+
+def reset(state_dir: str | Path, provider: str | None = None) -> None:
+    with _locked(state_dir):
+        data = load(state_dir)
+        for name in ([provider] if provider else list(data)):
+            if name in data:
+                data[name].update(state="ok", message="", retry_at="")
+        _save(state_dir, data)
+
+
+def block_reason(state_dir: str | Path, provider: str, daily_limit: int = 0) -> str:
+    """Why calls to `provider` are blocked right now ('' = allowed). Never contacts the provider."""
+    s = provider_status(state_dir, provider)
+    state = s.get("state", "ok")
+    if daily_limit and int(s.get("requests_today", 0)) >= daily_limit:
+        return (f"{provider}: daily request cap reached ({s.get('requests_today')}/{daily_limit}, "
+                "ai.daily_request_limit). Resets at local midnight, or raise the cap.")
+    if state not in BLOCKING:
+        return ""
+    retry_at = s.get("retry_at", "")
+    if retry_at:
+        try:
+            if datetime.fromisoformat(retry_at) <= _now():
+                return ""                       # the provider's own reset time has passed
+        except ValueError:
+            pass
+    elif state == "rate_limited":
+        return ""
+    when = f" Retry after {retry_at} (UTC)." if retry_at else " Fix the cause, then reset with `ti2dac ai-status --reset` or the AI page."
+    return f"{provider}: {state.replace('_', ' ')}. {s.get('message', '')}".strip() + when
+
+
+def human_wait(retry_at: str) -> str:
+    try:
+        secs = (datetime.fromisoformat(retry_at) - _now()).total_seconds()
+    except (ValueError, TypeError):
+        return ""
+    if secs <= 0:
+        return "now"
+    h, m = int(secs // 3600), int(secs % 3600 // 60)
+    return f"{h}h {m}m" if h else f"{m}m"
+
+
+def key_status(provider: str) -> str:
+    """Where credentials would come from (never the key itself)."""
+    if provider == "gemini":
+        for var in ("GEMINI_API_KEY", "GOOGLE_API_KEY"):
+            if os.environ.get(var):
+                return f"{var} is set"
+        return "not configured"
+    for var in ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"):
+        if os.environ.get(var):
+            return f"{var} is set"
+    if os.environ.get("ANTHROPIC_PROFILE") or (Path.home() / ".config" / "anthropic").is_dir():
+        return "`ant auth login` profile found"
+    return "not configured"

ti2dac/attack.py

@@ -0,0 +1,169 @@
+"""MITRE ATT&CK lookups, mapping validation and Navigator layer export.
+
+The full STIX bundle is ~55 MB; we ship a compact index (id -> name/tactics/flags) built
+from it. Refresh with ``ti2dac attack-update`` (writes to the state dir, which overrides
+the bundled copy).
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+import httpx
+
+STIX_URL = "https://raw.githubusercontent.com/mitre-attack/attack-stix-data/master/enterprise-attack/enterprise-attack.json"
+_BUNDLED = Path(__file__).parent / "data" / "attack_index.json"
+_OVERRIDE: Path | None = None
+
+
+def set_override_dir(state_dir: str | Path) -> None:
+    global _OVERRIDE
+    _OVERRIDE = Path(state_dir) / "attack_index.json"
+    load_index.cache_clear()
+    _successor_map.cache_clear()
+
+
+def build_index(stix: dict) -> dict:
+    techniques: dict[str, dict] = {}
+    version = ""
+    stix_ids: dict[str, str] = {}      # STIX id -> ATT&CK id, for revoked-by relationships
+    revoked_by: dict[str, str] = {}    # STIX id -> STIX id
+    for obj in stix.get("objects", []):
+        if obj.get("type") == "relationship" and obj.get("relationship_type") == "revoked-by":
+            revoked_by[obj.get("source_ref", "")] = obj.get("target_ref", "")
+        if obj.get("type") == "x-mitre-collection":
+            version = obj.get("x_mitre_version", version)
+        if obj.get("type") != "attack-pattern":
+            continue
+        ext = next((r for r in obj.get("external_references", []) if r.get("source_name") == "mitre-attack"), None)
+        if not ext:
+            continue
+        stix_ids[obj.get("id", "")] = ext["external_id"]
+        techniques[ext["external_id"]] = {
+            "name": obj.get("name", ""),
+            "tactics": [p["phase_name"] for p in obj.get("kill_chain_phases", []) if p.get("kill_chain_name") == "mitre-attack"],
+            "platforms": obj.get("x_mitre_platforms", []),
+            "deprecated": bool(obj.get("x_mitre_deprecated")),
+            "revoked": bool(obj.get("revoked")),
+        }
+    for src, dst in revoked_by.items():
+        if src in stix_ids and dst in stix_ids:
+            techniques[stix_ids[src]]["revoked_by"] = stix_ids[dst]
+    return {"attack_version": version, "techniques": techniques}
+
+
+def update_index(dest_dir: str | Path, source: str | None = None) -> Path:
+    if source and Path(source).is_file():
+        stix = json.loads(Path(source).read_text())
+    else:
+        r = httpx.get(source or STIX_URL, timeout=120, follow_redirects=True)
+        r.raise_for_status()
+        stix = r.json()
+    dest = Path(dest_dir) / "attack_index.json"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(json.dumps(build_index(stix), separators=(",", ":"), sort_keys=True))
+    load_index.cache_clear()
+    _successor_map.cache_clear()
+    return dest
+
+
+@lru_cache(maxsize=1)
+def load_index() -> dict:
+    for p in (_OVERRIDE, _BUNDLED):
+        if p and p.is_file():
+            return json.loads(p.read_text())
+    return {"attack_version": "", "techniques": {}}
+
+
+def lookup(tid: str) -> dict | None:
+    return load_index()["techniques"].get(tid.upper())
+
+
+def resolve_revoked(tid: str) -> tuple[str, str]:
+    """(current id, note) for a revoked technique: its revoked-by successor, or else the one live technique with the
+    same name (ATT&CK v20 moved e.g. T1562.001 "Disable or Modify Tools" to T1685 under defense-impairment).
+    Unchanged id and '' when the technique is live, unknown, or has no clear successor."""
+    idx = load_index()["techniques"]
+    t = idx.get(tid.upper())
+    if not t or not t.get("revoked"):
+        return tid, ""
+    new = t.get("revoked_by")
+    if not (new and new in idx and not idx[new]["revoked"] and not idx[new]["deprecated"]):
+        same = [k for k, v in idx.items() if k != tid.upper() and not v["revoked"] and not v["deprecated"]
+                and v["name"].lower() == t["name"].lower()]
+        new = same[0] if len(same) == 1 else None
+    if not new:
+        return tid, ""
+    return new, f"{tid} is revoked in ATT&CK; replaced by {new} ({idx[new]['name']})"
+
+
+def predecessors(tid: str) -> list[str]:
+    """Revoked techniques whose successor is `tid` (T1685 -> ['T1562.001']): lessons and history recorded under
+    the old id still apply to the new one."""
+    return _successor_map().get(tid.upper(), [])
+
+
+@lru_cache(maxsize=1)
+def _successor_map() -> dict[str, list[str]]:
+    out: dict[str, list[str]] = {}
+    for k, v in load_index()["techniques"].items():
+        if v.get("revoked"):
+            new, _ = resolve_revoked(k)
+            if new != k:
+                out.setdefault(new, []).append(k)
+    return out
+
+
+def validate_mapping(tid: str, name: str, tactic: str) -> tuple[bool, str, str, str]:
+    """Returns (valid, note, corrected_name, corrected_tactic)."""
+    idx = load_index()["techniques"]
+    if not idx:
+        return True, "ATT&CK index unavailable; mapping not verified", name, tactic
+    t = idx.get(tid.upper())
+    if t is None:
+        parent = idx.get(tid.split(".")[0].upper())
+        if parent:
+            return False, f"{tid} does not exist; parent {tid.split('.')[0]} ({parent['name']}) does", name, tactic
+        return False, f"{tid} is not an ATT&CK Enterprise technique", name, tactic
+    notes = []
+    if t["revoked"] or t["deprecated"]:
+        notes.append(f"{tid} is {'revoked' if t['revoked'] else 'deprecated'} in ATT&CK")
+    if tactic not in t["tactics"] and t["tactics"]:
+        notes.append(f"tactic '{tactic}' not listed for {tid}; using '{t['tactics'][0]}'")
+        tactic = t["tactics"][0]
+    if t["name"].lower() not in name.lower():
+        name = t["name"]
+    return not (t["revoked"] or t["deprecated"]), "; ".join(notes), name, tactic
+
+
+def navigator_layer(name: str, description: str, techniques: list[dict]) -> dict:
+    """techniques: [{id, tactic, comment, score}]"""
+    return {
+        "name": name[:120],
+        "versions": {"attack": load_index().get("attack_version") or "17", "navigator": "5.1.0", "layer": "4.5"},
+        "domain": "enterprise-attack",
+        "description": description[:500],
+        "sorting": 3,
+        "hideDisabled": False,
+        "techniques": [
+            {
+                "techniqueID": t["id"],
+                "tactic": t["tactic"],
+                "score": t.get("score", 1),
+                "color": "",
+                "comment": t.get("comment", ""),
+                "enabled": True,
+                "showSubtechniques": True,
+            }
+            for t in techniques
+        ],
+        "gradient": {"colors": ["#ffe766", "#ff6666"], "minValue": 0, "maxValue": 3},
+        "legendItems": [
+            {"label": "Detection generated (draft)", "color": "#ffe766"},
+            {"label": "Detection validated in lab", "color": "#ff6666"},
+        ],
+        "showTacticRowBackground": True,
+        "tacticRowBackground": "#205b8f",
+        "selectSubtechniquesWithParent": False,
+    }

ti2dac/chains.py

@@ -0,0 +1,211 @@
+"""Multi-event detections ("brute force, then a successful logon, then a new scheduled task within 10 minutes").
+
+Language models are reliable at single-event logic and unreliable at stateful joins, so the join is never
+written by the model: each step is an already generated (and validated) single-event rule, and this module
+joins them with a Sigma correlation rule (temporal / temporal_ordered) and, where a pySigma backend cannot
+convert that, with a fixed per-language template (KQL union + summarize, EQL sequence).
+"""
+from __future__ import annotations
+
+import uuid
+
+from . import sigma_tools as st
+from .correlate import HOST_COLUMN, KQL_TARGETS
+from .models import ChainPackage, DetectionPackage, QueryResult
+from .targets import TARGETS, make_backend
+
+_TIME_COLUMN = {"defender_xdr": "Timestamp"}
+
+
+def join_field(base_doc: dict, join_on: str) -> str:
+    """The Sigma field carrying the host / user / source IP for a rule's log source."""
+    ls = base_doc.get("logsource") or {}
+    product, category, service = ls.get("product", ""), ls.get("category", ""), ls.get("service", "")
+    if join_on == "host":
+        return "Computer" if product == "windows" else "Hostname"
+    if join_on == "user":
+        if product == "windows" and service in ("security", "system"):
+            return "TargetUserName"
+        return "User"
+    if category == "firewall":
+        return "src_ip"
+    if category in ("webserver", "proxy"):
+        return "c-ip"
+    if product == "windows" and service == "security":
+        return "IpAddress"
+    return "SourceIp"
+
+
+def _name(slug: str) -> str:
+    return "ti2dac_" + slug.replace("-", "_")
+
+
+def build_yaml(steps: list[DetectionPackage], *, name: str, ordered: bool, within: str, join_on: str,
+               author: str) -> tuple[str, list[dict], list[str], list[str]]:
+    """(rule YAML, step base docs, step join fields, warnings)."""
+    docs, fields, warnings = [], [], []
+    for p in steps:
+        base = dict(st.first_doc(p.rule_yaml))
+        if len(st.load_docs(p.rule_yaml)) > 1:
+            warnings.append(f"{p.slug} is a threshold rule; the chain uses its single event, not its threshold")
+        base["name"] = _name(p.slug)
+        base["level"] = "informational"   # each step alone is context; the chain is the alert
+        docs.append(base)
+        fields.append(join_field(base, join_on))
+    key = "|".join(p.rule_id for p in steps) + f"|{within}|{join_on}|{ordered}"
+    corr = {
+        "title": f"{name} (sequence)",
+        "id": str(uuid.uuid5(st.RULE_NAMESPACE, "chain:" + key)),
+        "status": "experimental",
+        "description": f"{' then '.join(p.draft.sigma.title for p in steps)}, on the same {join_on.replace('_', ' ')} "
+                       f"within {within}. Built by ti2dac from separately validated rules.",
+        "author": author,
+        "tags": sorted({t for d in docs for t in d.get("tags") or []}),
+        "correlation": {
+            "type": "temporal_ordered" if ordered else "temporal",
+            "rules": [d["name"] for d in docs],
+            "group-by": ["ti2dac_join"],
+            "timespan": within,
+            "aliases": {"ti2dac_join": {d["name"]: f for d, f in zip(docs, fields)}},
+        },
+        "falsepositives": ["Each step alone is common; review the combination"],
+        "level": "high",
+    }
+    return st.dump_docs([*docs, corr]), docs, fields, warnings
+
+
+def _kql(target: str, step_queries: list[str], keys: list[str], ordered: bool, within: str) -> tuple[str, str]:
+    t = _TIME_COLUMN.get(target, "TimeGenerated")
+    lets = [f"let Step{i} = {q}\n| extend JoinKey = tostring({k}), Step = {i};"
+            for i, (q, k) in enumerate(zip(step_queries, keys), 1)]
+    n = len(step_queries)
+    aggs = ["Steps = dcount(Step)", f"FirstSeen = min({t})", f"LastSeen = max({t})"]
+    where = [f"Steps == {n}"]
+    note = "Built by ti2dac (deterministic template, not AI). Fixed time bins: run every half-window."
+    if ordered:
+        aggs += [f"First{i} = minif({t}, Step == {i}), Last{i} = maxif({t}, Step == {i})" for i in range(1, n + 1)]
+        where += [f"First{i} <= Last{i + 1}" for i in range(1, n)]
+        note += " Order check is approximate (the first step i is before the last step i+1)."
+    q = "\n".join(lets) + f"\nunion {', '.join(f'Step{i}' for i in range(1, n + 1))}\n" \
+        f"| summarize {', '.join(aggs)} by JoinKey, bin({t}, {within})\n| where {' and '.join(where)}"
+    return q, note
+
+
+def _spl(step_queries: list[str], keys: list[str], ordered: bool, within: str) -> tuple[str, str]:
+    subs = "\n".join(f"    [search {q} | eval step={i}, join_key={k}]" for i, (q, k) in enumerate(zip(step_queries, keys), 1))
+    n = len(step_queries)
+    aggs = ["dc(step) as steps", "min(_time) as first_seen", "max(_time) as last_seen"]
+    where = [f"steps={n}"]
+    note = "Built by ti2dac (deterministic template, not AI). Fixed time bins: run every half-window."
+    if ordered:
+        aggs += [f"min(eval(if(step={i}, _time, null()))) as first{i} max(eval(if(step={i}, _time, null()))) as last{i}"
+                 for i in range(1, n + 1)]
+        where += [f"first{i}<=last{i + 1}" for i in range(1, n)]
+        note += " Order check is approximate (the first step i is before the last step i+1)."
+    q = (f"| multisearch\n{subs}\n| bin _time span={within}\n| stats {' '.join(aggs)} by join_key _time\n"
+         f"| where {' AND '.join(where)}")
+    return q, note
+
+
+def _esql(step_queries: list[str], keys: list[str], ordered: bool, within: str) -> tuple[str, str]:
+    import re
+
+    conds, sources = [], []
+    for q in step_queries:
+        m = re.fullmatch(r"(?s)\s*from\s+(\S+)(?:\s+metadata\s+[\w, ]+?)?\s*\|\s*where\s+(.+)", q)
+        if not m or "|" in m.group(2):
+            raise ValueError("unexpected ES|QL query shape")
+        sources.append(m.group(1))
+        conds.append(m.group(2).strip())
+    unit = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days"}[within[-1]]
+    step = "case(" + ", ".join(f"{c}, {i}" for i, c in enumerate(conds, 1)) + ")"
+    key = "case(" + ", ".join(f"step == {i}, {k}" for i, k in enumerate(keys, 1)) + ")"
+    source = ",".join(dict.fromkeys(x for s in sources for x in s.split(",")))   # every step's index pattern
+    q = (f"from {source} metadata _id, _index\n| where {' or '.join(f'({c})' for c in conds)}\n"
+         f"| eval step = {step}\n| eval join_key = {key}, timebucket = date_trunc({within[:-1]} {unit}, @timestamp)\n"
+         f"| stats steps = count_distinct(step), first_seen = min(@timestamp), last_seen = max(@timestamp) by timebucket, join_key\n"
+         f"| where steps == {len(conds)}")
+    note = "Built by ti2dac (deterministic template, not AI). Fixed time bins: run every half-window."
+    if ordered:
+        note += " Step order is not enforced here; use the EQL version for an ordered sequence."
+    return q, note
+
+
+def _eql(step_queries: list[str], keys: list[str], ordered: bool, within: str) -> tuple[str, str]:
+    body = "\n".join(f"  [{q}] by {k}" for q, k in zip(step_queries, keys))
+    note = "Built by ti2dac (deterministic template, not AI)."
+    if not ordered:
+        note += " EQL sequences are ordered; the steps are in report order."
+    return f"sequence with maxspan={within}\n{body}", note
+
+
+_TEMPLATES = {**{t: None for t in KQL_TARGETS}, "elastic_eql": _eql, "splunk": _spl, "elastic_esql": _esql}
+
+
+def queries(rule_yaml: str, docs: list[dict], fields: list[str], join_on: str, ordered: bool, within: str,
+            target_ids: list[str], client=None, index_overrides: dict[str, str] | None = None) -> list[QueryResult]:
+    from sigma.collection import SigmaCollection
+
+    out = []
+    product = (docs[0].get("logsource") or {}).get("product", "")
+    for tid in target_ids:
+        t = TARGETS.get(tid)
+        if t is None:
+            continue
+        res = QueryResult(target=tid, label=t.label, language=t.language, method="pysigma",
+                          client=client.name if client is not None else "")
+        try:   # 1. the backend's own correlation support
+            q = make_backend(t, product, client).convert(SigmaCollection.from_yaml(rule_yaml))
+            res.query = (q if isinstance(q, str) else "\n".join(map(str, q))).strip() or None
+            if res.query:
+                res.query = st.apply_index_override(tid, res.query, (index_overrides or {}).get(tid, ""))
+            if res.query:
+                out.append(res)
+                continue
+        except Exception as e:
+            res.error = st._short_error(e)
+        if tid not in _TEMPLATES:
+            res.error = f"no multi-event template for {tid} ({res.error or 'empty result'}); not sent to the AI"
+            res.validation = "failed"
+            out.append(res)
+            continue
+        # 2. ti2dac template over the separately converted steps
+        step_q, keys = [], []
+        for d, f in zip(docs, fields):
+            (q1,) = st.convert(st.dump_docs([{k: v for k, v in d.items() if k != "name"}]), [tid], index_overrides, client)
+            key = HOST_COLUMN.get(tid) if join_on == "host" else st.map_field(d, f, tid, client)
+            if not q1.query or not key or key.startswith("UNSUPPORTED"):
+                res.error = f"step {d.get('title')!r} does not convert for {tid}: {q1.error or key}"
+                break
+            step_q.append(q1.query)
+            keys.append(key)
+        else:
+            try:
+                q, note = (_kql(tid, step_q, keys, ordered, within) if tid in KQL_TARGETS
+                           else _TEMPLATES[tid](step_q, keys, ordered, within))
+                res.query, res.error, res.method, res.notes = q, None, "template", note
+            except ValueError as e:
+                res.error = f"{tid} template: {e}"
+        if res.error:
+            res.validation = "failed"
+        out.append(res)
+    return out
+
+
+def build(steps: list[DetectionPackage], *, slug: str, name: str, ordered: bool, within: str, join_on: str,
+          source: str, evidence: str, settings, clients=()) -> ChainPackage:
+    rule_yaml, docs, fields, warnings = build_yaml(steps, name=name, ordered=ordered, within=within,
+                                                   join_on=join_on, author=settings.author)
+    ok, issues = st.validate_rule(rule_yaml)
+    if not ok:
+        raise ValueError(f"chain {name!r} is not a valid Sigma correlation: {'; '.join(issues)[:300]}")
+    qs = queries(rule_yaml, docs, fields, join_on, ordered, within, settings.targets, None, settings.index_overrides)
+    for c in clients:
+        qs += queries(rule_yaml, docs, fields, join_on, ordered, within, c.targets or settings.targets, c, c.index_overrides)
+    unknown = [f"{d['name']}: {f}" for d, f in zip(docs, fields) if f in ("Hostname", "SourceIp", "User")
+               and (d.get("logsource") or {}).get("product") != "windows"]
+    if unknown:
+        warnings.append(f"join field guessed for non-Windows steps ({', '.join(unknown)}); check it in the rule file")
+    return ChainPackage(slug=slug, name=name, steps=[p.slug for p in steps], ordered=ordered, within=within,
+                        join_on=join_on, source=source, evidence=evidence, rule_yaml=rule_yaml, queries=qs,
+                        warnings=warnings)