feat(scanner): checkpoint schema, redaction guard, CI self-test (PR-06) (#35)

- schemas/dsgai-scan.schema.json: formal schema for DSGAI-scan.json that
  FORBIDS match_text/content/value/raw_grep_output on every finding
  ('field': false, not 'not/required' which would miss a lone field). The
  redaction guarantee is now machine-checkable.
- CLI self-validates the checkpoint (stdlib, no jsonschema at runtime) before
  writing and refuses to emit a finding carrying match content (exit 2).
- checkpoint_is_valid(): cache invalidation — a checkpoint may be reused only at
  the current HEAD, on a clean tree, with the current ruleset. The skill's
  resume logic uses this from PR-07 on; never serve stale findings with a fresh
  date.
- .github/workflows/scanner-selftest.yml: installs ripgrep, runs pytest,
  validates the ruleset + a fixture scan against their schemas, and asserts the
  JSON stays in sync with the YAML. This is the gate that makes external rule
  PRs safely mergeable.
- Fixed the PCRE compile check to key on rg's exit code (>=2) instead of the
  string 'regex parse error' — PCRE2 emits a different message, so the old
  check would have missed a broken PCRE2 pattern (and not failed CI). Added a
  guard-the-guard test.

Acceptance: pytest green (16 checks); schema rejects a match_text finding
(negative test); a deliberately broken PCRE is detected by exit code.

Author: emmanuelgjr

.github/workflows/scanner-selftest.yml

@@ -0,0 +1,63 @@
+name: scanner-selftest
+
+# The gate that makes external rule PRs safely mergeable: installs ripgrep,
+# runs the pytest suite, and validates the ruleset + a fixture scan against
+# their schemas. Path-filtered to the scanner subproject.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'dsgai_scanner_tool/**'
+      - '.github/workflows/scanner-selftest.yml'
+  pull_request:
+    paths:
+      - 'dsgai_scanner_tool/**'
+      - '.github/workflows/scanner-selftest.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  selftest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: '3.11'
+
+      - name: Install ripgrep (with PCRE2)
+        run: sudo apt-get update -qq && sudo apt-get install -y ripgrep
+
+      - name: Install dev dependencies
+        run: python -m pip install --quiet -r dsgai_scanner_tool/requirements-dev.txt
+
+      - name: Validate ruleset against its schema
+        run: |
+          python -c "import yaml, json, jsonschema; \
+            jsonschema.validate(yaml.safe_load(open('dsgai_scanner_tool/rules/dsgai-rules.yaml')), \
+            json.load(open('dsgai_scanner_tool/rules/rules.schema.json'))); \
+            print('ruleset schema OK')"
+
+      - name: Assert compiled JSON is in sync with YAML
+        run: python dsgai_scanner_tool/build/build_rules_json.py --check
+
+      - name: Run the self-test suite
+        working-directory: dsgai_scanner_tool
+        run: python -m pytest tests/test_runner.py -q
+
+      - name: Validate a fixture scan against the checkpoint + SARIF schemas
+        working-directory: dsgai_scanner_tool
+        run: |
+          python cli/dsgai_scan.py scan tests/fixtures/vulnerable-app \
+            --json-out /tmp/DSGAI-scan.json --sarif /tmp/scan.sarif --format none || true
+          python -c "import json, jsonschema; \
+            jsonschema.validate(json.load(open('/tmp/DSGAI-scan.json')), \
+            json.load(open('schemas/dsgai-scan.schema.json'))); \
+            print('checkpoint schema OK')"
+          python -c "import json; s=json.load(open('/tmp/scan.sarif')); \
+            assert s['version']=='2.1.0' and s['runs'][0]['tool']['driver']['name']=='dsgai-scan'; \
+            print('SARIF OK')"

dsgai_scanner_tool/CHANGES_v0.3.md

@@ -44,6 +44,15 @@ dates are ISO-8601. The previous line is recorded in [`CHANGES_v0.2.md`](CHANGES
   (9 tests) asserts every PCRE compiles, the fixture scan matches the answer sheet
   exactly, SARIF validity, and the redaction guarantee. `requirements-dev.txt` +
   dependabot `pip` for the scanner. (PR-05)
+- **Checkpoint schema + CI self-test**: `schemas/dsgai-scan.schema.json` formalizes
+  `DSGAI-scan.json` and **forbids** `match_text`/`content`/`value`/`raw_grep_output` on
+  every finding (`"field": false`), making the redaction guarantee machine-checkable.
+  The CLI self-validates its checkpoint (stdlib) before writing and gained a
+  cache-invalidation check (`checkpoint_is_valid`: reuse only at current HEAD, clean
+  tree, matching ruleset). New `.github/workflows/scanner-selftest.yml` installs
+  ripgrep, runs pytest, and validates the ruleset + a fixture scan against their schemas
+  — the gate that makes external rule PRs safely mergeable. The PCRE compile check now
+  keys on rg's exit code (catches PCRE2 errors the old substring check missed). (PR-06)
 
 ### Changed
 - `DSGAI-samplereport.png` compressed from ~5.0 MB to ~0.35 MB (14×) as an interim fix;

dsgai_scanner_tool/cli/dsgai_scan.py

@@ -30,6 +30,14 @@
 SKILL_VERSION = "0.3.0"
 
 VALUE_BEARING_CONTROLS = {"DSGAI02", "DSGAI13", "DSGAI14", "DSGAI15"}
+# Fields that must never appear on a finding — the redaction guarantee, enforced
+# in code before the checkpoint is written (and by schemas/dsgai-scan.schema.json).
+BANNED_FINDING_FIELDS = {"match_text", "content", "value", "raw_grep_output"}
+CHECKPOINT_REQUIRED = {
+    "schema_version", "ruleset_version", "skill_version", "framework", "engine",
+    "git_commit", "scanned_at", "scan_scope", "obfuscation", "controls",
+    "findings", "cves", "file_map_ref",
+}
 SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", "env",
              "dist", "build", ".mypy_cache", ".pytest_cache", ".tox", ".idea"}
 
@@ -349,6 +357,41 @@ def build_checkpoint(ruleset, findings, controls, scope, obfuscation, target):
     }
 
 
