First Commit

detections/tests/sigma_lint/check.sh

@@ -0,0 +1,85 @@
+#!/bin/sh
+#
+# In-container half of the ARTEX Sigma SigmaHQ-convention lint test. run.sh
+# launches this inside a Python container with the Sigma rule tree mounted
+# read-only at /sigma and this directory at /src. It installs a pinned sigma-cli
+# plus the pinned SigmaHQ validator plugin, then asserts two properties:
+#
+#   1. baseline is clean    sigma check with the documented validators.yml
+#                           baseline reports 0 errors and 0 issues.
+#   2. the full set is live  running ALL SigmaHQ validators (no exclusions) still
+#                           reports issues, and every issue type is one of the
+#                           four documented, excluded categories — nothing else.
+#
+# Property 2 is the anti-vacuity guard. If the validator plugin failed to load,
+# the "all" run would report zero issues and property 1 would pass vacuously;
+# requiring the known exclusions to appear proves the full SigmaHQ set actually
+# ran. It also fails the build the moment a rule picks up a NEW convention issue
+# outside the documented baseline (e.g. a mis-cased title or an invalid field),
+# because that issue type would not be in the allow-list below and property 1
+# would stop being clean.
+#
+# POSIX sh (the slim image ships dash). Exits non-zero if any assertion fails.
+set -eu
+
+VERSION="${SIGMA_CLI_VERSION:-3.1.0}"
+SIGMAHQ_VALIDATORS_VERSION="${SIGMAHQ_VALIDATORS_VERSION:-0.21.0}"
+
+pip install --quiet --disable-pip-version-check \
+  "sigma-cli==${VERSION}" "pySigma-validators-sigmahq==${SIGMAHQ_VALIDATORS_VERSION}" >/dev/null 2>&1
+
+# The four issue types the documented baseline (validators.yml) intentionally
+# excludes. Any issue outside this set must fail the build.
+ALLOWED='SigmahqGithubLinkIssue SigmahqFilenamePrefixIssue SigmahqCorrelationFilenamePrefixIssue SigmahqLogsourceUnknownIssue'
+
+printf 'validators:\n  - all\n' > /tmp/all.yml
+
+fail=0
+note() { printf '  %s\n' "$1"; }
+pass() { note "PASS  $1"; }
+bad()  { note "FAIL  $1"; fail=1; }
+
+echo "== 1/2  documented SigmaHQ baseline is clean (validators.yml) =="
+if base_out="$(sigma check --validation-config /src/validators.yml /sigma 2>&1)" \
+   && printf '%s' "$base_out" | grep -q 'Found 0 errors, 0 condition errors and 0 issues'; then
+  pass "sigma check with the documented baseline: 0 errors, 0 issues"
+else
+  bad  "the documented baseline reported problems (a non-excluded convention issue, or an error)"
+  printf '%s\n' "$base_out" | sed 's/^/        /'
+fi
+
+echo "== 2/2  the full SigmaHQ validator set runs, and only the documented exclusions remain =="
+all_out="$(sigma check --validation-config /tmp/all.yml /sigma 2>&1 || true)"
+# Collect the distinct issue types the full set reports.
+types="$(printf '%s' "$all_out" | grep -oE 'issue=Sigmahq[A-Za-z]+Issue' | sed 's/^issue=//' | sort -u)"
+
+if [ -z "$types" ]; then
+  bad  "the full validator set reported no SigmaHQ issues at all — the plugin did not load (vacuous)"
+else
+  # Anti-vacuity: the two load-bearing exclusions must actually appear.
+  for must in SigmahqGithubLinkIssue SigmahqLogsourceUnknownIssue; do
+    if printf '%s\n' "$types" | grep -qx "$must"; then
+      pass "full set is live: $must present"
+    else
+      bad  "expected $must from the full validator set but it was absent — plugin/version drift"
+    fi
+  done
+  # No issue type outside the documented allow-list may appear.
+  unexpected=0
+  for t in $types; do
+    case " $ALLOWED " in
+      *" $t "*) : ;;
+      *) bad "undocumented convention issue from the full set: $t"; unexpected=1 ;;
+    esac
+  done
+  [ "$unexpected" -eq 0 ] && pass "every reported issue is one of the four documented exclusions"
+fi
+
+echo
+echo "reference: sigma-cli ${VERSION}, pySigma-validators-sigmahq ${SIGMAHQ_VALIDATORS_VERSION}"
+if [ "$fail" -eq 0 ]; then
+  echo "RESULT: PASS"
+else
+  echo "RESULT: FAIL"
+fi
+exit "$fail"

