From bf216a1db05e982fd934fb02b9748f11d0ef5403 Mon Sep 17 00:00:00 2001 From: Mostafa Moradian Date: Thu, 24 Sep 2026 11:29:25 +0200 Subject: [PATCH 1/4] feat: add an agent skill for the rsigma CLI and MCP loop Agents were still being pointed at top-level rsigma eval and lint commands that no longer exist. The skill teaches the current command groups and the write-lint-evaluate-convert loop, and sends YAML authoring to sigma-rules. --- skills/rsigma/SKILL.md | 72 +++++++++++++++++++++++++++ skills/rsigma/references/workflows.md | 46 +++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 skills/rsigma/SKILL.md create mode 100644 skills/rsigma/references/workflows.md diff --git a/skills/rsigma/SKILL.md b/skills/rsigma/SKILL.md new file mode 100644 index 00000000..e3674424 --- /dev/null +++ b/skills/rsigma/SKILL.md @@ -0,0 +1,72 @@ +--- +name: rsigma +description: "Use the rsigma CLI and MCP server: engine eval, engine daemon, rule lint, rule draft, rule tune, rule backtest, backend convert, mcp serve. Prefer MCP tools when rsigma mcp serve is connected. For authoring Sigma YAML (detection, correlation, filters, pipelines, modifiers), use the sigma-rules skill. Use this skill whenever the user mentions rsigma, evaluating or linting Sigma rules, converting rules to a SIEM query, running a detection daemon, drafting or tuning rules from events, or backtesting a ruleset, even if they do not name the binary." +--- + +# rsigma + +Use rsigma to run Sigma rules. Author the YAML with the [sigma-rules](https://github.com/timescale/sigma-rules) skill (`npx skills add timescale/sigma-rules -g -y`). This skill covers the toolchain: command names, when to call MCP versus the CLI, and which command fits the job. + +Flag tables and option lists live at [rsigma.io](https://rsigma.io/). Read them when you need a flag. Do not invent flags, and do not memorize lint or auto-fix counts from memory. The [linting guide](https://rsigma.io/guide/linting-rules/) is the catalogue. + +## Command names + +The CLI is noun-led. These old top-level forms do not exist: + +| Do not run | Run instead | +|------------|-------------| +| `rsigma eval` | `rsigma engine eval` | +| `rsigma lint` | `rsigma rule lint` | +| `rsigma validate` | `rsigma rule validate` | +| `rsigma daemon` | `rsigma engine daemon` | + +Groups: + +| Group | Use it for | +|-------|------------| +| `engine` | Evaluate events, explain a miss, classify schemas, and run or inspect the daemon (`eval`, `explain`, `classify`, `discover-schemas`, `status`, `tap`, `tail`, `daemon`) | +| `rule` | Lint, validate, draft, tune, test exemplars, backtest, and reverse-convert | +| `backend` | Convert rules to a query (`convert`, `targets`, `formats`) | +| `pipeline` | See how a pipeline rewrites a rule (`diff`) and dry-run dynamic sources (`resolve`) | +| `mcp` | Serve the toolchain to an agent (`serve`) | +| `config` | Scaffold and inspect `rsigma.yaml` | + +`engine daemon` and `pipeline resolve` need a build with the `daemon` feature. `mcp serve` needs the `mcp` feature. Release binaries and the Docker image include both. `rsigma --features` prints what this binary was built with. + +Full tree: [CLI reference](https://rsigma.io/cli/). + +## Prefer MCP when it is connected + +If `rsigma mcp serve` is already connected, call its tools. They return JSON (`ok`, findings, matches) and you do not scrape CLI text. If it is not connected, use the CLI commands in [workflows.md](references/workflows.md). + +Start a local server only when the user wants the agent wired up: + +```bash +rsigma mcp serve --rules-dir rules/ +``` + +Point `--daemon-url` at a running daemon when the task is live triage (incidents, silences, dispositions). Those tools stay off until that URL is set. Writes stay behind `--allow-operate-writes`. Details: [MCP server guide](https://rsigma.io/guide/mcp-server/). + +## Which command + +- One-shot check against a file or a few events: `engine eval`. A long-running process with reload, metrics, and sinks: `engine daemon`. +- A rule from exemplar events (optional baseline, or `--groups` for a temporal correlation): `rule draft`. A rule the user already described in words: write the YAML with sigma-rules, then lint and evaluate it here. +- A noisy rule with known false positives and true positives that must still fire: `rule tune`. +- Embedded `rsigma.exemplars`: `rule test`. A separate corpus and expectations file: `rule backtest`. +- Why a rule missed: `engine explain`. How a pipeline rewrote fields: `pipeline diff`. + +The write-lint-evaluate-convert loop, with the MCP tool beside each CLI command, is in [workflows.md](references/workflows.md). + +## Convert + +Native targets run inside rsigma. Anything else is delegated to an installed [sigma-cli](https://github.com/SigmaHQ/sigma-cli). + +```bash +rsigma backend targets +rsigma backend convert -t postgres rules/ +rsigma backend convert -t splunk rules/ +``` + +Native targets include `postgres` (`postgresql`, `pg`), `lynxdb`, `fibratus`, and `test`. `backend targets` is the live list. Delegated conversion needs `sigma` on `PATH` (override with `RSIGMA_SIGMA_CLI`). The Docker image has no Python, so delegation is a local-binary feature. On MCP, `convert_rules` delegates only when the server was started with `--allow-sigma-cli`. Builtin pipeline names (`ecs_windows`, `fibratus_windows`, `sysmon`) are not translated for delegated targets. Pass a sigma-cli pipeline name or a YAML path. + +See [backend convert](https://rsigma.io/cli/backend/convert/) and [sigma-cli delegation](https://rsigma.io/reference/backends/sigma-cli/). diff --git a/skills/rsigma/references/workflows.md b/skills/rsigma/references/workflows.md new file mode 100644 index 00000000..12b820a4 --- /dev/null +++ b/skills/rsigma/references/workflows.md @@ -0,0 +1,46 @@ +# Workflows + +Command names and the convert split are in [SKILL.md](../SKILL.md). This page is the loop. Flag tables are on [rsigma.io](https://rsigma.io/), not here. + +Author Sigma YAML with the sigma-rules skill. Use the steps below to check and run it. + +## Write, lint, evaluate, convert + +Prefer the MCP tool when `rsigma mcp serve` is connected. Otherwise use the CLI. + +1. **Draft.** Hand-authored YAML (sigma-rules), `rule draft` from exemplar events, or `reverse_convert` / `rule reverse` from a Lucene query. Call `parse_rule` (or `rule parse`) and stop if the structure is invalid. +2. **Lint.** `lint_rules` or `rule lint`. Each finding has a rule id and a `fixable` flag. Apply a known-safe fix with `fix_rules` or `rule lint --fix`. Rewrite the rest by hand. Do not treat a count of checks as stable. The catalogue is the [linting guide](https://rsigma.io/guide/linting-rules/). +3. **Evaluate.** `evaluate_events` or `engine eval` against a few positive and negative events. `match_detail` of `summary` or `full` explains why an event matched. When the events live on the rule as `rsigma.exemplars`, `test_exemplars` or `rule test` is the closed runner. +4. **Tune.** For a noisy rule, `tune_rules` or `rule tune` with classified false positives and a true-positive set that must still fire. Review the returned filter before writing it. +5. **Validate.** `validate_rules` or `rule validate` on the set, with pipelines when the rules depend on them. +6. **Convert.** `convert_rules` or `backend convert` to the deployment target. Native targets run in-process. Other targets need sigma-cli, and on MCP they also need `--allow-sigma-cli`. + +Guide: [MCP server](https://rsigma.io/guide/mcp-server/). + +## Eval versus daemon + +`engine eval` reads a fixed input and exits. Use it to test a rule. + +`engine daemon` stays up, reloads rules, and exposes health and metrics. Use it when events are a stream (stdin, HTTP, NATS, OTLP). It needs the `daemon` feature. Release binaries include it. + +Guide: [Evaluating rules](https://rsigma.io/guide/evaluating-rules/), [Streaming detection](https://rsigma.io/guide/streaming-detection/). + +## Draft versus a rule you already know + +`rule draft` proposes a detection from exemplar events, optionally contrasted with a baseline. `rule draft --groups` proposes a temporal correlation from grouped, timed exemplars. Use draft when the user has events and wants a rule inferred from them. + +When the user describes the behavior in words, write the YAML with sigma-rules. Then run the loop above. Do not ask draft to invent a rule from a sentence. + +Guide: [Rule drafting](https://rsigma.io/guide/rule-drafting/). + +## Convert + +```bash +rsigma backend targets +rsigma backend convert -t postgres rules/ +rsigma backend convert -t splunk rules/ +``` + +`backend targets` is the list of compiled-in backends. `postgres`, `lynxdb`, `fibratus`, and `test` are native. Any other installed sigma-cli target is delegated. If delegation fails, the error is that `sigma` is missing, not that the target name is wrong. + +Reference: [backend convert](https://rsigma.io/cli/backend/convert/). From 17b0b94d9b68a4a8cad32f73de0ac3dd636228d2 Mon Sep 17 00:00:00 2001 From: Mostafa Moradian Date: Thu, 24 Sep 2026 11:30:13 +0200 Subject: [PATCH 2/4] docs: document how to install the rsigma agent skill The skill is only useful if agents can find it. The README and installation page point at npx skills add timescale/rsigma. --- CHANGELOG.md | 4 ++++ README.md | 7 +++++++ docs/content/getting-started/installation.md | 11 +++++++++++ 3 files changed, 22 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec1d91fd..5f607dab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to RSigma are documented in this file. Each entry correspond ## [Unreleased] +### Agent skill for the CLI and MCP loop + +`skills/rsigma/` teaches agents the current command groups (`engine`, `rule`, `backend`, `pipeline`, `mcp`, `config`) and the write-lint-evaluate-convert loop. Install with `npx skills add timescale/rsigma -g -y`. Sigma YAML authoring stays in the sigma-rules skill. + ### rstix: validate-on-ingest for TAXII collections (#499) **Public API (breaking vs 0.22.0):** diff --git a/README.md b/README.md index 51db0c2d..b41bf1a3 100644 --- a/README.md +++ b/README.md @@ -256,6 +256,13 @@ rsigma mcp serve --rules-dir rules/ The agent then calls structured tools (`parse_rule`, `lint_rules`, `validate_rules`, `evaluate_events`, `convert_rules`, `list_fields`, ...) and gets back JSON. Point `--daemon-url` at a running daemon to add the Operate-cycle tools. See the [MCP server guide](https://rsigma.io/guide/mcp-server/). +To teach an agent the current CLI and that loop, install the skill (Sigma YAML authoring is a separate skill): + +```bash +npx skills add timescale/sigma-rules -g -y +npx skills add timescale/rsigma -g -y +``` + ### Library Usage Use the crates directly from Rust: diff --git a/docs/content/getting-started/installation.md b/docs/content/getting-started/installation.md index 3d97c465..c0136306 100644 --- a/docs/content/getting-started/installation.md +++ b/docs/content/getting-started/installation.md @@ -133,6 +133,17 @@ rsigma --help You should see `rsigma {{ rsigma.version }}`, the Cargo features compiled into that binary, and a list of the top-level command groups (`engine`, `rule`, `backend`, `pipeline`, `config`, and `mcp` when built with the `mcp` feature). +## Agent skill + +Coding agents that run rsigma (eval, lint, draft, tune, convert, daemon) can load a skill that teaches the current command groups and the MCP loop. YAML authoring stays in the separate [sigma-rules](https://github.com/timescale/sigma-rules) skill. + +```bash +npx skills add timescale/sigma-rules -g -y +npx skills add timescale/rsigma -g -y +``` + +The rsigma skill is published from `skills/rsigma/` in this repository. It does not replace `rsigma mcp serve`. Connect the MCP server when you want typed tools instead of shelling out. + ## Next steps - Run your first rule in [the quick start](quick-start.md). From 78d9a21dd57895b6d482c9b46e9dfd42665df402 Mon Sep 17 00:00:00 2001 From: Mostafa Moradian Date: Thu, 24 Sep 2026 11:30:44 +0200 Subject: [PATCH 3/4] docs: cite the agent skill pull request in the changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f607dab..a457acb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to RSigma are documented in this file. Each entry correspond ## [Unreleased] -### Agent skill for the CLI and MCP loop +### Agent skill for the CLI and MCP loop (#501) `skills/rsigma/` teaches agents the current command groups (`engine`, `rule`, `backend`, `pipeline`, `mcp`, `config`) and the write-lint-evaluate-convert loop. Install with `npx skills add timescale/rsigma -g -y`. Sigma YAML authoring stays in the sigma-rules skill. From 628b5370746136dc052b11e4f447ebf89b074387 Mon Sep 17 00:00:00 2001 From: Mostafa Moradian Date: Thu, 24 Sep 2026 11:34:57 +0200 Subject: [PATCH 4/4] fix: correct delegation and daemon guidance in the rsigma skill With sigma-cli installed, an unknown target fails as an invalid target, not as a missing binary, so the skill now tells agents to install the backend plugin in that case. It also names the daemon-nats and daemon-otlp features, drops the duplicated convert section, and labels the test target as non-deployment. --- skills/rsigma/SKILL.md | 4 ++-- skills/rsigma/references/workflows.md | 12 ++---------- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/skills/rsigma/SKILL.md b/skills/rsigma/SKILL.md index e3674424..54904625 100644 --- a/skills/rsigma/SKILL.md +++ b/skills/rsigma/SKILL.md @@ -7,7 +7,7 @@ description: "Use the rsigma CLI and MCP server: engine eval, engine daemon, rul Use rsigma to run Sigma rules. Author the YAML with the [sigma-rules](https://github.com/timescale/sigma-rules) skill (`npx skills add timescale/sigma-rules -g -y`). This skill covers the toolchain: command names, when to call MCP versus the CLI, and which command fits the job. -Flag tables and option lists live at [rsigma.io](https://rsigma.io/). Read them when you need a flag. Do not invent flags, and do not memorize lint or auto-fix counts from memory. The [linting guide](https://rsigma.io/guide/linting-rules/) is the catalogue. +Flag tables and option lists live at [rsigma.io](https://rsigma.io/). Read them when you need a flag. Do not invent flags, and do not quote lint or auto-fix counts. The [linting guide](https://rsigma.io/guide/linting-rules/) is the catalogue. ## Command names @@ -67,6 +67,6 @@ rsigma backend convert -t postgres rules/ rsigma backend convert -t splunk rules/ ``` -Native targets include `postgres` (`postgresql`, `pg`), `lynxdb`, `fibratus`, and `test`. `backend targets` is the live list. Delegated conversion needs `sigma` on `PATH` (override with `RSIGMA_SIGMA_CLI`). The Docker image has no Python, so delegation is a local-binary feature. On MCP, `convert_rules` delegates only when the server was started with `--allow-sigma-cli`. Builtin pipeline names (`ecs_windows`, `fibratus_windows`, `sysmon`) are not translated for delegated targets. Pass a sigma-cli pipeline name or a YAML path. +Native targets are `postgres` (`postgresql`, `pg`), `lynxdb`, and `fibratus`, plus a backend-neutral `test` target that is not a deployment backend. `backend targets` is the live list. Delegated conversion needs `sigma` on `PATH` (override with `RSIGMA_SIGMA_CLI`). The Docker image has no Python, so delegation is a local-binary feature. On MCP, `convert_rules` delegates only when the server was started with `--allow-sigma-cli`. Builtin pipeline names (`ecs_windows`, `fibratus_windows`, `sysmon`) are not translated for delegated targets. Pass a sigma-cli pipeline name or a YAML path. See [backend convert](https://rsigma.io/cli/backend/convert/) and [sigma-cli delegation](https://rsigma.io/reference/backends/sigma-cli/). diff --git a/skills/rsigma/references/workflows.md b/skills/rsigma/references/workflows.md index 12b820a4..eeff966c 100644 --- a/skills/rsigma/references/workflows.md +++ b/skills/rsigma/references/workflows.md @@ -21,7 +21,7 @@ Guide: [MCP server](https://rsigma.io/guide/mcp-server/). `engine eval` reads a fixed input and exits. Use it to test a rule. -`engine daemon` stays up, reloads rules, and exposes health and metrics. Use it when events are a stream (stdin, HTTP, NATS, OTLP). It needs the `daemon` feature. Release binaries include it. +`engine daemon` stays up, reloads rules, and exposes health and metrics. Use it when events are a stream. It needs the `daemon` feature. NATS input also needs `daemon-nats`, and OTLP logs arrive on `/v1/logs` on the API address with `daemon-otlp`, not through `--input`. Release binaries include all three; a `cargo install rsigma` build has only `daemon`. Guide: [Evaluating rules](https://rsigma.io/guide/evaluating-rules/), [Streaming detection](https://rsigma.io/guide/streaming-detection/). @@ -35,12 +35,4 @@ Guide: [Rule drafting](https://rsigma.io/guide/rule-drafting/). ## Convert -```bash -rsigma backend targets -rsigma backend convert -t postgres rules/ -rsigma backend convert -t splunk rules/ -``` - -`backend targets` is the list of compiled-in backends. `postgres`, `lynxdb`, `fibratus`, and `test` are native. Any other installed sigma-cli target is delegated. If delegation fails, the error is that `sigma` is missing, not that the target name is wrong. - -Reference: [backend convert](https://rsigma.io/cli/backend/convert/). +Native versus delegated targets are in the Convert section of [SKILL.md](../SKILL.md#convert). When delegation fails, read the error. If `sigma` could not be found or executed, install sigma-cli or set `RSIGMA_SIGMA_CLI`. If sigma-cli rejects the target, install that backend plugin (`sigma plugin install `), then check `rsigma backend targets`.