chore(fuzz): add ClusterFuzzLite targets for the untrusted input surface

Mirrors agentrust-io/agent-manifest#405, which is merged and where the same
approach found a real bug in the COSE decoders on its first run.

Scorecard's Fuzzing check does not recognise Hypothesis or Atheris on their
own, so Python property tests would not have moved it. ClusterFuzzLite is what
it detects, and it runs real coverage-guided fuzzing rather than only
satisfying the check.

Two targets, on what arrives before anything about it has been verified:

  fuzz_attestation_parsers.py  parse_event_log walks a TCG event log, whose
                               Spec ID header declares digest algorithms and
                               lengths and whose every event declares its own
                               digest count and data length. parse_nv_certify
                               reads a size-prefixed TPM NV certification.
  fuzz_canonical_json.py       the bytes a catalog approval signature covers.

The parser target asserts each function fails closed: it returns, or raises the
ValueError its module documents. The canonicalizer target asserts a round trip
rather than absence of a crash, because the three RFC 8785 bugs found in the
sibling agent-manifest canonicalizer were all silent.

Standing when added: both parsers already fail closed under a local probe of
12,000 mutated inputs, and the canonicalizer round-tripped 17,918 generated
documents while refusing 12,080 as declared, with no invariant violation. These
are regression guards, not holes being closed.

Carries both fixes agent-manifest paid for: --collect-submodules=email, without
which PyInstaller misses the lazy import and libFuzzer reports the runtime
ModuleNotFoundError as a crash in the target; and a 45 minute budget, since the
oss-fuzz base image build dominates.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XbDBXDWWvMFa7c2jGgyq9t

Author: imran-siddique

.clusterfuzzlite/Dockerfile

@@ -0,0 +1,5 @@
+FROM gcr.io/oss-fuzz-base/base-builder-python
+
+COPY . $SRC/cmcp
+COPY .clusterfuzzlite/build.sh $SRC/build.sh
+WORKDIR $SRC/cmcp

.clusterfuzzlite/README.md