+def self_validate_checkpoint(cp):
+    """Stdlib self-check run before writing the checkpoint (no jsonschema at
+    runtime). Enforces required fields and the redaction guarantee."""
+    missing = CHECKPOINT_REQUIRED - set(cp)
+    if missing:
+        raise ValueError(f"checkpoint missing required fields: {sorted(missing)}")
+    for f in cp["findings"]:
+        leaked = BANNED_FINDING_FIELDS & set(f)
+        if leaked:
+            raise ValueError(f"finding would leak match content via {sorted(leaked)}: "
+                             f"{f.get('rule_id')} {f.get('path')}")
+    return True
+
+
+def checkpoint_is_valid(cp, target, current_ruleset_version):
+    """Cache invalidation: a checkpoint may be reused only if it was produced at
+    the current HEAD, on a clean working tree, with the current ruleset. Anything
+    else means the findings could be stale — delete and rescan. A compliance
+    artifact must never serve stale findings with a fresh date. (The skill's
+    resume logic calls this from PR-07 on.)"""
+    if cp.get("ruleset_version") != current_ruleset_version:
+        return False
+    head = git_commit(target)
+    if not head or cp.get("git_commit") != head:
+        return False
+    try:
+        r = subprocess.run(["git", "-C", os.path.abspath(target), "status", "--porcelain"],
+                           capture_output=True, text=True)
+        if r.returncode != 0 or r.stdout.strip():
+            return False  # dirty working tree
+    except Exception:
+        return False
+    return True
+
+
 SARIF_LEVEL = {"fail": "error", "warn": "warning", "pass_signal": "note",
                "count": "note", "info": "note"}
 
