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.

5.0 KB
Raw Blame

Detection translation drive

This is the most parallelisable contribution surface in the project, and the one where a first-time contributor can land something measurable in an hour.

The gap, in the project's own numbers

Copied from docs/detections/truth-table.md, which is generated by scripts/detection_truth_table.py and gated by --check against what the engine loads:

tier on disk executable
native 877 833
sigma (imported) 3132 1770
splunk (imported) 2005 0
chronicle (imported) 877 0
car (imported) 99 0
community 1 0

2,535 of 7,015 rules fire today. The other 4,480 are on disk for provenance and ATT&CK coverage mapping — 4,213 of them quarantined on import because their body is an upstream query language the engine does not execute, and 267 carrying enabled: false with a reason.

This table is copied from the generated file rather than counted by hand, and it has still gone stale once: it read native 869/869 and sigma 3132/77 against a source holding 877/833 and 3132/1770, and said in the paragraph above that being copied from a CI-gated source meant it could not drift. The gate holds the generated file to the engine. Nothing held this page to the generated file, so re-read it from the link above rather than trusting the numbers here.

The project is deliberately honest about this — the README quotes the executable figure, not the on-disk one. The way to improve the number is to translate rules, not to relabel them.

Start with Sigma, but read the refusals first

Of the four imported tiers, Sigma remains the best target, and what makes a useful contribution has changed: 1,770 Sigma rules now ship and 1,362 are refused, each with a recorded reason in docs/detections/sigma-compilation.md. The bulk one-at-a-time translation that used to be the ask is largely done, so picking an arbitrary quarantined rule is likely to land on one that was refused on purpose.

  • Sigma's selection / condition model maps closely onto the native match_when DSL, and there are now 1,770 worked examples in-tree rather than 77. It is mechanical, not a rewrite.
  • The highest-leverage work is a named capability gap, not a rule. The refusal table groups the 1,362 by cause, and several are one matcher feature standing in front of a whole family: 71 rules need a case-sensitive |re, 59 need a dotted field path, 17 need a |cidr operator, 14 need |all on a non-contains modifier, 10 use bare keywords against a field-scoped matcher. Closing one unlocks its family at once.
  • 556 were refused because no connector emits their log source, which is connector work rather than translation work, and is the largest single group.
  • 464 negations are refused deliberately and should stay refused. Sigma treats not filter as true when the field is absent, and only not_in and not_contains_any behave that way here, so compiling the rest would turn "not this value" into "fires whenever the field is missing". A translation that is merely close changes what a rule means.
  • SPL, YARA-L and CAR pseudocode need semantic reinterpretation and are a much poorer first task. Leave those.

What a translation looks like

  1. Pick a rule under detections/_quarantine/ in the sigma tier. Check no open PR already claims it.
  2. Translate the body into the native condition DSL. The 877 rules under detections/<category>/ are your reference, and the 1,770 already-compiled Sigma imports are the closest analogues.
  3. Write both fixtures under detections/fixtures/ — one event the rule must fire on, one it must stay quiet on. This is not optional paperwork: the gate replays both and a rule that fires on its negative fixture is rejected.
  4. Move the rule out of _quarantine/ into its category directory.
  5. Open a PR. validate-detections.yml replays every fixture and detection_truth_table.py --check updates the counts.

Why the negative fixture is the important one

A detection that fires on everything has perfect recall and no value. The negative fixture is what stops the corpus filling with rules that would drown an analyst, and it is the reason this drive can accept contributions from people who have never seen the codebase: the gate is objective. Either the rule fires on the positive and stays quiet on the negative, or CI says no.

Scope one PR sensibly

One to five related rules. A 200-rule PR cannot be reviewed meaningfully and will sit. A handful of rules covering one technique is a good unit, and it is fine for that to be your whole contribution.

If you want something smaller first

  • Add a negative fixture to an existing native rule that has only a positive one.
  • Fix a false positive someone has already reported against a firing rule.
  • Pick up an issue labelled good first issue.