@@ -0,0 +1,62 @@
+# Fuzzing
+
+Coverage-guided fuzzing via [ClusterFuzzLite](https://google.github.io/clusterfuzzlite/),
+running Atheris against the untrusted input surface. Mirrors the setup in
+agentrust-io/agent-manifest, where the same targets found a real bug.
+
+## What is fuzzed
+
+| Target | Surface |
+| --- | --- |
+| `fuzz_attestation_parsers.py` | `parse_event_log` walks a TCG event log: a Spec ID header declaring which digest algorithms are present and how long each is, then events each carrying their own declared digest count and data length. `parse_nv_certify` reads a bare or size-prefixed TPM NV certification. Every one of those lengths comes from the blob, which arrives from the platform before anything about it is verified. |
+| `fuzz_canonical_json.py` | The bytes a catalog approval signature covers. |
+
+## The properties
+
+The parser target asserts each function fails closed: it returns, or raises the
+`ValueError` its module documents (`EventLogError` is a `ValueError`). A
+`struct.error`, `IndexError`, `MemoryError` or `OverflowError` reaching the
+caller means a declared length was believed.
+
+`fuzz_canonical_json.py` asserts a round trip: parsing the canonical output must
+reproduce the input. That is stronger than checking for a crash, deliberately.
+The three RFC 8785 bugs found in the sibling agent-manifest canonicalizer in
+September 2026 were all silent; the sharpest normalized two distinct object keys
+into one, so the output carried that key twice and a field disappeared from a
+document whose signature claimed to cover it. Nothing raised. cmcp does not have
+that bug, and this is what keeps it that way.
+
+Equality is asserted up to JSON's number model, since JSON has one number type
+and a large float legitimately re-parses as an int.
+
+## Standing when added
+
+Both parsers already fail closed: a local probe of 12,000 mutated inputs found
+no undeclared exception escaping either. The canonicalizer is clean too: 17,918
+generated documents round-tripped and 12,080 were refused as declared, with no
+invariant violation. These are regression guards.
+
+## Bundling gotcha
+
+`compile_python_fuzzer` bundles each target with PyInstaller, which follows
+static imports only. The cryptography and pydantic stacks reach `email.mime`
+lazily, so without help the bundled target dies at runtime with
+`ModuleNotFoundError: No module named 'email.mime'`, and libFuzzer reports that
+as a crash in the target rather than a build problem. `build.sh` passes
+`--collect-submodules=email`. A new dependency with a lazy import can need the
+same treatment.
+
+## Running locally
+
+```
+git clone https://github.com/google/clusterfuzzlite --depth 1 /tmp/clusterfuzzlite
+python /tmp/clusterfuzzlite/infra/helper.py build_image --external $PWD
+python /tmp/clusterfuzzlite/infra/helper.py build_fuzzers --external --sanitizer address $PWD
+python /tmp/clusterfuzzlite/infra/helper.py run_fuzzer --external $PWD fuzz_canonical_json
+```
+
+## In CI
+
+`cflite_pr.yml` fuzzes only code the pull request touched, for five minutes.
+`cflite_batch.yml` runs every target for an hour, nightly. Both are read-only.
+Budget 45 minutes for the PR job: the oss-fuzz base image build dominates.

.clusterfuzzlite/build.sh

@@ -0,0 +1,19 @@
+#!/bin/bash -eu
+# Build the fuzz targets for ClusterFuzzLite.
+#
+# Installed rather than put on the path so the targets exercise the same import
+# surface a consumer gets.
+
+cd "$SRC/cmcp"
+pip3 install --no-cache-dir .
+
+# compile_python_fuzzer bundles each target with PyInstaller, which follows
+# static imports only. The cryptography and pydantic stacks reach email.mime
+# lazily, so without this the bundled target dies at runtime with
+# "ModuleNotFoundError: No module named 'email.mime'" and libFuzzer reports it
+# as a crash in the target.
+PYI_ARGS=(--collect-submodules=email)
+
+for target in "$SRC"/cmcp/.clusterfuzzlite/fuzz_*.py; do
+  compile_python_fuzzer "$target" "${PYI_ARGS[@]}"
+done

.clusterfuzzlite/fuzz_attestation_parsers.py

@@ -0,0 +1,48 @@
+#!/usr/bin/python3
+"""Fuzz the attestation blob parsers in cmcp_verify.
+
+parse_event_log walks a TCG event log: a Spec ID header that declares which
+digest algorithms are present and how long each one is, then a run of events
+each carrying its own declared digest count and data length. Every one of those
+numbers comes from the blob being parsed, and the log arrives from the platform
+before anything about it has been verified.
+
+parse_nv_certify reads a bare or size-prefixed TPM NV certification, where a
+length prefix decides how much of the rest is structure.
+
+The property is that each parser fails closed: it returns, or raises the
+ValueError its module documents (EventLogError is a ValueError). A struct.error,
+IndexError, MemoryError or OverflowError reaching the caller means a declared
+length was believed, and callers written against the documented exception will
+not catch it.
+"""
+import sys
+
+import atheris
+
+with atheris.instrument_imports():
+    from cmcp_verify.nv_certify import parse_nv_certify
+    from cmcp_verify.tcg_event_log import parse_event_log
+
+_TARGETS = [parse_event_log, parse_nv_certify]
+
+
+def TestOneInput(data: bytes) -> None:
+    if not data:
+        return
+    fdp = atheris.FuzzedDataProvider(data)
+    parser = _TARGETS[fdp.ConsumeIntInRange(0, len(_TARGETS) - 1)]
+    blob = fdp.ConsumeBytes(fdp.remaining_bytes())
+    try:
+        parser(blob)
+    except ValueError:
+        pass
+
+
+def main() -> None:
+    atheris.Setup(sys.argv, TestOneInput)
+    atheris.Fuzz()
+
+
+if __name__ == "__main__":
+    main()

.clusterfuzzlite/fuzz_canonical_json.py

@@ -0,0 +1,110 @@
+#!/usr/bin/python3
+"""Fuzz the canonicalizer that catalog approvals are signed over.
+
+canonical_json() produces the bytes an approval signature covers, so those bytes
+have to be a faithful, lossless encoding of the input. The property asserted
+here is a round trip: parsing the canonical output must reproduce the input.
+
+That is stronger than checking for a crash, deliberately. The three RFC 8785
+bugs found in the sibling agent-manifest canonicalizer in September 2026 were
+all silent. The sharpest was NFC normalization of object keys: two distinct keys
+normalized to one, the output carried that key twice, json.loads kept one of the
+pair, and a field disappeared from a document whose signature claimed to cover
+it. Nothing raised. cmcp's implementation does not have that bug, and this is
+what keeps it that way.
+
+Structure is built from the fuzz data rather than by mutating JSON text, so the
+budget goes on key and value shapes (combining marks, surrogate pairs, control
+characters, integer boundaries) instead of on producing syntactically valid JSON.
+"""
+import json
+import math
+import sys
+
+import atheris
+
+with atheris.instrument_imports():
+    from cmcp_runtime.catalog.approval import canonical_json
+
+_MAX_DEPTH = 4
+_MAX_ITEMS = 6
+
+
+def _build(fdp: atheris.FuzzedDataProvider, depth: int = 0):
+    if depth >= _MAX_DEPTH or fdp.remaining_bytes() == 0:
+        return fdp.ConsumeUnicodeNoSurrogates(16)
+    kind = fdp.ConsumeIntInRange(0, 7)
+    if kind == 0:
+        return None
+    if kind == 1:
+        return fdp.ConsumeBool()
+    if kind == 2:
+        # Straddle the safe-integer boundary on purpose: past it, RFC 8785 maps
+        # two distinct integers to the same digits, so the canonicalizer has to
+        # refuse rather than emit them.
+        return fdp.ConsumeIntInRange(-(2**54), 2**54)
+    if kind == 3:
+        return fdp.ConsumeFloat()
+    if kind == 4:
+        return fdp.ConsumeUnicodeNoSurrogates(64)
+    if kind == 5:
+        return [_build(fdp, depth + 1) for _ in range(fdp.ConsumeIntInRange(0, _MAX_ITEMS))]
+    return {
+        fdp.ConsumeUnicodeNoSurrogates(24): _build(fdp, depth + 1)
+        for _ in range(fdp.ConsumeIntInRange(0, _MAX_ITEMS))
+    }
+
+
+def _json_equal(a, b) -> bool:
+    """Equality up to JSON's number model.
+
+    JSON has one number type, so a float whose shortest form has no fractional
+    part re-parses as a Python int and will not compare equal to the float it
+    came from. That is correct output, not a defect, so the round trip is
+    asserted up to numeric type.
+    """
+    if isinstance(a, bool) or isinstance(b, bool):
+        return a is b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return float(a) == float(b)
+    if isinstance(a, dict) and isinstance(b, dict):
+        return a.keys() == b.keys() and all(_json_equal(a[k], b[k]) for k in a)
+    if isinstance(a, list) and isinstance(b, list):
+        return len(a) == len(b) and all(_json_equal(x, y) for x, y in zip(a, b))
+    return type(a) is type(b) and a == b
+
+
+def _has_nonfinite(value) -> bool:
+    """NaN and Infinity have no JSON form; the canonicalizer rejects them."""
+    if isinstance(value, float):
+        return not math.isfinite(value)
+    if isinstance(value, dict):
+        return any(_has_nonfinite(v) for v in value.values())
+    if isinstance(value, list):
+        return any(_has_nonfinite(v) for v in value)
+    return False
+
+
+def TestOneInput(data: bytes) -> None:
+    fdp = atheris.FuzzedDataProvider(data)
+    value = _build(fdp)
+    if _has_nonfinite(value):
+        return
+    try:
+        out = canonical_json(value)
+    except ValueError:
+        # Declared: CatalogApprovalError is a ValueError, and covers floats,
+        # integers outside the RFC 8785 safe domain, and unsupported types.
+        return
+
+    assert _json_equal(json.loads(out), value), f"canonical bytes did not round-trip: {out!r}"
+    assert canonical_json(value) == out, "canonicalization is not deterministic"
+
+
+def main() -> None:
+    atheris.Setup(sys.argv, TestOneInput)
+    atheris.Fuzz()
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/cflite_batch.yml

@@ -0,0 +1,37 @@
+name: ClusterFuzzLite batch
+
+on:
+  schedule:
+    # 04:20 UTC daily, off the hour so it does not queue behind everything else
+    # that runs at midnight.
+    - cron: '20 4 * * *'
+  workflow_dispatch:
+
+permissions: read-all
+
+concurrency:
+  group: cflite-batch
+  cancel-in-progress: false
+
+jobs:
+  fuzz:
+    name: Batch fuzz
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - name: Build fuzzers
+        uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          language: python
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: address
+
+      - name: Run fuzzers
+        uses: google/clusterfuzzlite/actions/run_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          # Every target, not just what changed, and long enough for the
+          # attestation parsers to get past their length and tag fields.
+          fuzz-seconds: 3600
+          mode: batch
+          sanitizer: address

.github/workflows/cflite_pr.yml

@@ -0,0 +1,41 @@
+name: ClusterFuzzLite PR
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - '.clusterfuzzlite/**'
+      - '.github/workflows/cflite_pr.yml'
+
+# Read-only. Findings surface in the job log and the uploaded crash artifact
+# rather than as code-scanning alerts, so no security-events: write is needed.
+permissions: read-all
+
+concurrency:
+  group: cflite-pr-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  fuzz:
+    name: Fuzz changed code
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      # Only the address sanitizer. The targets are pure Python under Atheris,
+      # where undefined-behaviour instrumentation has nothing to instrument.
+      - name: Build fuzzers
+        uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          language: python
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sanitizer: address
+
+      - name: Run fuzzers
+        uses: google/clusterfuzzlite/actions/run_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          fuzz-seconds: 300
+          # code-change fuzzes only what the PR touched, which is what keeps
+          # this inside a PR's time budget. The nightly batch covers the rest.
+          mode: code-change
+          sanitizer: address