v1.0.0: stable report contract + dialects

detdrift 1.0.0

Stable 1.0 release. Phase 4 dialects (KQL + SPL) are in, and the JSON report / exit-code contract is frozen.

Why 1.0 now

• Second dialect works behind the same CLI (KQL and SPL, in addition to Sigma)
• schema_version 1 is the stable 1.0 report contract (see docs/json-report.md)
• Exit codes 0 / 1 / 2 remain part of the interface

Install (GitHub; no PyPI in this release)

pip install git+https://github.com/chriswayneh/detdrift.git@v1.0.0

Action pin

- uses: chriswayneh/detdrift@v1.0.0
  with:
    before: samples/before.jsonl
    after: samples/after.jsonl
    rules: detections/
    # dialect: kql   # optional: sigma | kql | spl | auto

Highlights since 0.1

• Impact reports for Sigma field drift (CI-friendly exit codes)
• Fail-on severity/tag filters; reusable GitHub Action
• propose-patch helper + agent skill
• Sample importers, SARIF output, empty-after warnings
• Optional KQL/SPL field extractors (--dialect); Action dialect input

Not in this release

• PyPI publish (optional / later)
• Portfolio GIFs

Verify

pip install -e ".[dev]"
pytest -q
python -m detdrift diff -b fixtures/before -a fixtures/after -r rules
python -m detdrift diff -b fixtures/kql/before -a fixtures/kql/after -r examples/kql/rules --dialect kql
python -m detdrift diff -b fixtures/spl/before -a fixtures/spl/after -r examples/spl/rules --dialect spl

See CHANGELOG.md for the full 0.1 → 1.0 summary.

v0.6.1: Action dialect input

Action dialect input + CI dialect demos

Callers of the reusable composite Action can pass dialect (sigma|kql|spl|auto) into detdrift diff. CI examples run the bundled Sigma demo plus KQL/SPL fixtures when present.

What'''s new

• �ction.yml input dialect (default sigma) -> detdrift diff --dialect
• .github/workflows/detdrift.yml and docs/ci/detdrift.yml: KQL + SPL demo drift steps (hashFiles gated)
• README: Action dialect one-liner; CLI flag list includes spl
• ROADMAP: Action dialect noted under Phase 4

Not in this release

• PyPI publish
• Portfolio GIFs

Verify

pip install -e .[dev] pytest -q detdrift diff -b fixtures/before -a fixtures/after -r rules detdrift diff -b fixtures/kql/before -a fixtures/kql/after -r examples/kql/rules --dialect kql detdrift diff -b fixtures/spl/before -a fixtures/spl/after -r examples/spl/rules --dialect spl

v0.6.0 Phase 4 Broaden (SPL dialect)

Phase 4 Broaden — optional SPL field extraction

Sigma remains the default. This release adds a pluggable, offline SPL dialect for simple field references — not a query engine or matcher. Continues Phase 4 after KQL in v0.5.0.

What's new

• --dialect sigma|kql|spl|auto on detdrift diff and detdrift fields
• Simple SPL extraction: Field=, stats … by, table, rex field=
• Sample: examples/spl/rules + fixtures/spl
• Docs: README, ROADMAP, ARCHITECTURE, skill updated

Not in this release

• PyPI publish (needs secrets)
• Full SPL/eval/subsearch support

Verify

pip install -e .[dev]
pytest -q
detdrift fields examples/spl/rules/whoami_process.spl
detdrift diff -b fixtures/spl/before -a fixtures/spl/after -r examples/spl/rules --dialect spl

v0.5.0 Phase 4 Broaden (KQL dialect)

Phase 4 Broaden (partial) — optional KQL field extraction

Sigma remains the default. This release adds a pluggable, offline KQL dialect for simple field references — not a query engine or matcher.

What's new

• --dialect sigma|kql|auto on detdrift diff (default sigma) and detdrift fields (default auto by extension)
• Simple KQL extraction: where Field op, project, summarize … by, sort by
• Sample: examples/kql/rules + fixtures/kql
• Docs: README, ROADMAP, ARCHITECTURE updated (Phase 4 started)

Not in this release

• SPL dialect
• PyPI publish (needs secrets)

Verify

pip install -e .[dev]
pytest -q
detdrift fields examples/kql/rules/whoami_process.kql
detdrift diff -b fixtures/kql/before -a fixtures/kql/after -r examples/kql/rules --dialect kql

v0.4.2 Phase 3 Connect (importers)

Phase 3 Connect (complete) - v0.4.2

What shipped

• before/after samples accept flat JSON field maps, fields-list documents, and JSON arrays of events (NDJSON/JSONL unchanged)
• Docs: docs/importers.md
• 53 tests

Phase 3 series

• v0.4.0 empty/incomplete after-sample warnings
• v0.4.1 --format sarif + docs/ci/sarif-example.yml
• v0.4.2 flat JSON / fields-list / event-array samples

Offline; not a SIEM or matcher. No live connectors.

v0.4.1 Phase 3 Connect (SARIF)

Phase 3 Connect (continued) - v0.4.1

What shipped

• detdrift diff --format sarif emits SARIF 2.1.0 for IMPACTED rules (and sample warnings)
• --json still works (alias for --format json); default remains human
• Example CI snippet: docs/ci/sarif-example.yml (upload with github/codeql-action/upload-sarif)
• 47 tests

Already in v0.4.0

• Empty / incomplete after-sample warnings

Still to come in Phase 3

• At least one simple importer (or documented stub)

Offline; not a SIEM or matcher.

v0.4.0 Phase 3 Connect (warnings)

Phase 3 Connect (partial) - v0.4.0

First Phase 3 piece: warn when the after sample is empty or clearly incomplete.

What shipped

• Empty after NDJSON (0 events) produces a WARNING: an empty file is not the same as "nothing removed"
• After schemas with under 20% of before fields (when before has 5+ fields) also warn as incomplete
• Warnings appear in the human report, optional JSON warnings key, before_event_count / after_event_count, and stderr
• 43 tests

Still to come in Phase 3

• SARIF output for PR annotations
• At least one simple importer (or documented stub)

Not in scope

• Not a SIEM or matcher
• Offline default
• No auto-commit

v0.3.0 Phase 2 Assist

Phase 2 Assist (v0.3.0)

• propose-patch: generate human-readable notes and a patch suggestion for detection drift (no auto-commit)
• skill: Cursor/agent skill for using detdrift in assist workflows
• 37 tests covering propose-patch and related Phase 2 behavior
• Still offline by default; not a SIEM or matcher
• Does not auto-commit patches — review and apply yourself

What this is not

• Not a SIEM
• Not an auto-committer
• Portfolio demo assets stay outside the repo

See ROADMAP for Phase 3 Connect.

v0.2.1

Fix

• Schema loaders open NDJSON/JSON with utf-8-sig so UTF-8 BOM-prefixed files (common from Windows editors and PowerShell Set-Content -Encoding utf8) parse cleanly. Previously those files could make detdrift diff exit 2.

Dogfood

Ran against a sparse clone of SigmaHQ/sigma rules/windows/process_creation (~1185 YAML rules) with a synthetic CommandLine to cmd rename (detdrift 0.2.0):

• schema_version: 1
• removed: ['CommandLine']
• 914 IMPACTED (all missing CommandLine)
• 271 SAFE
• 0 UNKNOWN

See docs/dogfood.md.

Version

0.2.1

v0.2.0

Phase 1: stronger field extraction, recursive rule discovery, --fail-on-severity / --fail-on-tag, reusable Action, JSON report schema v1, CONTRIBUTING and SECURITY.