feat(ruleset): Phase 2 (task 3) — rules as governed data, severity from policy

Externalize detection rules to versioned TOML and remove rule-local severity, so rules detect and the central CWE policy decides severity — fixing "rules too influential / not centrally managed". Zero-dependency; detection is byte-identical (benchmark recall 44/47 = 93.6%, FP 0% unchanged) and the 90/10 gate holds. - RulesetStore (ruleset/store.py + ruleset/<lang>/rules.toml): PatternRule as data (rule_id, title, languages, cwe, tags, pattern, status, min_evidence_level, precision_estimate, version) with NO severity; load_ruleset (sorted, with optional rule_policy.json ledger overlay) and a stdlib TOML write_ruleset. The 32 rules were generated from the prior PATTERN_RULES with a verified exact round-trip (pattern/cwe/languages/tags/title). - findings.py: drop the hardcoded PatternRule class + PATTERN_RULES tuple; load the default ruleset from TOML; quick_scan_findings(root, targets, rankings, ruleset, policy) resolves each finding's severity from policy via resolve_severity (SEVERITY_LABEL maps 0-5 -> string) and tags findings with their rule status. - Three-status volume control: StaticFinding gains status (default "enabled"); disabled rules never fire; shadow findings are partitioned out of the report and score in the CLI (written to shadow_findings.json) — no shadow rules by default. - Emission floors (RulesetConfig.min_emit_priority / min_emit_precision, default 0.0 = emit all) replace "every match is a finding". - CLI loads the ruleset as a stage and uses it for the fail-loud policy check, detection, hunter pool, and the score CWE map. Wheel ships the ruleset TOML. 85 tests pass; ruff + mypy clean. Spec tasks 3.1-3.4 checked off. Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-10-19 13:10:03 +00:00 · 2026-06-22 15:27:16 +02:00
parent fb7594a3ed
commit 444d8c9490
15 changed files with 645 additions and 347 deletions
@@ -0,0 +1,17 @@
+"""Central, versioned detection ruleset (rules as governed data)."""
+
+from .store import (
+    DEFAULT_RULESET_DIR,
+    PatternRule,
+    RulesetError,
+    load_ruleset,
+    write_ruleset,
+)
+
+__all__ = [
+    "DEFAULT_RULESET_DIR",
+    "PatternRule",
+    "RulesetError",
+    "load_ruleset",
+    "write_ruleset",
+]
@@ -0,0 +1,71 @@
+[[rule]]
+rule_id = "c-exec-family"
+title = "C exec command execution needs review"
+languages = ["c", "cpp"]
+cwe = "CWE-78"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(execl|execlp|execle|execv|execvp|execvpe)\s*\('''
+
+[[rule]]
+rule_id = "c-shell-exec"
+title = "C shell execution needs review"
+languages = ["c", "cpp"]
+cwe = "CWE-78"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(system|popen)\s*\('''
+
+[[rule]]
+rule_id = "c-unsafe-copy"
+title = "Unsafe C string copy needs review"
+languages = ["c", "cpp"]
+cwe = "CWE-121"
+tags = ["memory_unsafe"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(gets|strcpy|strcat|sprintf)\s*\('''
+
+[[rule]]
+rule_id = "c-unsafe-format"
+title = "Unsafe C format string needs review"
+languages = ["c", "cpp"]
+cwe = "CWE-134"
+tags = ["memory_unsafe"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(printf|vprintf|vsprintf|vsnprintf|vfprintf|syslog)\s*\(\s*[A-Za-z_]'''
+
+[[rule]]
+rule_id = "c-unsafe-memory-copy"
+title = "Unsafe C memory copy needs review"
+languages = ["c", "cpp"]
+cwe = "CWE-121"
+tags = ["memory_unsafe"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(memcpy|memmove|bcopy)\s*\('''
+
+[[rule]]
+rule_id = "c-unsafe-scanf"
+title = "Unbounded C scanf needs review"
+languages = ["c", "cpp"]
+cwe = "CWE-121"
+tags = ["memory_unsafe"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(scanf|fscanf|sscanf)\s*\([^\n]*%s'''
@@ -0,0 +1,11 @@
+[[rule]]
+rule_id = "groovy-xss-unescaped"
+title = "Groovy template unescaped output needs review"
+languages = ["groovy"]
+cwe = "CWE-79"
+tags = ["injection"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''(yieldUnescaped)\s+[A-Za-z_]'''
@@ -0,0 +1,47 @@
+[[rule]]
+rule_id = "java-command-exec"
+title = "Java runtime command execution needs review"
+languages = ["java"]
+cwe = "CWE-78"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(exec)\s*\('''
+
+[[rule]]
+rule_id = "java-deserialization"
+title = "Java unsafe deserialization needs review"
+languages = ["java"]
+cwe = "CWE-502"
+tags = ["deserialization"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\.(readObject)\s*\('''
+
+[[rule]]
+rule_id = "java-sql-injection"
+title = "Java SQL string composition needs review"
+languages = ["java"]
+cwe = "CWE-89"
+tags = ["injection"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''(?i)\"\s*(select|insert|update|delete)\b[^\"]*\"\s*\+'''
+
+[[rule]]
+rule_id = "java-weak-hash"
+title = "Java weak hash needs review"
+languages = ["java"]
+cwe = "CWE-327"
+tags = ["crypto"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''MessageDigest\.getInstance\s*\(\s*\"(MD5|SHA-1)\"'''
@@ -0,0 +1,131 @@
+[[rule]]
+rule_id = "js-command-exec"
+title = "Node child_process command execution needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-78"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(exec|execSync)\s*\('''
+
+[[rule]]
+rule_id = "js-deserialize"
+title = "JavaScript unsafe deserialization needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-502"
+tags = ["deserialization"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(unserialize)\s*\('''
+
+[[rule]]
+rule_id = "js-dom-xss"
+title = "DOM sink with untrusted input needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-79"
+tags = ["injection"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\.(innerHTML|outerHTML)\s*=\s*[^\n]*\b(?:req|request|location|document\.location)'''
+
+[[rule]]
+rule_id = "js-eval"
+title = "Dynamic JavaScript evaluation needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-95"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(eval)\s*\('''
+
+[[rule]]
+rule_id = "js-function-constructor"
+title = "JavaScript Function constructor needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-95"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''new\s+(Function)\s*\('''
+
+[[rule]]
+rule_id = "js-path-traversal"
+title = "Node filesystem access with external input needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-22"
+tags = ["filesystem_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\bfs\.(readFile|readFileSync|writeFile|writeFileSync|createReadStream|unlink|unlinkSync)\s*\(\s*[^\n]*\b(?:req|request)\.'''
+
+[[rule]]
+rule_id = "js-spawn-shell"
+title = "Node spawn with shell needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-78"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(spawn|spawnSync)\s*\([^\n]*shell\s*:\s*true'''
+
+[[rule]]
+rule_id = "js-sql-injection"
+title = "JavaScript SQL string composition needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-89"
+tags = ["injection"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\.(query|execute)\s*\(\s*[^\n]*(?:\$\{|\+\s*[A-Za-z_$])'''
+
+[[rule]]
+rule_id = "js-ssrf"
+title = "JavaScript outbound request with external input needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-918"
+tags = ["network_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(axios|fetch|got)\s*[.(][^\n]*\b(?:req|request)\.'''
+
+[[rule]]
+rule_id = "js-weak-hash"
+title = "JavaScript weak hash needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-327"
+tags = ["crypto"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''createHash\s*\(\s*[\"'](md5|sha1)[\"']'''
+
+[[rule]]
+rule_id = "js-xss-response"
+title = "Unsanitized HTTP response reflection needs review"
+languages = ["javascript", "typescript"]
+cwe = "CWE-79"
+tags = ["injection"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\.(send|write|end)\s*\(\s*[^\n]*\b(?:req|request)\.(?:query|params|body)'''
@@ -0,0 +1,119 @@
+[[rule]]
+rule_id = "python-flask-debug"
+title = "Flask debug mode enabled needs review"
+languages = ["python"]
+cwe = "CWE-489"
+tags = ["insecure_default"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\.run\s*\([^\n]*(debug)\s*=\s*True'''
+
+[[rule]]
+rule_id = "python-os-command"
+title = "Python OS command execution needs review"
+languages = ["python"]
+cwe = "CWE-78"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(os\.system|os\.popen|os\.execl|os\.execlp|os\.execv|os\.execvp)\s*\('''
+
+[[rule]]
+rule_id = "python-path-traversal"
+title = "Python file open with external input needs review"
+languages = ["python"]
+cwe = "CWE-22"
+tags = ["filesystem_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(open)\s*\(\s*[^\n]*(?:request\.|req\.|argv|input\s*\(|params\[|GET\[|POST\[)'''
+
+[[rule]]
+rule_id = "python-shell-true"
+title = "Subprocess shell execution needs review"
+languages = ["python"]
+cwe = "CWE-78"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''subprocess\.[a-zA-Z_]+\s*\([^\n]*shell\s*=\s*True'''
+
+[[rule]]
+rule_id = "python-sql-injection"
+title = "Python SQL string composition needs review"
+languages = ["python"]
+cwe = "CWE-89"
+tags = ["injection"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''(\.execute)\s*\(\s*[^\n]*(?:[\"']\s*%\s*[(A-Za-z_]|\.format\s*\(|[\"']\s*\+|\bf[\"'])'''
+
+[[rule]]
+rule_id = "python-ssrf"
+title = "Python outbound request with external input needs review"
+languages = ["python"]
+cwe = "CWE-918"
+tags = ["network_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(requests\.(?:get|post|put|delete|head|patch)|urllib\.request\.urlopen|urlopen)\s*\(\s*[^\n]*(?:request\.|req\.|argv|input\s*\()'''
+
+[[rule]]
+rule_id = "python-ssti"
+title = "Python server-side template injection needs review"
+languages = ["python"]
+cwe = "CWE-94"
+tags = ["injection"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(render_template_string)\s*\('''
+
+[[rule]]
+rule_id = "python-unsafe-deserialization"
+title = "Unsafe Python deserialization needs review"
+languages = ["python"]
+cwe = "CWE-502"
+tags = ["deserialization"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(pickle\.loads|pickle\.load|cPickle\.loads|yaml\.load|marshal\.loads)\s*\('''
+
+[[rule]]
+rule_id = "python-unsafe-eval"
+title = "Dynamic Python execution needs review"
+languages = ["python"]
+cwe = "CWE-95"
+tags = ["syscall_entry"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\b(eval|exec)\s*\('''
+
+[[rule]]
+rule_id = "python-weak-hash"
+title = "Python weak hash needs review"
+languages = ["python"]
+cwe = "CWE-327"
+tags = ["crypto"]
+status = "enabled"
+min_evidence_level = "static_corroboration"
+precision_estimate = 0.0
+version = "1"
+pattern = '''\bhashlib\.(md5|sha1)\s*\('''
@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import tomllib
+from collections.abc import Iterable
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+DEFAULT_RULESET_DIR = Path(__file__).parent
+VALID_STATUS = ("enabled", "shadow", "disabled")
+
+
+class RulesetError(ValueError):
+    """Raised when a ruleset data file is malformed."""
+
+
+@dataclass(frozen=True)
+class PatternRule:
+    """A detection rule expressed as governed data (no rule-local severity).
+
+    ``pattern`` is human-PR-only; the self-improvement loop may only change
+    ``status``/``min_evidence_level``/``precision_estimate`` via the ledger.
+    """
+
+    rule_id: str
+    title: str
+    languages: tuple[str, ...]
+    cwe: str
+    tags: tuple[str, ...]
+    pattern: str
+    status: str = "enabled"
+    min_evidence_level: str = "static_corroboration"
+    precision_estimate: float = 0.0
+    version: str = "1"
+
+
+def load_ruleset(directory: Path = DEFAULT_RULESET_DIR, ledger: Path | None = None) -> tuple[PatternRule, ...]:
+    """Load every ``*.toml`` rule file under ``directory`` and apply the loop ledger.
+
+    Rules are returned sorted by ``rule_id`` for determinism. The optional ledger
+    (``rule_policy.json``) overlays loop-owned ``status``/``min_evidence_level``/
+    ``precision_estimate`` per ``rule_id``.
+    """
+    rules: dict[str, PatternRule] = {}
+    for path in sorted(directory.rglob("*.toml")):
+        payload = tomllib.loads(path.read_text())
+        for item in payload.get("rule", []):
+            rule = _rule_from_dict(item, path)
+            if rule.rule_id in rules:
+                raise RulesetError(f"duplicate rule_id {rule.rule_id!r} in {path}")
+            rules[rule.rule_id] = rule
+    overlay = _load_ledger(ledger)
+    resolved = [_apply_overlay(rule, overlay.get(rule.rule_id)) for rule in rules.values()]
+    return tuple(sorted(resolved, key=lambda rule: rule.rule_id))
+
+
+def write_ruleset(path: Path, rules: Iterable[PatternRule]) -> None:
+    """Write rules as TOML. Patterns use literal multi-line strings (no escaping)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    blocks: list[str] = []
+    for rule in rules:
+        if "'''" in rule.pattern:
+            raise RulesetError(f"rule {rule.rule_id} pattern cannot contain a triple single-quote")
+        blocks.append(
+            "\n".join(
+                [
+                    "[[rule]]",
+                    f"rule_id = {_s(rule.rule_id)}",
+                    f"title = {_s(rule.title)}",
+                    f"languages = {_arr(rule.languages)}",
+                    f"cwe = {_s(rule.cwe)}",
+                    f"tags = {_arr(rule.tags)}",
+                    f"status = {_s(rule.status)}",
+                    f"min_evidence_level = {_s(rule.min_evidence_level)}",
+                    f"precision_estimate = {float(rule.precision_estimate)}",
+                    f"version = {_s(rule.version)}",
+                    f"pattern = '''{rule.pattern}'''",
+                ]
+            )
+        )
+    path.write_text("\n\n".join(blocks) + "\n")
+
+
+def _rule_from_dict(item: dict[str, object], path: Path) -> PatternRule:
+    try:
+        rule_id = str(item["rule_id"])
+        cwe = str(item["cwe"])
+        pattern = str(item["pattern"])
+    except KeyError as exc:
+        raise RulesetError(f"rule in {path} missing required field {exc}") from exc
+    status = str(item.get("status", "enabled"))
+    if status not in VALID_STATUS:
+        raise RulesetError(f"rule {rule_id} has invalid status {status!r}")
+    if not pattern:
+        raise RulesetError(f"rule {rule_id} has an empty pattern")
+    return PatternRule(
+        rule_id=rule_id,
+        title=str(item.get("title", rule_id)),
+        languages=_str_tuple(item.get("languages")),
+        cwe=cwe,
+        tags=_str_tuple(item.get("tags")),
+        pattern=pattern,
+        status=status,
+        min_evidence_level=str(item.get("min_evidence_level", "static_corroboration")),
+        precision_estimate=float(item.get("precision_estimate", 0.0)),  # type: ignore[arg-type]
+        version=str(item.get("version", "1")),
+    )
+
+
+def _load_ledger(ledger: Path | None) -> dict[str, dict[str, object]]:
+    if ledger is None or not ledger.exists():
+        return {}
+    payload = json.loads(ledger.read_text())
+    return {str(key): value for key, value in payload.items() if isinstance(value, dict)}
+
+
+def _apply_overlay(rule: PatternRule, overlay: dict[str, object] | None) -> PatternRule:
+    if not overlay:
+        return rule
+    status = str(overlay.get("status", rule.status))
+    if status not in VALID_STATUS:
+        status = rule.status
+    return replace(
+        rule,
+        status=status,
+        min_evidence_level=str(overlay.get("min_evidence_level", rule.min_evidence_level)),
+        precision_estimate=float(overlay.get("precision_estimate", rule.precision_estimate)),  # type: ignore[arg-type]
+    )
+
+
+def _str_tuple(value: object) -> tuple[str, ...]:
+    if isinstance(value, list):
+        return tuple(str(item) for item in value)
+    return ()
+
+
+def _s(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _arr(values: tuple[str, ...]) -> str:
+    return "[" + ", ".join(_s(value) for value in values) + "]"