Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,16 @@ jobs:
with:
python-version: ${{ matrix.python }}
# Deliberately without the [camera] extra: tests must pass with no depthai and no camera.
# Every tool comes from a hash-pinned list; the package itself is installed
# without dependencies or build isolation, so nothing unpinned is fetched.
- name: Install
run: |
python -m pip install --upgrade pip
python -m pip install -e '.[mcp]' pytest
python -m pip install --require-hashes -r requirements/ci.txt
python -m pip install --no-deps --no-build-isolation -e .
- name: depthai must be absent
run: python -c "import importlib.util, sys; sys.exit(importlib.util.find_spec('depthai') is not None)"
- name: Lint (ruff, warnings fail the build)
run: |
python -m pip install ruff==0.17.3
ruff check src tests
run: ruff check src tests fuzz
- name: Test
run: python -m pytest -q
- name: CLI smoke
Expand Down
36 changes: 36 additions & 0 deletions .github/workflows/fuzz.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
name: fuzz

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
atheris:
name: atheris (zones and event files, 60 s)
# atheris publishes Linux x86_64 wheels only.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.11"
- name: Install
run: python -m pip install --require-hashes -r requirements/fuzz.txt
- name: Fuzz
env:
PYTHONPATH: src
run: |
mkdir -p crashes
python fuzz/fuzz_events.py -dict=fuzz/events.dict -max_total_time=60 -artifact_prefix=crashes/ fuzz/corpus
- name: Keep crashing inputs
if: failure()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: fuzz-crashes
path: crashes/
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ jobs:
python-version: "3.13"
- name: Build
run: |
python -m pip install --upgrade pip build
python -m build
python -m pip install --require-hashes -r requirements/release.txt
python -m build --no-isolation
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: dist
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,7 @@ htmlcov/
.DS_Store
.idea/
.vscode/

# Fuzzing output (fuzz/fuzz_events.py)
crash-*
/crashes/
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,30 @@ All notable changes to this project are documented here. The format follows
flow and privacy impact, SBOM (CycloneDX) with licence summary. README and
`SECURITY.md` link them and the CloudLab Works incident response plan.
- Configurable `oak-events mcp --stale-after SECONDS` threshold for camera health.
- Atheris fuzz harness `fuzz/fuzz_events.py` for zones files and event JSONL
files, run for 60 s on every push and pull request (`fuzz` workflow).

### Changed

- CI and release workflows install their tools from hash-pinned lists in
`requirements/` (`pip install --require-hashes`), and install or build the
package without build isolation so no unpinned package is fetched.

### Fixed

- `oak-events run --zones` now reports a malformed `z_mm` or `bbox` (not a
list, non-numeric or boolean values) as a one-line "bad zones file" error
naming the zone, with exit code 2, instead of a Python traceback.
- Zones files: `NaN`, `Infinity` and integers too large for a float in `z_mm`
or `bbox` are now a "bad zones file" error. A `NaN` bound used to be
accepted and silently matched every depth. Found by the fuzz harness.
- MCP tools: a daily event file with one invalid UTF-8 line made every tool
fail; that line is now skipped like any other malformed line. Found by the
fuzz harness. Lines are now split at line endings only, so a U+2028 inside a
field (kept raw by the sink) no longer splits an event in two.
- MCP `zone_state` no longer fails on an event whose `zone` is a list or
object, and `camera_health` no longer fails on a non-string or out-of-range
`ts`. Found by the fuzz harness.

## [0.1.1] - 2026-10-12

