diff --git a/.gitbook.yaml b/.gitbook.yaml new file mode 100644 index 0000000..23dad3a --- /dev/null +++ b/.gitbook.yaml @@ -0,0 +1,5 @@ +root: ./docs/ + +structure: + readme: README.md + summary: SUMMARY.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b45261f..1ce4dc4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,10 @@ All notable changes to this project are documented here. The format follows `oak_events-.intoto.jsonl`. Verify a download with `gh attestation verify --repo cloudlabworks/oak-events`. PyPI's own PEP 740 attestations are unchanged. +- User documentation in `docs/` (overview, install, quickstart, MCP server, + configuration, events reference, running it for real, security, + contributing), with `docs/SUMMARY.md` and `.gitbook.yaml` so the folder can + be synced to a GitBook site. ## [0.1.2] - 2026-11-02 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..766f283 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,65 @@ +# oak-events + +Privacy-first events from Luxonis OAK cameras for AI agents. + +An OAK camera detects people, tracks them and measures depth on its own chip. +`oak-events` turns that into one JSON line per event ("a person entered the +doorway zone", "something 40 cm closer has stood in cell r2c5 for a minute") +and serves those lines to agents through an MCP server. + +**Agents never receive a picture.** There is no image tool, no snapshot +command, and no code path that writes an image file. + +This documentation covers oak-events 0.1.2, the current release on +[PyPI](https://pypi.org/project/oak-events/). The source is on +[GitHub](https://github.com/cloudlabworks/oak-events). + +## Why + +Giving an agent a camera usually means giving it a video feed. Most agent +questions do not need one: *is anyone at the bench? did something on the shelf +move? is the camera alive?* Those are answerable from detections and a coarse +depth grid, which carry far less about the people in view than frames do. + +## Privacy model + +Stated plainly, so you can check it against the code: + +1. **Colour frames stay on the camera.** The colour sensor feeds the on-chip + detection network. Its frames are never linked to a host output queue. + Only two streams reach the host: detection results (label, confidence, + 3-D position, normalized box) and the stereo depth map + (`src/oak_events/camera.py`). +2. **Depth maps are reduced and dropped.** Each depth frame becomes a grid of + cell medians (default 6 x 8) in memory, then is discarded. No depth map is + stored. +3. **Only JSON lines are written**, to stdout and/or a daily `.jsonl` file. + A test scans the repo and a temporary run directory for image files. +4. **DepthAI telemetry, crash-dump upload and auto-calibration are off** by + default. See [Configuration](configuration.md#privacy-environment). +5. **The MCP server only reads the JSONL files.** It never opens the camera. +6. **No model download at runtime.** You point `--model` at a local NNArchive + you fetched once. + +What the events still reveal: when someone was present, for how long, how far +from the camera, and when objects moved. Treat the event files as sensitive +and keep them local. + +## Where to go next + +| Page | What it covers | +| --- | --- | +| [Install](install.md) | Supported hardware, installing from PyPI, fetching a model once | +| [Quickstart](quickstart.md) | Check the setup, run the camera, read events over MCP | +| [MCP server](mcp-server.md) | The three MCP tools, client configuration, access log | +| [Configuration](configuration.md) | Command line options, zones, model hash check, privacy environment | +| [Events reference](events.md) | Every event kind and its fields | +| [Running it for real](operations.md) | Supervisors, exit codes, PoE notes | +| [Security](security.md) | Reporting vulnerabilities, verifying releases, security and AI documents | +| [Contributing and licence](contributing.md) | Development setup, pull requests, MIT licence | + +--- + +oak-events is an independent community project by CloudLab Works, not +affiliated with or endorsed by Luxonis. OAK and DepthAI are Luxonis trademarks, +used here only to say which hardware and SDK the tool works with. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..e440641 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,30 @@ +# Table of contents + +* [Overview](README.md) + +## Getting started + +* [Install](install.md) +* [Quickstart](quickstart.md) + +## Using oak-events + +* [MCP server](mcp-server.md) +* [Configuration](configuration.md) +* [Events reference](events.md) +* [Running it for real](operations.md) + +## Security and AI + +* [Security](security.md) +* [Threat model](THREAT_MODEL.md) +* [Model card](MODEL_CARD.md) +* [Data flow and privacy impact](DATA_FLOW.md) +* [Software bill of materials](SBOM.md) +* [Shared responsibility](SHARED_RESPONSIBILITY.md) +* [Risk assessment](RISK_ASSESSMENT.md) +* [Hardening](HARDENING.md) + +## Project + +* [Contributing and licence](contributing.md) diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..e90ad52 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,94 @@ +# Configuration + +oak-events has no configuration file. Everything is a command line option, a +zones file, or an environment variable. + +## `oak-events run` + +| Option | Default | Meaning | +| --- | --- | --- | +| `--model PATH` | required | Local detection NNArchive (`.tar.xz`), fetched once (see [Install](install.md#fetch-a-model-once)) | +| `--device-id ID` | first device found | Device to open. Prefer it over addresses; the id survives network changes | +| `--out-dir DIR` | none | Also append events to `DIR/YYYY-MM-DD.jsonl` (mode 0600) | +| `--zones FILE` | one zone, `view` | Zones file (see [Zones](#zones)) | +| `--fps N` | `10` | Detection frame rate | +| `--alive-every SECONDS` | `300` | Interval of the `alive` heartbeat event | +| `--person-label NAME` | `person` | Model class treated as a person | +| `--person-confidence X` | `0.5` | Minimum detection confidence for a person | +| `--hold-seconds SECONDS` | `60` | How long a depth change must persist before it is reported | +| `--model-sha256 HEX` | off | Refuse to start unless the model archive has this SHA-256 | +| `--confidence-stats` | off | Add per-zone detection-confidence statistics to `alive` events | +| `--quiet` | off | Do not echo events to stdout | + +For `oak-events mcp` options, see [MCP server](mcp-server.md#options). +`oak-events doctor` takes only `--json`. + +## Zones + +By default everything is reported for one zone named `view`: the whole field +of view at any distance. A zones file names regions by normalized image box +and/or distance: + +```json +{ + "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]} + ] +} +``` + +- `bbox` is `[x0, y0, x1, y1]` in 0..1 with the origin top-left, and must + satisfy `0 <= x0 < x1 <= 1` and `0 <= y0 < y1 <= 1`. +- `z_mm` is `[min, max]` distance from the camera in millimetres. Either side + may be `null`; if both are set, `min` must be below `max`. +- A zone may have `bbox`, `z_mm`, both, or neither. +- 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. + +A malformed file stops `oak-events run` with a one-line `bad zones file` error +naming the zone, and exit code 2. + +## Model integrity check + +The SHA-256 of the model archive is computed at every start and recorded in +the `camera` `up` event (`model_sha256`), with or without any option. + +`--model-sha256 HEX` compares that hash with `HEX` (64 hexadecimal +characters) before the camera is opened. On a mismatch oak-events writes a +`camera` event with state `error`, `model_sha256` and `expected_sha256`, and +exits with code 3. The reference hash of the tested archive is in the +[model card](MODEL_CARD.md). + +## Confidence statistics + +`--confidence-stats` adds a `confidence` object to each `alive` event: per +zone, `n` counts per-frame person detections at or above +`--person-confidence`, `below` counts those under it, and `mean`, `min` and +`max` describe the accepted ones (`null` when `n` is 0). Each `alive` event +covers the time since the previous one. On a scene that does not change, a +falling mean or a rising `below` count means the model, the camera or the +light changed. The [model card](MODEL_CARD.md) describes a spot-check +procedure. + +## Privacy environment + +Before `depthai` is imported, oak-events forces these variables, overwriting +any value already set: + +| Variable | Forced value | Effect | +| --- | --- | --- | +| `DEPTHAI_TELEMETRY` | `0` | DepthAI telemetry off | +| `DEPTHAI_DISABLE_CRASHDUMP_COLLECTION` | `1` | Crash-dump upload off | +| `DEPTHAI_AUTOCALIBRATION` | `OFF` | On-device auto-calibration off | + +The only way to keep DepthAI's own defaults is `OAK_EVENTS_ALLOW_TELEMETRY=1`, +in which case oak-events leaves the environment untouched. + +Every run writes a `privacy` event before DepthAI loads: `private` is `false` +if any of the three variables differs from the private value, and +`deviations` names them. `oak-events doctor` shows the same state, and the MCP +`camera_health` tool returns the latest `privacy` event. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..e9fffbe --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,69 @@ +# Contributing and licence + +Bug reports, hardware reports (especially RVC4) and small, focused pull +requests are all welcome on +[GitHub](https://github.com/cloudlabworks/oak-events). The full guide is +[`CONTRIBUTING.md`](https://github.com/cloudlabworks/oak-events/blob/main/CONTRIBUTING.md) +in the repository; this page summarizes it. + +## The one rule + +**No pictures leave the camera.** Changes must not: + +- link a colour, preview or passthrough output to a host queue, +- write images, depth maps or arrays (`.jpg`, `.png`, `.npy`, ...) to disk, +- add an MCP tool or event field that carries image data. + +`tests/test_no_images.py` and the privacy tests enforce part of this; +reviewers check the rest. + +## Development setup + +```bash +python3 -m venv .venv +.venv/bin/pip install -e '.[mcp]' pytest +.venv/bin/pytest -q +``` + +Tests must pass **without a camera and without `depthai` installed**; that is +what CI runs (Ubuntu and macOS, Python 3.11 and 3.13). CI installs its tools +from the hash-pinned lists in `requirements/`. Put event logic in `events.py` +(pure, testable with synthetic data) and keep `camera.py` a thin adapter +around DepthAI. + +The parsing code (zones files, event files) also has an Atheris fuzz harness, +run for 60 seconds on every push and pull request. + +If you have hardware, also try `pip install -e '.[camera]'` and +`oak-events doctor`, then a short `oak-events run`, and mention the device and +results in your pull request. + +## Pull requests + +- One change per pull request, with tests for new logic. +- Update the event schema in `README.md` and in this documentation + ([Events reference](events.md)) when you add or change an event. +- Add a line under "Unreleased" in `CHANGELOG.md`. +- Do not include device ids, network addresses, hostnames or personal paths in + code, tests, docs or example output. + +## Editing this documentation + +These pages live in the `docs/` folder of the repository and are published +with GitBook. Edit the Markdown files and open a pull request like any other +change; `docs/SUMMARY.md` sets the page order. + +## Code of conduct + +This project follows the +[Contributor Covenant](https://github.com/cloudlabworks/oak-events/blob/main/CODE_OF_CONDUCT.md). + +## Licence + +oak-events is released under the +[MIT licence](https://github.com/cloudlabworks/oak-events/blob/main/LICENSE). +By contributing you agree your work is released under the same licence. + +oak-events is an independent community project by CloudLab Works, not +affiliated with or endorsed by Luxonis. OAK and DepthAI are Luxonis +trademarks, used here only to say which hardware and SDK the tool works with. diff --git a/docs/events.md b/docs/events.md new file mode 100644 index 0000000..fffe94d --- /dev/null +++ b/docs/events.md @@ -0,0 +1,92 @@ +# Events reference + +Every event is one JSON object on one line, with `ts` (ISO-8601 local time +with offset, to the second), `kind`, and the fields below. `oak-events run` +prints events to stdout and, with `--out-dir DIR`, appends them to +`DIR/YYYY-MM-DD.jsonl`. + +```json +{"ts": "2026-10-11T09:14:03-07:00", "kind": "person_enter", "zone": "doorway", "count": 1, "nearest_mm": 1840} +``` + +## Event kinds + +| kind | fields | meaning | +| --- | --- | --- | +| `person_enter` | `zone`, `count`, `nearest_mm` | A person was seen in 3 consecutive frames | +| `person_exit` | `zone`, `dwell_s` | Nobody seen for 10 seconds; dwell is first to last sighting | +| `depth_baseline` | `zone`, `cells_judged`, `cells_noisy`, `grid` | Baseline built; noisy cells (stereo noise, low texture) are ignored | +| `depth_change` | `zone`, `cells` (for example `["r0c3"]`), `delta_mm` | A cell's depth moved more than 15 % for `--hold-seconds` (60) with nobody present | +| `camera` | `state`, plus the fields below as relevant | Camera lifecycle | +| `alive` | `det_fps`, `person`, `occupied`; with `--confidence-stats` also `confidence` | Heartbeat every `--alive-every` seconds (300) | +| `privacy` | `private`, `telemetry_opt_in`, `deviations` | Written once per run, before DepthAI loads | + +## People + +A person tracker runs per zone. A detection counts when its label is +`--person-label` (`person`), its confidence is at least `--person-confidence` +(0.5), and it falls inside the zone. + +- `person_enter` fires after 3 consecutive frames with a person. `count` is + the number of people in that frame, `nearest_mm` the distance of the + nearest one. +- `person_exit` fires once nobody has been seen for 10 seconds. `dwell_s` is + the time from first to last sighting, in whole seconds. + +## Depth + +Each depth frame is reduced to a grid of cell medians (default 6 rows by 8 +columns) per zone and then dropped. Cells are named `rc`, +starting at `r0c0` top-left. + +- `depth_baseline`: the first 60 depth frames build a baseline. `grid` is + `[rows, columns]`, `cells_judged` the cells that will be watched, and + `cells_noisy` the cells ignored because their depth is unstable or often + invalid. +- `depth_change`: one or more cells differ from the baseline by more than + 15 % for `--hold-seconds`. `cells` lists them and `delta_mm` gives the + signed change for each, in the same order (negative means closer). The + baseline of those cells then moves to the new depth. + +Depth-change detection pauses while a person is present in that zone: people +are not scenery. + +## Camera lifecycle + +`camera` events carry `state`: + +| state | When | Extra fields | +| --- | --- | --- | +| `up` | Pipeline started | `device`, `device_model`, `bootloader`, `model`, `model_sha256`, `model_sha256_checked`, `zones` | +| `not_found` | No device found after up to 240 seconds of discovery | `device` | +| `reconnect` | DepthAI is reconnecting (up to 5 attempts) | `detail` | +| `pipeline_stopped` | The pipeline stopped running | | +| `error` | Model archive missing, model hash mismatch, or an unexpected error | `detail`; on a hash mismatch also `model`, `model_sha256`, `expected_sha256` | +| `stopped` | Stopped with Ctrl+C | | + +For the exit code that goes with each state, see +[Running it for real](operations.md#exit-codes). + +## Heartbeat + +`alive` events report `det_fps` (detection frames per second since the +previous heartbeat), `person` (`true` if any zone has a person present) and +`occupied` (the zones with a person present). + +With `--confidence-stats`, `confidence` holds per zone `n`, `mean`, `min`, +`max` and `below`; see +[Configuration](configuration.md#confidence-statistics). + +## Privacy + +The `privacy` event records whether the DepthAI privacy defaults held for this +run: `private` is `false` if any DepthAI privacy variable differs from the +private value, `telemetry_opt_in` is `true` if `OAK_EVENTS_ALLOW_TELEMETRY=1` +was set, and `deviations` names the variables that differ. See +[Configuration](configuration.md#privacy-environment). + +## What events never contain + +No event carries image data, a depth map, or an array of pixels. The only +spatial data is the per-zone grid size, cell names, distances in millimetres +and normalized zone boxes from your zones file. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..951a780 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,85 @@ +# Install + +## Supported hardware + +| Device | Status | +| --- | --- | +| RVC2: OAK-D PoE | Tested live (DepthAI 3.11, bootloader 0.0.29, macOS arm64) | +| RVC2: OAK-D (USB) | Expected to work; untested, reports welcome | +| RVC4 (e.g. OAK 4) | Untested; reports welcome | + +Requires Python 3.10 or later. Running the camera requires DepthAI v3 +(`depthai>=3.9`). Linux and macOS are the listed platforms. + +## Install from PyPI + +oak-events is published on PyPI as [`oak-events`](https://pypi.org/project/oak-events/). +The core package depends only on `numpy`. Two extras add the rest: + +| Extra | Adds | Needed for | +| --- | --- | --- | +| `camera` | `depthai>=3.9` | `oak-events run`, and device details in `oak-events doctor` | +| `mcp` | `mcp>=1.0` (official MCP Python SDK) | `oak-events mcp` | + +On the host that has the camera and also serves agents, install both: + +```bash +pip install 'oak-events[camera,mcp]' +``` + +A host that only serves events to agents (for example a sandboxed MCP server +reading a copied or shared events directory) needs only the `mcp` extra: + +```bash +pip install 'oak-events[mcp]' +``` + +Check the install: + +```bash +oak-events --version +oak-events doctor +``` + +`doctor` works without a camera and without `depthai` installed; it then +reports `depthai: not installed`. + +To verify the downloaded files against their build provenance, see +[Security](security.md#verifying-a-release). + +## Fetch a model once + +oak-events never downloads anything at runtime. Fetch a detection NNArchive +from the Luxonis model zoo once, with DepthAI itself, and keep the file: + +```python +import depthai as dai + +path = dai.getModelFromZoo( + dai.NNModelDescription(model="luxonis/yolov6-nano:r2-coco-512x288", platform="RVC2") +) +print(path) # copy this .tar.xz somewhere stable and pass it to --model +``` + +This one step contacts the Luxonis model hub. Check the exact model slug on the +Luxonis model zoo; any detection NNArchive whose classes include `person` +works (use `--person-label` if the class has another name). For RVC4, use +`platform="RVC4"`. + +The [model card](MODEL_CARD.md) describes the reference detector and gives the +SHA-256 of the archive the project tested. Check the hash of what you download +and, once you trust a file, pin it with `--model-sha256` (see +[Configuration](configuration.md#model-integrity-check)). + +## Install from source + +```bash +git clone https://github.com/cloudlabworks/oak-events.git +cd oak-events +python3 -m venv .venv +.venv/bin/pip install -e '.[mcp]' pytest +.venv/bin/pytest -q +``` + +Tests need neither a camera nor `depthai`. Add the `camera` extra to run +against real hardware. diff --git a/docs/mcp-server.md b/docs/mcp-server.md new file mode 100644 index 0000000..2aab0e5 --- /dev/null +++ b/docs/mcp-server.md @@ -0,0 +1,96 @@ +# MCP server + +`oak-events mcp --events-dir DIR` runs a stdio MCP server built on the +official `mcp` Python SDK (install the `mcp` extra). It reads the daily +`YYYY-MM-DD.jsonl` files that `oak-events run --out-dir DIR` writes. + +The server never opens the camera, has no image tool, takes no path arguments +and only reads `*.jsonl` files in `DIR`. Malformed lines, including lines with +invalid UTF-8, are skipped. + +## Options + +| Option | Default | Meaning | +| --- | --- | --- | +| `--events-dir DIR` | required | Directory written by `oak-events run --out-dir` | +| `--stale-after SECONDS` | `900` | `camera_health` reports `stale` when the newest `camera` or `alive` event is older than this | +| `--access-log FILE` | off | Append one JSON line per tool call to `FILE` (see [Access log](#access-log)) | + +## Tools + +All tools return JSON text. + +### `recent_events(limit=50, kind=None)` + +The latest events, oldest first. `limit` is clamped to 1..500. `kind` +filters to one event kind, for example `person_enter`. + +### `zone_state()` + +Per zone: whether a person is present (from the latest `person_enter` or +`person_exit` event), that event, and the latest `depth_change` and +`depth_baseline` events. Looks back at most 14 daily files. + +```json +{"zones": {"doorway": {"person_present": true, "person_event": {"ts": "...", "kind": "person_enter", "zone": "doorway", "count": 1, "nearest_mm": 1840}}}} +``` + +### `camera_health()` + +The latest `camera` and `alive` events with their age in seconds, the latest +`privacy` event, and: + +- `status`: `ok`, `stale` (newest event older than `--stale-after`), + `no_data` (no `camera` or `alive` event in the last 14 daily files), or the + last camera state (for example `not_found`, `error`) when the camera is not + up. +- `private`: `true` or `false` from the latest `privacy` event, or `null` if + no run has written one. + +## Client configuration + +Example for Claude Desktop (`examples/claude-desktop-mcp.json` in the +repository): + +```json +{ + "mcpServers": { + "oak-events": { + "command": "oak-events", + "args": ["mcp", "--events-dir", "~/.local/share/oak-events/events"] + } + } +} +``` + +With [uv](https://docs.astral.sh/uv/) the client can run the PyPI release +without a separate install. This is the form listed in the MCP registry as +`io.github.cloudlabworks/oak-events`: + +```json +{ + "mcpServers": { + "oak-events": { + "command": "uvx", + "args": ["--with", "mcp", "oak-events", "mcp", "--events-dir", "/path/to/events"] + } + } +} +``` + +## Access log + +`--access-log FILE` appends one JSON line per tool call to `FILE`, created +with mode 0600. Each line has `ts`, `kind` (`mcp_access`), `tool`, `args` +(each argument name with the size of its value), `result_count`, `ok`, +`error` (exception type) when a call failed, and `client_pid` (the process +that started the server, normally the MCP client). + +Argument values and results are never written: the log shows that an agent +read events, not what it read. `FILE` must be outside the events directory, +otherwise the tools would serve it as events. + +## Running the server isolated + +The [hardening guide](HARDENING.md) runs the MCP server read-only, with no +network and no devices, under a dedicated user. diff --git a/docs/operations.md b/docs/operations.md new file mode 100644 index 0000000..e3ef41b --- /dev/null +++ b/docs/operations.md @@ -0,0 +1,49 @@ +# Running it for real + +Run `oak-events run` under a supervisor that restarts it on exit (systemd, +launchd, a container restart policy). The process does not restart itself: +it exits with a `camera` event explaining why. + +## Exit codes + +| Code | Last `camera` state | Cause | +| --- | --- | --- | +| `0` | `stopped` | Interrupted (Ctrl+C) | +| `1` | `pipeline_stopped` or `error` | The pipeline stopped, or an unexpected error (`detail` says which) | +| `2` | `not_found`, or none | No device found after discovery, or a bad zones file (one-line error on stderr) | +| `3` | `error` | Model archive not found, or its SHA-256 does not match `--model-sha256`; the camera was not opened | +| `4` | none | `depthai` is not installed (install the `camera` extra) | + +`oak-events mcp` exits with code 2 for a bad `--access-log` path and 4 when +the `mcp` package is not installed. + +## Monitoring + +The MCP `camera_health` tool (see [MCP server](mcp-server.md#camera_health)) +gives a one-word status from the latest `camera` and `alive` events. Outside +an agent, watch the events directory for `camera` events other than `up`, an +`alive` gap longer than `--alive-every`, or a `privacy` event with `private` +set to `false`. `examples/webhook.md` in the repository shows alerting on the +privacy and model-integrity events. + +## Isolation + +The [hardening guide](HARDENING.md) runs the camera runner as a dedicated +user under a sandboxed systemd unit and the MCP server read-only, without +network or devices, with a container test bed. + +## PoE notes + +- **Bootloader:** RVC2 PoE devices with a bootloader older than **0.0.29** can + fail discovery; 0.0.29 fixes it. `oak-events doctor` shows the version when + the device is not in use. +- **The device can take from about 30 seconds to a few minutes to free up** + after a previous host disconnects (2.5 minutes observed on an OAK-D PoE). + `oak-events run` retries discovery for up to 4 minutes (240 seconds), then + asks DepthAI to reconnect up to 5 times before giving up. +- **macOS launchd:** observed, cause not proven: under a launchd job the device + could fail with `X_LINK_DEVICE_NOT_FOUND` while the same command worked from + a terminal. Running it under a supervisor process that has macOS + local-network permission worked. If you see this, check + *System Settings > Privacy & Security > Local Network*. +- Prefer `--device-id` over addresses; the id survives network changes. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..8e3a56c --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,77 @@ +# Quickstart + +This takes you from a fresh install to an agent reading camera events. It +assumes you installed `oak-events[camera,mcp]` and fetched a model archive +once (see [Install](install.md)). + +## 1. Check the setup + +```bash +oak-events doctor +``` + +`doctor` prints the oak-events, Python, DepthAI and MCP SDK versions, the +DepthAI privacy settings, and every visible device with its bootloader version +and advice. Add `--json` for machine-readable output. + +If no device is listed, see the [PoE notes](operations.md#poe-notes): a PoE +camera can take from about 30 seconds to a few minutes to free up after +another host disconnects, and on macOS the process needs local-network +permission. + +## 2. Run the camera + +```bash +oak-events run \ + --model ~/models/yolov6-nano.rvc2.tar.xz \ + --out-dir ~/.local/share/oak-events/events +``` + +Events print to stdout, one JSON object per line, and are appended to +`~/.local/share/oak-events/events/YYYY-MM-DD.jsonl` (files are created with +mode 0600). The first lines are a `privacy` event, written before DepthAI +loads, and a `camera` event with state `up`: + +```json +{"ts": "2026-10-11T09:14:03-07:00", "kind": "person_enter", "zone": "doorway", "count": 1, "nearest_mm": 1840} +``` + +Without a zones file everything is reported for one zone named `view`. To name +regions such as a doorway or a desk, see +[Zones](configuration.md#zones). Every event kind is listed in the +[Events reference](events.md). + +Stop with Ctrl+C; oak-events writes a `camera` event with state `stopped`. + +## 3. Let an agent read the events + +```bash +oak-events mcp --events-dir ~/.local/share/oak-events/events +``` + +This starts a stdio MCP server with three read-only tools: `recent_events`, +`zone_state` and `camera_health`. Normally your MCP client starts it for you. +For example, a Claude Desktop configuration: + +```json +{ + "mcpServers": { + "oak-events": { + "command": "oak-events", + "args": ["mcp", "--events-dir", "~/.local/share/oak-events/events"] + } + } +} +``` + +See [MCP server](mcp-server.md) for the tools and their output. + +## Next steps + +- Keep the camera runner alive under a supervisor: [Running it for real](operations.md). +- Isolate the runner and the MCP server: the + [hardening guide](HARDENING.md) runs both under a dedicated user, with a + read-only, network-free MCP server. +- Wire the event stream into automations: see + [`examples/openclaw-stream.md`](https://github.com/cloudlabworks/oak-events/blob/main/examples/openclaw-stream.md) + and [`examples/webhook.md`](https://github.com/cloudlabworks/oak-events/blob/main/examples/webhook.md). diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..655b416 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,64 @@ +# Security + +## Reporting a vulnerability + +Please report security issues **privately** through GitHub's security +advisories: open the repository's **Security** tab and choose +[**Report a vulnerability**](https://github.com/cloudlabworks/oak-events/security/advisories/new). +Do not open a public issue for security problems. + +Include what you found, how to reproduce it, and the impact you expect. You +should get an acknowledgement within a week. + +Reports are triaged, fixed and disclosed under the CloudLab Works +[incident response plan](https://github.com/cloudlabworks/.github/blob/main/policies/incident-response-plan.md), +which sets severity levels, fix targets and coordinated disclosure timelines. +Only the latest release receives fixes while the project is pre-1.0. + +## In scope + +Anything that breaks the [privacy model](README.md#privacy-model), for +example: + +- a code path that sends colour frames to the host, or writes any image or + depth map to disk, +- DepthAI telemetry, crash-dump upload or auto-calibration being enabled + without `OAK_EVENTS_ALLOW_TELEMETRY=1`, +- the MCP server exposing anything other than event data, reading files outside + the events directory, or touching the camera, +- event files being created with permissions broader than the owner. + +## Verifying a release + +PyPI serves PEP 740 publish attestations for every oak-events file it hosts, +including 0.1.2. + +From the release after 0.1.2, each version tag builds the sdist and wheel +once, records build provenance for them through Sigstore, publishes them to +PyPI and attaches the same files and `oak_events-.intoto.jsonl` to +the GitHub Release. To check a downloaded file: + +```bash +gh attestation verify oak_events--py3-none-any.whl --repo cloudlabworks/oak-events +``` + +Add `--bundle oak_events-.intoto.jsonl` to verify against the bundle +from the release instead of the GitHub attestations API. + +## Security and AI documentation + +| Document | What it covers | +| --- | --- | +| [Threat model](THREAT_MODEL.md) | Trust boundaries, threats (STRIDE, MITRE ATLAS, OWASP LLM Top 10) and residual risk | +| [Model card](MODEL_CARD.md) | The reference detector, its limits, failure modes and open-model risk | +| [Data flow, retention and privacy impact](DATA_FLOW.md) | What leaves the camera, what is stored, retention and redaction | +| [Software bill of materials](SBOM.md) | CycloneDX SBOM and licence summary for 0.1.2 | +| [Shared responsibility](SHARED_RESPONSIBILITY.md) | Who owns which security control (CloudLab Works, you, the model provider), per AI-CAIQ question | +| [Risk assessment](RISK_ASSESSMENT.md) | AI risk register and AI impact assessment | +| [Hardening](HARDENING.md) | Running oak-events as a dedicated user, with a sandboxed, read-only MCP server | + +The CloudLab Works +[security policies](https://github.com/cloudlabworks/.github/tree/main/policies) +cover the security baseline, the security and AI governance policy (including +acceptable use of oak-events), the incident response plan, the supply chain +policy and the security program index.