docs: reference detection spec for REP-001 + spec/catalog sync guard (roadmap #8) - #97
Merged
Merged
Conversation
…(roadmap #8) Blueprint differentiator 5 promises telemetry and detection ship together, but the ndr_rule/ndr_uc labels had no rule content behind them. This authors the first reference detection spec, phased on the pilot technique. - docs/detection-specs/REP-001.md: NDR-C2-001, the periodicity detection its telemetry is shaped to exercise. SIEM-neutral pseudocode (grouped inter-arrival CV + tight byte band), thresholds derived from the catalog presets (jitter -> CV bound), the load-bearing FP tuning (legit software beacons are periodic too; allowlist known-good egress; browsing separates on record count and byte variance per the benign baseline), how to exercise it with --pace plan, and what a green result does and does not prove (transferability transfers; delivery loopback-only until first observed fire). - docs/detection-specs/README.md: the phased index (pilot, then parser-only, then the rest after first fire) and the not-a-generated-rule boundary. - tests/test_detection_specs.py: fails when the catalog moves (rule id, uc, ATT&CK technique, transferability) and a spec does not follow, and when a spec file names a technique that does not exist. Written documentation only; no Sigma/AIE rule is generated at runtime. 1092 tests; gates clean.
… en-dash From /code-review on PR #97, verified before fixing: - The guard proved less than its name claimed (the recurring class). It now parses each spec's own header TABLE and asserts exact matches, generic across every REP-*.md so a new spec is guarded the moment it lands: - ATT&CK is an exact set comparison, so a spec still naming a technique the catalog dropped fails (presence-only could not catch that). - Transferability is read from the header cell, not matched anywhere in prose. - Rule id / use case / technique read from the header cell. - Added a REP-001 preset guard (interval per intensity, dpt_choices) for the README's 'every threshold ties to a catalog preset' promise. Positive control: flipping the transferability cell to contradict the catalog turns it red. - Index sync now checks rule id, use case AND filename per authored spec. - Non-vacuous: pins the pilot spec exists so the glob-driven tests exercise something. - A guard that no spec carries an em- or en-dash (both banned in docs). Fixes the one en-dash the earlier em-dash-only grep missed (150-2000). 1094 tests; black/ruff/mypy clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Roadmap 2026-09 item 8, phased on the pilot technique. Blueprint differentiator 5 promises telemetry and detection ship together, but the
ndr_rule/ndr_uclabels had no rule content behind them. This authors the first reference detection spec.What's new
docs/detection-specs/REP-001.md— NDR-C2-001, the periodicity detection REP-001's telemetry is shaped to exercise:(src, dst, dpt), measure inter-arrival coefficient of variation + a tight byte band.cv_max = 0.25clears all three presets while excluding human traffic).--pace plan), and what a green result does and does not prove (transferability = transfers; delivery loopback-only until first observed fire).docs/detection-specs/README.md— the phased index (pilot → parser-only → the rest after first fire) and the not-a-generated-rule boundary.tests/test_detection_specs.py— fails when the catalog moves (rule id, UC, ATT&CK technique, transferability) and a spec does not follow, and when a spec file names a non-existent technique. This is the drift guard the project's "no test asserts the docs match the code" lesson calls for.Written documentation only; no Sigma/AIE rule is generated at runtime (respecting the standing constraint). 1092 tests; gates clean. Decision record:
docs/roadmap-2026-09.md.