@@ -440,6 +483,12 @@ def cmd_scan(args):
     checkpoint = build_checkpoint(ruleset, findings, controls, scope,
                                   args.obfuscation, args.target)
 
+    try:
+        self_validate_checkpoint(checkpoint)
+    except ValueError as exc:
+        eprint(f"error: refusing to write an invalid checkpoint: {exc}")
+        return 2
+
     if args.format == "table":
         print_table(controls, findings)
     if args.json_out:

dsgai_scanner_tool/schemas/dsgai-scan.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/GenAI-Security-Project/GenAI-Data-Security-Initiative/dsgai_scanner_tool/schemas/dsgai-scan.schema.json",
+  "title": "DSGAI scan checkpoint (DSGAI-scan.json)",
+  "description": "Formal schema for the scanner checkpoint. Forbidding match_text/content/value/raw_grep_output on every finding makes the redaction guarantee machine-checkable.",
+  "type": "object",
+  "required": [
+    "schema_version", "ruleset_version", "skill_version", "framework",
+    "engine", "git_commit", "scanned_at", "scan_scope", "obfuscation",
+    "controls", "findings", "cves", "file_map_ref"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "ruleset_version": { "type": "string" },
+    "skill_version": { "type": "string" },
+    "framework": { "type": "string", "pattern": "^dsgai-[0-9]{4}-v[0-9]+\\.[0-9]+$" },
+    "engine": { "enum": ["deterministic-cli", "llm-grep"] },
+    "git_commit": { "type": ["string", "null"] },
+    "scanned_at": { "type": "string" },
+    "scan_scope": { "type": "string" },
+    "obfuscation": { "enum": ["strict", "internal"] },
+    "controls": {
+      "type": "object",
+      "additionalProperties": {
+        "enum": ["PASS", "WARN", "FAIL", "NOT VALIDATED", "NOT APPLICABLE",
+                 "VENDOR ATTESTATION REQUIRED"]
+      }
+    },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+    "cves": { "type": "array" },
+    "file_map_ref": { "type": ["string", "null"] }
+  },
+  "$defs": {
+    "finding": {
+      "type": "object",
+      "required": ["control", "rule_id", "path", "line", "status", "classification"],
+      "additionalProperties": false,
+      "properties": {
+        "control": { "type": "string", "pattern": "^DSGAI[0-9]{2}$" },
+        "rule_id": { "type": "string", "pattern": "^P[0-9]{2}\\.[0-9]+$" },
+        "path": { "type": "string", "minLength": 1 },
+        "line": { "type": "integer", "minimum": 1 },
+        "status": { "enum": ["fail", "warn", "pass_signal", "count", "info"] },
+        "classification": { "enum": ["structural", "value_bearing"] },
+        "note": { "type": "string" },
+
+        "match_text": false,
+        "content": false,
+        "value": false,
+        "raw_grep_output": false
+      }
+    }
+  }
+}

dsgai_scanner_tool/tests/test_runner.py

@@ -25,6 +25,8 @@
 SHEET = os.path.join(HERE, "expected-findings.yaml")
 RULES_YAML = os.path.join(SCANNER, "rules", "dsgai-rules.yaml")
 RULES_JSON = os.path.join(SCANNER, "rules", "dsgai-rules.json")
+RULES_SCHEMA = os.path.join(SCANNER, "rules", "rules.schema.json")
+SCAN_SCHEMA = os.path.join(SCANNER, "schemas", "dsgai-scan.schema.json")
 BANNED_FIELDS = {"match_text", "content", "value", "raw_grep_output"}
 
 
@@ -67,11 +69,24 @@ def test_all_pcres_compile():
     for r in _rules():
         p = subprocess.run([rg, "--pcre2", "-q", "-e", r["pcre"]],
                            input="x\n", capture_output=True, text=True)
