Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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.

feat(detections): author windowed aggregation rules, and stop telling people not to (#897)

Beenu Arorad0a040677d6d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89a7b3bc3..70f76b864 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
behaviour and requires all 1,687 Windows rules to stop firing, so the proof
is known to be capable of failing.
+- **Eight windowed aggregation rules**, covering the detection family the
+ quarantine index had been telling contributors to skip. Windows now
+ contributes here too: failed-logon volume per host, password spray counted by
+ distinct account rather than by attempt, service-install and scheduled-task
+ bursts, remote-thread fan-out, and per-process DNS fan-out for tunnelling
+ and domain-generation algorithms.
+
### Changed
- **Upstream lifecycle status no longer decides whether an imported rule runs.**
@@ -87,6 +94,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
thousands separator, so "2,603 executable" was compared as 603 — a gate
measuring a number the README never claimed.
+- **The quarantine index told translators to skip the largest untranslated
+ family in it.** Step 3 said `| stats` aggregations belong in the windowed
+ engine, "which today has three hardcoded rules and no loader. Skip those
+ until it has one." `load_window_rules()` reads `windowed_ruleset.json` and
+ `main.py` wires it on by default, so the instruction had been stale for some
+ time while continuing to steer people away from roughly half the Splunk
+ quarantine. Corrected in `scripts/build_quarantine_index.py`, since the
+ README is generated output and editing the file would have regenerated the
+ error — the same shape as the detection-coverage generator that kept
+ restoring a dead link after the page was fixed.
+
- **Auto-triage never asked the provider for JSON, so a third of the bundled
model's replies were thrown away.** `run_auto_triage` parses the reply as a
JSON object, but nothing in `services/agents/app/llm/` ever set
diff --git a/detections/splunk-imports/_quarantine/README.md b/detections/splunk-imports/_quarantine/README.md
index 351618638..d7d42cf88 100644
--- a/detections/splunk-imports/_quarantine/README.md
+++ b/detections/splunk-imports/_quarantine/README.md
@@ -24,7 +24,7 @@ Categories come from the `tags.categories` field on each rule. `production` vs `
2. **Read the existing YAML** in this directory. The Splunk SPL is captured under `detection.splunk_spl`; the metadata (MITRE, severity, category, references) is already populated.
3. **Re-author the detection as a Python spec**, not as YAML. This step used to say to write a `detection.condition` block under `detections/<category>/`, which does not work: everything under `detections/` is a *generated projection* of the spec modules and the engine never reads it. A rule authored that way passes CI, is counted by the truth table, and is never loaded — 44 rules in the native tier are in exactly that state. Add an `S(...)` entry to the matching `scripts/detection_specs_part3_<category>.py` with a flat `match_when`, then run `python3 scripts/generate_detections.py` followed by `python3 scripts/export_detection_ruleset.py`. Carry the original `provenance.upstream_path` over so attribution is preserved.
- **Check every field name against the emitting connector's `normalize()` output.** `scripts/check_detection_fields.py` gates computed fields — counters, window sizes, allowlist booleans — which cannot fire at all, because nothing in the pipeline computes them. They need a windowed-engine rule or a fusion-time enrichment instead.
- - **SPL with `| stats` or `| tstats` is not translatable to `match_when`.** Aggregation over a window belongs in `services/fusion/app/services/windowed_detection.py`, which today has three hardcoded rules and no loader. Skip those until it has one.
+ - **SPL with `| stats` or `| tstats` is not translatable to `match_when`,** because that matcher sees one event at a time. Aggregation over a window belongs in `services/fusion/app/services/windowed_detection.py`, which loads `app/data/windowed_ruleset.json` through `load_window_rules()` and is wired on by default in `main.py`. Add the rule to `scripts/export_windowed_ruleset.py` and re-export. This step used to say the windowed engine had "three hardcoded rules and no loader" and to skip those rules until it had one — that stopped being true when the loader landed, and in the meantime it told translators to skip the single largest untranslated family in this directory.
4. **Add fixtures** under `detections/fixtures/positive/<rule-id>.json` and `detections/fixtures/negative/<rule-id>.json`. [`scripts/validate_detections.py --strict-fixtures`](../../../scripts/validate_detections.py) will refuse to merge a rule that ships without both.
5. **Delete the quarantined file** as part of the same PR — the rule now lives in the native tier and the quarantine entry is no longer the source of truth.
6. **Re-run** `python3 scripts/build_quarantine_index.py` to regenerate this index, then commit the README delta with your translation. CI verifies the index is in sync (`--check` mode).
diff --git a/scripts/build_quarantine_index.py b/scripts/build_quarantine_index.py
index 89d59c6f3..4f0e48c01 100644
--- a/scripts/build_quarantine_index.py
+++ b/scripts/build_quarantine_index.py
@@ -302,9 +302,16 @@ def render_readme(rules: list[QuarantineRule]) -> str:
)
lines.append(
" - **SPL with `| stats` or `| tstats` is not translatable to "
- "`match_when`.** Aggregation over a window belongs in "
- "`services/fusion/app/services/windowed_detection.py`, which today has "
- "three hardcoded rules and no loader. Skip those until it has one."
+ "`match_when`,** because that matcher sees one event at a time. "
+ "Aggregation over a window belongs in "
+ "`services/fusion/app/services/windowed_detection.py`, which loads "
+ "`app/data/windowed_ruleset.json` through `load_window_rules()` and is "
+ "wired on by default in `main.py`. Add the rule to "
+ "`scripts/export_windowed_ruleset.py` and re-export. This step used to "
+ 'say the windowed engine had "three hardcoded rules and no loader" '
+ "and to skip those rules until it had one — that stopped being true "
+ "when the loader landed, and in the meantime it told translators to "
+ "skip the single largest untranslated family in this directory."
)
lines.append(
"4. **Add fixtures** under `detections/fixtures/positive/<rule-id>.json` "
diff --git a/scripts/export_windowed_ruleset.py b/scripts/export_windowed_ruleset.py
index cf9d2cc5e..918d2d004 100644
--- a/scripts/export_windowed_ruleset.py
+++ b/scripts/export_windowed_ruleset.py
@@ -194,6 +194,134 @@ WINDOWED_RULES: list[dict] = [
"threshold": 50,
"window_seconds": 300,
},
+ # ---------------------------------------------------------------------
+ # Windows aggregations.
+ #
+ # These could not be written before, for a reason that had nothing to do
+ # with the windowed engine: a Windows event nests its payload under
+ # `EventData` and its header under `System`, one level deeper than either
+ # engine flattens, so `EventID` and `Computer` read as absent and any rule
+ # naming them would have counted nothing forever. The `windows_event`
+ # connector now lifts both containers, which is what makes the group_by
+ # fields below real.
+ #
+ # `EventID` is matched as an anchored pattern rather than with equality
+ # because collectors disagree about whether it arrives as `4625` or
+ # `"4625"`, and `pattern_match_any` compares the string form of whatever
+ # turned up. An `EventID: 4625` equality clause would match one collector
+ # and silently not the other.
+ # ---------------------------------------------------------------------
+ {
+ "id": "wd-windows-failed-logons-per-host",
+ "name": "Repeated failed Windows logons against one host",
+ "severity": "high",
+ "category": "identity",
+ "mitre": ["T1110"],
+ "match_when": {"EventID_pattern_match_any": ["^4625$"]},
+ "group_by": "Computer",
+ "threshold": 15,
+ "window_seconds": 600,
+ # Higher than the generic `wd-bruteforce-auth` threshold of five on
+ # purpose: a Windows host aggregates failures from every account and
+ # every service on it, so five is background noise there in a way it
+ # is not for a single identity.
+ },
+ {
+ "id": "wd-windows-password-spray",
+ "name": "Windows logon failures across many accounts from one source",
+ "severity": "high",
+ "category": "identity",
+ "mitre": ["T1110.003"],
+ "match_when": {"EventID_pattern_match_any": ["^4625$"]},
+ "group_by": "IpAddress",
+ "distinct_by": "TargetUserName",
+ "threshold": 10,
+ "window_seconds": 900,
+ # Distinct accounts, not attempts. One account failing repeatedly is a
+ # forgotten password; ten different accounts failing once each from one
+ # address is someone working through a user list.
+ },
+ {
+ "id": "wd-windows-service-install-burst",
+ "name": "Several new Windows services installed on one host",
+ "severity": "high",
+ "category": "endpoint",
+ "mitre": ["T1543.003"],
+ "match_when": {"EventID_pattern_match_any": ["^7045$"]},
+ "group_by": "Computer",
+ "threshold": 4,
+ "window_seconds": 600,
+ # Service installation is rare outside patching, so the threshold is
+ # low. Patch windows are the expected false positive and are better
+ # handled by a maintenance-window suppression than by a number nobody
+ # can justify.
+ },
+ {
+ "id": "wd-windows-account-creation-burst",
+ "name": "One actor created several Windows accounts",
+ "severity": "high",
+ "category": "identity",
+ "mitre": ["T1136.002"],
+ "match_when": {"EventID_pattern_match_any": ["^4720$"]},
+ "group_by": "SubjectUserName",
+ "distinct_by": "TargetUserName",
+ "threshold": 5,
+ "window_seconds": 900,
+ },
+ {
+ "id": "wd-windows-scheduled-task-burst",
+ "name": "Several scheduled tasks registered on one host",
+ "severity": "medium",
+ "category": "endpoint",
+ "mitre": ["T1053.005"],
+ "match_when": {"EventID_pattern_match_any": ["^4698$"]},
+ "group_by": "Computer",
+ "threshold": 5,
+ "window_seconds": 600,
+ },
+ {
+ "id": "wd-sysmon-remote-thread-fanout",
+ "name": "One process created remote threads in many others",
+ "severity": "high",
+ "category": "endpoint",
+ "mitre": ["T1055"],
+ "match_when": {"EventID_pattern_match_any": ["^8$"]},
+ "group_by": "SourceImage",
+ "distinct_by": "TargetImage",
+ "threshold": 5,
+ "window_seconds": 300,
+ # Injecting into one process has a long list of benign explanations.
+ # Injecting into five different ones inside five minutes has very few.
+ },
+ {
+ "id": "wd-sysmon-dns-query-fanout",
+ "name": "One process resolved an unusual number of distinct domains",
+ "severity": "medium",
+ "category": "network",
+ "mitre": ["T1071.004"],
+ "match_when": {"EventID_pattern_match_any": ["^22$"]},
+ "group_by": "Image",
+ "distinct_by": "QueryName",
+ "threshold": 150,
+ "window_seconds": 300,
+ # Aimed at DNS tunnelling and at domain-generation algorithms, both of
+ # which show up as one binary resolving far more names than it has any
+ # reason to. Browsers legitimately clear this bar, which is why the
+ # grouping is per-image rather than per-host.
+ },
+ {
+ "id": "wd-sysmon-process-spawn-burst",
+ "name": "One parent process spawned an unusual number of children",
+ "severity": "medium",
+ "category": "endpoint",
+ "mitre": ["T1059"],
+ "match_when": {"EventID_pattern_match_any": ["^1$"]},
+ "group_by": "ParentImage",
+ "threshold": 100,
+ "window_seconds": 120,
+ # Script-driven enumeration and mass encryption both look like this.
+ # Build agents and installers do too, so this is deliberately medium.
+ },
]
diff --git a/services/fusion/app/data/windowed_ruleset.json b/services/fusion/app/data/windowed_ruleset.json
index f2659f2da..e79a13c67 100644
--- a/services/fusion/app/data/windowed_ruleset.json
+++ b/services/fusion/app/data/windowed_ruleset.json
@@ -1,5 +1,5 @@
{
- "count": 10,
+ "count": 18,
"rules": [
{
"category": "application",
@@ -149,6 +149,146 @@
"severity": "high",
"threshold": 50,
"window_seconds": 300
+ },
+ {
+ "category": "identity",
+ "group_by": "Computer",
+ "id": "wd-windows-failed-logons-per-host",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^4625$"
+ ]
+ },
+ "mitre": [
+ "T1110"
+ ],
+ "name": "Repeated failed Windows logons against one host",
+ "severity": "high",
+ "threshold": 15,
+ "window_seconds": 600
+ },
+ {
+ "category": "identity",
+ "distinct_by": "TargetUserName",
+ "group_by": "IpAddress",
+ "id": "wd-windows-password-spray",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^4625$"
+ ]
+ },
+ "mitre": [
+ "T1110.003"
+ ],
+ "name": "Windows logon failures across many accounts from one source",
+ "severity": "high",
+ "threshold": 10,
+ "window_seconds": 900
+ },
+ {
+ "category": "endpoint",
+ "group_by": "Computer",
+ "id": "wd-windows-service-install-burst",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^7045$"
+ ]
+ },
+ "mitre": [
+ "T1543.003"
+ ],
+ "name": "Several new Windows services installed on one host",
+ "severity": "high",
+ "threshold": 4,
+ "window_seconds": 600
+ },
+ {
+ "category": "identity",
+ "distinct_by": "TargetUserName",
+ "group_by": "SubjectUserName",
+ "id": "wd-windows-account-creation-burst",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^4720$"
+ ]
+ },
+ "mitre": [
+ "T1136.002"
+ ],
+ "name": "One actor created several Windows accounts",
+ "severity": "high",
+ "threshold": 5,
+ "window_seconds": 900
+ },
+ {
+ "category": "endpoint",
+ "group_by": "Computer",
+ "id": "wd-windows-scheduled-task-burst",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^4698$"
+ ]
+ },
+ "mitre": [
+ "T1053.005"
+ ],
+ "name": "Several scheduled tasks registered on one host",
+ "severity": "medium",
+ "threshold": 5,
+ "window_seconds": 600
+ },
+ {
+ "category": "endpoint",
+ "distinct_by": "TargetImage",
+ "group_by": "SourceImage",
+ "id": "wd-sysmon-remote-thread-fanout",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^8$"
+ ]
+ },
+ "mitre": [
+ "T1055"
+ ],
+ "name": "One process created remote threads in many others",
+ "severity": "high",
+ "threshold": 5,
+ "window_seconds": 300
+ },
+ {
+ "category": "network",
+ "distinct_by": "QueryName",
+ "group_by": "Image",
+ "id": "wd-sysmon-dns-query-fanout",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^22$"
+ ]
+ },
+ "mitre": [
+ "T1071.004"
+ ],
+ "name": "One process resolved an unusual number of distinct domains",
+ "severity": "medium",
+ "threshold": 150,
+ "window_seconds": 300
+ },
+ {
+ "category": "endpoint",
+ "group_by": "ParentImage",
+ "id": "wd-sysmon-process-spawn-burst",
+ "match_when": {
+ "EventID_pattern_match_any": [
+ "^1$"
+ ]
+ },
+ "mitre": [
+ "T1059"
+ ],
+ "name": "One parent process spawned an unusual number of children",
+ "severity": "medium",
+ "threshold": 100,
+ "window_seconds": 120
}
]
}