security: add ClusterFuzzLite fuzzing for the SQL-safety kernel (#300)

* security: add ClusterFuzzLite fuzzing for the SQL-safety kernel

Closes Scorecard Fuzzing alert #55. Scorecard's Fuzzing check does not
recognize Python source patterns at all (only Go/Haskell/JS-TS/Erlang);
the only path to real credit for a Python project is OSS-Fuzz or
ClusterFuzzLite deployment. Confirmed via the alert's own rule.help text
before building this, per the standard OSS-Fuzz Python integration
(https://google.github.io/oss-fuzz/getting-started/new-project-guide/python-lang/).

Harness (.clusterfuzzlite/sql_safety_fuzzer.py) targets
SafeSqlDriver._validate — the pglast parse + AST-walker in
mcpg.sql.safety — feeding it arbitrary bytes via Atheris and treating
anything but the documented ValueError as a bug. This is the project's
actual security-critical surface (see CLAUDE.md's "SQL-safety kernel"
section); the existing tests/unit/test_sql_kernel_fuzz.py property tests
cover known-shape adversarial inputs, this harness covers unknown-shape
ones.

Two workflows: cflite_pr.yml (5-minute fuzz run on PRs touching
src/mcpg/sql/** or .clusterfuzzlite/**, address+undefined sanitizers)
and cflite_batch.yml (1-hour daily batch run to build corpus depth over
time).

Also adds .gitattributes rules forcing LF for *.sh and .clusterfuzzlite/**
— these scripts run inside a Linux container and a CRLF-mangled shebang
would break the interpreter on a Windows checkout.

Verified: Atheris 3.1.0 ships wheels for cp312/cp313/cp314, matching
this project's requires-python >=3.12 — no version-compatibility gap on
the fuzzing library itself. Full build/run validated by this PR's own
cflite_pr.yml workflow run (Docker-in-Docker local validation wasn't
available in this session — see PR checks for the real signal).

Entire-Checkpoint: 9d5df8697fd3

* fix: ignore-requires-python in ClusterFuzzLite build (base image is 3.11)

PR #300's own CI run caught this: base-builder-python ships Python
3.11.13, below mcpg's declared floor (requires-python >=3.12, set for
the wider ~254-tool codebase). pip3 install . failed outright on the
version gate before ever reaching the actual code.

The fuzz harness only imports mcpg.sql.safety + its direct deps
(mcpg.sql.allowlist, mcpg.sql.driver) — verified none of the three use
any 3.12-only syntax, so --ignore-requires-python is safe here. Scoped
to the fuzzing container only; pyproject.toml's real floor is untouched.

Entire-Checkpoint: 3b7a9a8d9b30

* fix: keep-unaffected-fuzz-targets on ClusterFuzzLite PR fuzzing

PR #300's own CI run caught another real gap: without this,
build_fuzzers tries to prune "unaffected" targets by diffing against a
coverage baseline artifact (cifuzz-coverage-latest) that can't exist yet
on a brand-new integration — hard-fails with "No fuzz targets found" on
literally the first fuzzing PR ever. There's exactly one fuzz target in
this repo, so the optimization has no upside; keep it unconditionally.

Entire-Checkpoint: c84ca2b91fd2

* fix: restore LLVMFuzzerTestOneInput detection marker in fuzz wrapper

Third real gap PR #300's own CI caught: build succeeded (pyinstaller
packaged the binary fine, keep-unaffected-fuzz-targets sidestepped the
coverage-diff issue), but OSS-Fuzz's bad-build-check still reported "No
fuzz targets found". Root cause: the previous commit's execution-wrapper
heredoc dropped the "# LLVMFuzzerTestOneInput for fuzzer detection."
comment line from the OSS-Fuzz reference example — that line isn't
decorative, it's a literal string the detection step greps wrapper
scripts for to recognize them as fuzz targets. Restored verbatim.

Entire-Checkpoint: 0d81d061fe9a

* fix: scope fuzzer discovery to \$SRC root (Gemini review on #300)

gemini-code-assist correctly flagged: find "\$SRC" -name '*_fuzzer.py'
searches recursively, matching both the Dockerfile's intentional
COPY .clusterfuzzlite/sql_safety_fuzzer.py \$SRC/ and the incidental
copy that COPY . \$SRC/mcpg (the whole repo) also pulls in at
\$SRC/mcpg/.clusterfuzzlite/sql_safety_fuzzer.py. Confirmed in the prior
CI run's own log: two full pyinstaller passes for the same fuzzer,
silently overwriting the \$OUT wrapper the second time. -maxdepth 1
scopes discovery to the intentional copy only.

Entire-Checkpoint: 2bcc94e8e1a8

Author: devopam

.clusterfuzzlite/Dockerfile

@@ -0,0 +1,12 @@
+# ClusterFuzzLite build integration for the SQL-safety kernel
+# (mcpg.sql.safety). See docs/reviews/devendor-sql-kernel-security-review.md
+# for why this parser+AST-walker is the project's security-critical
+# surface. Atheris and the OSS-Fuzz Python toolchain are pre-installed on
+# this base image — see
+# https://google.github.io/oss-fuzz/getting-started/new-project-guide/python-lang/
+FROM gcr.io/oss-fuzz-base/base-builder-python
+
+COPY . $SRC/mcpg
+WORKDIR $SRC/mcpg
+COPY .clusterfuzzlite/build.sh $SRC/
+COPY .clusterfuzzlite/sql_safety_fuzzer.py $SRC/

.clusterfuzzlite/build.sh

@@ -0,0 +1,49 @@
+#!/bin/bash -eu
+# Standard OSS-Fuzz Python build script — see
+# https://google.github.io/oss-fuzz/getting-started/new-project-guide/python-lang/
+# for what each step does and why.
+
+# Build and install mcpg (using current CFLAGS/CXXFLAGS) so its C-extension
+# deps (pglast wraps libpg_query; psycopg's C extension) are compiled with
+# the sanitizer this run is instrumented with.
+#
+# --ignore-requires-python: base-builder-python ships Python 3.11, below
+# this project's declared floor (requires-python >=3.12 in pyproject.toml,
+# set for the wider ~254-tool codebase). The fuzz harness only imports
+# mcpg.sql.safety + its direct deps (mcpg.sql.allowlist, mcpg.sql.driver),
+# none of which use any 3.12-only syntax — verified before adding this
+# flag, not assumed. Loosening pyproject.toml's actual floor for the
+# whole package would be the wrong fix; this scopes the exception to the
+# fuzzing container only.
+pip3 install --ignore-requires-python .
+
+# -maxdepth 1: the Dockerfile COPYs the harness to $SRC/ directly, but
+# `COPY . $SRC/mcpg` also copies the whole repo (including
+# .clusterfuzzlite/sql_safety_fuzzer.py) underneath it — an unbounded
+# find would match both copies of the same file and build the fuzzer
+# twice, silently overwriting $OUT/sql_safety_fuzzer the second time
+# (both matches share the same basename). Confirmed in a real CI run
+# before this fix landed (two full pyinstaller passes in one build log).
+for fuzzer in $(find "$SRC" -maxdepth 1 -name '*_fuzzer.py'); do
+  fuzzer_basename=$(basename -s .py "$fuzzer")
+  fuzzer_package=${fuzzer_basename}.pkg
+
+  # Standalone package via pyinstaller, to avoid Python-version/environment
+  # drift between build time and whenever ClusterFuzzLite replays this
+  # binary later.
+  pyinstaller --distpath "$OUT" --onefile --name "$fuzzer_package" "$fuzzer"
+
+  # Execution wrapper: Atheris needs the sanitizer runtime preloaded, and
+  # this is the file ClusterFuzzLite actually invokes as the fuzz target.
+  # The "LLVMFuzzerTestOneInput" comment isn't decorative — OSS-Fuzz's
+  # fuzzer-detection step greps wrapper scripts for that literal string
+  # to recognize them as fuzz targets; omitting it fails the build with
+  # "No fuzz targets found" even though the binary built fine.
+  echo "#!/bin/sh
+# LLVMFuzzerTestOneInput for fuzzer detection.
+this_dir=\$(dirname \"\$0\")
+LD_PRELOAD=\$this_dir/sanitizer_with_fuzzer.so \
+ASAN_OPTIONS=\$ASAN_OPTIONS:symbolize=1:external_symbolizer_path=\$this_dir/llvm-symbolizer:detect_leaks=0 \
+\$this_dir/$fuzzer_package \$@" > "$OUT/$fuzzer_basename"
+  chmod +x "$OUT/$fuzzer_basename"
+done

.clusterfuzzlite/project.yaml

@@ -0,0 +1,6 @@
+language: python3
+fuzzing_engines:
+  - libfuzzer
+sanitizers:
+  - address
+  - undefined

.clusterfuzzlite/sql_safety_fuzzer.py

@@ -0,0 +1,37 @@
+"""Atheris fuzz harness for the SQL-safety kernel's parse+validate path.
+
+Feeds arbitrary bytes to ``SafeSqlDriver._validate`` — the ``pglast``-based
+parser + AST-walker in ``mcpg.sql.safety`` — and treats anything other than
+the documented ``ValueError`` (malformed or disallowed SQL) as a bug: an
+unhandled exception, a native crash inside the C-based ``pglast`` parser, or
+a hang. This is the project's actual security-critical surface; see
+CLAUDE.md's "SQL-safety kernel" section and
+docs/reviews/devendor-sql-kernel-security-review.md for the threat model
+this complements (that doc covers the adversarial *unit* test suite —
+known-shape attacks; this harness covers unknown-shape inputs).
+"""
+
+import sys
+
+import atheris
+
+with atheris.instrument_imports():
+    from mcpg.sql.safety import SafeSqlDriver
+
+# _validate() only reads the class-level ALLOWED_* policy aliases; the
+# wrapped driver is never touched during validation, so a real SqlDriver
+# is unnecessary here.
+_driver = SafeSqlDriver(sql_driver=None)  # type: ignore[arg-type]
+
+
+def test_one_input(data: bytes) -> None:
+    fdp = atheris.FuzzedDataProvider(data)
+    query = fdp.ConsumeUnicodeNoSurrogates(fdp.remaining_bytes())
+    try:
+        _driver._validate(query)  # fuzzing the private validator directly
+    except ValueError:
+        pass  # expected: malformed or policy-disallowed SQL is rejected
+
+
+atheris.Setup(sys.argv, test_one_input)
+atheris.Fuzz()

.gitattributes

@@ -1 +1,7 @@
 demo_data/*.sql filter=lfs diff=lfs merge=lfs -text
+
+# Scripts that run inside Linux containers (ClusterFuzzLite build, CI) must
+# keep LF endings regardless of the checkout platform's core.autocrlf — a
+# stray \r in a shebang line breaks the interpreter.
+*.sh text eol=lf
+.clusterfuzzlite/** text eol=lf

.github/workflows/cflite_batch.yml

@@ -0,0 +1,30 @@
+name: ClusterFuzzLite batch fuzzing
+on:
+  schedule:
+    - cron: "0 3 * * *" # Daily at 03:00 UTC.
+permissions: read-all
+jobs:
+  BatchFuzzing:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sanitizer:
+          - address
+          - undefined
+    steps:
+      - name: Build Fuzzers (${{ matrix.sanitizer }})
+        id: build
+        uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          language: python
+          sanitizer: ${{ matrix.sanitizer }}
+      - name: Run Fuzzers (${{ matrix.sanitizer }})
+        id: run
+        uses: google/clusterfuzzlite/actions/run_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          fuzz-seconds: 3600
+          mode: "batch"
+          sanitizer: ${{ matrix.sanitizer }}
+          output-sarif: true

.github/workflows/cflite_pr.yml

@@ -0,0 +1,44 @@
+name: ClusterFuzzLite PR fuzzing
+on:
+  pull_request:
+    paths:
+      - "src/mcpg/sql/**"
+      - ".clusterfuzzlite/**"
+permissions: read-all
+jobs:
+  PR:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ matrix.sanitizer }}-${{ github.ref }}
+      cancel-in-progress: true
+    strategy:
+      fail-fast: false
+      matrix:
+        sanitizer:
+          - address
+          - undefined
+    steps:
+      - name: Build Fuzzers (${{ matrix.sanitizer }})
+        id: build
+        uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          language: python
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: ${{ matrix.sanitizer }}
+          # Without this, build_fuzzers tries to diff against a coverage
+          # baseline (a `cifuzz-coverage-latest` artifact) to prune
+          # "unaffected" targets before running — which doesn't exist yet
+          # on a fresh integration (chicken-and-egg on the very first
+          # fuzzing PR) and fails the build outright. There's only one
+          # fuzz target in this repo, so the optimization has no upside
+          # anyway; always keep it.
+          keep-unaffected-fuzz-targets: true
+      - name: Run Fuzzers (${{ matrix.sanitizer }})
+        id: run
+        uses: google/clusterfuzzlite/actions/run_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          fuzz-seconds: 300
+          mode: "code-change"
+          sanitizer: ${{ matrix.sanitizer }}
+          output-sarif: true