-        if p.returncode >= 2 and "regex parse error" in p.stderr:
-            bad.append(r["id"])
+        # rg exit codes: 0 match, 1 no match, >=2 error (incl. any regex/PCRE2
+        # compile failure — the message differs between engines, so key on the
+        # exit code, not a substring).
+        if p.returncode >= 2:
+            bad.append((r["id"], p.stderr.strip()[:120]))
     assert not bad, f"PCREs failed to compile: {bad}"
 
 
+@requires_rg
+def test_compile_check_catches_a_broken_pattern():
+    """Guard the guard: a deliberately invalid PCRE must be detected, so a
+    corrupted rule really does fail CI."""
+    rg = _rg()
+    p = subprocess.run([rg, "--pcre2", "-q", "-e", "(unterminated[class"],
+                       input="x\n", capture_output=True, text=True)
+    assert p.returncode >= 2
+
+
 @requires_rg
 def test_scan_matches_sheet_exactly(scan, sheet):
     def key(f):
@@ -144,6 +159,53 @@ def test_value_bearing_execution_always_replaces():
     assert "--replace" in window, "value-bearing branch does not pass --replace"
 
 
+@requires_rg
+def test_checkpoint_validates_against_schema(scan):
+    jsonschema = pytest.importorskip("jsonschema")
+    schema = json.loads(open(SCAN_SCHEMA, encoding="utf-8").read())
+    jsonschema.validate(scan["json"], schema)
+
+
+def test_scan_schema_rejects_match_text():
+    """The redaction guarantee is machine-checkable: a finding carrying match
+    content must be rejected by the checkpoint schema."""
+    jsonschema = pytest.importorskip("jsonschema")
+    schema = json.loads(open(SCAN_SCHEMA, encoding="utf-8").read())
+    bad = {
+        "schema_version": "1.0", "ruleset_version": "0.3.0", "skill_version": "0.3.0",
+        "framework": "dsgai-2026-v1.0", "engine": "deterministic-cli",
+        "git_commit": None, "scanned_at": "2023-11-14T22:13:20+00:00",
+        "scan_scope": ".", "obfuscation": "strict", "controls": {},
+        "findings": [{
+            "control": "DSGAI02", "rule_id": "P02.1", "path": "config.py",
+            "line": 7, "status": "fail", "classification": "value_bearing",
+            "match_text": "sk-proj-LEAKED",
+        }],
+        "cves": [], "file_map_ref": None,
+    }
+    with pytest.raises(jsonschema.ValidationError):
+        jsonschema.validate(bad, schema)
+
+
+def test_rules_validate_against_schema():
+    jsonschema = pytest.importorskip("jsonschema")
+    rules = yaml.safe_load(open(RULES_YAML, encoding="utf-8"))
+    schema = json.loads(open(RULES_SCHEMA, encoding="utf-8").read())
+    jsonschema.validate(rules, schema)
+
+
+def test_cli_self_guard_rejects_leaked_finding():
+    """The CLI's runtime (stdlib) self-check must refuse to write a checkpoint
+    whose finding carries match content — independent of jsonschema."""
+    sys.path.insert(0, os.path.join(SCANNER, "cli"))
+    import dsgai_scan
+    cp = {k: v for k, v in zip(dsgai_scan.CHECKPOINT_REQUIRED,
+                               [None] * len(dsgai_scan.CHECKPOINT_REQUIRED))}
+    cp["findings"] = [{"rule_id": "P02.1", "path": "x", "match_text": "sk-LEAK"}]
+    with pytest.raises(ValueError):
+        dsgai_scan.self_validate_checkpoint(cp)
+
+
 def test_rules_json_in_sync():
     from_yaml = yaml.safe_load(open(RULES_YAML, encoding="utf-8"))
     rebuilt = json.dumps(from_yaml, indent=2, sort_keys=True, ensure_ascii=False) + "\n"