detections/tests/sigma_lint/run.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+#
+# Reproducible SigmaHQ-convention lint for the ARTEX Sigma rules (../../sigma/).
+# `sigma check` on its own runs only pySigma's core validators; this test runs
+# the full SigmaHQ convention set (the pySigma-validators-sigmahq plugin) against
+# the documented baseline in validators.yml, so the "passes sigma check cleanly"
+# claim in the README and CONTRIBUTING covers SigmaHQ's conventions, not just the
+# core checks.
+#
+# It proves two properties with no host dependency beyond Docker (everything runs
+# in a container, nothing is installed on the host and nothing is written to the
+# repo tree):
+#
+#   1. the documented baseline (validators.yml) reports 0 errors and 0 issues
+#   2. the full validator set actually runs, and only the four documented
+#      exclusions remain — the anti-vacuity guard (see check.sh)
+#
+# The four exclusions and the rationale for each live in validators.yml.
+#
+# Usage:   detections/tests/sigma_lint/run.sh
+# Env:     PYTHON_IMAGE                (default python:3.12-slim)
+#          SIGMA_CLI_VERSION           (default 3.1.0 — the pinned reference version)
+#          SIGMAHQ_VALIDATORS_VERSION  (default 0.21.0 — the pinned validator plugin)
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO="$(cd "$HERE/../../.." && pwd)"
+SIGMA_DIR="$REPO/detections/sigma"
+PYTHON_IMAGE="${PYTHON_IMAGE:-python:3.12-slim}"
+SIGMA_CLI_VERSION="${SIGMA_CLI_VERSION:-3.1.0}"
+SIGMAHQ_VALIDATORS_VERSION="${SIGMAHQ_VALIDATORS_VERSION:-0.21.0}"
+
+# Everything runs inside the container: check.sh installs the pinned sigma-cli and
+# SigmaHQ validator plugin, then asserts the two properties and exits non-zero on
+# any failure. The rule tree and this directory are mounted read-only.
+docker run --rm \
+  -v "$SIGMA_DIR:/sigma:ro" \
+  -v "$HERE:/src:ro" \
+  -e SIGMA_CLI_VERSION="$SIGMA_CLI_VERSION" \
+  -e SIGMAHQ_VALIDATORS_VERSION="$SIGMAHQ_VALIDATORS_VERSION" \
+  "$PYTHON_IMAGE" sh /src/check.sh

detections/tests/sigma_lint/validators.yml

@@ -0,0 +1,44 @@
+# SigmaHQ validator baseline for the ARTEX detection rules.
+#
+# `sigma check` on its own runs only pySigma's core validators. This config turns
+# on the full SigmaHQ convention set (the pySigma-validators-sigmahq plugin) and
+# then disables four checks that encode SigmaHQ *monorepo* conventions which do
+# not apply to this small, self-contained rule set. Every other SigmaHQ check is
+# enforced, and detections/tests/sigma_lint/ fails the build if any enabled check
+# reports an issue. Each exclusion below is a deliberate, documented decision, not
+# a silenced defect.
+#
+# Run:
+#   pip install pySigma-validators-sigmahq
+#   sigma check --validation-config detections/tests/sigma_lint/validators.yml detections/sigma/
+#
+validators:
+  - all
+
+  # sigmahq_github_link wants every `references:` URL to be a commit permalink
+  # rather than a branch link. That check exists so rules citing external,
+  # third-party write-ups keep pointing at the exact revision they were written
+  # against. Our references point at *our own* living defense docs
+  # (docs/defense-ko.md, docs/defense-en.md) on `main`: we want them to track the
+  # current guide, not freeze to a snapshot that goes stale as the guide improves.
+  - -sigmahq_github_link
+
+  # sigmahq_filename_prefix and sigmahq_correlation_filename_prefix require
+  # logsource-prefixed filenames (web_*, proxy_*) and a correlation_* prefix, the
+  # filing scheme of SigmaHQ's single flat rules/ tree. This repository ships a
+  # small set under detections/sigma/ with descriptive artex_* names and a
+  # correlation/ subdirectory, referenced by the correlation rules' header
+  # comments, the reproduction tests, and the README index. Renaming to the
+  # monorepo prefixes would desynchronize those references for no gain on a
+  # standalone set.
+  - -sigmahq_filename_prefix
+  - -sigmahq_correlation_filename_prefix
+
+  # sigmahq_logsource_unknown flags `category: application` (the guard-marker
+  # forensic log search) and a product-less `category: process_creation` (the
+  # cross-platform destructive-command hunting lead) as outside the SigmaHQ
+  # taxonomy. Both logsources are intentionally generic: these indicators appear
+  # across heterogeneous application/audit and process-creation logs, and the
+  # README tells defenders to map them to their own pipeline. Pinning a single
+  # product would narrow the rules incorrectly.
+  - -sigmahq_logsource_unknown