Expand Down
15 changes: 15 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,21 @@ python3 -m venv .venv
.venv/bin/pytest -q
```

CI installs from the hash-pinned lists in `requirements/` instead; see
`requirements/README.md` to add or update a tool.

The parsing code (zones files, event files) also has an Atheris fuzz harness,
run for 60 s by the `fuzz` workflow on every push and pull request. Atheris has
Linux x86_64 wheels only:

```bash
pip install --require-hashes -r requirements/fuzz.txt
PYTHONPATH=src python fuzz/fuzz_events.py -dict=fuzz/events.dict -max_total_time=60 fuzz/corpus
```

A crash writes the input to `crash-*`; add it as a test in
`tests/test_parsing_robustness.py` with the fix.

Tests must pass **without a camera and without `depthai` installed**; that is
what CI runs (Ubuntu and macOS, Python 3.11 and 3.13). Put event logic in
`events.py` (pure, testable with synthetic data) and keep `camera.py` a thin
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,8 @@ names regions by normalized image box and/or distance:
```

`bbox` is `[x0, y0, x1, y1]` in 0..1 with the origin top-left; `z_mm` is
`[min, max]` distance in millimetres (either side may be `null`). Each zone
`[min, max]` distance in millimetres (either side may be `null`). Numbers must
be finite: `NaN` and `Infinity` are rejected. Each zone
gets its own person tracker and depth-change grid. The depth map is aligned to
the colour camera only approximately, so leave some margin.

Expand Down
Binary file added fuzz/corpus/events-camera-error
Binary file not shown.
Binary file added fuzz/corpus/events-day
Binary file not shown.
7 changes: 7 additions & 0 deletions fuzz/corpus/zones-example
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"zones": [
{"name": "doorway", "bbox": [0.0, 0.0, 0.35, 1.0]},
{"name": "desk", "bbox": [0.4, 0.3, 1.0, 1.0], "z_mm": [400, 2500]},
{"name": "far_wall", "z_mm": [3000, null]}
]
}
1 change: 1 addition & 0 deletions fuzz/corpus/zones-list
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
[{"name": "a", "z_mm": [null, 100]}, {"name": "b", "bbox": [0.5, 0.5, 1, 1]}]
33 changes: 33 additions & 0 deletions fuzz/events.dict
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# libFuzzer dictionary for fuzz_events.py
"\"zones\""
"\"name\""
"\"bbox\""
"\"z_mm\""
"\"kind\""
"\"ts\""
"\"zone\""
"\"state\""
"\"up\""
"\"camera\""
"\"alive\""
"\"person_enter\""
"\"person_exit\""
"\"depth_change\""
"\"depth_baseline\""
"null"
"true"
"false"
"NaN"
"Infinity"
"-Infinity"
"1e400"
"["
"]"
"{"
"}"
":"
","
"\"2026-01-01T08:00:00+00:00\""
"\"0001-01-01T00:00:00\""
"\"9999-12-31T23:59:59\""
"\x0a"
102 changes: 102 additions & 0 deletions fuzz/fuzz_events.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
"""Atheris fuzz harness for the parsing code: zones files and event JSONL lines.

Run (Linux, x86_64; atheris has no other wheels):

pip install --require-hashes -r requirements/fuzz.txt
PYTHONPATH=src python fuzz/fuzz_events.py -dict=fuzz/events.dict -max_total_time=60 fuzz/corpus

Input layout, kept simple so seeds in ``fuzz/corpus`` can be written by hand:
byte 0 picks the target (odd: zones, even: events); for zones, bytes 1 and 2
set the depth array shape and the rest is the file; for events, the rest is
the file.

* zones: JSON text -> ``parse_zones``. Bad input must raise ``ValueError``
(which the CLI reports as "bad zones file"), never anything else; accepted
zones must satisfy the documented bounds and crop any depth array safely.
* events: bytes written as a daily JSONL file -> ``recent_events``,
``zone_state`` and ``camera_health``. Malformed lines are documented as
skipped, so no file content may raise, and every result must still be
JSON-serialisable (the MCP tools return ``json.dumps`` of it).

No camera and no depthai: only the pure modules are imported.
"""

from __future__ import annotations

import datetime as dt
import json
import math
import sys
import tempfile
from pathlib import Path

import atheris

with atheris.instrument_imports():
import numpy as np

from oak_events import mcp_server
from oak_events.events import parse_zones

