---
title: "Cookie scanner"
description: "The static scanner, OCDB freshness and runtime discovery."
url: https://docs.systhema.app/next/guides/cookie-consent/scanner
version: unreleased (main)
docs_index: https://docs.systhema.app/next/llms.txt
---

The scanner walks your source tree, detects cookie usage, classifies each cookie via the Open Cookie Database, and writes the result to `.systhema/cookies.discovered.json`. For the Payload starter, `systhema cookies seed --payload-config src/payload.config.ts` pushes the entries into the Payload global additively (never overwrites editor-edited fields).

```bash
# Scan + classify + write .systhema/cookies.discovered.json
systhema cookies scan

# Seed the Payload general-settings global with the discovered cookies
systhema cookies seed --payload-config src/payload.config.ts

# Refresh the project-local OCDB cache from upstream
systhema cookies update-db

# Preview scan output without writing
systhema cookies scan --dry-run
```

The detector picks up:

- Direct `document.cookie = '...'` assignments
- Next.js `cookies().set/get/delete('name', …)` API
- Helper imports, `setCookie('name')` from `cookies-next`, `nookies`, `js-cookie`
- `Set-Cookie` HTTP header strings
- Cookies implied by `package.json` deps (e.g. `@next/third-parties` → `_ga`, `_ga_*`, `_gid`)
- Auth library well-knowns from package detection (NextAuth, better-auth, etc.)

Hits are classified into one of the five categories using the OCDB plus a hardcoded auth/session whitelist (so app session cookies never get bucketed as analytics). Misses land in `discovered.uncategorized[]` for manual review.

## OCDB freshness

A snapshot of the [Open Cookie Database](https://github.com/jkwakman/Open-Cookie-Database) is bundled with each `@systhemaui/core` release, CI fetches it on every release tag. For projects that need fresher data than the installed Systhema version provides:

- `systhema cookies update-db`, fetches the latest from upstream and caches it at `.systhema/cache/open-cookie-database.json`. The scanner uses the cache when present.
- `systhema cookies scan --db <url|path>`, one-off override for a single scan run.
- `cookieConsent.scanner.databaseUrl` in `systhema.config.ts`, persistent override.

## Re-running

`systhema cookies scan` replaces the discovered output on each run, including its scan timestamp. Review it before seeding. `scan` and `seed` support `--dry-run`; `update-db` does not. `seed` is additive by cookie name. Existing entries stay untouched even if their classification changes upstream. Without `--payload-config`, it looks for `payload.config.ts` at the project root, which differs from the starter's `src/payload.config.ts`. Even a seed dry run loads Payload and reads the global; it is not an offline operation.

## Runtime cookies

Scripts that set cookies at runtime (chat widgets, ad networks, embeds, analytics SDKs) are invisible to the static scanner. The `systhema:discovering-runtime-cookies` agent skill fills that gap; install it with [`systhema skills install`](https://docs.systhema.app/next/cli/skills.md).

The flags of `scan`, `seed` and `update-db` are on [systhema cookies](https://docs.systhema.app/next/cli/cookies.md).