EVENTS_DIR = Path(tempfile.mkdtemp(prefix="oak-events-fuzz-"))
EVENTS_FILE = EVENTS_DIR / "2026-01-01.jsonl"
NOW = dt.datetime(2026, 1, 1, 12, 0, tzinfo=dt.timezone.utc)


def check_zones(data: bytes, shape: tuple[int, int]) -> None:
try:
spec = json.loads(data)
except (ValueError, RecursionError):
return # not JSON: load_zones never gets this far
try:
zones = parse_zones(spec)
except ValueError:
return
assert zones, "parse_zones returned no zones"
names = [z.name for z in zones]
assert len(names) == len(set(names)), names
depth = np.full(shape, 1500, dtype=np.uint16)
for z in zones:
assert isinstance(z.name, str) and z.name
if z.bbox is not None:
x0, y0, x1, y1 = z.bbox
assert 0.0 <= x0 < x1 <= 1.0 and 0.0 <= y0 < y1 <= 1.0, z.bbox
for bound in (z.z_min_mm, z.z_max_mm):
assert bound is None or math.isfinite(bound), (z.name, bound)
if z.z_min_mm is not None and z.z_max_mm is not None:
assert z.z_min_mm < z.z_max_mm
crop = z.crop(depth)
assert crop.ndim == 2 and crop.shape[0] <= shape[0] and crop.shape[1] <= shape[1]
z.contains(1500.0, 0.5, 0.5)


def check_events(data: bytes) -> None:
EVENTS_FILE.write_bytes(data)
results = [
mcp_server.recent_events(EVENTS_DIR, limit=50),
mcp_server.recent_events(EVENTS_DIR, limit=5, kind="camera"),
mcp_server.zone_state(EVENTS_DIR),
mcp_server.camera_health(EVENTS_DIR, now=NOW),
]
for result in results:
json.dumps(result)
assert results[3]["status"] in ("ok", "stale", "no_data") or results[3]["last_camera"] is not None


def test_one_input(data: bytes) -> None:
if not data:
return
if data[0] & 1:
shape = (data[1] % 40 + 1 if len(data) > 1 else 1, data[2] % 40 + 1 if len(data) > 2 else 1)
check_zones(data[3:], shape)
else:
check_events(data[1:])


def main() -> None:
atheris.Setup(sys.argv, test_one_input)
atheris.Fuzz()


if __name__ == "__main__":
main()
28 changes: 28 additions & 0 deletions requirements/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Hash-pinned tool lists for the workflows

Each `*.in` file lists what one workflow needs; the matching `*.txt` pins every
package, including transitive ones, to an exact version and the SHA-256 of
every published file. The workflows install with `pip install --require-hashes`,
so a changed or substituted file fails the install.

| File | Used by |
| --- | --- |
| `ci.txt` | `.github/workflows/ci.yml`: hatchling, numpy, mcp, pytest, ruff |
| `fuzz.txt` | `.github/workflows/fuzz.yml`: atheris and numpy for `fuzz/fuzz_events.py` |
| `release.txt` | `.github/workflows/release.yml`: build and hatchling |

hatchling is in the lists because the package is installed and built without
build isolation (`--no-build-isolation`, `python -m build --no-isolation`);
with isolation, pip would fetch the build backend unpinned.

After editing an `.in` file, regenerate its `.txt` (one command per file):

```bash
uv pip compile --universal --python-version 3.11 --generate-hashes \
--custom-compile-command "see requirements/README.md" \
requirements/ci.in -o requirements/ci.txt
```

`--universal` keeps one file valid for every OS and Python version in the CI
matrix. The weekly Dependabot pip update for `/` also reads this `requirements/`
folder and regenerates the hashes in its pull requests.
8 changes: 8 additions & 0 deletions requirements/ci.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Tools and test dependencies for .github/workflows/ci.yml (no depthai: tests run without a camera).
# Regenerate ci.txt after editing, see requirements/README.md.
hatchling
editables # hatchling needs it for editable installs (pip install -e)
numpy
mcp
pytest
ruff==0.17.3
Loading
Loading